Subprogram NWUTPRT: CICS Print Utility
If you have any questions about the content of this page, please contact CICS Requests for clarification
The CICS print utility, NWUTPRT, simplifies the printing of reports generated by CICS application programs. The application program merely writes the desired report lines to a temporary storage queue and then links to NWUTPRT to print the report. Reports processed in this manner are sent from CICS directly to JES2, the MVS spool facility. CICS has no part in the actual printing process. The printers are not connected to CICS. VPS, accessed via TSO, is the principle point of control for 3270 printers.
- COPY NWUTPRT Statement
- Building The Queue
- Required COMMAREA Fields
- Optional COMMAREA Fields
- When The Queue Has Been Built
- Optional Features
Include in your program the COPY statement for the COMMAREA required by NWUTPRT. COPY NWUTPRT which will generate the following:
01 NWUTPRT.
05 NWUTPRT-COMMAREA.
10 FILLER PIC X(8) VALUE 'NWPRCOM1'.
10 NWUTPRT-QNAME PIC X(8).
10 NWUTPRT-PRTDEST PIC X(8).
10 FILLER PIC X(11).
10 NWUTPRT-RETURN PIC X(1).
10 NWUTPRT-BANNER PIC X(8).
10 NWUTPRT-LENGTH PIC S9(4) COMP.
10 NWUTPRT-ASACC PIC X(1).
10 NWUTPRT-SAVEQ PIC X(1).
10 NWUTPRT-CLASS PIC X(1).
10 NWUTPRT-CHKDEST PIC X(1).
10 FILLER PIC X(18).
10 NWUTPRT-RESERVED PIC X(12).
Or, code: COPY NWUTPRTX which is similar to the description above but with an extra 100 byte field called NWUTPRT-OUTPUT appended to the end. This field is used for greater control of the printing process, details later.
Write your report to the TS queue. For example:
EXEC CICS WRITEQ TS QUEUE (NWUTPRT-QNAME) FROM (working storage field) LENGTH (nnnnn) END-EXEC.
The report lines may be written to the TS queue one line at a time, or they may be blocked more than one per TS record. If you write only one report line per TS record, then the report lines (and consequently the TS records) may be variable length. If you block multiple report lines per TS record, then the report lines must be the same length and you must supply the length via COMMAREA field NWUTPRT-LENGTH.
Required COMMAREA Fields
Place the name of the temporary storage (TS) queue you will build into COMMAREA field NWUTPRT-QNAME. Place the printer destination into the COMMAREA field NWUTPRT-PRTDEST. This value can be the VTAM ID of a printer, like TW11NWE2 or it can be a destination of the form Rnnn or NnnnRnnn.
COMMAREA fields which optionally may be loaded are described as follows:
NWUTPRT-BANNER - may be loaded with up to an 8 byte value (alphanumeric or national characters) which will be printed on the banner page if the print destination is under VPS control. If no value is supplied, print directed to a VPS printer will have a default banner consisting of the CICS logon ID of the terminal operator, preceded by a dollar sign ($).
NWUTPRT-LENGTH - may be loaded with the length of the report lines. If no value is loaded, each TS record will be treated as a single report line. For example, if the report lines are 90 characters and there are 20 lines blocked per TS record (thus creating a TS record length of 1800), then NWUTPRT-LENGTH must be loaded with a value of 90. Otherwise, the entire 1800 byte TS record will be treated as a single report line, resulting in "wrapping" of the report lines at the printer. NOTE: Blocking the report lines is desirable, since it will reduce the number of "EXEC CICS WRITEQ TS" commands needed when building the report and the number of "EXEC CICS READQ TS" commands needed by NWUTPRT when submitting the report for printing.
NWUTPRT-ASACC - must be loaded with a "Y" if the report lines are built with ASA carriage control codes in byte 1 of each line. If "Y" is not supplied, the report lines will be assumed to have no carriage control.
NWUTPRT-SAVEQ - must be loaded with a "Y" if the TS queue is to be saved after processing by NWUTPRT. The default will be to delete the queue. (An example of a reason to save the TS queue would be if the same report were to be printed to more than one printer, then it would not have to be rebuilt prior to subsequent links to NWUTPRT.)
NWUTPRT-CLASS - may be loaded with a valid one byte SYSOUT CLASS code. This will default to CLASS "A."
NWUTPRT-CHKDEST - may be loaded with a "Y" if you merely wish to have NWUTPRT verify that a printer destination is valid. In this case, only NWUTPRT-PRTDEST needs to be loaded, and, NO PRINT WILL BE SUBMITTED BY NWUTPRT.
When The Queue Has Been Built
After writing the entire report to the TS queue, the program links to NWUTPRT. The exact command is:
Note: LENGTH will be different if the optional "OUTPUT" parameter has been used.
Upon return, COMMAREA field NWUTPRT-RETURN will contain a return code showing the success or failure of the request. The possible values are:
| 0 | successful |
| 1 | COMMAREA length less than 80 |
| 2 | COMMAREA eyecatcher, "NWPRCOM1", not found |
| 3 | TS queue name not specified; queue doesn't exist or is empty |
| 4 | invalid print destination |
| 6 | invalid sysout class |
| 7 | undetermined error with TS queue |
| 8 | unexpected SPOOL error, contact NWRDC |
| 9 | environment error; print request may be successful if retried in a few minutes |
| A | invalid OUTPUT string |
| B | OUTPUT function not available (wrong MVS or JES), contact NWRDC |
Optional Features
Output can be sent to a node and logon ID (rather than being printed) by placing the node in the COMMAREA field NWUTPRT PRTDEST and the logon ID in the COMMAREA field NWUTPRT-BANNER.
The JCL OUTPUT statement parameters can be used to set additional attributes for the print data set. Any parameters specified must be appended to the supplied 80-byte COMMAREA and the LINK to NWUTPRT must reflect the total length of the passed COMMAREA (80 + length of JCL OUTPUT parameters). The parameters use the same keywords and values as the JCL OUTPUT statement, but the syntax varies slightly. The following is the format:
keyword1(value1) keyword2(value1,value2) ...
this corresponds to the JCL OUTPUT statement parameter string:
keyword1=value1 keyword2=(value1,value2) ...
The CLASS parameter cannot be specified here. Also, if you wish to specify a node and logon ID via the DEST parameter of the OUTPUT statement, then you must set COMMAREA fields NWUTPRT-PRTDEST and NWUTPRT-BANNER to "*."
For details of valid key words refer to the MVS/ESA Job Control Language Reference.