Enhanced record processing

The following sections describe how File Manager performs enhanced record processing for each utility function.

Copy Utility (option 3.3) or Data Set Copy function (DSC)
In DSC record processing, each record is read from the input file. The input record is passed to the user procedure in an input record buffer, and also in an initially identical output record buffer. The user procedure can take a number of actions or, as long as they are mutually compatible, any combination of actions, based on data inside the record and from other sources. The user procedure then returns control to File Manager. At this point, File Manager copies the output record from the user procedure to the primary output file (assuming that those are the instructions from the user procedure).
For each input record, the procedure can:
  • Leave the output record unchanged and return it for copying to the output file. (RETURN command)
  • Modify some or all of the output record and then return if for copying to the output file. (RETURN command)
  • Choose to not copy the output record to the output file. (RETURN DROP command)
  • Stop processing the input file and therefore stop writing to the output file. (RETURN STOP and RETURN STOP IMMEDIATE commands)
  • Format new records based on any data in the input record and write one or more new records to one or more output files other than the primary output file. (WRITE command)

A user procedure is optional for DSC.

Print Utility (option 3.2) or Data Set Print function (DSP)
The record processing for DSP is very similar to that for DSC. However, whereas DSC writes the user procedure's output record to an output file, DSP formats the output record as requested for printing and sends it to the print destination.

A user procedure is optional for DSP.

Data Set Update (DSU) function
DSU record processing differs from DSC and DSP in that the records in the data set are not copied. Instead, records can be optionally updated by the user procedure. The user procedure is invoked after File Manager reads a record. The user procedure's input and output record buffers are set to the record as present in the file.
For each input record, the procedure can:
  • Leave the output record unchanged. If the output record is unchanged, File Manager does not update the file record. (RETURN command)
  • Modify some or all of the output record and then return it for updating in the file. (RETURN command)
  • Explicitly choose to not update the file record. (RETURN DROP command)
  • Stop processing the input file. (RETURN STOP and RETURN STOP IMMEDIATE commands)
  • Format new records based on any data in the input record, and write one or more new records to one or more output files other than the primary output file. (WRITE command)

There are a few restrictions on DSU. The main restriction is that DSU performs an update in place. That is, the updated data set record must be the same length as the record prior to updating.

A user procedure is required for DSU.

Data Set Edit in Batch (DSEB) function
DSEB record processing is similar to that for DSU. Like DSU, the DSEB user procedure can perform an update in place at any record. However, in DSEB, the user procedure can only traverse the records in the data set by including navigational commands such as UP() and DOWN(). As a result, the input data set records can be traversed and updated in any order.

A user procedure is required for DSEB.

Find/Change Utility (option 3.6) or Find/Change function (FCH)
Normal FCH usage is without a user procedure. In this case, FCH primary commands are used to search for strings (and possibly change them) in a data set or library.

An FCH user procedure can perform complex logic instead of a simple string match on a record. It can then use RETURN or RETURN DROP to indicate whether the record should be reported as selected (found) in the FCH output report. The user procedure can also change the record by RETURNing a changed output record; in this case the record is always also considered found or selected.