Reviewed and revised April 2024
xcall SPOOL, file {,printer, switches, copies, form, lpp, width, prefix, suffix, overlay, totpages}
Parameters
All of the parameters are [in].
file (String)
is the specification of the file to print, and is the only required parameter.
printer (String)
is the name of the printer to send the file to. If not specified, the default defined by the PRINTER parameter in miame.ini will be used. In most cases, the printer name should correspond to a printer initialization file with a matching name, either sys:<printer>.ini or ashcfg:<printer>.pqi. The exceptions to this rule are as follows.
Under Windows, you may specify the pseudo printer name "PROMPT", which is interpreted as a printer whose initialization file contains the following:
DEVICE = PROMPT:
PASSTHROUGH = OFF
PITCH = AUTO
If the name you specify is longer than 6 characters (which was the maximum for AMOS printer names and remains the maximum for A-Shell printers which have corresponding initialization files), then it is interpreted like the PROMPT example above, except with the DEVICE set to the name you specify. (This "implied printer" technique can be taken to its logical extreme by specifying a \\machine\sharename name for the printer, in which case there does not even need to be a local printer driver definition.)
Under Unix, if you specify a printer name which has no corresponding initialization file, then it is treated as if the initialization file were simply:
DEVICE = <printer>
Refer to Printer Configuration for more information about printer initialization files.
switches (Num)
may be any combination of the following:
Symbol |
Value |
Equivalent PRINT.LIT switch |
|---|---|---|
SPSW_BANNER |
&h00000001 |
BANNER (applies only to Unix, if at all) |
SPSW_NOBANNER |
&h00000002 |
NOBANNER |
SPSW_DELETE |
&h00000004 |
DELETE |
SPSW_NODELETE |
&h00000008 |
NODELETE |
SPSW_HEADER |
&h00000010 |
HEADER; ignored by A-Shell, see note 5 below |
SPSW_NOHEADER |
&h00000020 |
NOHEADER; ignored by A-Shell, see note 5 below |
SPSW_FF |
&h00000040 |
FF (formfeed after printing) |
SPSW_NOFF |
&h00000080 |
NOFF |
SPSW_WAIT |
&h00000100 |
WAIT; applies only to PDFX, see note 4 below |
SPSW_INFORM |
&h00000400 |
INFORM; ignored by A-Shell, see note 5 below |
SPSW_KILL |
&h00000800 |
KILL; ignored by A-Shell, see note 5 below |
SPSW_PASSTHROUGH |
&h00002000 |
PASSTHROUGH (Windows only) |
SPSW_NOPASSTHROUGH |
&h00004000 |
NOPASSTHROUGH (Windows only |
SPSW_LANDSCAPE |
&h00008000 |
LANDSCAPE (Windows only); see Note 2 below |
SPSW_PORTRAIT |
&h00010000 |
NOLANDSCAPE (Windows only); see Note 2 below |
SPSW_PREVIEW |
&h00080000 |
Force Preview on; see Note 3 below |
SPSW_NOPREVIEW |
&h00100000 |
Force Preview off; see Note 3 below |
SPSW_APEX |
&h00400000 |
Force APEX Preview on; see Note 3 below |
SPSW_NOSAVESTATE |
&h02000000 |
Don't save APEX state on exit |
Definition file: ashell.def |
||
Notes on Switches
| 1 | Any switches specified this way will override the corresponding switches in the printer’s initialization file. |
| 2 | The LANDSCAPE and NOLANDSCAPE switches are equivalent to the printer init commands ORIENTATION=LANDSCAPE and ORIENTATION=PORTRAIT, respectively. |
| 3 | In the standard Windows GUI environment, the Force Preview On switch (&h00080000) will use the GUI-mode APEX previewer rather than the EZVUE text-mode version. But in the case of a telnet connection to a server, the default is to preview the file using EZVUE on the server side, unless the Force APEX Preview switch is set. Set both switches to automatically use APEX whenever applicable, and to fall back to EZVUE otherwise. |
| 4 | The WAIT switch (see History) applies only to PDFX version 5 or higher. When set, the subroutine will wait until the PDFX driver has written the PDF file to disk before returning to the application. This is useful when you need to do something with the PDF file immediately after creating it. Note since it is not always possible to predict the final PDF filespec, particularly if the user is allowed access to the Save As dialog, the application may want to use MX_LASTPRTFIL to retrieve the filespec after return from SPOOL. |
| 5 | The switches referring to this note apply only to pre-A-Shell versions of EZSPL. In A-Shell they have no use or meaning and should be ignored. |
copies (Num)
is the number of copies to print (default 1).
form (String)
is the form name. Note that names are not generally used in the Windows or Unix world and are thus ignored by A-Shell. To get the equivalent effect, you would probably define multiple logical printers associated with a single physical printer.
lpp (Num)
is the number of lines per page (ignored).
width (Num)
is the number of columns per page (ignored).
prefix (String)
specifies the name of a file to be prepended to the front of the printfile before sending it to the printer. This is useful for sending printer initialization codes or routing instructions.
suffix (String)
specifies the name of a file to be appended to the end of the printfile.
overlay (String)
specifies the name of an overlay file. This has the same affect as setting OVERLAY= in the printer ini file, but any overlay specified in the subroutine statement will override an overlay in the printer ini file.
totpages (Num)
This parameter, which works only in the Windows GDI printing environment, specifies the number of pages in the printout. If specified, any occurrence of "%#" in the printfile will be replaced with the total number of pages. For example, a string in the printfile of the form "Page 1 of %#" would be converted to "Page 1 of 100", assuming that the total pages had been set to 100. Obviously you could have done this directly in your application, but it is often difficult to know in advance how many pages you are going to generate, whereas it is easy to count them as you generate them and then pass the total to SPOOL/EZSPL.name of a file to be appended to the end of the printfile.
History
2018 February, A-Shell 6.5.1630: Add switch SPSW_NOSAVESTATE.
2016 April, A-Shell 6.3.1509: Re-define WAIT function to be PDFX-specific, add MX_LASTPRTFIL to A-Shell also.
