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 control file. A control file is a structured file contain-
ing 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 copied to the control file is allocated whenever a
process 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
For a complete list of supported printers and options, see Printing in
the Domain/OS Environment: System Administrator's and
Programmer's Guide.
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".
SPOOL_NODE 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/startup.prf.
TEXT Specifies text mode for printing ASCII files. TEXT is the
default print mode.
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 its normal interpretation
for the target printer.
PAPER_SIZE A|B|LEGAL|A3|A4|A5|B4|B5
Use the specified page size.
__________________________
| 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) |
|______|__________________|
The following print options apply to text files only:
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. The
default state is PORTRAIT. Specifiying this option will over-
ride any auto-rotation performed on bitmaps.
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 |
|_____________|____________________|
|Genicom 3404 | 10, 12, 13.1, 16.7 |
| | |
|_____________|____________________|
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.
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_$job_entry_t
A record for storing print job information.
15 0
______________________________________________________________
| job_id |
|_____________________________________________________________|
| job_id |
|_____________________________________________________________|
| pr_usr |
|_____________________________________________________________|
| pr_usr |
|_____________________________________________________________|
| job_name |
|_____________________________________________________________|
| job_name |
|_____________________________________________________________|
| job_priority |
|_____________________________________________________________|
| job_priority |
|_____________________________________________________________|
| job_status |
|_____________________________________________________________|
| job_status |
______________________________________________________________
15 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 printer is idle and waiting to print.
prf_$susp
The printer is suspended awaiting a continue signal.
prf_$name_t
A record for passing string arguments to prf_$ calls.
15 0
______________________________________________________________
| name |
|_____________________________________________________________|
| 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 0
______________________________________________________________
| name |
|_____________________________________________________________|
| name |
|_____________________________________________________________|
| st |
|_____________________________________________________________|
| st |
|_____________________________________________________________|
| des |
|_____________________________________________________________|
| des |
______________________________________________________________
15 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.