Log Archive utility (DFSUARC0)

You can use the Log Archive utility (DFSUARC0) to produce an SLDS from a filled OLDS or a batch IMS SLDS.

IMS DB writes log records on an SLDS that can be on tape or DASD. This allows an IMS batch user to log to DASD, create an SLDS, and later copy that SLDS to DASD or tape.

The Log Archive utility provides the following optional functions. You must specify these functions with utility control statements.

Creating an RLDS (recovery log data set)

You can request creation of an output data set containing all the log records needed for DB recovery. The output data set is referred to as a recovery log data set (RLDS). If the input data set contains records for DB recovery, the RLDS is known to DBRC and is used in place of the SLDS by GENJCL when creating JCL for DB recovery and change accumulation. If the input data set contains no records needed for DB recovery, the RLDS is a null data set. In this case DBRC records the data set name and volume serial number of the SLDS, in place of the RLDS DSNAME and volume serial number, and then uses the SLDS for GENJCL instead of the null RLDS.

Omitting log records on an SLDS

Generally, the SLDS should contain all the log records from the OLDS, but if you need to omit some types of log records from the SLDS, these log records must be specified in an SLDS control statement, using the NOLOG parameter. The SLDS must contain those records that might be needed for database recovery and IMS restart. The Log Archive utility will issue an error message and terminate if a required record type is specified to be omitted.

Copying log records into user data sets
The Log Archive utility can copy selected log records into multiple user data sets directly. In SYSIN control statements, you can specify the log records to be selected and the ddname of the data set to which the records are to be written.
Specifying user exit routines
You can specify multiple user exit routines for the archive utility. The Log Archive utility passes control to each user exit routine at initialization, input log read, and termination time. User exit routines can process the log records or create a data set.
Specifying forced end of volume (EOV)
To ensure that corresponding volumes in a dual SLDS on tape contain the same records (and consequently are interchangeable), the number of blocks to be written on a volume can be specified. EOV will be forced to both SLDSs when the specified number of log blocks have been written.

Subsections:

Restrictions

Currently, no restrictions are documented for the DFSUARC0 utility.

Prerequisites

Currently, no prerequisites are documented for the DFSUARC0 utility.

Requirements

Currently, no requirements are documented for the DFSUARC0 utility.

Recommendations

Currently, no recommendations are documented for the DFSUARC0 utility.

Input and output

The Log Archive utility has two types of input: OLDSs and SLDSs. The utility accepts only log data sets that are created by the same release of IMS as the utility release level.

OLDS input

The OLDS used for input must have been successfully closed. The status in RECON for the input OLDS must be 'ARCHIVE NEEDED'.

An error in a single OLDS causes the archive job to terminate. Run the Log Recovery utility to recover the OLDS, and rerun the Log Archive utility.

If dual OLDSs were used during IMS online execution, both are used as input to the Log Archive utility. If an error is encountered in the primary OLDS, the archive utility switches to the secondary OLDS. If the record is found in the secondary OLDS, the archive job continues. If an error is encountered in the same block, the archive job terminates. Run the Log Recovery utility to recover the OLDS, and rerun the Log Archive utility. If one dual OLDS is not available, for example the status is not 'ARCHIVE NEEDED', only the available OLDS is used as input. The unavailable OLDS is ignored.

If dual OLDSs are used as input and an error exists in the first block of the primary OLDS, the Log Archive utility terminates unsuccessfully. Sequence errors are indicated on the first block of both OLDSs, even though the secondary OLDS might be correct. The Log Archive utility uses the first block of the primary OLDS as an anchoring point. If this block is in error, data collected from it cannot be verified by comparison to the secondary OLDS. If errors exist on the first block of either OLDS, run the Log Recovery utility to recover the OLDS, then rerun the Log Archive utility.

If multiple OLDSs are specified as the input OLDS, they must have been created consecutively. OLDSs created by different IMS system executions cannot be input at one time.

If any OLDS in the input was terminated at a recovery point (a recovery point results at every /DBRECOVERY and /DBDUMP command that forces an OLDS switch), the archive utility performs as follows:

  • If at least one of the SLDSs and RLDSs is placed on DASD, the output data sets are closed and the archive job terminates after processing any OLDS that terminates at a recovery point. Remaining OLDS that might not have been processed are still in a state of ARCHIVE NEEDED.
  • If all SLDSs and RLDSs are placed on tape, IMS forces end of volume for all SLDSs and RLDSs and the archive job continues using the next volume for the SLDS and RLDS.

DBRC verifies the input OLDS. If there is an error in the OLDS specifications, the Log Archive utility terminates with an error message.

SLDS input

The single SLDS used for input is the SLDS on DASD created in an IMS batch environment. Also, this SLDS must have closed successfully. When DBRC=NO is specified in the EXEC parameter, tape SLDS input is permitted. You can use the SLDS of a previous archive and archive it again; however, this is not an intended use.

Dual SLDSs can be used as input. If an error is encountered in the primary SLDS, the Log Archive utility switches to the secondary SLDS. If the record is found on the secondary SLDS, the archive job continues. An error in a single SLDS or errors in the same block in dual SLDSs terminates the archive job. Run the Log Recovery utility to recover the SLDS and rerun the Log Archive utility.

When the input is from a DASD SLDS created with DBRC present, the Log Archive utility will notify DBRC to update the existing SLDS record with the new SLDS information. You must create the JCL for the archive job of a batch SLDS.

Output

In addition to the SLDS, the optional RLDS, and the user data set produced as output, the Log Archive utility also produces a listing in SYSPRINT. SYSPRINT contains the following:

  • A listing of control statements
  • A listing of checkpoint time stamp IDs
  • A listing of descriptive messages
  • A listing of the result of the archive

The following figure is an example of a SYSPRINT listing of control statements.

********LOG ARCHIVE UTILITY CONTROL STATEMENT********
SLDS -
   NOLOG(10,16,5F,67,69) FEOV(08000)
COPY  DDNOUT1(DATASET1) -
  RECORD(OFFSET(5) FLDTYP(X) VALUE(16) FLDLEN(1) COND(E)) -
  RECORD(OFFSET(5) FLDTYP(X) VALUE(50) FLDLEN(1) COND(E)) -
  RECORD(OFFSET(5) FLDTYP(X) VALUE(51) FLDLEN(1) COND(E)) -
  RECORD(OFFSET(5) FLDTYP(X) VALUE(52) FLDLEN(1) COND(E))
EXIT  NAME(UEXIT01)

The following figure is an example of a listing of checkpoint time stamp IDs.

  USER CHECKPOINT RECORD - yyyy.ddd hh:mm:ss.t CHKPT-id region-id prg-name (v1)(v2)
SYSTEM CHECKPOINT RECORD - yyyy.ddd hh:mm:ss.t chkpt-id (v1)(v2) CHECKPOINT XXX  (RESTART TTT)

When checkpoint log records (X'18' and X'4001') are found, the SYSPRINT listing prints one of the preceding output lines. Date, time, and checkpoint ID are shown for both. Region-ID and program name are for X'18' records; checkpoint request type is for X'4001' records, where XXX is the type of checkpoint requested in English. Also shown is the volume serial of the output primary SLDS volume (v1) and, if dual output, the secondary SLDS volume (v2) to which the checkpoint is copied. Restart type is also given for the first X'4001' record where TTT is the type of restart performed in English.

The following figure is an example of a SYSPRINT listing of descriptive messages.

*** END OF VOLUME FORCED ON SLDS. PRIMARY(volser) SECONDARY(volser) ***
*** WRITE ERROR ON SLDS|USER|RLDS ddname ***
*** OUT-OF-SPACE on SLDS|USER|RLDS ddname ***
*** NO RECORD FOUND FOR SLDS|USER|RLDS ddname ***

The following figure shows an example of a SYSPRINT listing of the result of the archive.

*** LOG ARCHIVE UTILITY (DFSUARC0)                **hh:mm yy.ddd **
       COPIED LOG RECORDS
 
FROM     DDNAME=ddname VOLSER=volser          DDNAME=ddname VOLSER=volser
           (for primary input)                    (for secondary input)
                .
                .       .
TO PRIMARY SLDS DSNAME=dsname
    VOLSER =   volser  volser  volser .............
TO SECONDARY SLDS DSNAME=dsname
    VOLSER =   volser  volser  volser .............
 
SLDS DOES NOT CONTAIN THE FOLLOWING LOG RECORDS:
  'xx' 'xx' 'xx' 'xx' ......
 
TO PRIMARY RLDS   DSNAME=dsname
     VOLSER =   volser  volser  volser .............
TO SECONDARY RLDS DSNAME=dsname
     VOLSER =   volser  volser  volser .............

JCL specifications

The Log Archive utility runs as a z/OS® batch job, and multiple log archive utility jobs can execute concurrently. A job statement, an EXEC statement, and DD statements that define input and output are required. When dual output is requested, the SLDS consists of primary and secondary data sets.

EXEC statement

Defines the utility to be run and optional execution parameters. Its format is: 

//STEP EXEC PGM=DFSUARC0
            PARM= 'nnnn, DBRC=nnn, IMSPLEX=imsplex_name, DBRCGRP=xxx'
PARM=
Indicates the subsystem identifier and whether DBRC is specified.
nnnn
Indicates a 1- to 4-character IMS subsystem identifier and must be specified if the input data set is an OLDS. This is the same value as the IMSID for the online IMS system that created the data in the OLDS.
DBRC=YES|NO
DBRC=NO (or N) can be specified to explicitly declare that DBRC is not to be used for this execution of this utility.

DBRC=YES (or Y) can be specified to explicitly declare that DBRC is to be used for the execution of this utility.

If DBRC= is not specified, YES is the default.

IMSPLEX=imsplex_name
Indicates which IMSplex DBRC should join. IMSPLEX= is an optional parameter.
DBRCGRP=xxx
Specifies the DBRC group ID defined in the RECON data set used by the DBRC group.

DD statements

STEPLIB DD
Points to the program libraries that contains the Log Archive program and to any user exit routines.
DFSOLPnn DD (for primary OLDS)
DFSOLSnn DD (for secondary OLDS)
Describes the OLDS used for input. You can specify dual OLDSs. In the case of dual OLDSs, the suffixes of the primary and secondary OLDS must match. The value of nn (the suffix) is 00 through 99 and must be the same ddname that was used when the log data was created by online execution. All OLDSs used as input must have been used consecutively during an online execution.

If DBRC=Y, the OLDS DD statements can be specified in any sequence in the DD statements.

If DBRC=N, the OLDS DD statements must be specified in the sequence they were created, and dual OLDS must be specified as a sequence of primary and secondary pairs.

You can specify between 2 and 99 read buffers for the DCB BUFNO keyword.

DFSSLDSP DD (for primary input SLDS)
DFSSLDSS DD (for secondary input SLDS)
Specifies the batch SLDS. Optionally, you can specify a dual SLDS for a batch SLDS. A SLDS and an OLDS used for input are mutually exclusive. You can specify 2 through 99 read buffers.
DFSSLOGP DD (for primary output SLDS)
DFSSLOGS DD (for secondary output SLDS)
Defines the SLDS used for output. Its format will depend on the device type used. If the SLDS is on DASD, you must allocate sufficient space to contain the log being archived. The SLDS block size can be specified and can be different from the input data set block size. If not specified, the block size of the input data set is used. The secondary SLDS is optional and specifies dual archiving. If the input is a batch SLDS and the Log Archive utility is run with DBRC present, dual output can be created only if dual SLDS records are already known to DBRC.

If dual SLDSs are being created, they can have different block sizes. However, if FEOV is specified, it is ignored unless the block size of both data sets are equal and both are allocated to tape. If tape is specified, it must have a standard label. You can specify 2 through 99 write buffers.

Restriction: Do not use the JCL parameter FREE=CLOSE on these DD statements. The data sets are dynamically deallocated, and using FREE=CLOSE can produce unpredictable results.
ddname DD (for either RLDS or user output data set, or both)
Defines either a user data set or recovery log data set (RLDS) or both. If the data set is on DASD, you must allocate sufficient space to contain the records being copied to it. The data set is created with RECFM=VB. The block size can be specified and can be different from the block size of the input data set, but it must be large enough to contain your longest record. If not specified, the block size of the input data set is used. If dual data sets are being created, they can have different block sizes. You can specify 2 through 99 write buffers.
SYSPRINT
Defines the output message data set.
SYSUDUMP
Defines the dump data set.
SYSIN DD
Specifies the control statements.
RECON1 DD
Defines the first DBRC (Database Recovery Control) RECON data set. This RECON1 data set must be the same RECON1 data set used by the IMS control region.
RECON2 DD
Defines the second DBRC RECON data set. This RECON2 data set must be the same RECON2 data set used by the IMS control region.
RECON3 DD
Defines the optional DBRC RECON data set used when an error is encountered in RECON1 or RECON2. This RECON3 data set must be the same RECON3 data set used by the IMS control region.

Do not use these RECON data set ddnames if you are using dynamic allocation.

Utility control statements

All control statements are optional. Use the control statements when:

  • Using user exit routines
  • Creating an RLDS
  • Placing certain records into a user data set
  • Eliminating certain records from being copied to the SLDS
  • Forcing duplicate tape output volumes

There are three types of control statements, and each statement consists of an operation code and parameters. The rules for using the control statement are:

  • Control statements can be placed in columns 1 to 72 in free format. Parameters can be in any sequence.
  • Each operation code and parameter must be separated with a blank, a comma, or a comment.
  • Multiple lines can be used for a control statement. Continuation characters (+ and -) can be placed between columns 1 and 72. If (+) is used, the lines are concatenated without a blank. If (-) is used, the lines are concatenated with a blank.
  • The value of any parameter must be specified between single parentheses.

SLDS statement

An SLDS statement specifies log record types that are not written to the SLDS. It also specifies that end-of-volume is forced for tape output volumes. If omitted, all log records are copied to the SLDS. Only one SLDS control statement is allowed.

The format of the SLDS control statement is:

Read syntax diagramSkip visual syntax diagramSLDSNOLOG(, n)FEOV( nnnnn)CMPRSNR(ALL, dddddddd)
NOLOG
Defines the log record types that are not to be copied to the SLDS. The value of a NOLOG subparameter should be specified in hexadecimal, for example, SLDS NOLOG (19,1A,1B).

The SLDS must contain those records that might be needed for database recovery and for system restart. The Log Archive utility issues an error message and terminates if a required record type is specified to be omitted.

FEOV
Specifies duplicate output tape volumes. This parameter is only applicable in a dual tape SLDS environment. It ensures that corresponding volumes in a multivolume data set contain the same records (and consequently are interchangeable).

nnnnn indicates the number of blocks to be written to a tape SLDS. Each time the blocks are written, a FEOV is issued for both the primary and secondary SLDSs. The block number is specified in 5 decimal digits. If the block sizes of both SLDSs are not equal, the FEOV parameter is ignored.

CMPRSNR
Determines the disposition of the database update log records for nonrecoverable full-function databases. Specifying CMPRSNR overrides the default behavior of copying the log records in to the archive.
CMPRSNR(ALL)
Indicates that the log records are compressed. Compressing the records causes them to be replaced by minimal size placeholder records.
CMPRSNR(dddddddd)
An 8-character string that indicates that the log records are compressed only if the database name matches the dddddddd string.

COPY statement

The COPY statement is used to create an RLDS or a user data set during archive. The format for the COPY statement is:

Read syntax diagramSkip visual syntax diagramCOPYDDNOUT1( nnnnnnnn)DDNOUT2( nnnnnnnn)ADBRECOV
A
Read syntax diagramSkip visual syntax diagramRECORD(OFFSET( aaa)FLDTYP(XC)VALUE( bbb)FLDLEN( ddd)COND(EMTYTNMTYMTNETYETN))

The following abbreviations can be used in place of the keywords in the COPY statement:

Keyword
Abbreviation
OFFSET
O
FLDTYP
T
VALUE
V
FLDLEN
L
COND
C
DDNOUT1
DDNOUT2
Identifies the ddnames of the data sets. DDNOUT2 only applies if dual copies are being created. The DD statements must be included in the JCL. nnnnnnnn is a ddname value.
RECORD
Identifies the conditions for selecting a record to be written to the specified data set.
OFFSET(aaa)
Defines the beginning of the field to be tested in the record. The default is position one of the record.

aaa is the value and can be in the range from 1 up to and including the length of the record under test. Maximum value is 32767 bytes. No checking is performed to determine if the logical record length is exceeded. The value specified in the OFFSET keyword is always expressed as relative to byte 1.

FLDTYP(X)|(C)
Defines the type of data in the VALUE field. A value of X or C must be specified.

X defines the data to be treated as hexadecimal character pairs. The test data is packed, two bytes into one, to form hexadecimal equivalents. X is the default.

C defines the data to be treated as EBCDIC.

VALUE(bbb)
Can be specified in hexadecimal if FLDTYP(X) is specified, or in EBCDIC if FLDTYP(C) is specified. The value is specified between quotation marks in EBCDIC. The quotation mark notation is required when the character string contains a separator of blank or comma. Any characters can be specified within the quotation marks. (Double quotation marks within quotation marks represent a single quotation mark.) If a minus sign is the last nonblank character, it is assumed that the value is continued on the next line.
Restriction: The value of bbb cannot exceed 255 EBCDIC or 510 hexadecimal characters.

The length of this field is determined by the FLDLEN value and not by the number of nonnull characters in this field.

FLDLEN(ddd)
Defines the number of characters to be used from the test field.

ddd represents the actual number of bytes to be used, not the number of characters specified in VALUE. The acceptable range of values for this field is 1 to and including 255. The default is 1.

COND(x)
Defines the type of test and its relationship to other tests in the group. The default is COND(E). You can specify COND(x) singularly or join multiple options together.
E
Marks the last (or only) element in a test series. Any record control statements appearing after this form a new series of tests. This allows various tests to be performed on each record and each test series can be used on different fields within the record.
M
Indicates this is a multifield test; more than one test is to be made on each input record. All tests in this series must be satisfied before final output selection and processing of this record can begin.
T
Causes the VALUE byte to be used as a test under mask value, instead of a compare field. Only the first byte (two hexadecimal characters if FLDTYP(X)) of the VALUE field will be used. If FLDTYP(C) is used, the hexadecimal equivalent of the EBCDIC character is the test value. If this parameter is used, the FLDLEN keyword must not be specified and a default length of one is assumed.
Y
Indicates that there must be a bit in the record test field for each corresponding bit of the test byte for the test under mask. This is equivalent to a branch if ones test.
N
Indicates that there must not be a bit in the record test field for any of the corresponding bits of the test byte for the test under mask. This is equivalent to a branch if zeros test.
MT
Defines a test under mask option with the properties of a multifield test. This parameter must be used for a multifield test that starts with a test under mask value.
ET
Signifies that a multifield test series ends with a test under mask condition.
DBRECOV
Copies all log records needed for database recovery to the specified output data set. This output data set is known to DBRC and is used by the GENJCL process in lieu of the created SLDS when creating JCL for DB Recovery or Change Accumulation. This output data set is the recovery log data set (RLDS). If there are no records needed for DB recovery, the RLDS is a null data set. In this case DBRC records the DSNAME and volume serial number of the SLDS, in place of the RLDS DSNAME and volume serial number, and uses the SLDS for GENJCL, instead of the null RLDS.

DDNOUT1 is a required parameter on a COPY control statement. You can specify as many RECORD parameters as needed in a COPY control statement. If no RECORD parameter is specified, all log records are copied to the specified data set.

On a given COPY statement, the RECORD parameter and the DBRECOV parameter are mutually exclusive. You can specify multiple COPY control statements, but only one COPY statement with the DBRECOV parameter is allowed.

Two COPY statements must not specify the same output data set.

EXIT statement

An EXIT statement specifies that a user exit routine is to be used.

The format of the EXIT statement is:

Read syntax diagramSkip visual syntax diagramEXITNAME( nnnnnnnn)
NAME(nnnnnnnn)
Specifies the member name of the user exit. The user exit routine is accessed with a LOAD from the archive utility program; preferably binded into either JOBLIB or STEPLIB.

You can specify multiple EXIT control statements or multiple NAME parameters.

Return codes

The Log Archive utility provides the following return codes:

Code
Meaning
0
Archive processing completed successfully.
4
This return code is issued if one or both of the following events occur:
  • Archive processing completed successfully, but not all OLDS were archived. A recovery point was encountered and end of job was forced. Rerun the Log Archive utility for the remaining unarchived OLDS. See SYSPRINT messages.
  • An OLDS specified as input to the archive utility was already archived when this job ran. The SYSPRINT messages identify the OLDS that were already archived.
8
Archive processing completed unsuccessfully. Messages DFS3263I or DFS3062I indicate the reason.
U3274
ABEND—DBRC internal failure. Message DFS3274I plus various DSPxxxxx messages indicate the reason.