asnapply: Starting Apply

Use the asnapply command to start the Apply program on Linux®, UNIX, Windows, and UNIX System Services (USS) on z/OS®. Run this command at an operating system prompt or in a shell script.

After you start the Apply program, it runs continuously until you stop it or it detects an unrecoverable error.

Syntax

Read syntax diagramSkip visual syntax diagramasnapplyRequired z/OS parametersRequired Linux, UNIX and Windows parameterOptional parameters
Required z/OS parameters
Read syntax diagramSkip visual syntax diagramapply_qual= apply_qualifierdb2_subsystem= name
Required Linux, UNIX and Windows parameters
Read syntax diagramSkip visual syntax diagramapply_qual= apply_qualifiercontrol_server= db_name
Optional parameters
Read syntax diagramSkip visual syntax diagramapply_path= pathnamepwdfile=asnpwd.autfilenamelogreuse=nylogstdout=nyloadxit=nyinamsg=ynnotify=nycopyonce=nysleep=yntrlreuse=nyopt4one=nydelay= nerrwait= nterm=ynrefresh_commit_cnt= ntolerate_lsn_trunc=nyOptional z/OS parametersOptional Linux, UNIX and Windows parameters
Optional z/OS parameters
Read syntax diagramSkip visual syntax diagramspillfile=memdiskarm= identifiercaf=yn
Optional Linux, UNIX and Windows parameters
Read syntax diagramSkip visual syntax diagramsqlerrcontinue=nyspillfile=disk

Parameters

Table 1 defines the invocation parameters.

Table 1. asnapply invocation parameter definitions for Linux, UNIX, Windows, and z/OS operating systems
Parameter Definition
apply_qual=apply_qualifier Specifies the Apply qualifier that the Apply program uses to identify the subscriptions sets to be served.

The value that you enter must match the value of the APPLY_QUAL column in the IBMSNAP_SUBS_SET table. The Apply qualifier name is case sensitive and can be a maximum of 18 characters.
db2_subsystem=name

z/OS: Specifies the name of the Db2® subsystem where the Apply program will run. The subsystem name that you enter can be a maximum of four characters. There is no default for this parameter. This parameter is required.
control_server=db_name Specifies the name of the Apply control server on which the subscription definitions and Apply program control tables reside. This parameter is mandatory. On z/OS, this parameter specifies the location name of the Apply control server.
apply_path=pathname Specifies the location of the work files used by the Apply program. The default is the directory where the asnapply command was invoked.
pwdfile=filename Specifies the name of the password file. If you do not specify a password file, the default is asnpwd.aut.

This command searches for the password file in the directory specified by the apply_path parameter. If no apply_path parameter is specified, this command searches for the password file in the directory where the command was invoked.
logreuse=y/n Specifies whether the Apply program reuses or appends messages to the log file.
n (default)
The Apply program appends messages to the log file, even after the Apply program is restarted.
y
The Apply program reuses the log file by deleting it and then re-creating it when the Apply program is restarted.

z/OS: The log file name does not contain the Db2 instance name: control_server.apply_qualifier.APP.log.

Linux, UNIX, Windows: The log file name contains the Db2 instance name: db2instance.control_server.apply_qualifier.APP.log.
logstdout=y/n Specifies where the Apply program directs the log file messages:
n (default)
The Apply program directs most log file messages to the log file only. Initialization messages go to both the log file and the standard output (STDOUT).
y
The Apply program directs log file messages to both the log file and the standard output (STDOUT).
loadxit=y/n Specifies whether the Apply program invokes ASNLOAD. ASNLOAD is an IBM®-supplied exit routine that uses the export and load utilities to refresh target tables.
n (default)
The Apply program does not invoke ASNLOAD. Instead, it performs a SELECT operation on the source table and inserts the rows into the target, which is costly because each insert is logged at the target.
y
The Apply program invokes ASNLOAD and for each subscription set member uses the option that you specify in the LOADX_TYPE column of the IBMSNAP_SUBS_MEMBR table.
inamsg=y/n Specifies whether the Apply program issues a message when the Apply program is inactive.
y (default)
The Apply program issues a message when inactive.
n
The Apply program does not issue a message when inactive.
notify=y/n Specifies whether the Apply program should invoke ASNDONE. ASNDONE is an exit routine that returns control to you when the Apply program finishes copying a subscription set.
n (default)
The Apply program does not invoke ASNDONE.
y
The Apply program invokes ASNDONE.
copyonce=y/n Specifies whether the Apply program executes one copy cycle for each subscription set that is eligible at the time the Apply program is invoked. Then the Apply program terminates. An eligible subscription set meets the following criteria:
  • (ACTIVATE > 0) in the IBMSNAP_SUBS_SET table. When the ACTIVATE column value is greater than zero, the subscription set is active indefinitely or is used for a one-time-only subscription processing.
  • (REFRESH_TYPE = R or B) or (REFRESH_TYPE = E and the specified event occurred). The REFRESH_TYPE column value is stored in the IBMSNAP_SUBS_SET table.

The MAX_SYNCH_MINUTES limit from the subscription sets table and the END_OF_PERIOD timestamp from the IBMSNAP_SUBS_EVENT table are honored if specified.

n (default)
The Apply program does not execute one copy cycle for each eligible subscription set.
y
The Apply program executes one copy cycle for each eligible subscription set.
sleep=y/n Specifies how the Apply program is to proceed if no new subscription sets are eligible for processing.
y (default)
The Apply program sleeps.
n
The Apply program stops.
trlreuse=y/n Specifies whether the Apply program empties the IBMSNAP_APPLYTRAIL table when the Apply program starts.
n (default)
The Apply program appends entries to the IBMSNAP_APPLYTRAIL table. The Apply program does not empty the table.
y
The Apply program empties the IBMSNAP_APPLYTRAIL table during program startup.
opt4one=y/n Specifies whether the performance of the Apply program is optimized if only one subscription set is defined for the Apply program.
n (default)
The performance of the Apply program is not optimized for one subscription set.
y
The performance of the Apply program is optimized for one subscription set. If you set optimization to y, the Apply program caches and reuses the information about the subscription-set members. This reuse of subscription-set member information reduces CPU usage and improves throughput rates.
delay=n Specifies the delay time (in seconds) at the end of each Apply cycle when continuous replication is used. Apply accepts values from 0 to the maximum integer value for this parameter. The default of 6 is used during continuous replication (that is, when the subscription set uses sleep=0 minutes). This parameter is ignored if you specify copyonce.
errwait=n Specifies the number of seconds (1 to 65535) that the Apply program waits before retrying after the program encounters an error condition. The default value is 300 seconds (five minutes).
Note: Do not specify too small a number, because the Apply program runs almost continuously and generates many rows in the IBMSNAP_APPLYTRAIL table.
term=y/n Specifies whether the Apply program continues to run if it cannot connect to its control server.
y (default)
By default, the Apply program terminates if it cannot connect to its control server.
n
The Apply program does not terminate. Instead, Apply logs an error, waits for the amount of time set by the errwait parameter, then retries the connection.

This parameter is ignored if copyonce is specified.
spillfile=filetype Specifies where the fetched answer set is stored.

On z/OS, valid values are:

mem (default)
A memory file. If there is insufficient memory for the answer set, the Apply program uses a disk file.
disk
A disk file.
hs
High-performance data space (hiperspace)

On Linux, UNIX, and Windows, valid values are:

disk (default)
A disk file.
arm=identifier

z/OS: Specifies a three-character alphanumeric string that is used to identify a single instance of the Apply program to the Automatic Restart Manager. The value that you supply is appended to the ARM element name that Apply generates for itself: ASNTAxxxxyyyy (where xxxx is the data-sharing group attach name, and yyyy is the Db2 member name). You can specify any length of string for the arm parameter, but the Apply program will concatenate only up to three characters to the current name. If necessary, the Apply program will pad the name with blanks to make a unique 16-byte name.
caf=n/y

z/OS: Specifies whether the Apply program runs with Recoverable Resource Manager Services (RRS) connect (caf=n). The runtime parameter Call Attach Facility (CAF) (caf=y) option specifies that the replication program overrides RRS connect and runs with CAF connect. The caf=n option is the default for the Apply program. If your z/OS Apply is connecting to any remote Linux, UNIX, or Windows source, you must specify caf=y or you will get SQL error -30090.

y
Apply runs with CAF connect.
n (default)
The Apply program uses RRS connect.
sqlerrcontinue=y/n Specifies whether the Apply program continues processing when it encounters certain SQL errors.

The Apply program checks the failing SQLSTATE against the values specified in the SQLSTATE file, which you create before running the Apply program. If a match is found, the Apply program writes the information about the failing row to an error file (apply_qualifier.ERR) and continues processing. The SQLSTATE file can contain up to 20 five-byte values.

n (default)
The Apply program does not check the SQLSTATE file.
y
The Apply program checks the SQLSTATE file during processing.
refresh_commit_cnt=n During full refresh, Apply issues a COMMIT statement after the specified number of rows are inserted into the target table. Values can range from 0 to 134217727. A default value of 0 means that only one commit is issued after all rows have been inserted; no intermediate commits are issued. This option is not supported for CCD sources.
tolerate_lsn_trunc=n Specifies whether the Apply program truncates 16-byte log sequence numbers (LSN) to 10 bytes before applying them to consistent-change data (CCD) targets. Apply uses 16-byte LSNs for source Capture programs at v10.2.1 and later. This parameter enables Apply to tolerate 10-byte LSN data while you migrate your CCD tables to the longer data length. If you start Apply with tolerate_lsn_trunc=y, Apply truncates the LSN data to 10 bytes before inserting it into the IBMSNAP_COMMITSEQ and IBMSNAP_INTENTSEQ columns of the CCD table. After all CCD target tables are modified to handle 16-byte LSNs, you can run Apply with tolerate_lsn_trunc=n.
Note: SQL Replication does not support 10-byte IBMSNAP_UOWID columns in CCD tables, so tolerate_lsn_trunc does not work for this column. You must alter the IBMSNAP_UOWID column to 12 bytes. If you cannot alter this column, you must change its column type in the ASN.IBMSNAP_SUBS_COLS table to C (computed column) and then use the substr() option to enable the truncation:
UPDATE ASN.IBMSNAP_SUBS_COLS SET COL_TYPE='C',
EXPRESSION='SUBSTR(IBMSNAP_UOWID,1,10)'
WHERE TARGET_NAME='IBMSNAP_UOWID';

Return codes

The asnapply command returns a zero return code upon successful completion. A nonzero return code is returned if the command is unsuccessful.

Examples for asnapply

The following examples illustrate how to use the asnapply command.

Example 1

To start an Apply program with an Apply qualifier named AQ1, a control server named dbx with work files located in the /home/files/apply/ directory: 

asnapply apply_qual=AQ1 control_server=dbx apply_path=/home/files/apply/ 
  pwdfile=pass1.txt
The Apply program searches the /home/files/apply/ directory for the password file named pass1.txt.

Example 2

To start an Apply program that invokes the ASNLOAD exit routine: 

asnapply apply_qual=AQ1 control_server=dbx pwdfile=pass1.txt loadxit=y
In this example, the Apply program searches the current directory for the password file named pass1.txt.

Example 3

To start an Apply program that executes one copy cycle for each eligible subscription set: 

asnapply apply_qual=AQ1 control_server=dbx apply_path=/home/files/apply/ 
  copyonce=y
In this example, the Apply program searches the /home/files/apply/ directory for the default password file named asnpwd.aut.