Fast/Unload user exits or filters: Difference between revisions
(Automatically generated page update) |
m (add template) |
||
(One intermediate revision by the same user not shown) | |||
Line 1: | Line 1: | ||
<!-- Page name: Fast/Unload user exits or filters--> | <!-- Page name: Fast/Unload user exits or filters--> | ||
<p | <p class="note"><b>Note:</b> <var class="product">Fast/Unload</var> has several extremely efficient features that | ||
may reduce the need for output filters: | may reduce the need for output filters: | ||
%variables, #functions, arithmetic expressions, | %variables, #functions, arithmetic expressions, | ||
FUEL outside FOR EACH RECORD, and the opportunity to write | FUEL outside <var>FOR EACH RECORD</var>, and the opportunity to write | ||
your own assembler language #functions. | your own assembler language #functions. | ||
</ | </p> | ||
Before sending data to an output data set or to a sort package, one can | 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. | have an output record passed through a user-written load module. | ||
This | This load module must be written in assembler and can be used to modify, replace, | ||
load module must be written in assembler and can be used to modify, replace, | |||
or prevent output of a record. | or prevent output of a record. | ||
In addition, the user exit can request that | In addition, the user exit can request that the run be terminated. | ||
the run be terminated. | |||
Because of their function, these exits are referred to as <b>filters</b>. | Because of their function, these exits are referred to as <b>filters</b>. | ||
To have an output record pass through a user filter, one should code the | To have an output record pass through a user filter, one should code the | ||
FILTER option on an OUTPUT statement. | <var>FILTER</var> option on an <var>OUTPUT</var> statement. | ||
For example, the statement | For example, the following statement indicates that you would like the current output record to be passed through the filter <code>HOHO</code>. | ||
<p class="code">OUTPUT FILTER HOHO | |||
</p> | |||
indicates that you would like the current output record to be passed through | |||
the filter HOHO. | In the above example, <code>HOHO</code> must be a load module contained in a PDS concatenated | ||
<p></p> | to <code>STEPLIB</code> for the <var class="product">Fast/Unload</var> step. | ||
In the above example HOHO must be a load module contained in a PDS concatenated | |||
to STEPLIB for the <var class="product">Fast/Unload</var> step. | Under CMS, a <code>HOHO</code> module would have to be | ||
linked as a <code>MODULE</code> file on an accessed disk. | |||
Under CMS, a HOHO module would have to be | In addition <code>HOHO</code> would have to | ||
linked as a MODULE file on an accessed disk. | have been linked with either the <code>RLDSAVE</code> option or with an <code>ORIGIN</code> that does not overlap the <var class="product">Model 204</var> CMS interface or <var class="product">Fast/Unload</var>. | ||
In addition HOHO would have to | The CMS interface is typically loaded at address X'20000' and <var class="product">Fast/Unload</var> is loaded at X'30000'. | ||
have been linked with either the RLDSAVE option or with an ORIGIN that does not | |||
overlap the <var class="product">Model 204</var> CMS interface or <var class="product">Fast/Unload</var>. | |||
The CMS interface is | |||
typically loaded at address X'20000' and <var class="product">Fast/Unload</var> is loaded at X'30000'. | |||
Any address greater than X'50000' or the transient area should be all right as | Any address greater than X'50000' or the transient area should be all right as | ||
an ORIGIN for your load module. | an <code>ORIGIN</code> for your load module. | ||
The entry point of the load module indicated by OUTPUT FILTER is entered | The entry point of the load module indicated by <code>OUTPUT FILTER</code> is entered | ||
each time the OUTPUT statement is executed. | each time the <var>OUTPUT</var> statement is executed. | ||
The registers on entry to | The registers on entry to the filter load module are: | ||
the filter load module are: | <table class="thJustBold"> | ||
<table> | <tr><th>R0</th> | ||
<tr><th>R0</th><td>0 Indicates record is fixed format, 1 indicates record is variable format.</td></tr> | <td>0 Indicates record is fixed format, <code>1</code> indicates record is variable format.</td></tr> | ||
<tr><th>R1</th><td>Address of output record. If record format is variable R1 points to the | |||
<tr><th>R2</th><td>Length of the record. If record format is variable, this includes the 4 byte length of the RDW.</td></tr> | <tr><th>R1</th> | ||
<tr><th>R3-R12</th><td>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.</td></tr> | <td>Address of output record. If record format is variable, R1 points to the record's <code>RDW</code> (record descriptor word).</td></tr> | ||
<tr><th>R13</th><td>Pointer to a 24 fullword save area.</td></tr> | |||
<tr><th>R14</th><td>Return address.</td></tr> | <tr><th>R2</th> | ||
<td>Length of the record. If record format is variable, this includes the 4-byte length of the <code>RDW</code>.</td></tr> | |||
<tr><th>R3-R12</th> | |||
<td>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 <var>OUTPUT</var> 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.</td></tr> | |||
<tr><th>R13</th> | |||
<td>Pointer to a 24 fullword save area.</td></tr> | |||
<tr><th>R14</th> | |||
<td>Return address.</td></tr> | |||
<tr><th>R15</th><td>Entry point address for filter load module.</td></tr> | <tr><th>R15</th><td>Entry point address for filter load module.</td></tr> | ||
</table> | </table> | ||
The filter is only responsible for preserving R14 on return to <var class="product">Fast/Unload</var>. | The filter is only responsible for preserving R14 on return to <var class="product">Fast/Unload</var>. | ||
In addition it must set R0 with a code indicating the required output action | In addition it must set R0 with a code indicating the required output action | ||
Line 57: | Line 61: | ||
These codes are: | These codes are: | ||
<ul> | <ul> | ||
<li>0 | <li>0 — Put the current output record into output stream. | ||
<li>1 | <li>1 — Replace current output record with record pointed to by R1. | ||
<li>2 | <li>2 — Do not place the current output record into the output stream. | ||
</ul> | </ul> | ||
Note that if code 1 is returned and the output format is variable, the record | Note that if code 1 is returned and the output format is variable, the record | ||
pointed to by R1 must have a valid | pointed to by R1 must have a valid <code>RDW</code>. | ||
< | |||
If code 0 is returned the filter may also modify the current output record in | If code 0 is returned, the filter may also modify the current output record in | ||
the following ways : | the following ways: | ||
<ul> | <ul> | ||
<li>It may modify any part of it. | <li>It may modify any part of it. | ||
<li>It may decrease the length of a variable format part by modifying the RDW. | <li>It may decrease the length of a variable format part by modifying the <code>RDW</code>. | ||
</ul> | </ul> | ||
Note that it may not increase the length of a variable format record by | Note that it may not increase the length of a variable format record by | ||
modifying | modifying the <code>RDW</code>. | ||
the RDW. | |||
To increase the length of a record, code 1 must be returned and | 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. | the extended record must be copied to a work area pointed to by R1. | ||
<var class="product">Fast/Unload</var> will detect certain errors by a user filter and issue a user ABEND | <var class="product">Fast/Unload</var> will detect certain errors by a user filter and issue a user <var>ABEND</var> when one is detected. | ||
when one is detected. | These <var>ABEND</var> codes and errors are: | ||
These ABEND codes and errors are: | |||
<ul> | <ul> | ||
<li>001 | <li>001 — Storage corruption. | ||
<li>002 | <li>002 — Record length increased for variable format record. | ||
<li>003 | <li>003 — RDW corrupted. | ||
<li>004 | <li>004 — Negative code returned in R0. | ||
<li>005 | <li>005 — Invalid code returned in R0. | ||
</ul> | </ul> | ||
When one of these abends is issued, R3 through R12 are loaded with the | When one of these abends is issued, R3 through R12 are loaded with the | ||
registers as they were on exit from the user filter. | registers as they were on exit from the user filter. | ||
In addition, | In addition, R1 on exit from the user filter is moved to R15. | ||
R1 on exit from the user filter is moved to R15. | |||
==See also== | ==See also== | ||
{{Template:Fast/Unload topic list}} |
Latest revision as of 19:46, 11 March 2015
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.
See also
- Fast/Unload overview
- Fast/Unload invocation
- Fast/Unload program parameters
- Fast/Unload Extraction Language (FUEL)
- Fast/Unload standard #functions
- Fast/Unload BLOB/CLOB processing considerations
- Fast/Unload datetime processing considerations
- Fast/Unload DATESTAT analysis
- Fast/Unload job statistics
- Fast/Unload SOUL Interface
- Fast/Unload with an external sort package
- Fast/Unload with DBCS data
- Fast/Unload customer-written assembler #function packages
- Fast/Unload user exits or filters
- Fast/Unload with Model 204 file groups
- Fast/Unload with Model 204 fieldgroups
- Fast/Unload with the Sir2000 Field Migration Facility
- Fast/Unload floating point arithmetic and numeric conversion
- Fast/Unload program return codes
- Fast/Unload installation
- Fast/Unload customization of defaults
- Fast/Unload SMF record format
- Fast/Unload release notes
- Fast/Unload messages