Updated February 2015

COMMAND = SBX:<sbxname>{,<optional parameters>}

This form of the command invokes the specified SBX subroutine. In order to use this form of the command, you will have to have an appropriate SBX routine in DSK0:[7,6]. That subroutine will be "XCALLed" with the following parameters:

xcall <SBXNAME>,status, fspec, printer, switches, copies, form {,<optional parameters>}

Status is mapped B,1 and must returned with a positive number if you want the print operation to proceed. Else set it to 0 to cancel the print operation, or a negative number to signify an error. (It gets passed in as -1, so you don't need to set it to abort.)

If status comes back to the print processor set to 1 or more, then it will first check to see if the subroutine has changed the printer name. If so, it starts the print operation all over again with a different printer initialization file. Otherwise, it proceeds to process the current printer request as if the COMMAND had not been executed. (This only has an effect if your printer initialization file also contains a DEVICE statement.)

The remaining parameters are all string format. You can convert switches and copies to numeric variables, but if you want to change them, convert them back to strings before passing the parameters back.

Any parameters that are specified on the COMMAND = SBX: line will be added to the end of the parameter list, to be interpreted by the SBX subroutine. For example:

COMMAND = SBX:EMAILP,4,"Subject","Intro, text…"

In the above example, the subroutine EMAILP.SBX will be called with the following parameter list:

XCALL EMAILP, STATUS, FSPEC, PRINTER, SWITCHES, COPIES, FORM, 4, "Subject", "Intro, text..."

The SBX subroutine may change any of the first six parameters (status thru form), and the changes will take effect before the print operation proceeds (assuming STATUS is set > 0.)

Four sample routines (PFILTR, EMAILP, HTMLP, and GDIPRT) are supplied, with source, in the samples directory. PFILTR just prints out the parameters and allows you to update them before returning to the print processor. (This is very useful for learning/testing.) EMAILP launches the local email client and inserts the print file into the message (either in the body or as an attachment.) HTMLP wraps the print file with a simple HTML header and trailer (using a temporary file) and then displays it in your default browser (as a sort of preview utility). GDIPRT can be used under A-Shell/UNIX, to forward the print file to be processed on the local PC. (It requires ZTERM, ATE or A-Shell/Windows on the PC.)

APEX Export Extensions

APEX supports custom export/extension modules which use the same print filter interface specification, except that APEX will always pass two additional parameters (inifile and flags) following the form parameter. So if you are adding custom parameters to a print filter routine, if you want the routine to be fully compatible with APEX, you should allow for those two parameters—and add your custom parameters after that. Because of this distinction, APEX includes a variation of the EMAILP routine, called PRTMAPI, with the parameters so adjusted. But had the APEX version been created first, it would have served just as well as EMAILP, except with slightly different COMMAND=SBX: syntax due to the additional parameters. See APEX Extensions for more detail.

History

2014 November, A-Shell 6.1.1398:  Print filter enhancement: The printer init statement COMMAND=SBX:filter,... now supports two optional macro arguments, $PREFIX and $SUFFIX, which evaluate to the current prefix and suffix options. For example, given the following printer init file:

DEVICE=TEST

COMMAND=SBX:PFILTR,$PREFIX,$SUFFIX

PREFIX=TEST.PFX

SUFFIX=TEST.SFX

the print filter PFILTR.SBX would receive "TEST.PFX" and "TEST.SFX" as the 7th and 8th arguments. The first 6 arguments to a printer filter are always preset to STS,FSPEC,PRINTER,SWITCHES,COPIES and FORM.