Version 8.2.5
 —  User, Hyperdescriptor, Collation Descriptor, and SMF Exits  —

User Exit 12 (Multiple Data Set Log Processing)

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

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

The user exit routine is designed to invoke a procedure that will execute the appropriate function (CLCOPY or PLCOPY) of the ADARES utility.

User exit 12 is invoked

The user exit is provided with information about the type of log (PLOG or CLOG) and the status of the multiple log data sets.

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

An example of user exit 12 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 BASSM R14,R15 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 the user exit 2 section Output Parameter.

Note:
User exit 12 must return the same AMODE value to the calling program that was active when user exit 12 was called. The recommended Assembler instruction to return is BSM 0,R14.

This document covers the following topics:


User Exit 12 Calling Sequence

graphics/multi_log_flow.png

Multiple Log Processing Flow

Top of page

User Exit Interface

Optionally, the user exit may initialize its operation. It may store any value in field EX12USER of the EX12PARM parameter block to keep track of its resources. This field is considered as "owned" by the user exit and is supplied again for all subsequent executions of the exit. It is set to zero when the exit is first called and is not modified by Adabas thereafter.

The user exit is called again during termination to do any necessary finishing or 'cleanup' work.

Parameters

graphics/ue12parms.png

User Exit 12 Parameters

DSECT of the EX12PARM Parameter Block

         MACRO
         EX12PARM
.**********************************************************************
.*                                                                    *
.* Name          Ex12Parm                                             *
.*                                                                    *
.* Component     ADABAS User Exit                                     *
.*                                                                    *
.* Function      Parameter list for User Exit 12                      *
.*               (replacement for User Exit 2 for use when there are  *
.*                more than 2 PLOGs or CLOGs)                         *
.*                                                                    *
.* Parameters    None                                                 *
.*                                                                    *
.* Restrictions  None                                                 *
.*                                                                    *
.* Notes         None                                                 *
.*                                                                    *
.**********************************************************************
.*
EX12PARM DSECT ,                   User Exit 12 Parameter List
*
EX12HDR  DS    0F                  Common header section
*
EX12USER DS    F                   Reserved for the user.  This field  +
                                   is initialized to zero before the   +
                                   exit is called the first time, and  +
                                   will not be altered by ADABAS after +
                                   that.  It can be used to maintain   +
                                   information across invocations.
*
EX12LOGT DS    X                   Log type
EX12PLOG EQU     C'P'                PLOG
EX12CLOG EQU     C'C'                CLOG
*
EX12TYPE DS    X                   Call type
EX12TBEG EQU     C'S'                Nucleus start
EX12TSW  EQU     C'W'                Log switch
EX12TEND EQU     C'T'                Nucleus termination
EX12TFRC EQU     C'F'                Forced switch
         DS    XL2                 Reserved
*
EX12NLOG DS    F                   Number of logs
EX12DBID DS    F                   Database ID
EX12NUCI DS    F                   Nucleus ID
*
EX12PLGN DS    F                   Current session PLOG number         +
                                     (zero for CLOGs)
EX12NCMP DS    F                   Log just completed                  +
                                     (zero during initialization and   +
                                      for forced CLOG switch)
EX12STAT DS    X                   Flags of next log in sequence
EX12WNUC EQU     X'80'               Being written by the nucleus
EX12FULL EQU     X'40'               Completed by the nucleus
EX12RES  EQU     X'20'               Being copied by ADARES
EX12CL5  EQU     X'08'               CLOGLAYOUT=5
EX12NMRG EQU     X'04'               Log not merged (cluster)
EX12PMRG EQU     X'02'               Log partially merged (cluster)
EX12UNUS EQU     X'00'               Unused and/or copied
         DS    XL3                 Reserved
         DS    4F                  Reserved
*
EX12HDRL EQU   *-EX12HDR           Length of header section
*
EX12ENT  DSECT ,
EX12LOG  DS    0F                  Start of individual log dataset     +
                                   entries.  This section is repeated  +
                                   for the number of logs specified in +
                                   field EX12NLOG
*
EX12LTIM DS    XL8                 Time stamp of write to log dataset
EX12LNUM DS    F                   Number of log dataset
EX12LFLG DS    X                   Flags (mapped as in EX12STAT)
         DS    XL3                 Reserved
         DS    4F                  Reserved
*
EX12LOGL EQU   *-EX12LOG           Length of a log dataset entry
*
*
         MEND

Top of page

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 12 again with updated status for all log data sets. During this time, no commands that may create log entries are processed.

Top of page

Activating the Sample User Exit

The sample user exit is written in Assembler language. It performs the following functions:

Activating in z/OS

The sample user exit UX12SAMP is delivered on z/OS as source and as a load module that can be used without change or reassembly.

The source and load forms of the user exit are delivered in the Adabas source and load libraries, respectively. The job to assemble the user exit UX12ASML is located in the Adabas jobs library. The jobs library also contains a sample job UX12CJOB to be customized and submitted by the user exit that invokes the ADARES utility PLCOPY or CLCOPY function.

Activate the sample user exit as follows:

  1. In addition to ADARUN NxLOG={2-8}, specify ADARUN UEX12=UX12SAMP for the Adabas nucleus.

  2. Supply the job control model that the user exit is supposed to submit under the DDNAME COPYJOB.

Provide the following DD statement:

//INTRDR2  DD  SYSOUT=(*,INTRDR)

Note:
The same DD statement is used by the sample user exit 2 or 12 for submitting PLCOPY or CLCOPY jobs.

Activating in z/VSE

The sample user exit UX12SAMP is delivered on z/VSE as source and as a phase that can be used without change or reassembly.

The source A.book and phase are delivered in the Adabas z/VSE sublibrary. The job to assemble the user exit UX12ASML.X is also provided in the Adabas sublibrary. The sample job UX12CJOB.X is to be customized and submitted by the user exit that invokes the ADARES utility PLCOPY or CLCOPY function.

Activate the sample user exit as follows:

  1. In addition to ADARUN NxLOG={2-8}, specify ADARUN UEX12=UX12SAMP for the Adabas nucleus.

  2. Supply the job control model that the user exit is supposed to submit under the DLBL COPYJOB.

Activating in BS2000

The sample user exit UEX12 is delivered on BS2000 as source and can be assembled using the sample job ASMBS2.as an object module that can be used without change or reassembly.

To activate the sample user exit:

  1. In addition to ADARUN NxLOG={2-8}, specify ADARUN UEX12=UEX12 for the Adabas nucleus.

  2. Use one of the following methods to set up the Adabas nucleus job appropriately:

Method 1 - With Job Variables

If the machine can process job variables, place the following statement in the Adabas nucleus job:

/DEL-JV ENTER.ADARES.xLCOPY                                 
/SET-JOB-STEP                                     
/CRE-JV ENTER.ADABAS.xLCOPY                                 
/SET-JV-LINK *DDJBx12,ENTER.ADABAS.xLCOPY                   
/MOD-JV LINK(*DDJBx12),-                          
/  SET-VAL='ENT-PROC (srclib,ux12cjbx,DB=dbid,J-N=X12COPY'

or, in ISP format:

/DCLJV   ENTER.ADARES.xLCOPY,LINK=*DDJBx12
/SETJV *DDJBx12,C'ENTER-PROC(srclib,ux12cjbx),(DB=dbid),J-N=X12COPY'
x is either "P" for a PLCOPY job or "C", for a CLCOPY job
srclib is the library where the UX12CJBx is stored
ux12cjbx is the element name of the respective procedure job.
dbid is the database ID of this nucleus.

Method 2 - Without Job Variables

If the machine cannot process job variables, place the following statement in the Adabas nucleus job:

ENTER-PROC (ADABAS.SRC,UX12CJBx),(DBID=dbid),J-N=X12xCOPY

Be sure to set x to "P" for a PLCOPY job or "C" for a CLCOPY job. Also set dbid to the calling DBID (UX12CJBC and UX12CJBP examples can be taken from the ADARESCC and ADARESCP examples respectively).

Top of page