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

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.

Building  The Queue

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.

Optional COMMAREA Fields

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:

    EXEC CICS LINK PROGRAM ('NWUTPRT')          COMMAREA (NWUTPRT-COMMAREA) LENGTH (80) END-EXEC.

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:

  

0successful
1COMMAREA length less than 80
2COMMAREA eyecatcher, "NWPRCOM1", not found
3TS queue name not specified; queue doesn't exist or is empty
4invalid print destination
6invalid sysout class
7undetermined error with TS queue
8unexpected SPOOL error, contact NWRDC
9environment error; print request may be successful if retried in  a few minutes
Ainvalid OUTPUT string
BOUTPUT 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.