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 (ALCOPY, CLCOPY or PLCOPY for Audit Log, Command Log or Protection Log) of the ADARES utility.
User exit 12 is invoked
during Adabas nucleus startup if a multiple PLOG/CLOG/ALOG data set has to be copied;
whenever a switch to another log data set occurs;
at the end of a PLCOPY, CLCOPY or ALCOPY job if ADARES determines there are more copies needed;
during Adabas nucleus shutdown.
The user exit is provided with information about the type of log (PLOG, CLOG or ALOG) and the status of the multiple log data sets.
The user exit can decide which action is to be taken:
Ignore the call and allow Adabas to proceed;
Submit a job to copy and mark as empty the log data set just filled (ADARES utility);
Direct Adabas to wait for a specified interval, then call the user exit again with updated PLOG/CLOG/ALOG data set status information. During the wait interval, no commands that may produce log records for the log type being processed are allowed to proceed.
Note:
If automated CLOG merge is being used in a cluster environment,
it is critical that the exit 12 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.
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.
For more information regarding Standard MVS Calling Conventions and Return from User Exits please refer the respective sections in the Overview.
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:
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.
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 *
.* two or more PLOGs, CLOGs or ALOGs) *
.* *
.* 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
EX12ALOG EQU C'A' ALOG
*
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' Records include time stamp (PLOG)
* CLOG 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
| 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. |
Note:
Sample user exit routines are not supported under any maintenance contract
agreement.
Adabas is delivered with a sample user exit 12 routine. This routine is written in the Assembler language and performs the following functions:
Issues a message identifying the reason and the type of log, for which it was called.
Issues a message with the status and timestamp of all log data sets that are not empty.
If any log data set is full and the status of at least one log data set changed since the last time the exit was called, the exit reads 80-byte records from the input data set with DD-name COPYJOB and processes them either as a job to be submitted or a started task to be initiated.
If the first two characters in the first record are equal to "//", the exit processes the input as a job to be submitted (the model job). This is expected to be an ADARES PLCOPY, CLCOPY, or ALCOPY job.
If the first two characters in the first record are not equal to "//", the exit processes the input as an MVS operator command to be issued (the model command). This is expected to be a START command for an ADARES PLCOPY, CLCOPY or ALCOPY started task.
Replaces all occurrences of the character "?" with either "P", C", or "A", depending on whether the exit is invoked to process a PLOG, CLOG, or ALOG event, respectively. This allows a single input model to accommodate an event for any of the log types.
When the exit processes a job to be submitted, such as job control statements to be directed to a job execution queue:
If a record in the model job starts with the special stop mark "//*?", the exit:
replaces the stop mark with "//* ", in other words it changes the "?" to a blank.
stops copying further records to the output, when it is a PLOG or CLOG.
continues copying records and replacing "?" with "A", when the output is ALOG.
The exit writes the processed records to the output data set with DD-name INTRDR2 (normally, the JES internal reader).
When processing an MVS operator command to be issued, the exit:
Picks up the contents of the first record as the default command to be issued, independent of event type, replacing "?" with "P", "C" or "A".
Reads any subsequent record and – if it starts with "P:", "C:" or "A:" and the event type is PLOG, CLOG, or ALOG, respectively – picks up the contents of the record starting at the third column (directly following the ":"), again replacing "?" with "P", "C" or "A".
Issues the last record picked up as an MVS command. This requires Adabas to run APF-authorized (the standard for Adabas installations).
If at least one log data set is not full, it returns to the caller with R15 equal to zero. This allows Adabas to proceed.
If all log data sets are full, it returns to the caller with R15 nonzero. This directs Adabas to wait for the number of seconds in R15, then call the exit again with an updated status of all log data sets. The default wait time is 30 seconds.
Important:
This sample user exit routine submits a job or issues an MVS operator command
under the user ID and privileges given to the Adabas nucleus. It reads the job or
operator command from the data set or member specified in the Adabas JCL under DD-name
COPYJOB. This data set or member must be protected against unauthorized access, like the
APF-authorized load library used for Adabas must be protected. If a user can modify the
COPYJOB data set or member to induce Adabas to perform an action that the user is
unauthorized to perform, this can open the way to a privilege elevation
attack.
The sample user exit 12 routine is delivered as a source (member UEX12) and as a load module (member UX12SAMP) 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 for submitting ADARES PLCOPY, CLCOPY, or ALCOPY jobs, as well as a sample MVS command UX12SRPC to be customized for initiating ADARES PLCOPY, CLCOPY, or ALCOPY started tasks.
You can activate the sample user exit as follows:
Specify ADARUN parameter UEX12=UX12SAMP for the Adabas nucleus, in
addition to ADARUN NPLOG={2-8}, NCLOG={2-8}, and/or
NALOG={2-8}.
Under the DDNAME COPYJOB, supply the model job that you want the user exit to adjust and submit, or the model command that you want the user exit to adjust and issue.
If you want the sample user exit to submit jobs, provide the following DD statement:
//INTRDR2 DD SYSOUT=(*,INTRDR)
Note:
Both sample user exits 2 and 12 use this DD statement for submitting PLCOPY, CLCOPY,
or ALCOPY jobs.
Member UX12ZAP in the Adabas jobs library contains a sample IMASPZAP job for customizing certain aspects of the sample user exit 12 load module (UX12SAMP), such as the wait time if all log data sets are full, or the message ID for the messages it writes to the operator console.
The sample user exit 12 routine writes messages to the operator console, identified by message IDs. Refer to the UEX12* - Messages Written by the Sample User Exit 12 section in Messages and Codes for more information.