Replication Guide and Reference

Additional Apply program operations

This section provides information about performing two additional Apply program functions: using the ASNDONE exit routine and refreshing target tables with the ASNLOAD exit routine.

Using the ASNDONE exit routine for AS/400

The ASNDONE exit routine is a program that the Apply program can optionally call after subscription processing completes, regardless of success or failure. A separate subscription notify program can be provided for each Apply qualifier. For general information about the ASNDONE exit routine, see Using the ASNDONE exit routine.

This section provides information about customizing the ASNDONE routine for an AS/400 environment.

When creating your subscription notify program, consider these activation group concerns:

If the program is created to run with a new activation group: the Apply program and the subscription notify program will not share SQL resources, such as RDB connections and open cursors. The activation handling code in the AS/400 operating system frees any resources allocated by the subscription notify program before control is returned to the Apply program. Additional resource is used every time that the Apply program calls the subscription notify program.

If the program is created to run in the caller's activation group: it shares SQL resources with the Apply program. Design the program so that you minimize its impact on the Apply program. For example, the program might cause unexpected Apply program processing if it changes the current relational database (RDB) connection.

If the program is created to run in a named activation group: it does not share resources with the Apply program. Using a named activation group will avoid the activation group overhead every time the subscription notify program is called. Run time data structures and SQL resources can be shared between invocations. Application cleanup processing is not performed until the Apply program is ended, so the subscription notify program must be designed to ensure that it does not cause lock contention with the Apply program by leaving source tables, target tables, or control tables locked when control is returned to the Apply program.

When you start the Apply program, specify the name of the subscription notify program using the parameter SUBNFYPGM on the STRDPRAPY command. For example, if the program is named ASNDONE_1 and resides in library APPLIB, the parameter is coded:

SUBNFYPGM(APPLIB/ASNDONE_1).

Refreshing target tables with the ASNLOAD exit routine for AS/400

The ASNLOAD full-refresh exit routine is called by the Apply program:

• When it determines that a full refresh of a target table is necessary.

• If you specify the name of a full refresh program on the FULLREFPGM parameter when you start the Apply program.

When a full refresh of a subscription set is necessary, the Apply program calls the exit routine. The program then performs a full refresh of the target table (if necessary), or of each target table listed in the subscription set.

You can use an exit routine instead of the Apply program to perform a full refresh more efficiently. For example, if you are copying every row and every column from a source table to a target table, you can design a full-refresh exit routine that uses a Distributed Data Management (DDM) file and the Copy File (CPYF) CL command to copy the entire file from the source table to the target table.

If the exit routine returns a non-zero return code, the current subscription set being processed by the Apply program fails. Processing of the remainder of the subscription set is discontinued until the next iteration.

Guidelines for using ASNLOAD

The source for sample exit routines is included with DPROPR/400. The samples for the C, COBOL, and RPG languages are:

Compiler language	Library name	Source file name	Member name
C	QDPR	QCSRC	ASNLOAD
COBOL	QDPR	QCBLLESRC	ASNLOAD
RPG	QDPR	QRPGLESRC	ASNLOAD

You cannot direct the Apply program to use another program unless you end the Apply program and start it again with another STRDPRAPY command.

• To avoid interference with the Apply program, compile the exit routine so that it uses a new activation group (not the caller's activation group).

• The exit routine should perform a COMMIT operation.

• The system calls the exit routine to perform a full refresh of each target table associated with the subscription set. You can either:

  • Design the program to distinguish between the different target tables and subscription sets.

  • Associate a single subscription set with a single member to one Apply qualifier.

• You can compile the exit routine with a named activation group or with a new activation group. To get better performance, use a named activation group. With a named activation group, the exit routine must commit or roll back changes as needed. The Apply program will not cause changes to be committed or rolled back (unless it ends).

  The exit routine should either explicitly commit changes, or it should be compiled to implicitly commit changes when it completes. Any uncommitted changes when the exit routine completes are not committed until either:

  • The Apply program calls another exit routine with the same activation group.

  • The job started for the Apply program ends.

Required parameters for ASNLOAD

Return code

Specifies whether the exit routine was successful, indicated by a return code of 0. If the return code is not 0 the Apply program produces an error. If trace is on, the Apply program produces trace output.

Reason code

Specifies a value that can be used to further describe the exit routine failure. If the return code is not 0 and if trace is on, the Apply program includes the reason code information as part of the trace output. The values for the reason code should be specific to your user application.

Control server RDB name

Specifies the RDB name of the database where the subscription set tables are located. The name is padded with blanks.

Target server relational database (RDB) name

Specifies the name of the database where the target table is located. The name is padded with blanks.

Target table library

Specifies the name of the library that contains the target table. If the target server RDB name is not an AS/400 database, this parameter is the authorization ID of the target table, which is obtained from the TARGET_OWNER column of the row of the subscription member table that is currently processed by the Apply program. The name is padded with blanks.

Target table name

Specifies the name of the target table, which is obtained from the TARGET_TABLE column of the row in the subscription-targets-member table that is currently processed by the Apply program. If the target server is a database for AS/400, the name can be either an SQL table name or an AS/400 system file name. The name is padded with blanks.

Control server RDB name

Specifies the RDB name of the database where the subscription tables are located. The name is padded with blanks.

Apply qualifier

Specifies the qualifier used to start this instance of the Apply program. This value is obtained from the APPLY_QUAL column of the row in the subscription set table that is currently processed by the Apply program. The name is padded with blanks.

Subscription set name

Specifies the name of the subscription set that the Apply program has just completed. This value is obtained from the SET_NAME column of the row in the subscription set table that is currently processed by the Apply program. The name is padded with blanks.

Source server RDB name

Specifies the RDB name of the database where the source table is located. The name is padded with blanks.

SQL SELECT statement

Specifies a variable length SQL statement that you can use to select the source table rows and columns to be copied to the target table. The following table shows the structure of the SQL SELECT statement.

Decimal Offset	Hex Offset	Type	Field
0	0	BINARY(4)	SQL statement length
4	4	Char(*)	SQL select statement

Trace indicator

Specifies whether the Apply program generates trace data. The exit routine can use the trace indicator to coordinate its internal trace with the Apply trace.

When the Apply program generates a trace, it prints to a spool file. If the exit routine is running in a separate activation group, the results print to a separate spool file. If the exit routine runs in the caller's activation group, the results print to the same spool file as the Apply trace.

The values for trace indicator are:

YES

Trace data is being produced.

NO

No trace data is being produced.

Other

No trace data is being produced.

[ DB2 List of Books | Search the DB2 Books ]