Fast/Unload user exits or filters

Note: Fast/Unload has several extremely efficient features that may reduce the need for output filters: %variables, #functions, arithmetic expressions, FUEL outside FOR EACH RECORD, and the opportunity to write your own assembler language #functions.

Before sending data to an output data set or to a sort package, one can have an output record passed through a user-written load module. This load module must be written in assembler and can be used to modify, replace, or prevent output of a record. In addition, the user exit can request that the run be terminated.

Because of their function, these exits are referred to as filters. To have an output record pass through a user filter, one should code the FILTER option on an OUTPUT statement. For example, the following statement indicates that you would like the current output record to be passed through the filter HOHO.

OUTPUT FILTER HOHO

In the above example, HOHO must be a load module contained in a PDS concatenated to STEPLIB for the Fast/Unload step.

Under CMS, a HOHO module would have to be linked as a MODULE file on an accessed disk. In addition HOHO would have to have been linked with either the RLDSAVE option or with an ORIGIN that does not overlap the Model 204 CMS interface or Fast/Unload. The CMS interface is typically loaded at address X'20000' and Fast/Unload is loaded at X'30000'. Any address greater than X'50000' or the transient area should be all right as an ORIGIN for your load module.

The entry point of the load module indicated by OUTPUT FILTER is entered each time the OUTPUT statement is executed. The registers on entry to the filter load module are:

R0	0 Indicates record is fixed format, `1` indicates record is variable format.
R1	Address of output record. If record format is variable, R1 points to the record's `RDW` (record descriptor word).
R2	Length of the record. If record format is variable, this includes the 4-byte length of the `RDW`.
R3-R12	On first entry these registers are all 0. After first entry these registers are the same as they were on exit from the filter load module. If a filter is used on more than one `OUTPUT` statement these registers are the same as on exit from the last time a filter with the same name as the current filter was invoked.
R13	Pointer to a 24 fullword save area.
R14	Return address.
R15	Entry point address for filter load module.

The filter is only responsible for preserving R14 on return to Fast/Unload. In addition it must set R0 with a code indicating the required output action for Fast/Unload. These codes are:

0 — Put the current output record into output stream.
1 — Replace current output record with record pointed to by R1.
2 — Do not place the current output record into the output stream.

Note that if code 1 is returned and the output format is variable, the record pointed to by R1 must have a valid RDW.

If code 0 is returned, the filter may also modify the current output record in the following ways:

It may modify any part of it.
It may decrease the length of a variable format part by modifying the RDW.

Note that it may not increase the length of a variable format record by modifying the RDW. To increase the length of a record, code 1 must be returned and the extended record must be copied to a work area pointed to by R1.

Fast/Unload will detect certain errors by a user filter and issue a user ABEND when one is detected. These ABEND codes and errors are:

001 — Storage corruption.
002 — Record length increased for variable format record.
003 — RDW corrupted.
004 — Negative code returned in R0.
005 — Invalid code returned in R0.

When one of these abends is issued, R3 through R12 are loaded with the registers as they were on exit from the user filter. In addition, R1 on exit from the user filter is moved to R15.

Fast/Unload user exits or filters

See also

Navigation menu