A user separation routine separates a SYSOUT file into several reports. A new report starts every time the routine detects a new value in a predefined line and column location on a SYSOUT page.
This section describes the user separation routine interface as well as some examples of supplied user separation routines. User separation routines determine the contents of a report. The contents of a report are a continuous part or parts in one SYSOUT file.
If user separation routines are defined for the report, they are called for each record in the identified SYSOUT file. However, the routine can direct the Monitor to position anywhere else on the SYSOUT file.
User separation routines are normally coded in Natural. Other languages can be used as well, but they must follow the rules for interfacing with the Monitor.
The routine communicates with the Monitor by means of a parameter data area. This data area contains various parameters. Some can be modified by the routine and returned to the Monitor, others are read-only and cannot be modified.
The list of parameters is fixed. Their format, length, dimensions and position within the list must be adhered to.
A parameter data area called P-UEXIT is supplied and
should be used when coding user separation routines.
Examples of the use of the "action" parameters described below can
be found in the library SYSNOMS.
If you have not done so already, copy the examples to the library
SYSNOMU (see
Adapting
to an Existing Environment in the
Installation documentation).
You can try these examples by executing the program
UEXEMPL in a batch job. Catalog the program first to point to the
current EMPLOYEES file. The TRACE
command can subsequently be used for testing.
The following programs are available:
| Example Report | Exit | Description | Actions |
|---|---|---|---|
UEX-ADDFP-OPEN
|
UEXAOP |
Separates SYSOUT into several reports depending on break of main department. | FORW, ADDFP,
OPEN |
UEX-CREATE |
UEXCRE |
Separates SYSOUT into several reports depending on the break of department. | CREATE |
| --- | UEXDEF |
Separates SYSOUT into several reports depending on the spool attributes. | CREATE |
UEX-FORW-BACKW
|
UEXFBT |
Forward and backward positioning. | FORW, BACKW,
GOTOP, NEXTP |
UEX-GO
|
UEXGGN |
Forward and backward positioning. | GOTO, GOTOP,
NEXTP |
UEX-UNSL-ADDP |
UEXAPI |
Replace first line of a page. | INSL,
ADDP |
| --- | UEXOPO |
For Open Print Option (OPO) only. Separates SYSOUT into several reports depending on the report name or file name. | CREATE |
The following actions may be invoked by a user exit to influence processing. Every action is based on various parameters, which are described below.
| Action | Description |
|---|---|
CACHEON |
Enable cacheing of source records. Entire Output Management will cache 126 records. This significantly improves performance, if the exit repositions on a page. This action is the default. |
CACHEOFF |
Disable cacheing of source records. |
BUNDLE |
Add report to an active bundle. |
| Action | Description |
|---|---|
GOTOP
|
Reposition Monitor to top of current page. The next time the routine is called, it gets the record at the top of the current page. Page top is detected either by channel 1 ANSI or by machine code. |
GOTO
|
Reposition to record number returned in parameter
P-RECNO.
|
NEXTP
|
Go to top of next page. |
FORW, BACKW
|
Number of lines in P-RECNO.
|
| Action | Description |
|---|---|
INSL
|
Insert up to 10 lines at the current position. The
number of lines to be inserted is returned in parameter P-RECNO
and the text lines to be inserted are returned in the array parameter
P-INSERT-LINES.
|
| Action | Description |
|---|---|
ADDR
|
Add range of lines, where the record number
of the range to be included is returned in the parameters
P-FROMLINE and P-TOLINE: The next call to the exit
starts one line after the last record in the range specified
(P-TOLINE + 1).
|
ADDP
|
Add all records from the current line until end of current page to the current report. The next call to the exit starts at the top of the next page. |
ADDFP
|
Add full page. All of the current page is added to the current report. The next call to the exit starts at the top of the next page. |
CREATE
|
Create report from a range of record numbers
supplied in the parameters P-FROMLINE and P-TOLINE.
The report number to be created must be returned in
When this action is specified and there is an opened
report, the report is closed first. The next call to the exit starts one line
after the last record in the range specified ( |
OPEN
|
Close current report and open new
report. The new report to be opened must be returned in
P-REPNAME.
|
CLOSE
|
Close current report. Report processing parameters can be overwritten, if supplied in the exit parameters. |
This section describes the parameters for user separation routines:
| Parameter | Description |
|---|---|
P-RC
|
A return code which tells whether to include the current record in the report or not. The return code is returned by the exit to the Monitor and can contain the following values: 0 = Include current record in report; 1 = Ignore the current record; 3 = End of processing, close current report. |
P-ACTION |
An action code which tells the Monitor to perform a specific action (see Actions). |
P-MASTER |
Name of the master or default report definition currently processed. |
P-UPARM1 |
An array of five parameters supplied by the monitor to the routine. The values are defined in the appropriate master or default report definitions. Evaluate or save these parameters upon the first call to the exit. |
P-RECNO |
Current record number within the source being processed. |
P-RECORD
|
Contents of the current record. |
P-INSERT-LINES
|
An array of ten lines which may be inserted with
action INSL.
|
P-FROMLINE |
Start record number of a range of lines referenced by actions which add lines to the current active report. |
P-TOLINE |
End record number of a range of lines referenced by actions which add lines to the current active report. |
P-WORK
|
Work area for the user separation routines to save data for subsequent calls. |
| Parameter | Description | |
|---|---|---|
P-SOURCE-TYPE
|
Indicates the type of source being processed. | |
| 1 | JES2 | |
| 2 | JES3 | |
| 3 | POWER | |
| 4 | Entire Output Management database (container file) | |
| 5 | Sequential file (z/OS) | |
| 6 | Sequential file (z/VSE) | |
| 7 | BS2000 | |
| 11 | Natural Advanced Facilities | |
| 14 | CA Spool | |
P-SOURCE-CC-TYPE
|
Indicates the type of carriage control characters. | |
| 1 | ASA | |
| 2 | Machine | |
| 3 | Reserved for BS2000 | |
| 4 | No carriage control. | |
P-SOURCE-NUMBER-OF-LINES
|
Total number of lines in the source. | |
P-MAXREC
|
See
P-SOURCE-NUMBER-OF-LINES above. This field is still available for
compatibility reasons but will be deleted with the next version.
|
|
P-SOURCE-RECORD-LENGTH
|
The current record length in bytes including carriage control characters, if present. It should not be modified. | |
P-RECLEN
|
See
P-SOURCE-RECORD-LENGTH above. This field is still available for
compatibility reasons but will be deleted with the next version.
|
|
P-SOURCE-ATTRIBUTES
|
Source-specific
attributes which are redefined depending on P-SOURCE-TYPE are
described below.
|
|
| Parameter | Description |
|---|---|
P-POWER-NODE
|
Entire System Server node by which the source is being read. |
P-POWER-JOB-NAME
|
The job name of the SYSOUT file currently being processed. |
P-POWER-JOB-NUMBER
|
The POWER job number of the SYSOUT file currently being processed. |
P-POWER-TYPE
|
Always LS for POWER list queue.
|
P-POWER-SEGMENTS
|
The number of segments. |
P-POWER-SEG-LASTLINE
|
An array of up to 40 occurrences indicating the last logical line for each segment. |
| Parameter | Description |
|---|---|
P-FVSE-NODE
|
The Entire System Server node by which the current source is being read. |
P-FVSE-VOLSER
|
The volume serial number on which the file resides. |
P-FVSE-DSNAME
|
The data set name. |
P-FVSE-RECFM
|
The record format of the data set. |
P-FVSE-LRECL
|
The record length of the data set. |
P-FVSE-BLKSIZE
|
The block size of the data set. |
These parameters are used to put reports into bundles dynamically.
| Parameter | Description |
|---|---|
P-BUNDLE
|
An array of up to 5 bundles into which the report is put. |
P-BUNDLE-COORDINATOR
|
User ID of the bundle coordinator. |
P-FLUSH-TIME
|
Time when the bundle is to be closed and printed. |
P-BUNDLE-FLUSH-LINES |
Number of lines at which the bundle is to be closed and printed. |
P-BUNDLE-SEPSTART
|
Bundle start separator. |
P-BUNDLE-SEPEND
|
Bundle end separator. |
P-BUNDLE-SEPNO
|
Number of separator copies. |
P-BUNDLE-PRINTER
|
Printer on which the bundle is to be printed. |
P-BUNDLE-JOBCARDS
|
Up to 3 job cards used when printing bundle in batch mode. |
P-BUNDLE-GROUP
|
Up to 5 bundle groups. |
P-BUNDLE-SEQUENCE-NR
|
Up to 5 sequence numbers. |
P-BUNDLE-REPORT-SEPARATORS
|
Bundle report separator. |
P-BUNDLE-PRINTERS
|
Up to 20 bundle printers. |
P-BUNDLE-PRINTERS-COPY
|
Up to 20 bundle printer copies. |
P-BUNDLE-HOLD
|
Bundle hold status. |
P-BUNDLE-GRANT
|
Up to 6 granted users
(P-BUNDLE-GRANTED-USER) for the bundles created by this exit. Each
specification consists of a user ID and its granting options
(P-BUNDLE-GRANT-OWNER, -MODIFY, -PURGE,
-DISPLAY, -ARCHIVE, -REVIVE). Grant options should be set to "Y" or "N". |
P-BUNDLE-DESCRIPTION |
Bundle description. |
P-CONTROL-EXIT-LIBRARY |
Natural library containing bundle print control exit. |
P-CONTROL-EXIT-MEMBER |
Name of bundle print control exit. |
P-BUNDLE-FLUSH-REPORT |
Up to 4 report names which will cause the bundle to flush. |
P-BUNDLE-FLUSH-START |
Scheduled flush start time in format HHII (hours and minutes). |
P-BUNDLE-FLUSH-END |
Scheduled flush end time in format HHII (hours and
minutes). Must be greater than P-BUNDLE-FLUSH-START.
|
P-BUNDLE-FLUSH-INT |
Scheduled flush time interval in format HHII (hours and minutes). |
| All 3 of the above parameters must be supplied, or the flush schedule is ignored. | |
P-BUNDLE-FLUSH-DAYS |
Days of the month when the bundle should be flushed. Must be in the range 1-31, ALL or LD. |
P-BUNDLE-FLUSH-WEEK-DAYS |
Days of the week when the bundle should be flushed. Must specify the first two letters of the day name. English: SA, SU, MO, TU, WE, TH, FR. German: SA, SO, MO, DI, MI, DO, FR. |
P-BUNDLE-FLUSH-CALENDAR |
Calendar to be used for distinguishing holidays from
working days - must be specified if P-BUNDLE-FLUSH-BEFORE-AFTER is
specified.
|
P-BUNDLE-FLUSH-BEFORE-AFTER |
A or B to flush the bundle after or before a day defined as a holiday in the specified calendar. |
If any of the bundle flush parameters are invalid, they are all ignored and an error message is written to the monitor output listing.
| Parameter | Description |
|---|---|
P-REPNAME
|
Used in OPEN and CREATE
actions to specify the report to be opened or created.
|
P-REPORT-DESCRIPTION
|
Long description of the report. |
P-OWNER
|
Master owner of the report. |
P-KEYWORDS
|
An array of up to 6 keywords which are used when creating the report or overwriting at close time. |
P-STORE-NRM
|
"Y" means store report in Entire Output Management database. Used only when opening or creating new reports. |
P-DISTRIBUTION
|
An array of up to 10 members for distribution. Used at create and open. |
P-PRINTERS
|
An array of up to 20 logical printers to print the
report. Used to overwrite with CREATE, OPEN or
CLOSE actions.
|
P-COPIES
|
The number of copies of the report to be printed on
each printer specified with P-PRINTERS.
|
P-HOLD
|
Hold status to queue printouts. Used to overwrite with
CREATE, OPEN or CLOSE actions. Possible
values:
H = Hold printout. |
P-REPORT-SEPSTART
|
Report start separator. |
P-REPORT-SEPEND
|
Report end separator. |
P-REPORT-SEPNO
|
Number of separator copies. |
P-REPORT-JOBCARDS
|
Up to 3 job cards used when printing reports in batch mode. |
P-ARCHIVE
|
Y = Report is marked for archiving upon creation. |
P-RETENTION-NUM
|
The number of retention period units the report contents is available online. |
P-RETENTION-UNIT
|
Unit for retention period:
W = Working days. |
P-RETENTION-CALENDAR
|
The name of the calendar used to calculate working days. |
P-RETENTION-ACTION
|
Used to overwrite with CREATE,
OPEN or CLOSE actions.
P = Purge report after expiration. |