A-Shell Reference

Reviewed and revised December 2023

tab(-10, AG_SPOOLCFG); file, ptr, fsize, internal, switches, copies, filesize, ack; chr(127);     Tab(-10,x) Syntax Notes

AG_SPOOLCFG (54) allows the host to adjust or control how ATE handles data sent to its "auxiliary port."

Background: Terminal emulators often emulate the auxiliary port feature that some dumb terminals had. Since the most common use of such auxiliary ports was to connect a printer to the back of a terminal, the usual way to emulate this capability is for the terminal emulator to capture the data intended for the aux port and then send it to a Windows printer instead. ZTERM, ATE, and other emulators allow the user to define which printer to use, or to select a "prompt" option in which the user is prompted to select a printer each time data is output to the auxiliary port. The application initiates output to the auxiliary port by sending Tab(-1,82). Everything output to the terminal after this should be captured by the emulator and redirected to the aux port (however it is defined) rather than to the screen. To mark the end of the auxiliary output, the application sends a Tab(-1,83).

Note: ZTERM and ATE also support "Serial Passthrough", which is a scheme for bidirectional communications with an actual device (such as cash drawer) physically connected to a serial port on the PC. See ZTERM Escape Sequences for more details.

If the application knows that the emulator is ATE (see AUI_ENVIRONMENT), it can adjust the aux port behavior by sending a AG_SPOOLCFG command prior to the start of the auxiliary port operation, i.e. prior to the Tab(-1,82). Note that the effect of the AG_SPOOLCFG command only lasts until the end of the next auxiliary port operation (i.e. the original configuration is restored by the next Tab(-1,83) command).

Parameters

file

is an optional filename to use for the print operation on the client side. This is handled automatically by the AUXLOC: driver so is only of use when you are going to use Tab(-1,82) directly to output text to the aux port (rather than indirectly via spooling to the AUXLOC: driver).

ptr

is an optional printer name, which temporarily overrides the printer choice in the ATE connection properties. Without this feature, the only way to change the ATE printer is for the user to do it manually via the Connection Properties dialog, which makes it hard to ensure synchronization with the needs of the application.

fsize

is an optional parameter specifying the number of bytes to be output. When non-zero, the subsequent auxiliary port output operation will be handled as binary data. This provides a means of transferring a binary file from the server to the client through the terminal channel without requiring FTP.

internal

is a field reserved for internal use. If you want to specify the switches parameter, then insert an extra comma between fsize and switches to mark the position of this parameter.

switches

contains the SPOOL switches you want to pass to the ATE client. Depending on the circumstances, some or all of them may be ignored—e.g. when the operation is really just a file transfer, the printing switches are not relevant. But if the operation does result in printing, these switches will generally override those otherwise set in the client configuration. One exception is that the APEX Preview Preference settings "Never" and "Always" take precedence over the PREVIEW and NOPREVIEW switches specified by the application.

copies

if not specified, the default is 1. The value will be used by the ATE client to generate multiple copies of the subsequent printfile send via the AUXLOC: mechanism. This feature is primarily used within A-Shell when processing AUXLOC: printing requests. If used directly by an application, you should first verify that the client is ATE 5.1.1208.0 or higher; see MX_GETVER. There is no harm in sending the copies parameter to older versions of ATE, but it will have no effect (and thus the extra copies

filesize

size of the print file in bytes. Helps the client be more responsive.

ack

see Response.

All of the parameters are optional, although all are supplied by A-Shell when printing to the AUXLOC: device.

Response

None, unless the ack parameter is specified and set to a non-zero value, in which case the response will be "ack"

Examples

One example of this would be if the app wanted to export a report to PDF, and it "knew" that all ATE clients had a PDF printer whose name started with "PDF":

PRINT TAB(-10,AG_SPOOLCFG)",PDF";chr(127);

xcall SPOOL,FILE,"AUXLOC"

 

Assuming that there is a printer ini file on the server called "AUXLOC" that contained DEVICE=AUXLOC:, this would transfer the file to the PC, and send it to the "PDF" printer regardless of (and without changing) the current printer setting for the ATE connection. We don't need to specify the filename above in the AG_SPOOLCFG statement because the AUXLOC: driver handles that automatically (but we do need the comma so that PDF is properly recognized as the ptr parameter).

Another example would be to use the DISK: pseudo-printer to simulate an ASCII FTP transfer:

PRINT TAB(-10,AG_SPOOLCFG);"DISK:%ATECACHEDIR%";chr(127);

xcall SPOOL,FILE,"AUXLOC"

 

This would transfer file from the server to the ATE client %ATECACHEDIR% directory, which might be handy if FTP was not available on the server.

See Also

History

2006 March, A-Shell 4.9.952:  Added to A-Shell