STRDPRAPY: Starting Apply (System i)

Use the Start DPR Apply (STRDPRAPY) command to start an Apply program on your local system. The Apply program continues to run until you stop it or until it detects an unrecoverable error.

After you type the command name on the command line, you can press the F4 key to display the command syntax.

To display a complete description of this command and all of its parameters, move the cursor to the command at the top of the screen and press the F1 key. To display a description of a specific parameter, place the cursor on that parameter and press the F1 key.


>>-STRDPRAPY--+-------------------------+----------------------->
              |        .-*CURRENT--.    |   
              '-USER(--+-*JOBD-----+--)-'   
                       '-user-name-'        

>--+-------------------------------------------------+---------->
   |        .-*LIBL/QZSNDPR---------------------.    |   
   '-JOBD(--+-library-name/job-description-name-+--)-'   

>--+----------------------------------+------------------------->
   |           .-*USER-----------.    |   
   '-APYQUAL(--+-apply-qualifier-+--)-'   

>--+--------------------------+--+------------------------+----->
   |          .-*LOCAL---.    |  |         .-*NONE---.    |   
   '-CTLSVR(--+-rdb-name-+--)-'  '-TRACE(--+-*ERROR--+--)-'   
                                           +-*ALL----+        
                                           +-*PRF----+        
                                           '-*REWORK-'        

>--+-----------------------------------------------+------------>
   |              .-*NONE---------------------.    |   
   '-FULLREFPGM(--+-library-name/program-name-+--)-'   

>--+----------------------------------------------+------------->
   |             .-*NONE---------------------.    |   
   '-SUBNFYPGM(--+-library-name/program-name-+--)-'   

>--+------------------------+--+------------------------+------->
   |            .-*YES-.    |  |            .-*YES-.    |   
   '-INACTMSG(--+-*NO--+--)-'  '-ALWINACT(--+-*NO--+--)-'   

>--+---------------------------+-------------------------------->
   |         .-6----------.    |   
   '-DELAY(--+-delay-time-+--)-'   

>--+----------------------------------+------------------------->
   |           .-300-------------.    |   
   '-RTYWAIT(--+-retry-wait-time-+--)-'   

>--+------------------------+--+------------------------+------->
   |            .-*NO--.    |  |            .-*NO--.    |   
   '-COPYONCE(--+-*YES-+--)-'  '-TRLREUSE(--+-*YES-+--)-'   

>--+-------------------------+---------------------------------><
   |             .-*NO--.    |   
   '-OPTSNGSET(--+-*YES-+--)-'

Table 1 lists the invocation parameters.

Table 1. STRDPRAPY command parameter definitions for System i
Parameter	Definition and prompts
USER	Specifies the name of the user ID for which to start the Apply program. When you run this command, you must be authorized (have USE rights) to the specified user profile; the Apply program runs under this specified user profile. The control tables are located on the relational database specified by the CTLSVR parameter. The same control tables are used regardless of the value specified on the USER parameter. CURRENT (default) The user ID associated with the current job is the same user ID associated with this Apply program. JOBD The user ID specified in the job description associated with this Apply program. The job description cannot specify USER(RQD). user-name The user ID associated with this Apply program. The following IBM-supplied objects are not valid on this parameter: QDBSHR, QDFTOWN, QDOC, QLPAUTO, QLPINSTALL, QRJE, QSECOFR, QSPL, QSYS, or QTSTRQS. When prompting on the STRDPRAPY command, you can press the F4 key to see a list of users who defined subscription sets.
JOBD	Specifies the name of the job description to use when submitting the Apply program. *LIBL/QZSNDPR (default) The default job description provided with DB2® DataPropagator for System i®. library-name/job-description-name The name of the job description used for the Apply program.
APYQUAL	Specifies the Apply qualifier to be used by the Apply program. All subscriptions sets that are grouped together with this Apply qualifier are run by the Apply program. USER (default) The USER parameter value that you enter is used as the name of the Apply qualifier. apply-qualifier* The name used to group the subscription sets that are to be run by this Apply program. You can specify a maximum of 18 characters for the Apply qualifier name. This name follows the same naming conventions as a relational database name. When prompting on the STRDPRAPY command, you can press the F4 key to see a list of Apply qualifier names with existing subscription sets.
CTLSVR	Specifies the relational database name of the system that contains the Apply control tables. *LOCAL (default) The Apply control tables reside locally (on the machine where you are running the STRDPRAPY command). rdb-name The name of the relational database where the Apply control tables reside. You can use the Work with RDB Directory Entries (WRKRDBDIRE) command to find this name. When prompting on the STRDPRAPY command, you can press the F4 key to see a list of available RDB names.
TRACE	Specifies whether the Apply program should generate a trace. The Apply program writes the trace data to a spool file called QPZSNATRC. NONE (default) No trace is generated. ERROR The trace contains error information only. ALL The trace contains error and execution flow information. PRF The trace contains information that can be used to analyze performance at different stages of the Apply program execution. *REWORK The trace contains information about rows that were reworked by the Apply program.
FULLREFPGM	Specifies whether the Apply program is to invoke an exit routine to initialize a target table. When the Apply program is ready to perform a full refresh of a target table, the Apply program invokes the specified exit routine rather than performing the full refresh itself. When a full-refresh exit routine is used by the Apply program, the value of the ASNLOAD column in the IBMSNAP_APPLYTRAIL table is Y. *NONE (default) A full-refresh exit routine is not used. library-name/program-name The qualified name of the program that is called by the Apply program performing a full refresh of a target table. For example, to call program ASNLOAD in library DATAPROP, the qualified name is DATAPROP/ASNLOAD.
SUBNFYPGM	Specifies whether the Apply program is to invoke an exit routine when the program finishes processing a subscription set. Input to the exit routine includes the subscription set name, Apply qualifier, completion status, and statistics with the number of rejects. The notify program allows you to examine the unit-of-work (UOW) table to determine when transactions have been rejected and when to take further actions, such as issuing a message or generating an event. *NONE (default) An exit routine is not used. library-name/program-name The qualified name of the exit routine program called by the Apply program when processing a subscription set. For example, to call program APPLYDONE in library DATAPROP, the qualified name is DATAPROP/APPLYDONE.
INACTMSG	Specifies whether the Apply program is to generate a message whenever the program completes its work and becomes inactive for a period of time. YES (default) The Apply program generates message ASN1044 before beginning a period of inactivity. Message ASN1044 indicates how long the Apply program remains inactive. NO No message is generated.
ALWINACT	Specifies whether the Apply program can run in an inactive (sleep) state. YES (default) The Apply program sleeps if there is nothing to process. NO If the Apply program has nothing to process, the job that submitted and started the Apply program ends.
DELAY	Specifies the delay time (in seconds) at the end of each Apply program cycle when continuous replication is used. 6 (default) The delay time is six seconds. delay-time The delay time, entered as a number between 0 and 6 inclusive.
RTYWAIT	Specifies how long (in seconds) the Apply program is to wait after it encounters an error before it retries the operation that failed. 300 (default) The retry wait time is 300 seconds (five minutes). retry-wait-time The wait time, entered as a number between 0 and 35000000 inclusive, before the Apply program retries the failed operation.
COPYONCE	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 IBMSNAP_SUBS_SET table and the END_OF_PERIOD timestamp from the IBMSNAP_SUBS_EVENT table are honored if specified. NO (default) The Apply program does not execute one copy cycle for each eligible subscription set. YES The Apply program executes one copy cycle for each eligible subscription set and then terminates.
TRLREUSE	Specifies whether the Apply program empties the IBMSNAP_APPLYTRAIL table when the Apply program starts. NO (default) The Apply program does not empty the IBMSNAP_APPLYTRAIL table during program startup. YES The Apply program empties the IBMSNAP_APPLYTRAIL table during program startup.
OPTSNGSET	Specifies whether the performance of the Apply program is optimized if only one subscription set is processed. This parameter does not pertain to replica target tables. If you set this parameter to YES, the Apply program fetches the members and columns of a subscription set only once and reuses this fetched information when processing the same subscription set in two or more consecutive processing cycles. NO (default) The performance of the Apply program is not optimized if only one subscription set is processed. *YES The performance of the Apply program is optimized if only one subscription set is processed. The Apply program reuses the subscription set information during subsequent processing cycles, requiring fewer CPU resources and improving throughput rates.

Usage notes

You can set up the system to start the subsystem automatically by adding the command that is referred to in the QSTRUPPGM value on your system. If you use the QDP4/QZSNDPR subsystem, it is started as part of the STRDPRAPY command processing.

If the relational database (RDB) specified by the CTLSVR parameter is a DB2 for i5/OS™ database, the tables on the server are found in the ASN library. If the RDB is not a DB2 for i5/OS database, you can access the tables by using ASN as the qualifier.

Error conditions when starting the Apply program

The STRDPRAPY command issues an error message if any of the following conditions occur:

If the user does not exist.
If the user running the command is not authorized to the user profile specified on the command or the job description.
If an instance of the Apply program is already active on the local system for this combination of Apply qualifier and control server.
If the RDB name specified by the CTLSVR parameter is not in the relational database directory.
If the control tables do not exist on the RDB specified by the CTLSVR parameter.
If no subscription sets are defined for the Apply qualifier specified by the APYQUAL parameter.

An Apply program must be started for each unique Apply qualifier in every IBMSNAP_SUBS_SET table. You can start multiple Apply programs by specifying a different Apply qualifier each time that you issue the STRDPRAPY command. These Apply programs will run under the same user profile.

Identifying Apply program jobs

Each Apply program is identified by using both the Apply qualifier and the control server names. When run, the job started for the Apply program does not have sufficient external attributes to correctly identify which Apply program is associated with a particular Apply qualifier and control server combination. Therefore, the job is identified in the following way:

The job is started under the user profile associated with the USER parameter.
The first 10 characters of the Apply qualifier are truncated and become the job name.
DB2 DataPropagator for System i maintains an IBMSNAP_APPLY_JOB table named in the ASN library on the local system. The table maps the Apply qualifier and control server values to the correct Apply program job.
You can view the job log. The Apply qualifier and control server names are used in the call to the Apply program.

In general, you can identify the correct Apply program job by looking at the list of jobs running in the QZSNDPR subsystem if both:

The first 10 characters of the Apply qualifier name are unique.
The Apply program is started for the local control server only.

Examples for STRDPRAPY

The following examples illustrate how to use the STRDPRAPY command.

Example 1:

To start the Apply program that uses the AQHR Apply qualifier and Apply control tables that reside locally and to generate a trace file that contains error and execution flow information:

STRDPRAPY APYQUAL(AQHR) CTLSVR(*LOCAL) TRACE(*ALL)

Example 2:

To start an Apply program with Apply control tables that reside locally and to specify that the job that started this Apply program automatically end when the Apply program has nothing left to process:

STRDPRAPY APYQUAL(AQHR) CTLSVR(*LOCAL) ALWINACT(*NO)

Example 3:

To start an Apply program that empties the IBMSNAP_APPLYTRAIL table during program startup:

STRDPRAPY APYQUAL(AQHR) CTLSVR(*LOCAL) TRLREUSE(*YES)

Example 4:

To start an Apply program with all default values:

STRDPRAPY