User Exit 2 (Dual Log Processing)

This user exit is given control by the Adabas nucleus during a switch from one dual log to the alternate dual log for the purpose of copying the log before it is reused by Adabas. This switch occurs only if dual data protection logging or dual command logging is in effect for the session.

For more information regarding Standard MVS Calling Conventions and Return from User Exits please refer the respective sections in the Overview.

Note:
UEX2 and UEX12 are mutually exclusive for an Adabas nucleus session: only one can be specified.

The user exit routine must invoke a procedure whereby the appropriate function of the ADARES utility (CLCOPY or PLCOPY) is executed.

User exit 2 is invoked:

  • during Adabas nucleus startup if a PLOG/CLOG has to be copied;

  • whenever a dual command or dual protection log switch occurs between two log data sets;

  • at the end of a PLCOPY or CLCOPY job if ADARES determines there are more copies needed;

  • during Adabas nucleus shutdown.

The user exit is provided with information about the status of the dual log data sets.

The user exit can decide which action is to be taken:

  • Ignore the call;

  • Submit a job to copy the log data set just filled up (ADARES utility);

  • Wait for completion of the copy job just submitted.

    Note:
    If automated CLOG merge is being used in a cluster environment, it is critical that the exit 2 is used in the suggested manner to copy the CLOGs in a timely fashion as illustrated in the sample exit. Invoking the CLCOPY process in a different manner can result in time stamp inconsistencies between the CLOG datasets in a cluster environment causing CLOG merge issues. The PLOG merge is always automatic and also requires that the PLOGs are copied in a timely manner.

If the data set to be overwritten contains data, console message ADAN46 Function not executable is issued.

An example of user exit 2 is supplied with the Adabas installation procedure. Refer to the Adabas Installation documentation for more information.

The call to the user exit is made using a standard BASR 14,15 Assembler instruction. All registers must be saved when control is received and restored immediately prior to returning control to Adabas. Register 15 contains an action code as described in Output Parameter.

This document covers the following topics:


User Exit 2 Calling Sequence

graphics/dual_log_flow.png

Dual Log Processing Flow

Input Parameters

graphics/dual_log_parms.png

Dual Log Processing User Exit (2) Parameters

The input parameters for the address list are as follows:

Parameter A fullword address of . . .
0 (R1) the C/PLOG indicators and flag ½.
4 (R1) the four-byte timer 1 field.
8 (R1) the four-byte timer 2 field.
12 (R1) the current session's PLOG number, followed by the database ID.
16 (R1) a four-byte area where the first two bytes contain the number of PLOG1, and the second two bytes hold the number of PLOG2.

Other input parameters are explained in the following table:

Parameter Usage
Flag 1 Status flags for DD/PLOGR1 and DD/CLOGR1; and
Flag 2
Status flags for DD/PLOGR2 and DD/CLOGR2:
B'1... ....' : Data set being written by nucleus
B'.1.. ....' : Data set has been completed by nucleus
B'.11. ....' : Being copied by ADARES
B’…. .1..’:

Records include time stamp (PLOG)

CLOG not merged (Cluster)

B'0000 0000' : Data set is empty (or copied) and reusable for the nucleus.
All other flag ½ field values are reserved. For DD/CLOGR1/2 only: X`08' for CLOGLAYOUT=5. Flag ½ bit settings can be combined (X`40' and X`20' as X`60', for example).
If OPENOUT is specified, these flags are set after OPEN is issued for the output data set; otherwise, the flags are set before the OPEN is issued.
Session Status
Contains information about the status of the nucleus when the exit was called:
X'S' Called during nucleus session startup.
X'T' Called while terminating the nucleus session.
X'W' Called following a dual protection log switch.
TIMERn Time-stamp (highest four bytes of a STCK instruction) for the time the first block of the log data set has been written. TIMER1 for DD/PLOGR1 and DD/CLOGR1, and TIMER2 for DD/PLOGR2 and DD/CLOGR2
PLOG Current session protection log number (two bytes). This value is set for PLOG only; the field contains X`00' for CLOG.
DBID Database ID (two bytes).
PLOG1/2 Two 2-byte PLOG numbers found on PLOG 1 and PLOG 2. If the previous nucleus session ended abnormally, these four bytes contain that session`s PLOGNUM value, which can be used in the initial user exit 2 call to copy that session's PLOG. During any subsequent session, these bytes contain the current PLOGNUM value. If the preceding session ends abnormally, these four bytes contain the ended session's PLOG numbers during the nucleus start phase. This PLOG information is needed during the start phase to assign the correct PLOG numbers to the PLOG areas to be copied. During subsequent exit calls, the current PLOG values are in these fields.

Output Parameter

Parameter Usage
R15 = 0 Nucleus continues processing.
R15 > 0 R15 is treated as the number of seconds to wait before calling user exit 2 again. During this time, the nucleus is in a "hard" wait. No commands are processed during the wait.