READ – Read an external file or the external data queue

Use the READ command to load external data sources into OBJECT variables.

READ <file>[+|-] | * OBJECT(<object>) 
[ADID(<application>)]
[CLIP(<n>|<-n>)]
[COUNT(0|<num-of-records>)]
[EXCLUDE|INCLUDE([a]n,<comparator>,<string>)]
[FROM|FROMX(<string>)]
[IA(<iput-arrival>)]
[JOB(<job-name>)]
[JOBID(<jes-number>)]
[MATCHTYP(EXA|END|INC|PFX|SFX|<n>)]
[OPNO(<operation-number>)]
[POSITION(UNIQUE|EARLIEST|LATEST)]
[PREDECESSOR(Y|N)]
[SKIP(0|<records>)]
[SCOPE(ALL|ACTIVE|HELD|OUTPUT)]
[SOURCE(DATASTORE|DSN|FILE|SYSOUT)]
[TEMPFILE(<dd-name>)]
[TO|TOX(<string>)]

where:

<file>

Name of an input DD statement, data set, or a SYSOUT identifier from which to read. If the SOURCE is SYSOUT, the format is PROCSTEP.JOBSTEP.DDNAME; you can omit PROCSTEP if not appropriate.

[+|-]

Specifies whether the output file can be written by further commands or is to be closed, allowing the subsequent commands in the same step to read it. The plus sing (+) allows additional writing; the minus sign (-) closes the output file. The plus or minus sign must be appended immediately after the end of the DD statement. The default is the plus sign (+), meaning that a DD statement without a suffix allows subsequent writing to the file.

*

Valid only for SOURCE(FILE). Indicates that the external data queue is to be used as input.

OBJECT(<object>)

Valid only for SOURCE(DATASTORE). Name of the application that contains the job for which you want to extract the job log.

ADID(<application>)

Name of the object variable into which to read the data.

CLIP(<n>|<-n>)

Deletes n characters from the beginning of each record of the input file. This is useful to delete control characters from the beginning of a SYSOUT file, so that the column positions match the original input data rather than the printed version. If you specify a positive number, the record is cut before the FROM|TO and INCLUDE|EXCLUDE processing is performed. If you use a negative number, the FROM|TO and INCLUDE|EXCLUDE processing is performed before cutting the absolute number of characters.

For example, if you specify CLIP(-1) the first character is deleted after FROM|TO and INCLUDE|EXCLUDE comparisons are performed.

COUNT(0|<num-of-records>)

When SOURCE(FILE): The COUNT keyword allows large files to be read in small blocks to manage memory usage. If you set a number of records with the COUNT keyword, the command reads that number of records in the file. A following READ command starts from that point in the file, rather than from the beginning. If COUNT is set to a number higher than the number of remaining records, all the remaining records are read and a message is issued, setting RC=4.
If you set COUNT(0) the file is closed after reading, therefore subsequent READ commands start again from record 1.
When SOURCE(DSN), SOURCE(SYSOUT), or SOURCE(DATASTORE): The COUNT keyword limits the number of records stored in the OBJECT, but subsequent READ requests to the same input will always start from the beginning.

EXCLUDE|INCLUDE([a]n,<comparator>,<string>)

The filter by which to include or exclude a record. You can define multiple filters for each READ command, but you cannot mix INCLUDE and EXCLUDE keywords. By setting the INCLUDE filter, only records that match the filter will be output. By setting the EXCLUDE filter, all records except those that match the filter will be output. Filtering is performed after the FROM|TO processing.

You can set the following values:

[a]n

The presence of a single alpha character prefix indicates that the filter is grouped (AND) with all adjacent filters with the same group character. The absence of a single alpha character indicates a standalone (OR) filter, where only one filter needs to be true to trigger the INCLUDE or EXCLUDE processing. n specifies the column at which to do the comparison.

For example, the following command returns rows that begin with A if they have C in column 3, all records beginning with C, and rows with C in column 1 and E in column 3.

INCLUDE(A1,EQ,A) INCLUDE(A3,EQ,C) INCLUDE(1,EQ,B) INCLUDE(C1,EQ,C) INCLUDE(C3,EQ,E)

<comparator>

The following list shows the allowed comparators:

EQ, Equal to
NE, Not equal to
LT, Less than
GT, Greater than
LE, Less than or equal to
GE, Greater that or equal to
BL, Blank at that point
NB, Not blank at that point

<string>

The string to be compared. In the case of comparator NB or BL, this argument can be the number to indicate the length of the non-blank or blank character. If omitted, only a single character is compared.

FROM|FROMX(<string>)

A range filter that does not output any records until a match is found. FROM starts the output from the row of the match, FROMX starts the output from the following row. The MATCHTYP keyword affects how the match is made. If you do not specify FROMn or FROMX, the output starts from the beginning of file.

IA(<input-arrival>)

Valid only for SOURCE(DATASTORE). The input arrival (in the format YYMMDDHHMM) of the occurrence that contains the job for which you want to extract the job log.

JOB(<job-name>)

Valid only for SOURCE(DATASTORE) and SOURCE(SYSOUT). Name of the job for which you want to extract the job log or SYSOUT.

JOBID(<jes-number>)

Valid only for SOURCE(SYSOUT). JES number of the job for which you want to extract the job log. The format corresponds to the format of the JES numbers for your system.

MATCHTYP(EXA|END|INC|PFX|SFX|<n>)

Determines how the FROM and TO strings are matched:

EXA will make an exact match for the entire row, trailing blanks are ignored. This is the default.
END will compare with the end of the record. Trailing blanks are compared.
INC will match if the string is found anywhere in the row.
PFX will match if the record begins with the string.
SFX will match if the non-blank portion of the record matches the string. Trailing blanks are ignored.
<n> will match if the string appears at that specific column in the record.

OPNO(<operation-number>)

Valid only for SOURCE(DATASTORE). Operation number of the job for which you want to extract the job log.

POSITION(UNIQUE|EARLIEST|LATEST)

Valid only for SOURCE(DATASTORE) and SOURCE(SYSOUT). The position in the queue of the matching elements to select for processing. Allowed values are:

UNIQUE, meaning that your selection criteria must identify a single job, otherwise the command fails. This is the default.
EARLIEST, to select the first entry on the list.
LATEST, to select the last entry on the list.

If you use OPTIONS TRACE(1) before the READ command, all identified entries in the list are shown.

PREDECESSOR(Y|N)

Valid only for SOURCE(DATASTORE), and only for jobs being run from within the current plan. Restricts the search for the job for which you want to extract the job log to its direct predecessors. Making the job for which you want to extract the job log a predecessor is highly recommended, because the PREDECESSOR(Y) option avoids searching the entire current plan, consuming less resources.

This keyword can be shortened to PRED without specifying a value, as long as it is not coded the first keyword to the READ command. Default is N.

SCOPE(ALL|ACTIVE|HELD|OUTPUT)

This keyword can be shortened to PRED without specifying a value, as long as it is not coded the first keyword to the READ command. Default is N.

SKIP(0<records>)

Number of records to skip before loading the input into the OBJECT. Default is 0.

SOURCE(DATASTORE|DSN|FILE|SYSOUT)

The type of data being read. Allowed values are:

DATASTORE, to fetch a job log from the HCL Workload Automation for Z data store, if the data store feature has been configured.
DSN, to dynamically allocate a data set to read, using the name specified as the first argument, and then free it afterwards. The data set is allocated to the DD statement specified by the TEMPFILE keyword, if any; otherwise it uses the name set by OPTIONS TEMPFILE.
FILE, to read from the DD statement named as the first argument. This is the default data source, unless you specify an asterisk (*) as the file name, in which case it reads from the External Data Queue (REXX stack).
SYSOUT, to read SYSOUT from the JES spool, using the name specified as the first argument. This option is valid only if SDSF is installed.

TO|TOX(<string>)

Range filter that stops the output when a match is found. TO stops the output after the row of the match, TOX does not output the line of the match or any following lines. The MATCHTYP keyword affects how the match is made.

The READ command allows data from an external source to be loaded into an OBJECT variable, allowing the contents to be interrogated either with bespoke code in a DO loop, or with commands such as VARSCAN.

For example:

To read data from the DD statement MYFILE and store it in object MYOBJ, issue the following command:
```
READ MYFILE OBJECT(MYOBJ)
```
To read the first three records from the DD statement MYFILE and store them in object MYOBJ, issue the following command. Subsequent READ commands will start from record 1 due to minus sign (–) DD suffix:
```
READ MYFILE- OBJECT(MYOBJ) COUNT(3)
```
To read data from SYSOUT file SYSUT2 in step IEBGENR in the current job, issue the following command:
```
READ IEBGENR.SYSUT2 SOURCE(SYSOUT) OBJECT(MYOBJ)
```

Issue the following command to read lines 2 to 4 from SYSOUT file SYSUT2 in step IEBGENR in the current job, then look for the text JAM in the text, which if found will cause return code 16 to be set.

VARSUB SCAN
READ IEBGENR.SYSUT2 SOURCE(SYSOUT) OBJECT(MYOBJ)
                    SKIP(1) COUNT(3)
DO I = 1 TO !@MYOBJ                     
   VARSET THISLINE @V(@MYOBJ-!I)        
   IF POS("JAM","!THISLINE") > 0 THEN DO
      WRITE OUTDATA "JAM DETECTED"      
      WRITE OUTDATA "!THISLINE"         
      EXIT 16                           
   END                                  
END

To read the JES message log from the last instance of DEANWPL1, issue the following command:
Note: If the job running this command is also named DEANWPL1, it is not classed at the latest job, because active jobs are listed before completed jobs for SCOPE(ALL). To get the currently running job, use SCOPE(ACTIVE) or POSITION(EARLIEST).
To read the job log from the immediate predecessor to this job, issue the following command. If the job has more than one predecessor, you must specify additional keywords to restrict the selection to only one of the potential predecessors.
```
READ SOURCE(DATASTORE) OBJECT(MYOBJ) PRED
```
To read the job log from the immediate predecessor to this job, and process only the JESMSGLG portion of the job log, issue the following command:
```
READ SOURCE(DATASTORE) OBJECT(MYOBJ) PRED
     FROMX(££EQQFSWWU-START-JESMSG)
     TOX(££EQQFSWWU-START-JESJCL)
```
Issue the following command to read a report from file and output pages 8 to 19, where the page marker is at column 113 on each page before clipping, then to remove the first character:
```
READ LTP SOURCE(FILE) OBJECT(MYOBJ) CLIP(-1)
         MATCHTYP(113) FROM(PAGE 0008) TOX(PAGE 0020)
```
Issue the following command to read a report from the first occurrence of LONG TERM PLAN FOR DATE until the line before GRAND TOTAL WORKLOAD FOR PERIOD. Note that depending on where the report header appears on the page, you might lose some header lines from the first page, and gain redundant lines from the start of the next section.
```
READ LTP SOURCE(FILE) OBJECT(MYOBJ) CLIP(-1)
         MATCHTYP(INC) 
         FROM(LONG TERM PLAN FOR DATE) 
         TOX(GRAND TOTAL WORKLOAD FOR PERIOD)
```

Issue the following command to extract a job log from the data store. By using FROM and TO filters, you restrict the processing to the JES message log portion of the output. The INCLUDE filters are set to pick up the -JOBNAME header as a standalone filter. The minus sign (–) and the job name are combined in a group filter to find the job specific rows.

The CONTENTION keyword reduces the waiting time between the recall of the job log and its subsequent reprocessing.

VARSUB SCAN                                       
OPTIONS CONTENTION(5,60)                          
VARSET JOB = "TWSXCPEX"                           
READ SOURCE(DATASTORE) OBJECT(MYOBJ)              
     ADID(DH#PLANNING) JOB(!JOB) POSITION(LATEST) 
     FROMX(££EQQFSWWU-START-JESMSG)               
     INCLUDE(20,EQ,-JOBNAME)                      
     INCLUDE(J20,EQ,-)                            
     INCLUDE(J21,EQ,!JOB)                         
     TOX(££EQQFSWWU-START-JESJCL)

Output example:

12.04.45 JOB08895  -JOBNAME  STEPNAME PROCSTEP    RC   EXCP
12.04.45 JOB08895  -TWSXCPEX          DNTOP       00   1241
12.04.48 JOB08895  -TWSXCPEX          SORT        00     65
12.04.51 JOB08895  -TWSXCPEX          DPREPORT    00    363
12.04.51 JOB08895  -TWSXCPEX          RCLDUMMY    00      2
12.04.51 JOB08895  -TWSXCPEX ENDED.  NAME-

Issue the following command to read from the data store. By using FROMX you restrict processing to the JES message section of the job log, before using INCLUDE to extract all the IGD104I messages that also have EQQ at column 72.
```
READ SOURCE(DATASTORE) OBJECT(MYOBJ)              
     ADID(DH#PLANNING) JOB(!JOB) POSITION(LATEST) 
     FROMX(££EQQFSWWU-START-JESMSG)               
     INCLUDE(A1,EQ,IGD104I)                       
     INCLUDE(A72,EQ,EQQ)
```

Note:

POSITION(EARLIEST|LATEST) refers to the elements found and their order in the list. It does not refer to the scheduled start time or any other time based field.
If not selecting the element you expect, using OPTIONS TRACE(1) causes Workload Automation Programming Language to list all the potential elements that match your criteria.
FROM|TO processing is not performed on skipped records.
FROM|TO and INCLUDE|EXCLUDE processing is performed on data after it is read from the data source. If you know the range of records in which the required data occurs, you can make the process more efficient by also using SKIP and COUNT, to reduce the number of records being filtered.
For INCLUDE and EXCLUDE as each separate AND group is aggregated together with other filter keywords by OR, only a single AND group, or OR filter needs to be true for the filter to be true.
To use SOURCE(SYSOUT), ensure that the SDSF product is installed and that you are authorized to use it and access the requested data.
By setting SOURCE(DATASTORE), the first time the job log is accessed a recall command is issued; then Workload Automation Programming Language retries later to check if the recall was successful. OPTIONS CONTENTION determines the delay between the recall and retry, and the number of retry attempts. For example, by setting OPTIONS CONTENTION(5,60)Workload Automation Programming Language waits 5 seconds and retries up to 60 times. It is recommended that you check your site default for the wait parameter, because the product default is to wait for 30 seconds, which could be longer than needed for a data store recall.