File Select and Formatting Print utility (DFSERA10)

The utility can:

• Print or copy an entire log data set
• Print or copy from multiple log data sets based upon control statement input
• Print Operations Manager (OM) log records
• Select and print log records on the basis of sequential position in the data set
• Select and print external trace data sets
• Select and print log records based upon data contained within the record itself, such as the contents of a time, date, or identification field
• Allow modules to special process any selected log records

Use a series of control statements to define the input and output options, selection ranges, and various field and record selection criteria.

Subsections:

• Restrictions
• Prerequisites
• Requirements
• Recommendations
• Input and output
• JCL specifications
• Utility control statements

Restrictions

Currently, no restrictions are documented for the DFSERA10 utility.

Prerequisites

Currently, no prerequisites are documented for the DFSERA10 utility.

Requirements

Currently, no requirements are documented for the DFSERA10 utility.

Recommendations

Currently, no recommendations are documented for the DFSERA10 utility.

Input and output

All data input is processed using QSAM and can reside on either tape or direct-access storage devices. Data set organization must be physical sequential. The record format can be fixed or variable in length, blocked or unblocked, or of undefined length. You can use multiple input and output data sets, and they can reside on different device types.

The data set containing control information must have a record length of 80. These statements are reproduced on the output print data set in the same format and sequence as they are processed. If error conditions are encountered, error messages are produced following the statement to which they apply.

Output data can be formatted and printed on the SYSPRINT data set, copied to a specified data set unchanged, or both.

Data to be printed is formatted into 32-byte segments and displayed in both hexadecimal and EBCDIC forms, with the hexadecimal relative offset value preceding each segment.

The flow of control for the program passes through two major stages:

• Control statement processing, where construction of record test and selection parameters takes place and control statement errors are diagnosed
• Record selection and output processing, where the input data is read, analyzed, and compared with the selection parameters to determine the applicability of the record for output

The first phase reads and examines the parameter statements and constructs the required test or test series to create a test group. This test group is then used in record selection when control passes to the next phase of the program. The second phase reads the input data and determines the disposition by the results of each test in the group. When the end of the input data is reached, either by encountering an end-of-file condition or the satisfying the indicated record count, program control shifts back to phase one, where the next group of tests is constructed.

JCL specifications

The File Select and Formatting Print utility executes as a standard operating system job. You must define a JOB statement, an EXEC statement, and DD statements defining input and output.

EXEC statement

Must be in the format

// EXEC PGM=DFSERA10

Alternatively, the EXEC statement can be included in a cataloged procedure.

DD statements

STEPLIB DD

Defines a partitioned data set containing the EXIT routine modules. If EXIT routines are not used or if the modules reside in LINKLIB, this statement is not required.

SYSPRINT DD

Describes the output data set to contain the formatted print records and control messages. It is usually defined as SYSOUT=A.

The RECFM=FBA DCB parameter is specified for this data set. LRECL and block size can be provided on the SYSPRINT DD statement and must be a multiple of 133. The default for both is 133.

Attention: If you specify a non-default LRECL and the EXITR option statement, you must specify a EXITR module that supports the non-default LRECL. If the EXITR module does not support the non-default LRECL, the default value of 133 must be used.

SYSIN DD

Describes the input control data set. This file must contain fixed-length 80-character records.

input or data DD

Defines the input data set to be examined to produce the formatted print records.

These data sets must be standard labeled files, either direct-access or tape. They can be of any record format (F, FB, V, VB, VBS, or U), as long as they are of DSORG=PS.

If a file with RECFM=U is used, the DCB BLKSIZE parameter must be specified. These files are processed using QSAM. Any file that QSAM supports can be described as input.

If a ddname is not specified in the CONTROL statement, the default ddname used is SYSUT1.

output or data DD

Defines the optional output data set to contain the selected records.

DFSERA10 sets the RECFM of this data set equal to the RECFM specified for the input data set. This is also done for LRECL and BLKSIZE if not specified.

The default ddname used is SYSUT4.

Utility control statements

This utility uses three types of control statements. You can use an additional statement type to provide titles or comments on the output listings. Keyword operands on these statements can be extended to additional statements, to a maximum of 9, by placing a nonblank character in position 72 and continuing the parameter in position 16 of the next statement. Each full keyword has an abbreviation that you can use.

The CONTROL statement defines the ddnames used for the input and output data sets and the beginning and ending limits of the data set being scanned. This statement is optional if the default parameter values are satisfactory.

The OPTION statement defines the test or series of tests performed on the data of the candidate record to determine its qualification for selection. You can execute one or more tests on each logical record by the appropriate number of OPTION statements, creating the logical OR function. You can analyze records with the logical AND function by creating a test series using the multifield test capability of the COND parameter and the necessary number of OPTION statements. Use the operands COND=M and COND=E to denote the beginning and ending, respectively, of a series for multifield testing of a record.

Each OPTION function has its own output processing defaults. If you use multiple OPTION functions to create a multifield test series, final output processing is determined by the OPTION statement coded with the COND=E keyword.

Use the END statement as a delimiter to separate one group of tests (made up of one or more OPTION statements) from subsequent groups of tests on the next data set. When an END statement is encountered in the control input stream, the construction of record selection parameters ceases and the processing of input data records starts. Proper use of the END statement allows one execution of the utility program to perform a varied number of tests on one or more IMS log data sets.

You can use the * or COMMENT statement to include any additional information in identifying tests or data. Those statements have no effect on the utility program.

CONTROL statement

The CONTROL statement is optional. If it is not specified, the SYSUT1 input file is examined. The optional output data set defined on the SYSUT4 DD statement is opened only if you specify the OPTION COPY function in the current group of tests. This data set is used only if COND=E is also specified.

CONTROL or CNTL

Identifies the CONTROL statement.

SKIP= or K=

Defines the first record tested. All prior records are ignored.

If this keyword is not specified, a default value of zero is used and the first record on the input file is tested.

aaa

Must be specified in the range of zero to 99999999, and cannot have embedded commas.

STOPAFT= or H=

Defines the last record to be tested. The current group of tests terminates when this value has been reached by counting processed records.

If this keyword is not specified, a default value of 16777215 is used.

If the STOPAFT parameter uses the default value of 16777215 and message DFS707I indicating EOF does not appear, the records after 16777215 have not been processed.

bbb

Must be specified in the range of 1 to 99999999, with no embedded commas. If the value zero is specified, one record is processed.

EOF

Denotes end-of-file condition. Use of the EOF parameter allows record processing beyond the stated maximum of 99999999 records.

E

Causes records to be counted for test sequence termination only if they satisfy selection criteria. Otherwise, all records read (after the SKIP value) are counted.

DDNAME= or D=

Identifies the input data set for the current group of tests. A corresponding DD statement must be supplied.

If this keyword is not specified, a default of SYSUT1 is used and the appropriate DD statement must be supplied.

DDNOUT= or O=

Identifies the optional output data set for the current group of tests.

This keyword is used with the OPTION COPY function and is only required if a ddname other than the default of SYSUT4 is required. (DDNOUT or the presence of SYSUT4 will not cause this data set to be used; this data set will be used only if OPTION COPY is specified with COND=E.)

OPTION statement

The OPTION statement constructs one set of tests. One or more OPTION functions can be specified in any combination desired to further define the selection criteria and output processing performed against each input record. Except for EXITR and DDNAME keyword operands, omitting the keyword operands causes all records processed by phase 2 of this program to be displayed on the SYSPRINT data set or transferred to the specified output data set.

A

Options

Each option has two distinct functions:

1. Determines starting position for OFFSET keyword
2. Determines output processing to be performed

If individual options are combined to form a multifield test, the use of OFFSET remains unchanged; however, output processing is determined by the OPTION coded with the COND=E keyword.

PRINT

Causes all selected records to be displayed on the SYSPRINT data set.

COPY

Causes all selected records to be transferred to the specified output data set. These records can also be displayed on the SYSPRINT data set by use of the PRTSYS keyword.

NEGOF

Causes the OFFSET keyword value to be used as a negative offset from the end of the log record. All records selected using this function are displayed on the SYSPRINT data set.

Keywords

The following keywords are all optional:

OFFSET= or O=

Is used to define the location of the first byte of the field to be tested in the record. The default is position one of the record.

aaa

Must be specified 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.

If you use DSECTs to locate values in control records or blocks, you must adjust the starting value for the OFFSET parameters. Most DSECTs start with a relative value of ZERO, while the value specified in the OFFSET keyword is always expressed as relative to byte 1.

PARM=

Is used to pass parameters to the DFSERA70 exit routine.

SYM=

Is used to define a value as a symbol. This option replaces the VALUE keyword and must not be used in the same element tests as the VALUE= keyword.

&xxxxxxxx

Is the unique name of a symbol. The '&' is the recognition character. The 'xxxxxxxx' is a 1- to 8-character symbol name. It must be unique for each SYM= specified. This symbol can be used for a VALUE= option in one or many of the following elements in a test series.

FLDTYP= or T=

Is used to define the type of data in the VALUE=field.

X

Defines the data to be treated as hexadecimal pairs. The test data is packed (2 bytes into one to form hexadecimal equivalents). This is the default value.

Example: If VALUE=D9D6D6E3E2C5C7 (14 bytes) is specified with the FLDTYP=X parameter, the resultant VALUE= is: ROOTSET in EBCDIC or D9D6D6E3E2C5C7 in hexadecimal; in either case, the length is only 7 bytes.

C

Defines the data to be treated as EBCDIC. The test data is used as punched in the card, with no alterations.

VALUE= or V=

Defines the characters of the test field. If FLDTYPE=X is specified, this data must be entered as hexadecimal character pairs. For a test under mask condition, a single pair must represent the hexadecimal value for the test. If FLDTYP=C is specified, this data must be entered as EBCDIC characters. If the character of blank or comma is to be included in this parameter, FLDTYP=X must be used with the appropriate hexadecimal equivalent.

Restriction: This option must not be used in the same element test as the SYM= keyword.

bbb

Cannot exceed 255 EBCDIC or 510 hexadecimal characters. The length of this field is determined by the FLDLEN= keyword value and not by the number of nonnull characters in this field.

&xxxxxxxx

Is the symbol name of a preceding SYM= option. Each symbol has a value associated with it that is determined by the SYM= option.

FLDLEN= or L=

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 the VALUE= keyword. The acceptable range of values for this field is 1 to and including 255. The default is 1.

STOPAFT= or H=

Defines the number of records to be selected for a single test or a multifield test. This statement can only be specified on the COND=E control statement for each element test.

aaaaa

Can be from 0 to 32767 elements.

STARTAF= or B=

Defines the number of selected records to be skipped for a single or a multifield test. This statement can only be specified on the COND=E control statement for each element test.

aaaaa

Can be from 0 to 32767 elements.

COND= or C=

Defines the type of test and its relationship to other tests in the group. If this keyword is not specified, the default is COND=E.

E

Marks the last (or only) element in a test series. Any OPTION 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. Final output processing is determined by the OPTION function defined with this keyword value.

I

Tests the VALUE= value. The record passes if the test fails. This option can stand alone or precede the E, M, or T parameters.

M

Indicates that this is a multifield test. All tests in this series must be satisfied before final output selection and processing of this record begins.

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 is 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 1 is assumed.

Y

Indicates that, for the test under mask to be considered satisfied, there must be a bit in the record test field for each corresponding bit of the test byte. This is equivalent to a branch if ones test.

N

Indicates that, for the test under mask to be considered satisfied, there must not be a bit in the record test field for any of the corresponding bits of the test byte. This is equivalent to a branch if zeros test.

MT

Defines a test under mask OPTION but with the properties of a multifield test as described in the M parameter. Because the T parameter assumes a default value of 1,e, the MT parameter must be used for a multifield test that starts with a test under mask value.

ET

Indicates that a multifield test series ends with test under mask condition.

EXITR= or E=

Specifies the entry point name of an exit routine to be given control when a candidate record has satisfied all selection criteria for the current test.

If multiple test groups have specified the same exit routine, an attempt is made to load the routine into storage for each group; therefore, the routine should be re-enterable. Upon reaching end of file on input, a final call is made to the exit routine. You can determine if end of file was reached by checking for zeros in the parameter field.

Interface to the exit routine is as follows:

• ENTRY:

  REGISTERS

  R1

  Contains a pointer to a parameter list.

  R13

  Points to an empty save area.

  R14

  Contains a return address.

  R15

  Contains the exit routine entry address.

  PARMLIST

• The parameter list consists of two words, the first is a pointer to the candidate record; the second (with the high order bit on) is a pointer to the SYSPRINT data set DCB.

• EXIT:
• Upon return from the exit routine, register 15 is used to determine whether or not processing is to continue on this record.
• A nonzero value indicates that no further processing is done on this record, and selection tests start again against the next input record.
• A zero value indicates that this record is required, and output processing is now determined based upon the last OPTION statement encountered containing the COND=E keyword.
• If the EXITR keyword is omitted, processing continues as though a return code value of zero had been received.

DDNAME= or D=

Defines the output data set used by the DL/I call trace log record retrieval routine (DFSERA50) whenever it is specified as the user exit routine. A corresponding DD statement must be supplied.

If this keyword is not specified and DFSERA50 is the exit routine, a default of TRCPUNCH is used and the appropriate DD statement must be supplied.

PRTSYS= or P=

Is used to display selected records on the SYSPRINT data set.

N

Indicates that no printing of selected records is done.

Y

Indicates that all records transferred to the output data set are also formatted and printed.

This keyword can only be used with OPTION COPY function. N is the default.

END statement

When you have defined all tests for the current input file, use the END statement to execute those tests.

END is entered at position 1. Positions 10 and on can be used for comments.

COMMENT statement

The COMMENT statement is optional. If used, the contents are displayed on the SYSPRINT data set.

Alternatively, you can use an asterisk (*) in position 1 to indicate a comment; however, comments inserted using an asterisk are not displayed in the SYSPRINT data set.