User Separation Routines

#### Search Results

Search

# User Separation Routines

- Creating User Separation Routines

- Examples

- Actions

- Parameters

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.

## 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 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`

## Actions

- Miscellaneous Actions

- Positioning Actions

- Inserting Text in a Report

- Including More Than One Line in One Routine Call

The following actions may be invoked by a user exit to influence processing. Every 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

- Source Parameters

- Bundle Parameters

- Report Parameters

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

Parameter | Description
--- | ---
`P-SOURCE-TYPE` | Indicates the type of source being processed: 1 = JES2 2 = JES3 4 = Entire Output Management database (container file) 5 = Sequential file (z/OS) 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.

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

### On this page

- Creating User Separation Routines
- Examples
- Actions
- Parameters