This section covers the following topics:
If a Printer Exit is specified in the logical printer definition, control is passed to this exit at print time for each record to be printed. Here you can insert, modify or suppress records.
Usually a Printer Exit is used to insert escape sequences, so that the printer can select special print styles.
As in the examples PRCANON and PRKYOCER in library SYSNOMS, this could be an escape sequence at the beginning of the printout to switch to landscape mode.
Ideally, the printout should contain mnemonics for all kinds of print attributes (highlighting, underscoring, etc.) which are translated into escape sequences depending on the physical printer to be used. In this way, the printout is independent of any physical printer type.
| Printer Exit | Format | Description |
|---|---|---|
| PRT-RC | (B2) | Return code to be set by the exit:
0 = No modification |
| PRT-RECORD | (A251) | The record to be printed. |
| PRT-RECNO | (N9) | The current record number. |
| PRT-FLAG | (A1) | Flag with the following meaning:
F = First record, |
| PRT-WORK | (A250) | Work area for the Printer Exit. |
| PRT-REPORT | (A25) | The name of the report being printed. |
| PRT-BUNDLE | (A25) | The name of the bundle being printed. |
| PRT-RECFM | (A3) | The record format of the printout. |
A user separation routine separates a SYSOUT dataset 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 dataset.
If user separation routines are defined for the report, they are called for each record in the identified SYSOUT dataset. However, the Routine can direct the Monitor to position anywhere else on the SYSOUT dataset.
User separation routines are normally coded in the Natural 4GL language, but there are no restrictions on using other languages, as far as they 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 followed.
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 on the following page can be found in the SYSNOMS library.
If you have not done so already (see Adapting to Existing Environment in Installation and Customization documentation), copy the examples to the SYSNOMU library.
You can try these examples by executing the UEXEMPL program 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 |
|---|---|---|
| UEX-ADDFP-OPEN | UEXADP | Separates SYSOUT into several reports depending on break of main department. Actions: FORW, ADDFP, OPEN |
| UEX-CREATE | UEXCRE | Separates SYSOUT into several reports depending on the break of department. Actions: CREATE |
| UEX-FORW-BACKW | UEXFBT | Forward and backward positioning. Actions: FORW, BACKW, GOTOP, NEXTP |
| UEX-GO | UEXGGN | Forward and backward positioning. Actions: GOTO, GOTOP, NEXTP. |
| UEX-UNSL-ADDP | UEXAPI | Replace first line of a page. Actions: INSL, ADDP |
The following actions may be invoked by a user exit to influence processing. Each 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. CACHEON 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 P-FROMLINE and P-TOLINE parameters. 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. |
The following is a description of the parameters for user separation routines.
| Parameter | Description |
|---|---|
| P-RC | This is 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 | This is 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. |
These parameters are common to all sources.
| 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 | CMASPOOL | |
| 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. | |
| 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 | 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 dataset name. |
| P-FVSE-RECFM | The record format of the dataset. |
| P-FVSE-LRECL | The record length of the dataset. |
| P-FVSE-BLKSIZE | The block size of the dataset. |
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). |
| Note: 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-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. |
| Parameter | Description | |
|---|---|---|
| P-HOLD | Hold status to queue printouts. Used to overwrite with CREATE, OPEN or CLOSE actions. Can have the following 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 | Retention period unit. | |
| 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. | |
Separator Pages can be created for reports or bundles. All Separator members containing parameters for the Separator Pages must reside on the Entire Output Management user library, SYSNOMU, as source members. The names of Separator members for reports must start with an "RS-" prefix. The names of Separator members for bundles must start with BS- prefix. Use the Natural editor to create the Separator member.
The Separator member consists of four types of data:
| Carriage control character | Entered in the first byte of every line. Leave this byte empty when no carriage control is required for the line. |
| Text | Printed as is. |
| Substitution variables | Starting with @ which are replaced by their current value at print time. |
| NOP symbols | Starting with @@, replaced by appropriate NOP symbol value at print time. |
The first byte on every line of the member is assumed to be a carriage control character (ANSI code). A special control character K can be specified in the first byte, to represent BLOCK LETTER character mode.
Entered in the form:
@@owner.symbol-table.symbol-name
for master symbols
or
@@owner.symbol-table.symbol-name.network.run
for active symbols
where owner, symbol-table, network, run are values of predefined NOP symbols and symbol-name is the name of a defined NOP symbol.
The following keywords can be specified as substitution variables anywhere in the text of the Separator member:
| Substitution Variable | Description |
|---|---|
| @REPORT | Report name |
| @BUNDLE | Bundle name |
| @DATE | Current date |
| @TIME | Current time |
| @CDATE | Report creation or bundle open date |
| @CTIME | Report creation or bundle open time |
| @EXIT | Exit name used for separating SYSOUT |
| @DESCR | Report or bundle description for a separator |
| @JOBNAME | Job name of SYSOUT |
| @JOBNO | Job number of SYSOUT |
| @USER | User ID |
| @NAME | User name (first and last concatenated) |
| @DEPTNO | User's department number |
| @DEPTNAME | Name of user's department |
| @LOCATION | Location of user's department |
| @ORGANIZATION | Name of user's organization |
| @ADDRESS1 | User's address, line 1 |
| @ADDRESS2 | User's address, line 2 |
| @ADDRESS3 | User's address, line 3 |
| @PHONE | User's phone number |
| Substitution Variable | Description |
|---|---|
| @COORDINATOR | Coordinator ID |
| @COORD-NAME | Coordinator name(first and last concatenated) |
| @COORD-DEPTNO | Coordinator's department number |
| @COORD-DEPTNAME | Name of coordinator's department |
| @COORD-PHONE | Coordinator's phone number |
| @COORD-LOCATION | Location of coordinator's department |
| @COORD-ORGANIZATION | Name of coordinator's organization |
| @COORD-ADDRESS1 | Coordinator's address, line 1 |
| @COORD-ADDRESS2 | Coordinator's address, line 3 |
| @COORD-ADDRESS3 | Coordinator's address, line 3 |
