User Separation Routines

A user separation routine separates a SYSOUT data set 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 data set.

If user separation routines are defined for the report, they are called for each record in the identified SYSOUT data set. However, the routine can direct the Monitor to position anywhere else on the SYSOUT data set.


Creating User Separation Routines

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

Examples of the use of the "action" parameters described below can be found in the SYSNOMS library.

If you have not done so already, copy the examples to the SYSNOMU library (see Adapting to 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:

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.
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.

Actions

The following actions may be invoked by a user exit to influence processing. Each action is based on various parameters, which are described below.

Miscellaneous Actions

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.

Positioning Actions

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.

Inserting Text in a Report

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.

Including More Than One Line in One Routine Call

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 P-REPNAME. If the report is not defined in the master database, it is created dynamically in the master database using the parameters returned by the exit.

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 (P-TOLINE + 1).

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.

Parameters

This section describes the parameters for user separation routines:

General Parameters

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.

Source Parameters

Parameters Common to All Source Types

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/OSD
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/OSD
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.

Parameters for Source Type POWER

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 currently being processed.
P-POWER-JOB-NUMBER  The POWER job number of the SYSOUT 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.

Parameters for Source Type "Sequential File z/VSE"

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.

Bundle Parameters

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.

Report Parameters

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-STORE-CONNECT  Con-nect cabinet. Used only when opening or creating new reports.
P-CONNECT-SUBJECT  Document subject in Con-nect.
P-CONNECT-DISTRIBUTION  Con-nect distribution list. Used only when opening or creating new reports.
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.
R = Release printout.
C = Confirm all users in the distribution to release.

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.
A = Absolute days.
V = Weeks.
M = Months.

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.
A = Archive report after expiration.