The WRITE PRINTER statement transmits data from a task to a terminal defined to the system as a printer device during system generation. Any type of terminal can be designated as a printer; however, the terminal is usually a hard-copy device.
The system does not transmit data directly from program variable storage to the terminal. Rather, data is passed to a queue maintained by the system, and from the queue to the printer. The data stream passed to the queue by the WRITE PRINTER request contains only data; the system adds the necessary line and device control characters when it writes the data to the printer.
Note: Native mode data streams (that is, those that contain device-control information as well as user data) can also be transmitted with a WRITE PRINTER request. This capability is useful in formatting reports for 3280-type printers.
Each line of data transmitted in a WRITE PRINTER request is considered a record. Each record is associated with a report in the print queue. A report consists of one or more records. Any task can have up to 256 active print reports. A program can issue multiple WRITE PRINTER requests, each specifying a different report. Because the system maintains the records associated with each report individually, records associated with one report are not interspersed with records associated with other reports when printed.
WRITE PRINTER Directs Reports to Print Classes and Destinations
The WRITE PRINTER request can direct reports to print classes and to destinations:
The system prints a report only when that report is completed, either explicitly as part of a WRITE PRINTER request or implicitly when the issuing task terminates.
Affect of Termination
Normal task termination, a FINISH TASK request, or a COMMIT TASK request will end all of the task's reports. Queued reports are made eligible for printing.
Abnormal task termination (abend) or a ROLLBACK TASK request will cause any queued reports belonging to the task to be deleted.
►►─── WRITE PRINTER ─┬───────────┬──┬──────────┬──────────────────────────────► ├─ NEWPAGE ─┤ └─ ENDRPT ─┘ └─ ERASE ───┘ ►─┬──┬──────────┬─ FROM (message-location) ─┬─ TO (end-message-location) ─┬┬─► │ └─ NATIVE ─┘ └─ LENGTH (message-length) ───┘│ └─ SCREEN CONTENTS ──────────────────────────────────────────────────────┘ ►─┬─────────────────────────────────┬─┬───────────────────────────────────┬──► └─ COPIES ( ─┬─ 1 ◄ ────────┬─ ) ─┘ └─ REPORT ID ( ─┬─ 1 ◄ ───────┬─ ) ─┘ └─ copy-count ─┘ └─ report-id ─┘ ►─┬───────────────────────────────────────────────────┬──────────────────────► └─┬─ CLASS (printer-class) ───────────────────────┬─┘ └─ DESTINATION (printer-destination) ─┬───────┬─┘ └─ ALL ─┘ ►─┬────────┬─┬────────┬─ ; ──────────────────────────────────────────────────►◄ └─ HOLD ─┘ └─ KEEP ─┘
Specifies that the data stream will be printed beginning on a new page. The keywords NEWPAGE and ERASE are synonymous.
Indicates that the data stream constitutes the last record in the specified report. When ENDRPT is specified, the report can be printed before the issuing task has terminated. However, the program must issue a COMMIT TASK request to signal the system to print the ended report. A subsequent WRITE PRINTER request with the same report id will start a separate report.
Specifies the program variable-storage entry of the data to be transmitted to the print queue. Message-location is the symbolic name of a user-defined field. The length of the data area is determined by one of the following specifications:
Indicates the end of the program variable-storage entry that contains the data to be transmitted to the print queue and is specified following the last data-item entry in message-location. End-message-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data.
Defines the length, in bytes, of the data stream. Message-length is either the symbolic name of a user-defined field that contains the length of the data, or the length itself expressed as a numeric constant.
Specifies that the data stream contains device-control characters. If NATIVE is not specified, the system automatically inserts the necessary characters.
Specifies (for 3270-type devices only) that the contents of the currently displayed screen are to be transmitted to the print queue. If SCREEN CONTENTS is specified with a non-3270 terminal or a remote 3270 terminal running under TCAM, an error condition results.
Specifies the number of copies of the report to be printed. The specified copy count must be an integer in the range 1 through 255; the default is 1. Copy-count is either the symbolic name of a user-defined field that contains the copy count, or the count itself expressed as a numeric constant.
Specifies the identifier of the report to be printed. The specified identifier must be an integer in the range 1 through 255; the default is 1. Report-id is either the symbolic name of a user-defined field that contains the report ID, or the ID itself expressed as a numeric constant.
Specifies the print class to which the report will be assigned. Valid print classes are 1 through 64; the default is 1. Printer-class is either the symbolic name of a user-defined field that contains the print class, or the class itself expressed as a numeric constant.
Specifies the 1- to 8-character destination to which the report will be routed. Printer-destination is either the symbolic name of a user-defined field that contains the destination, or the destination itself enclosed in quotation marks. The specified destination must have been defined during system generation.
Specifies that the report is to be printed on all of the printers belonging to the specified destination. The report will be printed, one printer at a time, and saved until it has been printed on each of the printers associated with the destination.
Specifies a print class or destination (terminal, printer, or user). Specify this parameter only for the first line of each report. If you specify no class or destination, the default print class assigned to the issuing task's physical terminal during system generation is used.
Specifies that a queued report will be held without being printed. The specified report will be held until a DCMT VARY REPORT report-name RELEASE command is issued at runtime.
Specifies that the system will keep the report in the print queue after it has been printed. The report can be released for printing with a DCMT VARY REPORT report-name RELEASE command. In this way, the report can be printed several times. A KEPT report can be deleted from the print queue manually (using a DCMT VARY REPORT report-name DELETE command at runtime) or automatically (when the queue retention period has been exceeded).
The following statement associates the data in the specified location with report 32 in the print queue and prints it beginning on a new page. Report 32 will print on the first terminal assigned to print class 3 when the program notifies the system that the report is complete or when the task terminates.
WRITE PRINTER NEWPAGE FROM (PASSGR_RPT) TO (END_PASSGR_RPT) REPORT ID (32) CLASS (3);
The following statement prints three copies of the current screen contents on a printer associated with destination A, and keeps the contents of the report in the print queue after it has printed:
WRITE PRINTER
SCREEN CONTENTS
COPIES (3)
DESTINATION ('A')
KEEP;
Upon completion of the WRITE PRINTER function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
An I/O error has occurred while placing the record in the print queue.
The current system definition contains no logical terminal-printer associations.
The specified printer destination is undefined or is not a printer.
The parameter list is invalid.
The derived length of the specified printer output data area is zero or negative.
The specified program variable-storage entry has not been allocated as required. A GET STORAGE request for the specified variable must be issued before the WRITE PRINTER statement.
A WRITE PRINTER SCREEN CONTENTS request cannot be serviced because the terminal associated with the issuing task is not a 3270-type device or is a remote 3270 device running under TCAM.
A terminal I/O error has occurred.
|
Copyright © 2014 CA.
All rights reserved.
|
|