INIT request

The INIT PAPL also contains some parameters needed to initialize the DRA. If the same parameter appears in both the INIT PAPL and in the DRA startup parameter table, the specification in the INIT PAPL will override that in the startup table.

In addition to the required parameters of INIT PAPL, the optional parameters include:

Field

Contents

PAPLFUNC

PAPLINIT

PAPLSUSP

The address of the Suspend exit routine

PAPLRESM

The address of the Resume exit routine

PAPLTECB

To use the default Suspend exit routine and Resume exit routine, each DRA request must have the field PAPLTECB set with the address of a CCTL ECB to be used if the thread is waited or posted. If your CCTL does not provide Suspend and Resume exit routines, the DRA default exit routines will be used.

PAPLCNTL

The address of the Control exit routine

PAPLTSTX

The address of the Status exit routine

After the INIT request and the startup table have been processed, the DRA returns the following data to the CCTL in the INIT PAPL:

Field

Contents

PAPLDBCT

The IMS DB identifier (this is the IMSID parameter from system definition)

PAPLCTOK

The request token that identifies the CCTL to the DRA

PAPLTIMO

DRA TERM request timeout value (in seconds)

PAPLRETC

A code returned to the CCTL specifying the status of the request

PAPLDLEV

A flag indicating to CCTL which functions the DRA supports. (For the latest version of PAPL mapping format see the IMS. library; member name is DFSPAPL.)

INIT request, identify to DBCTL

To make the DRA functional, the DRA must identify itself to IMS DB, thus establishing a link between IMS DB and the CCTL. The identify process occurs in two cases:

• As a direct result of an INIT request.
• As part of a terminate/reidentify request from a Control exit routine invocation.

The DRA identifies itself to the IMS DB subsystem specified in the final DRA startup parameters. The identify process executes asynchronously to the INIT process. Therefore, it is possible for the INIT request to complete successfully while the identify process fails. In this case, the Control exit routine notifies the CCTL that the connection to IMS DB failed.

If IMS DB is not active, the console operator will receive a DFS690 message (a code of 0 was returned in the PAPLRETC field). You must reply with either a CANCEL or WAIT response. If you reply with WAIT, the DRA waits for a specified time interval before attempting to identify again. The waiting period is necessary because the identify process will not succeed until the DBCTL restart process is complete. You specify the length of the waiting period on the TIMER DRA startup parameter. If subsequent attempts to identify fail, the console operator will receive message DFS691, WAITING FOR IMS DB.

If the DRA cannot identify to IMS DB because the subsystem does not reach a restart complete state, there are two ways to terminate the identify process:

• The Control exit routine is called with each identify failure. This sets a PAPL return code of 4 or 8, terminating the identify process.
• The CCTL can issue a TERM request.

If you reply with CANCEL to message DFS690, control is passed to the Control exit routine, and the DRA acts upon the routine's decision.

After the identify process successfully completes, the DRA makes the CCTL address space non-swappable and calls the Control exit routine with a list of in-doubt UORs. If no in-doubt UORs exist, a null list is passed. The CCTL can use the RESYNC request to resolve any in-doubt UORs that do exist.

The INIT request attempts to create the MINTHRD number of thread TCBs. The actual number of TCBs created might be less than this value due to storage constraints.

INIT request after a previous DRA session termination

If a prior DRA session ended with a TERM request that received a PAPL return code=0, this INIT request must specify PAPLCTOK=0. If PAPLCTOK other than 0 is sent, the INIT request fails.

The INIT request must pass the PAPLCTOK value of the prior session in the current PAPLCTOK field if a DRA session ended because of:

• A nonzero return code from a TERM request.
• An internal TERM request from a Control exit routine request.
• A DRA failure.

INIT request to use the DRA open thread TCB option

The DRA open thread TCB allows the CCTL to direct the DRA not to attach dedicated DRA thread TCBs. Instead, DRA thread requests are processed on the CCTL application TCB.

The DRA open thread TCB option is either in use or not in use for the duration of the DRA instance.

To request activation of the DRA open thread TCB, set the following fields for the INIT request:

PALPFNCL

3 (PAPLFNC3)

PAPLOOTT

Set this bit (X’08’) to activate the open thread TCB.

You can verify that the TCB open thread is in use for the DRA by examining the PAPLDLEV flag field in the CCTL in INIT PAPL that the DRA returns after the INIT call. If the PAPLOTCB (X’08’) flag is set to 1, the open thread TCB option is in use.

INIT request to use the DRA open thread TCB option

When DRA open thread support processing is enabled, the DRA will or will not monitor and report the CPU time usage statistics that are related to the DRA thread processing based on the value specified for TIMETHREADCPU= on the DFSPRP macro in DFSPZPxx member.

If anything other that TIMETHREADCPU=CLIENT is specified in the DFSPZPxx member, the DRA ignores what is specified on the INIT call.

To request the DRA not to monitor CPU time usage statistics, set the following fields for the INIT request:

PALPFNCL

3 (PAPLFNC3)

PAPLOTCN

Set this bit (X'20') in field PAPLDROP to disable DRA thread CPU time usage statistics monitoring.

To determine if CPU usage statistics are being monitored for DRA thread processing, check the PAPLDLEV flag field in the CCTL INIT PAPL that the DRA returns after the INIT call. CPU usage statistics is not being monitored and reported if the PAPLOTCF (x'40') flag is set to 1.

INIT request to notify the DRA that CCTL is using Sync Continue behavior