PRF_$INTRO Domain/OS PRF_$INTRO
NAME
intro - the Domain/OS print library
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/prf.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/prf.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
DESCRIPTION
The prf_$ calls allow an application to use Domain/OS printing services.
The following is a list of the prf_$ calls.
prf_$config_file set print options from a file
prf_$edit_job edit a print job at the current site
prf_$get_printers get a list of printers at the current site
prf_$get_sites get a list of print sites
prf_$init initialize print request options
prf_$inq_option get a print request option
prf_$name_print spool a file for printing
prf_$queue_file queue a print request
prf_$read_queue get a list of print jobs in the queue
prf_$set_option set an option in a print request
prf_$signal_printer signal a print job
prf_$stream_print print from a stream
Domain/OS supports a network-wide collection of print managers which
route print jobs to appropriate print servers. The prf_$get_sites and
prf_$get_printers system calls supply information about the printing
resources currently available on a Domain internet.
Starting Print Jobs
A print job consists of a print file containing data to be printed, and
an associated print request. A print request is a structured file con-
taining a list of print option name/value pairs that control the result
of a print operation. The print file can be spooled from a stream, a
spooled copy of a file retained by a user, or even another file not on
the print spool.
The data structure queued in a print request is allocated whenever a pro-
cess accesses the print library, and initialized via the prf_$init call.
Thereafter, a process can modify the results of a print job by changing
print option values from their defaults. The print option names are
strings, but the print option values may be specified as strings or as
numeric values. When specified numerically the print option values have
type num_var_t.
After setting options via prf_$config_file, and prf_$set_option a process
can queue a print request with prf_$name_print, prf_$queue_file, or
prf_$stream_print.
Until the next call to prf_$init, the process may find out and alter the
status of the print services relevant to the queued print job with
prf_$edit_job. The prf_$read_queue and prf_$signal_printer calls allow a
process to find out what jobs are pending or in progress and delete or
abort them.
Print Options
The following print options apply to all types of files:
SEARCH_DIR ON|OFF
ON tells the print server to search through the working direc-
tories of all the active processes on the node for the files to
be printed. OFF, the default, tells the print server to search
only the current working directory of the calling process.
COPIES n
Print n copies of the file. One copy is printed by default.
PRINTER name
Print the file on the printer named name. A printer's name is
defined in its configuration file. If this option is not
specified, the print server uses the default printer name "P".
SITE node_entry_dir
Queue the print request on the node whose node entry directory
is node_entry_dir.
DELETE ON|OFF
ON tells the print server to delete the print file after it has
been printed. The default state is on; that is, if this option
is not specified, the print server deletes the print file indi-
cated by the print request after printing.
USER_NAME name
Print name as the user name on the banner page of the printed
file. If the SIGNAL option is set to ALARM, the print server
also sends an alarm to the user specified in name when printing
is complete. Therefore, name must be a valid log-in name when
requesting an alarm from the print server.
SIGNAL ALARM|OFF
ALARM tells the print server to notify a user when printing is
finished. The print server sends an alarm to the user speci-
fied with the USER_NAME option if it is set, or to the current
log-in name for the calling process if the USER_NAME option is
not set. This option's default value is OFF.
BANNER ON|OFF
ON tells the print server to print a banner page displaying a
job name, log-in name, and system information. OFF, the
default, tells the print server to not print a banner page.
CONFIG_FILE pathname
Read print request options from pathname. If pathname is null,
the print server reads print request options from the confi-
guration file at ~user_data/prf.db.
TEXT Specifies text mode for printing ASCII files. TEXT is the
default print mode.
PLOT ON|OFF
Use PLOT ON to print GPR bitmaps or to print from graphics
metafiles. PLOT OFF is the default.
TRANSPARENT ON|OFF
ON tells the print server to pass the file directly to the
printer driver routine with no processing by the print server;
that is, the printer can interpret the file directly. OFF, the
default, tells the print server to do it's normal interpreta-
tion for the target printer.
PAPER_SIZE A|B|LEGAL|A3|A4|A5|B4|B5
Use the specified page size on the Domain/Laser-26 printer.
__________________________
| Paper Size Codes |
|_________________________|
|size | paper dimensions |
|code | in inches (mm) |
|______|__________________|
|A | 8.50 x 11.00 |
| | (218 x 282) |
|______|__________________|
|B | 11.00 x 17.00 |
| | (282 x 436) |
|______|__________________|
|LEGAL | 8.50 x 14.00 |
| | (218 x 359) |
|______|__________________|
|A3 | 11.69 x 16.54 |
| | (297 x 420) |
|______|__________________|
|A4 | 8.27 x 11.69 |
| | (210 x 297) |
|______|__________________|
|A5 | 5.38 x 8.27 |
| | (137 x 210) |
|______|__________________|
|B4 | 9.84 x 13.90 |
| | (257 x 364) |
|______|__________________|
|B5 | 5.93 x 9.89 |
| | (182 x 257) |
|______|__________________|
This option is only meaningful for Domain/Laser-26 and APPLE
LaserWriter printers.
The following print options apply to text files only:
MARGINS ON|OFF
ON tells the print server to use the margin settings specified
with the TOP, BOTTOM, RIGHT, and LEFT options. OFF tells the
print server to ignore the TOP, BOTTOM, RIGHT, and LEFT
options. The default state is ON.
TOP n
The top margin is n inches, where n is a real number.
BOTTOM n
The bottom margin is n inches, where n is a real number.
RIGHT n
The right margin is n inches, where n is a real number.
LEFT n
The left margin is n inches, where n is a real number.
HEADERS ON|OFF
ON tells the print server to use the header and footer defined
with the HEAD_STRING and FOOT_STRING options. OFF tells the
print server to ignore the header and footer defined with the
HEAD_STRING and FOOT_STRING options. The default state is ON.
HEAD_STRING left/center/right
Use this option to define a page header. Specify the header as
a single string of three components delimited with slashes (/).
The resulting header has left printed flush against the left
margin, center centered on the page, and right printed flush
against the right margin. Components may be empty; that is,
"//" is a valid string and results in a blank header. The
print server interprets the following special character
sequences and substitutes the strings indicated when the char-
acters appear in the header string:
_________________________________________________
| Special | Substituted String |
|Character | |
|__________|_____________________________________|
| @ | The escape character. Turns off |
| | any special interpretation of the |
| | following character. For instance, |
| | "@*" results in a "*" instead of a |
| | space. |
|__________|_____________________________________|
| # | The current page number with a |
| | leading and a trailing space. |
|__________|_____________________________________|
| % | The current date. |
|__________|_____________________________________|
| ! | The name of the file being printed. |
|__________|_____________________________________|
| & | The time and date the file being |
| | printed was last modified. |
|__________|_____________________________________|
| * | A space. Inserts a space in the |
| | header. Literal spaces are not |
| | permitted in header strings. |
|__________|_____________________________________|
The header string "Page*@##/!/Printed*on**%" will produce a
header with the label "Page #" followed by the page number
flush left, the file name centered, and the label
"Printed on " followed by the current date flush right.
FOOT_STRING left/center/right
Use this option to define a page footer. The format is the
same as for HEAD_STRING.
FTN ON|OFF
ON tells the print server to use FORTRAN forms control even if
the file does not have the FORTRAN carriage control flag. With
FTN ON, the print server interprets the first character of each
line as a FORTRAN carriage control character and doesn't print
it, so the first character of every line will be lost if the
file does not use FORTRAN carriage control. The default state
is OFF.
WRAP ON|OFF
WRAP ON tells the print server to wrap any lines that exceed
the right margin onto the next line. WRAP OFF tells the print
server to truncate lines that exceed the right margin. The
default state is OFF.
The following print options apply to plot files; that is, graphics
metafiles and GPR bitmaps:
RESOLUTION n
Print the file with a resolution as close to n dots per inch as
possible, where n is an integer. This option applies only to
plot files.
WHITE_SPACE n
Leave n inches of white space between plots, where n is a real
number. The default is 3 inches, or "WHITE_SPACE 3".
BW_REV ON|OFF
ON tells the print server to reverse black and white values in
bitmaps. The default state is OFF.
MAGNIFICATION n
Use this option to specify a bitmap magnification value, where
n is an integer in the range -1 to 16. MAGNIFICATION -1 tells
the print server to scale the bitmap to fill the available page
space. MAGNIFICATION 0 tells the print server to print a
graphics metafile with a one-to-one scaling between the display
and the printer. If the print file is a GPR bitmap, MAGNIFICA-
TION 0 is equivalent to MAGNIFICATION 1. A magnification value
of 1 through 16 scales the bitmap by that value. Regions of
the magnified bitmap that extend beyond the printer's page
boundaries are clipped.
The following print options are for printers that support variable font
and pitch sizes:
PITCH n
Set the printer's pitch to n characters per inch. The follow-
ing pitch settings are supported:
_____________________________________
| Printer Pitch Settings |
|____________________________________|
| Printer | Pitch |
|____________|_______________________|
|Printronix | 10 |
|____________|_______________________|
|Spinwriter | 12 |
|____________|_______________________|
|IMAGEN | 8.5, 10, 12, 15, 17.1 |
|____________|_______________________|
|GE 3000 | 10, 12, 13.1, 16.7 |
|____________|_______________________|
|Versatec | 12 |
|____________|_______________________|
|LaserWriter | 1 to 100 |
|____________|_______________________|
|Laser-26 | 1 to 100 |
|____________|_______________________|
POINT n
Set the size of the font to n points.
WEIGHT LIGHT|MEDIUM|BOLD
Use this option to set the font weight for a GE 3000 printer;
it is not valid with other printers. The default is WEIGHT
MEDIUM.
LQ ON|OFF
ON tells the print server to print the document at letter qual-
ity. OFF tells the print server to print in draft mode. The
default state is OFF. The LQ option is valid only for GE 3000
printers.
The following options are for printers that contain a POSTSCRIPT inter-
preter, such as the Domain/Laser-26 and APPLE LaserWriter.
POSTSCRIPT ON|OFF
ON tells the print server to invoke the printer's POSTSCRIPT
interpreter while printing. OFF, the default, tells the print
server to bypass the printer's POSTSCRIPT interpreter.
COLUMNS 1|2
Format text in the specified number of columns. This option is
meaningful only to a POSTSCRIPT printer. COLUMNS 1 is the
default.
LPI n
Set the printer's line spacing to n lines per inch, where n is
a real number.
ORIENTATION PORTRAIT|LANDSCAPE
PORTRAIT tells the print server to print text lines or the x-
axis of bitmaps parallel to the short edge of the page.
LANDSCAPE tells the print server to print text lines or the x-
axis of bitmaps perpendicular to the short leading edge. This
option applies only to printers that include the POSTSCRIPT
interpreter (i.e., Laser-26, LaserWriter, GENICOM, and V80
printers with the POSTSCRIPT decomposer software). The default
state is PORTRAIT. Specifiying this option will override any
auto-rotation performed on bitmaps.
Data Types
num_var_t
This is a variant record type for the numeric value of a print
request option.
15 0
______________________________________________________________
| real32 |
|_____________________________________________________________|
| real32 |
______________________________________________________________
15 0
OR
15 0
______________________________________________________________
| int32 |
|_____________________________________________________________|
| int32 |
______________________________________________________________
15 0
OR
15 0
______________________________________________________________
| NOT USED |
|_____________________________________________________________|
| int16 |
______________________________________________________________
15 0
OR
15 0
______________________________________________________________
| NOT USED |
|_____________________________________________________________|
| int16_n |
______________________________________________________________
15 0
OR
15 0
______________________________________________________________
| NOT USED |
|_____________________________________________________________|
| NOT USED | int8 |
______________________________________________________________
15 8 7 0
OR
15 14 0
______________________________________________________________
|i | NOT USED |
______________________________________________________________
15 14 0
real32
A 32-bit real number.
int32
A positive 31-bit number.
int16
A positive 16-bit number.
int16_n
A positive or negative 16-bit number.
int8 A positive 8-bit integer.
int1 (labeled as "i" in the diagram) A boolean value.
prf_$edit_job_t
An enumerated type for specifying the intended operation in the
prf_$edit_job call. It takes one of the following values:
prf_$del_job
Delete the job.
prf_$prior
Alter the job's priority.
prf_$time_print
Postpone printing the job.
prf_$job_entry_t
A record for storing print job information.
15 0
______________________________________________________________
| job_id |
|_____________________________________________________________|
| job_id |
|_____________________________________________________________|
| pr_usr | ... |
|______________________________|______________________________|
| job_name | ... |
|_____________________________________________________________|
| job_priority |
|_____________________________________________________________|
| job_priority |
|_____________________________________________________________|
| job_status | |
______________________________________________________________
15 8 7 0
job_id
An integer label for the job.
pr_usr
The user name or printer name for the job. It has type
prf_$name_t.
job_name
The name of the job. It has type prf_$name_t.
job_priority
The priority of the job.
job_status
The status of the job. It has type prf_$name_t.
prf_$job_status_t
An enumerated type for specifying the status of a print job. It
takes one of the following values:
prf_$prntg
The job is printing.
prf_$idle
The job is idle and waiting to print.
prf_$susp
The job is suspended awaiting a continue signal.
prf_$name_t
A record for passing string arguments to prf_$ calls.
15 8 7 0
______________________________________________________________
| name | ... |
|_____________________________________________________________|
| length |
______________________________________________________________
15 0
name The string. It may be up to 32 bytes long.
length
The number of bytes in name.
prf_$pr_sig_t
An enumerated type for specifying the signal to send with
prf_$signal_printer. It takes one of the following values:
prf_$abort_job
Abort the job.
prf_$suspend
Suspend the job.
prf_$continue
Continue the job.
prf_$printer_array_t
An array of type prf_$printer_t.
prf_$printer_t
A record type for holding information on a printer.
15 8 7 0
______________________________________________________________
| name | ... |
|______________________________|______________________________|
| st | ... |
|______________________________|______________________________|
| des | ... |
______________________________________________________________
15 8 7 0
name The name of the printer. It has type prf_$name_t.
st The status of the printer. It has type prf_$name_t.
des A description of the printer. It has type prf_$name_t.
prf_$read_opt_t
An enumerated type for restricting the information returned by
prf_$read_queue. The type can currently take on only one possible
value:
prf_$read_by_printer
Return a list of jobs by printer.
NOTES
APPLE and LaserWriter are registered trademarks of Apple Computer, Inc.
GENICOM is a trademark of Genicom corporation. IMAGEN is a registered
trademark of the IMAGEN Corporation. POSTSCRIPT is a registered trade-
mark of Adobe Systems. Spinwriter is a registered trademark of NEC.
Versatec is a trademark of Versatec, Inc.