File processing NOTES & Illustrations on EXECIO:
NOTES: EXECIO:
SYNTAX: EXECIO lines DISKW ddname write parms DISKR ddname read parms DISKRU linenum read parms
WRITE Parms: STEM varname OPEN|FINISH
READ Parms: (FIFO | OPEN FINISH SKIP ) LIFO | STEM Varname
This command controls I/O of information to and from a dataset. Information can be read from a dataset to a data stack for serialized processing or to a list of variables for random processing. Information from the data stack or a list of variables can be written to a data set. You can use the EXECIO command to do various types of I/O tasks, such as copy information to and from a data set to add, delete, or update the information. Restriction: The EXECIO command does not support I/O on files allocated to data sets with spanned, track overflow, or undefined record formats.
An I/O data set must be either sequential or a single member of a PDS. Before the EXECIO command can perform I/O to or from the data set, the data set must be allocated to a file that is specified on the EXECIO
command. The EXECIO command does not perform the allocation. When performing I/O with a system data set that is available to multiple users, allocate the data set as OLD, before issuing the EXECIO command, to have exclusive use of the data set. When you use EXECIO, you must ensure that you use quotation marks around any operands, such as DISKW, STEM, FINIS, or LIFO. Using quotation marks prevents the possibility of the operands being substituted as variables. For example, if you assign the variable stem to a value in the exec and then issue EXECIO with the STEM option, if STEM is not enclosed in quotation marks, it will be substituted with its assigned value. Lines:
The number of lines to be processed. This operand can be a specific decimal number or an arbitrary number indicated by *. When the operand is * and EXECIO is reading from a data set, input is read until EXECIO reaches the end of the data set. If you specify a value of zero (0), no I/O operations are performed unless you also specify either OPEN, FINIS, or both OPEN and FINIS. •
If you EXECIO lines. EXECIO
specify OPEN and the data set is closed, opens the data set but does not read any If you specify OPEN and the data set is open, does not read any lines.
In either case, if you also specify a non-zero value for the linenum operand, EXECIO sets the current record number to the record number indicated by the linenum operand. •
If you specify FINIS and the data set is open, EXECIO does not read any lines, but EXECIO closes the data set. If you specify FINIS and the data set is not already opened, EXECIO does not open the data set and then close it.
•
If you specify both OPEN and FINIS, EXECIO processes the OPEN first as described above. EXECIO then processes the FINIS as described above.
DISKR
Opens a data set for input (if it is not already open) and reads the specified number of lines from the data set and places them on the data stack. If the STEM operand is specified, the lines are placed in a list of variables instead of on the data stack. While a data set is open for input, you cannot write information back to the same data set.
DISKRU
Opens a data set for update (if it is not already open) and reads the specified number of lines from the data set and places them on the data stack. If the STEM operand is specified, the lines are placed in a list of variables instead of on the data stack. While a data set is open for update, the last record read can be changed and then written back to the data set with a corresponding EXECIO DISKW command.Typically, you open a data set for update when you want to modify information in the data set. ddname
The name of the file to which the sequential data set or member of the PDS was allocated. You must allocate the file before you can issue EXECIO. For example, you can allocate a file using the ALLOCATE command in the TSO/E address space only or a JCL DD statement. linenum
The line number in the data set at which EXECIO is to begin reading. When a data set is closed and reopened as a result of specifying a record number earlier than the current record number, the file is open for: - input if DISKR is specified - update if DISKRU is specified
When a data set is open for input or update, the current record number is the number of the next record to be read. When linenum specifies a record number earlier than the current record number in an open data set, the data set must be closed and reopened to reposition the current record number at linenum. When this situation occurs and the data set was not opened at the same task level as that of the executing exec, attempting to close the data set at a different task level results in an EXECIO error. The linenum operand must not be used in this case. FINIS:
Close the data set after the EXECIO command completes. A data set can be closed only if it was opened at the same task level as the exec issuing the EXECIO command. You can use FINIS with a lines value of 0 to have EXECIO close an open data set without first reading a record. Because the EXEC command (when issued from TSO/E READY mode) is attached by the TSO/E terminal monitor program (TMP), data sets opened by a REXX exec are typically closed automatically when the top level exec ends. Good programming practice, however, would be to explicitly close all data sets when finished with them. OPEN:
Opens the specified data set if it is not already open. You can use OPEN with a lines value of 0 to have EXECIO do one of the following: Open a data set without reading any records Set the current record number (that is, the number of the next record EXECIO will read) to the record number indicated by the linenum operand, if you specify a value for linenum. STEM var-name
The stem of the set of variables into which information is to be placed. To place information in compound variables, which allow for easy indexing, the var-name should end with a period. For example,
MYVAR. When var-name does not end with a period, the variable names are appended with numbers and can be accessed in a loop such as: "EXECIO * DISKR MYINDD (FINIS STEM MYVAR" DO i = 1 to MYVAR0 this_line = VALUE('MYVAR'¦¦i) END In the first example above, the list of compound variables has the stem MYVAR. and lines of information (records) from the data set are placed in variables MYVAR.1, MYVAR.2, MYVAR.3, and so forth.The number of variables in the list is placed in MYVAR.0. Thus if 10 lines of information were read into the MYVAR variables, MYVAR.0 contains the number 10, indicating that 10 records are read. Furthermore, MYVAR.1 contains record 1, MYVAR.2 contains record 2, and so forth up to MYVAR.10 which contains record 10. All stem variables beyond MYVAR.10 (i.e. MYVAR.11, MYVAR.12, etc.) are residual and contain the values that they held prior to entering the EXECIO command.
To avoid confusion as to whether a residual stem variable value is meaningful, you may want to clear the entire stem variable prior to entering the EXECIO command. To clear all compound variables whose names begin with that stem, you can either:
- Use the DROP instruction as follows, to set all possible compound variables whose names begin with that stem to their uninitialized values: DROP MYVAR. - Set all possible compound variables whose names begin with that stem to nulls as follows: MYVAR. = ''
LIFO Places information on the data stack in LIFO (last in first out) order. FIFO Places information on the data stack in FIFO (first in first out) order. FIFO is the default when neither LIFO or FIFO is specified. SKIP Reads the specified number of lines but does not place them on the data stack or in variables. When the number of lines is *, EXECIO skips to the end of the data set.
ILLUSTRATIONS: 1)This is an illustration of 2 execs to show how a data set remains open. The first (top level) exec, EXEC1, allocates a file and then calls EXEC2. The second exec (EXEC2) opens the file, reads the first three records, and then returns control to EXEC1. Note that EXEC2 does not specify FINIS on the EXECIO command, so the file remains open. When the first exec EXEC1 regains control, it issues EXECIO and gets the fourth record because the file is still open. If EXEC2 had specified FINIS on the EXECIO command, EXEC1 would have read the first record. In the example, both execs run at the same task level.
FIRST EXEC ---- EXEC1 /*REXX exec (EXEC1) invokes another exec (EXEC2) to open/* /* a file. EXEC1 then continues reading the same file. */ say 'Executing the first exec EXEC1' "ALLOC FI(INPUTDD) DA(MYINPUT) SHR REUSE" /* Allocate input file /* /* Now invoke the second exec (EXEC2) to open the INPUTDD file. /* The exec uses a call to invoke the second exec. You can /* also use the TSO/E EXEC command, which would have the /* same result. /* If EXEC2 opens a file and does not close the file before /* returning control to EXEC1, the file remains open when /* control is returned to EXEC1.
*/ */ */ */ */ */ */ */ */
/* */ say 'Invoking the second exec EXEC2' call exec2 /* Call EXEC2 to open file */ say 'Now back from the second exec EXEC2. Issue another EXECIO.' "EXECIO 1 DISKR INPUTDD (STEM X." /* EXECIO reads record 4 */ say x.1 say 'Now close the file' "EXECIO 0 DISKR INPUTDD (FINIS" /* Close file so it can be freed */ "FREE FI(INPUTDD)" EXIT 0 SECOND EXEC ---- EXEC2 /* REXX exec (EXEC2) opens the file INPUTDD, reads 3 records, and */ /* then returns to the invoking exec (EXEC1). The exec (EXEC2) */ /* returns control to EXEC1 without closing the INPUTDD file. */ /* */ say "Now in the second exec EXEC2" DO I = 1 to 3 /* Read & display first 3 records*/ "EXECIO 1 DISKR INPUTDD (STEM Y." say y.1 END
2) This example copies an entire existing sequential data set named prefix.MY.INPUT into a member of an existing PDS named DEPT5.MEMO(MAR22), and uses the ddnames DATAIN and DATAOUT respectively. "ALLOC DA(MY.INPUT) F(DATAIN) SHR REUSE" "ALLOC DA('DEPT5.MEMO(MAR22)') F(DATAOUT) OLD" "NEWSTACK" /* Create a new data stack for input only */ "EXECIO * DISKR DATAIN (FINIS" QUEUE '' /* Add a null line to indicate the end of information */ "EXECIO * DISKW DATAOUT (FINIS" "DELSTACK" /* Delete the new data stack */ "FREE F(DATAIN DATAOUT)"
3) This example copies an arbitrary number of lines from existing sequential data set prefix.TOTAL.DATA into a list of compound variables with the stem DATA., and uses the ddname INPUTDD: ARG lines "ALLOC DA(TOTAL.DATA) F(INPUTDD) SHR REUSE" "EXECIO" lines "DISKR INPUTDD (STEM DATA." SAY data.0 'records were read.'
4) To update the second line in data set EPT5.EMPLOYEE.LIST in file UPDATEDD, allocate the data set as OLD to guarantee exclusive update. "ALLOC DA('DEPT5.EMPLOYEE.LIST') F(UPDATEDD) OLD" "EXECIO 1 DISKRU UPDATEDD 2" PULL line PUSH 'Crandall, Amy AMY 5500' "EXECIO 1 DISKW UPDATEDD (FINIS"
"FREE F(UPDATEDD)"
5) The following example scans each line of a data set whose name and size is specified by the user. The user is given the option of changing each line as it appears. If there is no change to the line, the user presses the Enter key to indicate that there is no change. If there is a change to the line, the user types the entire line with the change and the new line is returned to the data set. PARSE ARG name numlines /* Get data set name and size from user */ "ALLOC DA("name") F(UPDATEDD) OLD" eof = 'NO' /* Initialize end-of-file flag */ DO i = 1 to numlines WHILE eof = no "EXECIO 1 DISKRU UPDATEDD " /* Queue the next line on the stack */ IF RC = 2 THEN /* Return code indicates end-of-file */ eof = 'YES' ELSE DO PARSE PULL line SAY 'Please make changes to the following line.' SAY 'If you have no changes, press ENTER.' SAY line PARSE PULL newline IF newline = '' THEN NOP ELSE DO PUSH newline "EXECIO 1 DISKW UPDATEDD" END END END "EXECIO 0 DISKW UPDATEDD (FINIS"
6) This example reads from the data set allocated to INDD to
find the first occurrence of the string "Jones". Upper and lowercase distinctions are ignored. The example demonstrates how to read and search one record at a time. For better performance, you can read all records to the data stack or to a list of variables, search them, and then return the updated records. done = 'no' DO WHILE done = 'no' "EXECIO 1 DISKR INDD" IF RC = 0 THEN /* Record was read */ DO PULL record lineno = lineno + 1 /* Count the record */ IF INDEX(record,'JONES') ¬= 0 THEN DO SAY 'Found in record' lineno
done = 'yes' SAY 'Record = ' record END ELSE NOP END ELSE done = 'yes' END "EXECIO 0 DISKR INDD (FINIS" EXIT 0
7) This exec copies records from data set prefix.MY.INPUT to the end of data set prefix.MY.OUTPUT. Neither data set has been allocated to a ddname. It assumes that the input data set has no null lines. "ALLOC DA(MY.INPUT) F(INDD) SHR REUSE" "ALLOC DA(MY.OUTPUT) F(OUTDD) MOD REUSE" SAY 'Copying ...' "EXECIO * DISKR INDD (FINIS" QUEUE '' /* Insert a null line at the end to indicate end of file */ "EXECIO * DISKW OUTDD (FINIS" SAY 'Copy complete.' "FREE F(INDD OUTDD)" EXIT 0
8) This exec reads five records from the data set allocated to MYINDD starting with the third record. It strips trailing blanks from the records, and then writes any record that is longer than 20 characters. The file is not closed when the exec is finished. "EXECIO 5 DISKR MYINDD 3" DO i = 1 to 5 PARSE PULL line stripline = STRIP(line,t) len = LENGTH(stripline) IF len > 20 THEN SAY 'Line' stripline 'is long.' ELSE NOP END /* The file is still open for processing */ EXIT 0
9) This exec reads the first 100 records (or until EOF) of the data set allocated to INVNTORY. Records are placed on the data stack in LIFO order. A message is issued that gives the result of the EXECIO operation. eofflag = 2 /* Return code to indicate end of file */ "EXECIO 100 DISKR INVNTORY (LIFO" return_code = RC
IF return_code = eofflag THEN SAY 'Premature end of file.' ELSE SAY '100 Records read.' EXIT return_code
10) This exec erases any existing data from the data set FRED.WORKSET.FILE by opening the data set and then closing it without writing any records. By doing this, EXECIO just writes an end-of-file marker, which erases any existing records in the data set. In this example, the data set from which you are erasing records must not be allocated with a disposition of MOD. If you allocate the data set with a disposition of MOD, the EXECIO OPEN followed by the EXECIO FINIS results in EXECIO just rewriting the existing end-of-file marker. "ALLOCATE DA('FRED.WORKSET.FILE') F(OUTDD) OLD REUSE" "EXECIO 0 DISKW OUTDD (OPEN" /* Open the OUTDD file for writing, but do not write a record */ "EXECIO 0 DISKW OUTDD (FINIS" /* Close the OUTDD file. This basically completes the erasing of any existing records from the OUTDD file. */ Note that in this example, the EXECIO ... (OPEN command followed by the EXECIO ... (FINIS command is equivalent to: "EXECIO 0 DISKW OUTDD (OPEN FINIS"
11) This exec opens the data set MY.INVNTORY without reading any records. The exec then uses a main loop to read records from the data set and process the records. "ALLOCATE DA('MY.INVNTORY') F(INDD) SHR REUSE" "ALLOCATE DA('MY.AVAIL.FILE') F(OUTDD) OLD REUSE" "EXECIO 0 DISKR INDD (OPEN" /* Open INDD file for input, but do not read any records */ eof = 'NO' /* Initialize end-of-file flag */ avail_count = 0 /* Initialize counter */ DO WHILE eof = 'NO' /* Loop until the EOF of input file */ "EXECIO 1 DISKR INDD (STEM LINE." /* Read a line */ IF RC = 2 THEN /* If end of file is reached,*/ eof = 'YES' /* set the end-of-file (eof) flag */ ELSE /* Otherwise,a record is read*/ DO IF INDEX(line.1,'AVAILABLE') THEN /* Look for records marked "available"*/
DO "EXECIO 1 DISKW OUTDD"
/* "Available" record found */ /* Write record to available file */ avail_count = avail_count + 1 /* Increment "available" counter */ END END END "EXECIO 0 DISKR INDD (FINIS" /* Close INDD file that is currently open */ "EXECIO 0 DISKW OUTDD (FINIS" /* Close OUTDD file if file is currently open. If the OUTDD file is not open, the EXECIO command has no effect. */ EXIT 0
12) This exec opens the data set MY.WRKFILE and sets the current record number to record 8 so that the next EXECIO DISKR command begins reading at the eighth record. "ALLOC DA('MY.WRKFILE') F(INDD) SHR REUSE" "EXECIO 0 DISKR INDD 8 (OPEN" /* Open INDD file for input and set current record number to 8. */ CALL READ_NEXT_RECORD /* Call subroutine to read record on to the data stack. The next record EXECIO reads is record 8 because the previous EXEC IO set the current record number to 8.*/ . . . "EXECIO 0 DISKR INDD (FINIS" /* Close the INDD file. */
ILLUSTRATION of the effect of residual data in STEM variables: 13) This exec uses EXECIO to successively append the records from 'sample1.data' and then from 'sample2.data' to the end of the data set 'all.sample.data'. It illustrates the effect of residual data in STEM variables. Data set 'sample1.data' contains 20 records. Data set 'sample2.data' contains 10 records. "ALLOC FI(MYINDD1) DA('SAMPLE1.DATA') SHR REUSE" /*input file 1 */ "ALLOC FI(MYINDD2) DA('SAMPLE2.DATA') SHR REUSE" /* input file 2 */ "ALLOC FI(MYOUTDD) DA('ALL.SAMPLE.DATA') MOD REUSE" /* output append file */ /*******************************************************************/
/* Read all records from 'sample1.data' and append them to the */ /* end of 'all.sample.data'. */ /*******************************************************************/ exec_RC = 0 /* Initialize exec return code */ "EXECIO * DISKR MYINDD1 (STEM NEWVAR. FINIS" /* Read all records */ if rc = 0 then /* If read was successful */ do /*****************************************************************/ /* At this point, newvar.0 should be 20, indicating 20 records */ /* have been read. Stem variables newvar.1, newvar.2, ... through*/ /* newvar.20 will contain the 20 records that were read. */ /*****************************************************************/ say "-----------------------------------------------------" say newvar.0 "records have been read from 'sample1.data': " say do i = 1 to newvar.0 /* Loop through all records */ say newvar.i /* Display the ith record */ end "EXECIO" newvar.0 "DISKW MYOUTDD (STEM NEWVAR." /* Write exactly the number of records read */ if rc = 0 then /* If write was successful */ do say say newvar.0 "records were written to 'all.sample.data'" end else do exec_RC = RC /* Save exec return code */ say say "Error during 1st EXECIO ... DISKW, return code is " RC say end end else do exec_RC = RC /* Save exec return code */ say say "Error during 1st EXECIO ... DISKR, return code is " RC say end If exec_RC = 0 then /* If no errors so far... continue */ do /***************************************************************/ /* At this time, the stem variables newvar.0 through newvar.20 */ /* will contain residual data from the previous EXECIO. We */ /* issue the "DROP newvar." instruction to clear these residual*/ /* values from the stem. */ /***************************************************************/ DROP newvar. /* Set all stems variables to their */ uninitialized state */ /***************************************************************/ /***************************************************************/ /* Read all records from 'sample2.data' and append them to the */ /* end of 'all.sample.data'. */ /***************************************************************/ "EXECIO * DISKR MYINDD2 (STEM NEWVAR. FINIS" /*Read all records*/ if rc = 0 then /* If read was successful */
do /*************************************************************/ /* At this point, newvar.0 should be 10, indicating 10 */ /* records have been read. Stem variables newvar.1, newvar.2,*/ /* ... through newvar.10 will contain the 10 records. If we */ /* had not cleared the stem newvar. with the previous DROP */ /* instruction, variables newvar.11 through newvar.20 would */ /* still contain records 11 through 20 from the first data */ /* set. However, we would know that these values were not */ /* read by the last EXECIO DISKR since the current newvar.0 */ /* variable indicates that only 10 records were read by */ /* that last EXECIO. */ /*************************************************************/ say say say "-----------------------------------------------------" say newvar.0 "records have been read from 'sample2.data': " say do i = 1 to newvar.0 /* Loop through all records */ say newvar.i /* Display the ith record */ end "EXECIO" newvar.0 "DISKW MYOUTDD (STEM NEWVAR." /* Write exactly the number of records read */ if rc = 0 then /* If write was successful */ do say say newvar.0 "records were written to 'all.sample.data'" end else do exec_RC = RC /* Save exec return code */ say say "Error during 2nd EXECIO ...DISKW, return code is " RC say end end else do exec_RC = RC /* Save exec return code */ say say "Error during 2nd EXECIO ... DISKR, return code is " RC say end end "EXECIO 0 DISKW MYOUTDD (FINIS" /* Close output file */ "FREE FI(MYINDD1)" "FREE FI(MYINDD2)" "FREE FI(MYOUTDD)" exit 0
