C$LOCALPRINT

The C$LOCALPRINT routine provides access to the ACUCOBOL-GT window manager's local print mechanism. This allows the program to write to a printer or other device attached directly to the user's terminal. One or two USING parameters should be provided.

Usage

CALL "C$LOCALPRINT"
    USING SOURCE-DATA, LINE-SPACE

Parameters

SOURCE-DATA PIC X(n)

This contains the data that will be sent to the local device. Any trailing spaces will be removed before the data is sent.

LINE-SPACE Numeric parameter (optional)

The second parameter, if specified, determines the line spacing provided by the routine. Its value is interpreted as follows:

0	No additional characters are sent after the data
1	A carriage return is sent after the data
2	A carriage return and a line feed are sent after the data
3	A carriage return and a form feed are sent after the data

If the second parameter is not supplied, then it is treated as if it were a 2.

You may add either or both of the following values to the value contained in the second parameter:

+10	Any line-advancing control sequences are sent before the data instead of after.
+20	Inhibits the sending of the disable-printer terminal sequence after sending the data.

For example, a second parameter value of 12 causes the printer to be advanced one line prior to sending the data (since a value of 2 causes the printer to advance one line after sending the data).

A second parameter value of 8 (with a dummy first parameter) causes the disable-print sequence to be sent to the terminal on its own.

Description

When this routine executes, it performs the following steps in this order:

The terminal's Enable Print command is sent. This causes subsequent data sent to the terminal to be also sent to the attached device.
The data specified in the first USING parameter (less trailing spaces) is sent to the terminal. No interpretation or modification is done to this data.
The appropriate line spacing characters specified by the second USING parameter are sent to the terminal.
The terminal's Disable Print command is sent. This turns off the pass-through mode.
The current cursor location is set to the home position of the current window. The window manager is instructed to define the current screen state as undefined. This causes the window manager to behave correctly if the terminal's pass-through mode is destructive to the screen (e.g., characters appear on the screen as well as being sent to the attached device).

Note: Some terminals handle pass-through printing in an invisible fashion (the characters go to the printer, but do not show up on the screen), while others echo the characters onto the screen too. For maximum portability, you should assume that a call to C$LOCALPRINT will cause garbage to appear on the screen and should arrange to repaint the screen when you are finished with the local device.

The routine assumes that the attached terminal is able to do pass-through printing. You may use the ACCEPT FROM TERMINAL-INFO verb to test for this ability beforehand if you desire. You need to ensure that any communication restrictions imposed by the terminal are followed. For example, some terminals require that the attached device run at the same baud rate as the terminal.

With programs that use the Window's console (DOS-box) runtime, the C$LOCALPRINT routine simulates local printing via the following procedure. When the routine is called for the first time, the runtime system opens a file to which it writes the passed data. The name of the file is determined by the setting of the environment variable LPRINTER. Usually this will be set to the name of a device such as PRN, LPT1, and so forth. If this variable is not set, then the default name PRN is used. Serial ports are not supported.

Once this file is open, it is not closed by the runtime system. If you need to close it, you can call C$LOCALPRINT with a dummy first parameter and a second parameter of 9. Non-Windows console runtimes ignore this form of the call. Also note that no error checking is possible. If the runtime cannot open the LPRINTER file, it prints an error message and stops.