PrintXchange
Command Line Interface Reference Guide
Version 1.2 613P07260 May 1998
Xerox Corporation
701 S. Aviation Boulevard El Segundo, CA 90245 Publication 613P07260 May 1998
© Copyright 1997-1998 Xerox Corporation. All rights reserved.
Portions of this software also include copywritten software modules from Sun Microsystems, Digital Equipment Corporation, and Raima Corporation.
Copyright protection claimed includes all forms and matters of copyrightable material and information now allowed by statutory or judicial law or hereinafter granted, including without limitation, material generated from the software programs which are displayed on the screen, such as icons, screen displays, looks, etc.
Xerox, The Document Company, the stylized X, and all Xerox product names mentioned in this publication are trademarks of Xerox Corporation. Sun, SPARCstation, NIS, NIS+, OpenWindows, and Solaris are registered trademarks of Sun Microsystems, Inc.
1. Overview
The PrintXchange Command Line Interface Reference Guide provides information on maintaining and operating the PrintXchange printing system. It consists of the following:
• Chapter 1, an overview of the command line interface
• Chapters 2 through 18, PrintXchange commands
• Appendix A, Attributes
• Appendix B, Filters
• Appendix C, Attribute mapping
• Appendix D, Events
• Appendix E, -r verbose & -r brief attributes
Related documentation
In addition to this guide, the following PrintXchange publications are available:
• Command Line Interface User Guide. A guide available to CLI users that provides information on submitting jobs to your printer using the command line on your workstation.
• System Administration and Operations Guide. A guide intended to be used by PrintXchange administrators and operators when performing the tasks related to day-to-day management of the system.
• UNIX man pages. A quick reference for information on PrintXchange commands. They are available to all UNIX CLI users.
• On-line help files. An on-line guide, available to Windows NT users, that provides information on PrintXchange functionality.
OVERVIEW
Notation conventions
This guide uses the following command line notation conventions:
• Attribute names and actual values of variables are presented in bold text. For example, class=job.
• Variable information is presented in italic text. For example, filename, option_argument, object_instance,
class=class_name.
• Square brackets ( [ ] ) indicate that the information within the brackets is optional. The brackets themselves are not part of the option/operand and should not be included in the command line.
• Ellipses ( ... ) denote that one or more occurrences of an option or operand is allowed. When an option or operand followed by ellipses is enclosed in square brackets, then zero or more options or operands are allowed.
Examples:
— command_name -a option_argument ... [operand ... ] One or more instances of option_argument can be present for a single instance of the -a option. Zero or more operands can be present.
— command_name [-b option_argument] ... [operand ... ] Zero or more instances of the -b option can be present.
Each instance of the -b option has one instance of option_argument. Zero or more operands can be present.
About the CLI
This chapter describes the syntax and behavior of the command line interface (CLI). The CLI is accessible through the UNIX workstation and through the Windows NT and Windows95 console mode (via the DOS command prompt).
The CLI gives you access to all of the PrintXchange functionality. The CLI consists of commands that you may invoke either directly or by scripts.
OVERVIEW
CLI for Windows NT
For Windows NT users, the CLI provides the PrintXchange
administrator with a programmable interface that enables batch and off-hours processing as well as integration with other script-enabled applications. It also provides access to PrintXchange processing information that enables the administrator to better manage the printing system.
Depending on the administrator's system knowledge as well as the goals of the printing system, the CLI for Windows NT can reside in any of the following three environments:
• Windows NT Command Interpreter + Resource Kit
This environment is recommended for administrators who want to use simple scripts and who are familiar with DOS batch scripts.
• Bourne Again Shell (BASH)
This environment is recommended for administrators who are familiar with the UNIX shell environment.
• Practical Extraction and Report Language (Perl)
This environment is recommended for administrators who want to use complicated text processing scripts.
OVERVIEW
CLI user privileges
PrintXchange users are classified by privilege level. The ability to access PrintXchange commands depends on the privilege level assigned. The three privilege levels are:
• End user
• Operator
• Administrator
The user privilege levels have an access order. An administrator can configure objects in addition to performing all operator tasks. An operator can control printing and perform all end user tasks.
End user
As an end user, you can:
• Submit a print job to a printer supported by the print server.
• List the names and values of print object attributes.
• Request the status of print jobs.
• Modify or set job and document attributes of your previously submitted jobs.
• Remove (cancel) your previously submitted print jobs or particular documents within a multi-document job.
• Request that your print jobs be resubmitted to another specified printer.
• Pause and resume printing of your jobs.
Operator
In addition to accessing all of the commands available to the end user, an operator can:
• Delete previously submitted print jobs or particular documents within a multi-document job.
• Cause a specified print job to be moved forward to print next on
OVERVIEW
• Resume paused jobs, printers, queues, or spoolers.
• Delete all jobs residing on a spooler.
• Delete all jobs in a queue.
• Shut down a spooler or supervisor.
Administrator
In addition to those commands performed by end users and operators, an administrator can:
• Create initial-value-documents, initial-value-jobs, printers, or queues, and set their attributes to the values specified in the options.
• Delete document, job, initial-value-document, initial-value-job, printer, server, and queue objects.
• Set the attribute values for all print objects.
• Set event notification and access rights for all print objects.
• Generate data for a print job accounting report.
• Display attributes in the object identifier database and add attributes to the database.
OVERVIEW
CLI syntax and elements
The syntax for all PrintXchange commands has the following format:
Figure 1-1. Command syntax
The four syntax elements are:
• Command
• Option
• Option argument
• Operand
Commands
There are many PrintXchange commands that control printing system operations. The commands include parameters that specify print objects and options.
The command name must always be the first element on the command line, If no options are specified, the default options for the operand are applied when the command executes. If no operand is specified, the default operand for the command is used when the command executes.
The following tables describe the CLI commands available to the three classes of PrintXchange users. The descriptions in each table pertain to the privilege level of the user. For instance, the pdset capabilities of an administrator extend beyond the support permitted for an operator. Similarly, the pdmod capabilities of an operator extend beyond those of an end user.
command_name [-a] [-b option_argument] [object_instance . . .]
Options
Option argument Command
Operand
OVERVIEW
Table 1-1. CLI administrator commands
Table 1-2 lists the CLI commands an operator is allowed to use to maintain PrintXchange systems. In addition to the commands shown, an operator has access rights to all end user commands
Table 1-2. CLI operator commands Command Description
pdcreate Create an object and set its attributes.
pddelete Delete an object.
pdset Set the attributes of all supported printing objects.
pdaccount Generate data for a print job accounting report.
Command Description
pdclean Remove all jobs scheduled on a specified server or queue.
pddisable Stop acceptance of print jobs by servers, printers, or queues.
pdenable Allow acceptance of print jobs by servers, printers, or queues.
pdpause Pause jobs, physical printers, queues, and spoolers.
pdpromote Promote a job to print next on a logical printer.
pdresubmit Resubmit queue and job objects.
pdresume Resume paused jobs, physical printers, queues, and spoolers.
pdset Set xxx-ready attributes of physical printer objects.
pdshutdown Shut down servers.
OVERVIEW
Table 1-3 lists the CLI commands an end user is authorized to use to submit jobs and obtain the status of those jobs on PrintXchange systems.
Table 1-3. CLI end user commands
Options
Options and option arguments modify the default behavior of PrintXchange commands. As shown in Figure 1-2, options are preceded by a hyphen character ( - ).
Figure 1-2. Options and argument syntax Command Description
pdls List attributes of print objects such as jobs and documents.
pdmod Modify user's previously submitted jobs.
pdpause Pause user's jobs.
pdpr Submit a print job.
pdq Report or obtain status of print jobs.
pdresubmit Resubmit print jobs to another logical printer.
pdresume Resume user's jobs.
pdrm Remove (cancel) user's print jobs.
pdset Set attributes of user’s print jobs
command_name [-a] [-b option_argument] [object_instance . . .]
Options
Option argument
OVERVIEW
Table 1-4 lists the options available for the various CLI commands.
Table 1-4. Common options and arguments
Option/Argument Used with these commands
Description
-c class_name pdclean pdpause
pdcreate pdresubmit pddelete pdresume pddisable pdset pdenable pdshutdown pdls
Identifies the object class of the operand.
-f filename pdpr Identifies a file that is to be printed as a document in a print job.
-f filter_text pdls pdq Specifies the selection criteria to be used among candidate objects. (Refer to Appendix B of the PrintXchange Command Line Interface Reference Guide for information on filters.)
-F pdls pdq Turns off all filtering, including any default filtering
provided when the -f option is unspecified.
This option takes precedence over any -f filter_expression options that are specified.
-g pdcreate pdpr
pdls pdq
pdmod pdset
Turns off column headings on output of requested attributes specified with the
-r option.
-h All commands Displays help information about the command.
-m message_text pdclean pdpause pdcreate pdpromote pddelete pdresume pddisable pdrm pdenable pdset
pdmod pdshutdown
Attaches a message to the specified object.
-n copies pdmod pdpr Specifies the number of copies of the print job that should be printed.
-N notification_method pdmod pdpr Specifies how a user wishes to be notified of events that occur during print job processing. (Refer to Appendix D of the PrintXchange Command Line Interface Reference Guide for a list of events and messages.)
-p printer_name pdpr pdq Specifies the printer to which the print job is to be submitted.
-r requested_attributes pdcreate pdpr
pdls pdq
pdmod pdset
Specifies those attributes the command writes to standard output. (Refer to Appendix E of the PrintXchange Command Line Interface Reference Guide for a list of attributes written to output when this option is used.)
-r retention_period pdrm Specifies the amount of time a server should keep a job in the retained state before deleting the job.
OVERVIEW
Option arguments
As shown in Table 1-4, many options require arguments. Options and their associated arguments modify the default behavior of PrintXchange commands.
For example, the following command does not include an option or argument. It submits a document called report.txt to the default printer.
pdpr report.txt
However, to indicate a specific printer, you may use the -p option and its required printer_name argument. The following command submits report.txt to the printer named joes-printer.
pdpr -p joes-printer report.txt
An option argument always follows the option, separated by at least one space. When an option includes several arguments, each argument must be separated with a space or a comma.
Operands
Operands identify the object a command affects when executed. In this guide, the operand is referred to as the object_instance.
-s style_name pdcreate pdpr
pdls pdq
pdmod pdset
Determines the style (format) in which output is written to standard output.
-t job_name pdmod pdpr Assigns a name to a new print job.
-w when_time pdshutdown Specifies when you want the server to shut down.
-x extended_attribute_string All commands Identifies one or more attribute=value pairs to be used by the command. (Refer to Appendix A of the PrintXchange Command Line Interface Reference Guide for detailed information on attributes.) -X attribute_filename All commands Identifies a file that contains attribute=value pairs to
be used by the command.
Option/Argument Used with these commands
Description
OVERVIEW
Figure 1-3. Operand syntax
The syntax of object_instance is:
• object_name
Where object_name is the name of a spooler, supervisor, queue, logical printer, or physical printer. Since these objects have their names registered with the PrintXchange Name Service, their unique names are known after creation.
• [spooler_name:] object_name
Where object_name is the name of a non-registered object, such as a job identifier, document identifier, initial-value- document, or initial-value-job.
The optional [spooler_name:] portion of the object_instance refers to the name of the spooler the object was created on. If the spooler name is omitted, the default spooler name is assumed.
The following conditions apply to object_instance:
• The object_instance specified in the command line must correspond to the default class for that command or to the class specified with the -c class_name option. Table 1-5 lists
PrintXchange object classes.
• When using the pdls or pdq command, the object_instance may be omitted. The object_name that the command affects is either the default spooler, default queue, or default logical printer (depending on the object class specified).
• The order of multiple operands specified in the command line may be important, depending on the command.
command_name [-a] [-b option_argument] [object_instance. . .]
Operand
OVERVIEW
Table 1-5. Object classes
Object class Definition
server The name of the server the command affects. * printer The name of the printer the command affects. * queue The name of the queue the command affects. *
job The system-assigned number that uniquely
identifies the job the command affects.
document The system-assigned number that uniquely identifies the job, and the number that identifies the position of the specific document within the job, that the command affects.
initial-value-job The name of the specific initial-value-job the command affects. *
initial-value-document The name of the specific initial-value-document the command affects. *
* = These object names are assigned by the administrator when the object is created.
OVERVIEW
Attributes
The -r requested_attributes and -x extended_attribute_string options include attributes as arguments.This chapter discusses two types of attributes:
• Object attributes
• Client attributes
Object attributes are properties or characteristics of print objects.
Client attributes specify parameters for the operation of CLI commands.
Object attributes
PrintXchange objects are defined by a set of object attributes. Each object attribute has values associated with it. In this guide, attributes are referred to as:
• Not settable - you cannot change the value of these attributes.
An example of an attribute that is not settable is printer-state.
This attribute indicates the current state of a printer. Its values include idle, printing, needs-attention, and paused.
PrintXchange automatically sets the value of this attribute when the printer state changes. You cannot set the value yourself.
• Settable - you can change the value of these attributes. By doing so, you change the characteristics of the print object associated with the attribute.
An example of a settable attribute is sides. This attribute specifies if a job should be printed on one or two sides of the paper. You can set the attribute to 1 or 2, depending on your needs.
• Settable only at object creation - you can set the value of these attributes only at the time you create the object.
An example of an attribute that is settable only at object creation is printer-name. This attribute specifies a unique name for an individual printer. You can set this attribute only when creating the printer object. Thereafter, you cannot modify the attribute.
Attributes can be applied to a print object in one or all of the following ways:
• As system defaults.
• By including the -x extended_attribute_string option and argument in the command line. This specifies a series of attributes and their corresponding values.
• By including -X attribute_filename option and argument in the command line. This identifies an attribute file to be read by a command. The attribute file contains attributes and their corresponding values.
Note: Refer to Appendix A of the PrintXchange Command Line Interface Reference Guide for a listing of all supported object attributes.
OVERVIEW
Client attributes
Client attributes modify the action of CLI commands entered at the client.
Client attributes are mainly used to allow what would normally be an option to be entered as an argument to the -x option. For example:
-c server is identical to -x "class=server"
-X attribute_filename is identical to -X "attributes=attribute_filename"
-s line is identical to -x "style=line"
Client attributes are used to:
• Format output regarding print object status and properties.
• Copy attributes from one object to another.
• Specify the length of time a server should keep a job in the retained state after it has been terminated.
PrintXchange supports the following client attributes:
• attributes
• class
• copy-from
• count-limit
• document-filename
• filter
• headings
• requested-attributes
• retention-period
• scope
• style
• time-limit
• when
Note: Refer to Appendix A of the PrintXchange Command Line Interface Reference Guide for an explanation of the above client attributes.
OVERVIEW
Attribute value string syntax
The representation for both object and client attributes is the following:
• The attribute name, which identifies the specific attribute.
• An operator, the equal ( = ) sign, which indicates that the attribute is to be set to a new value.
• The new attribute value.
For example,
When creating a new printer, the administrator sets the following attribute to identify the physical location of the printer:
"printer-locations = 'LabA, BldgM1' "
Most of the CLI commands accept the -x option followed by a list of attributes and their values. This list is called an attribute value string.
Table1-6 defines quoting rules for attribute value strings. The rules in the table apply to the POSIX shell as well as the Bourne and Korn shells. Special rules for the C shell are explained later in this chapter.
Since the POSIX shell is not generally available, PrintXchange supports only scripts written for the Bourne shell.
Table 1-6. Quoting rules for attribute value strings
Rule Rule example
Use of quotes
You can always surround the entire attribute value string in double quotes.
-x "attribute = value"
Multiple attributes in a single command You can enter multiple attribute value strings by using either
multiple instances of the -x option or by
a single -x option followed by multiple attribute value strings enclosed in double quotes.
-x "attribute1 = value1" -x "attribute2 = value2"
is the same as
-x "attribute1 = value1 attribute2 = value2"
However, the following is incorrect:
-x attribute1=value1 attribute2=value2 Multiple values for an attribute
Specify attributes with multiple values by enclosing the entire attribute value string with double quotes
or
enclosing only the value with double quotes.
The following examples are both correct:
-x attribute = "value1 value2 value3"
-x "attribute = value1 value2 value3"
OVERVIEW
Special rules for the C shell
The C shell and the Bourne shell handle input differently. Because of these differences, when using the C shell, you must enter attributes and values according to the following rules:
• Do not use double quotes within double quotes or single quotes within single quotes.
This rule is true, regardless of the use of escape characters ('\').
Incorrect:
Text attributes with spaces
Specify attributes with text type syntax that includes spaces by surrounding it with two levels of quotes.
Note that single-quote (') notation is not available in Windows NT Command Interpreter and PERL.
The following examples are all correct:
-x attribute = " 'single valued string with spaces' "
-x 'attribute = "single valued string with spaces" '
-x attribute = " 'value1 with spaces' 'value2 with spaces' "
-x "attribute = value attribute = 'a text attribute with spaces' "
Text with internal quotes
You must precede quotes or apostrophes within an attribute value by a backslash.
Note that a backslash is not needed in Windows NT Command Interpreter.
The following examples are all correct:
-x attribute = " 'It\'s time to retire' "
-x "attribute = 'Bob\'s printer' "
-x "attribute = 'Quote of the day: \"It ain\'t over till it\'s over\" ' "
White space (spaces, tabs) within attribute strings
White space is parsed out if you do not enclose it within the value string.
Note that single-quote (') notation is not available in Windows NT Command Interpreter and PERL.
The following two examples are identical:
-x " attribute= 'Hello World' "
-x "attribute='Hello World' "
Complex attributes
These are specified using braces { }. Each component of the complex attribute is enclosed with these braces as if it were itself an attribute.
-x "results-profile = {delivery-method=pickup results-set- comment=" 'As soon as possible' " job-copies=3 output- bin=top}"
Rule Rule example
OVERVIEW
• You must enclose the asterisk ('*') in quotes.
Incorrect:
pdls -f job-name*
pdls -f message*=" 'Initial String' "
Correct:
pdls -f "job-name*"
pdls -f "message*='Initial String' "
Special rules for the Windows NT Command Interpreter
The following special rules apply to the Windows NT Command Interpreter:
• You cannot use single quote (') notation.
The Command Interpreter cannot interpret single quote (') notation. If you need to specify text attributes with space, you must specify attributes separately. For example:
— POSIX shell
pdpr -x attribute=" 'value1 with spaces' 'value2 with spaces' "
— Command Interpreter
pdpr -x attribute="value1 with spaces" -x attribute+="value2 with spaces"
• You cannot use a back quote (‘)
The Command Interpreter does not have a back quote (‘) function. You must use file redirection or the FOR /F command.
For example:
— File Redirection
pdpr -c printer SERVER_spl:>tmpfile.txt
— FOR /F command SET printers=
FOR /F "skip=2" %i IN ('pdls -c printer SERVER_spl:') DO pdenable -c printer SERVER_spl:%i
• Escape character
If you need to use a special character of the Command Interpreter (&,(,),|) as a value string, you must precede the character with a caret (^) character or use a double quote ("). For example:
— pdpr -x message=Bye^&Bye hello.ps or
— pdpr -x message="Bye&Bye"
If you need to use a double quote (") character as a value string, you must precede it with a backslash (\) character. For example:
— pdpr -x message=\"Hello\" hello.ps
OVERVIEW
• No unfolding wildcard character
The Command Interpreter does not unfold the wildcard character. For example:
— pdpr -p Printer1 *.ps causes
— Client File System Error - directory or file not found <*.ps>
• You cannot use block sentence
The Command Interpreter does not have block sentence.
Instead, use the parentheses ((,)) characters and the ampersand (&) character to group multiple commands. For example:
— IF "%1" == "SPL" (ECHO - enable spooler - & pdenable -c server %COMPUTERNAME%_SPL)
The CALL command is also available to execute another script.
For example:
— IF "%1" == "SPL" CALL enablespooler.bat
%COMPUTERNAME%_spl
Clearing attribute values
There may be cases in which you need to clear an attribute of all values.
For instance, you might have set the media-ready attribute as follows:
pdset -c printer -x media-ready=na-letter-white myprinter_PP
However, all trays on your printer may be out of service. In this case, you can clear the media-ready attribute of all values by entering:
pdset -c printer -x media-ready="{}" myprinter_PP For information on using the +, -, and = operators to modify attributes, refer to Chapter 9, pdmod.
Attribute files
OVERVIEW
You can use an attribute file in the following ways:
• Use the -X option and specify the attribute file name. For example:
pdset -X AttrFilePP2 PhysPtr2
• Use the -x option and the client attribute attributes. For example:
pdset -x “attributes=AttrFilePP2” PhysPtr2
• Both of the above
The attribute file in the preceding two examples might look like this:
# Physical Printer Attribute File
# AttrFilePP2
document-formats-supported =PCL PostScript maximum-copies-supported =3
document-sheets-supported =none doc-set-start-copies-separate printer-timeout-period =05
The following command is equivalent to using a pdset command that references the preceding attribute file with the -X or -x option:
pdset -x “document-formats-supported=PCL
PostScript maximum-copies-supported=3 document- sheets-supported=none doc-set-start-copies- separate printer-timeout-period=05” PhysPtr2
Special rules for attribute files
Attribute files contain extended attribute strings comparable to those you specify in the command line with the -x option. The following rules apply to the use of attribute files:
• An attribute value string must reside in one line only. Even if the line seems too long, you cannot split a value string into multiple lines.
• The maximum length for a line in an attribute file is 1024 characters.
• Each line in the file can contain one or more strings.
• An attribute file can reference another attribute file by specifying the attribute value string "attributes=attribute_filename." There is no limit to how many attribute files you can nest; however, you must not exceed your system limits for the number of open files.
• If the path to the attribute file is included in the
attribute_filename, the command uses the specified path. If the path is not included, PrintXchange uses the path designated by the PDPATH environment variable.
• Using the comment character ( # ) in an attribute file causes everything that appears after it on the line to be ignored.
OVERVIEW
Environment variables
You can use environment variables to hold information specific to your system and site configuration. For example, you can use environment variables to set defaults, determine paths to locate files, provide numeric, character, and date and time format information, and the language to be used.
The CLI commands use the current value of an environment value as the default, unless you specify a different value in the command line.
Table 1-7 lists environment variables that, based on their value, may affect CLI commands.
Table 1-7. Environment variables that affect CLI commands
Variable Description
NLSPATH Specifies the directory path for CLI message files only if the files do not reside in the standard directory. Standard directories are listed in the PrintXchange System Administration and Operations Guide.
PDDOMAIN (Windows NT only)
Specifies the domain name used on operations that do not specify the domain-name attribute for cross-domain or cross-platform requests. For cross-platform objects, the UNIX domain name must be prefixed by nis:
PD_OID_DB_PATH Specifies the path to the directory containing the object identification (OID) database files only if the OID database does not reside in the default location. Default directory locations are listed in the PrintXchange System
Administration and Operations Guide.
PDPATH Consists of a colon-separated list of directories (paths) that are successively tried for the file name specified in the -X attribute_filename option.
The PDPATH environment variable is processed for attribute_filename in the same way the PATH environment variable is processed for logical command names.
PDPRINTER Determines the default logical printer when the printer- name-requested attribute or the -p printer_name option is unspecified.
Also determines the default server when you do not specify a server. The default server is the server associated with the default logical printer.
OVERVIEW
In addition to the environment variables listed in the preceding table, the following environment variables used for localization may affect the behavior of the CLI.
In the UNIX environment:
• LANG
• LC_ALL
• LC_COLLATE
• LC_CTYPE
• LC_MESSAGES
• LC_NUMERIC
• LC_TIME
In the Windows NT environment:
• NS_LM_LF
• PX_ROOT
Refer to the PrintXchange System Administration and Operations Guide for a detailed description of environment variables.
Exit values
When a PrintXchange command has completed, it returns one of the following:
0 A zero value indicates the command completed successfully.
>0 A non-zero value indicates that an error occurred.
OVERVIEW
2. pdaccount
Name
pdaccount - format data for a print job accounting report.
Synopsis
pdaccount [-o outfile] [-s start_date] [-e end_date] [-d] [-a] [-g]
[-p accounting_log_path] [-O oid_database_path] spooler_name
Description
Use this command to access and report print job accounting information when a job terminates for any reason (canceled, aborted, or printing completed). The output from this command is a
tab-delimited file that can be presented in a spreadsheet format.
Use this command to display help about pdaccount.
pdaccount -h
access level Administrator and operator
PDACCOUNT
Options
The following options are supported for pdaccount.
-o output
Specifies the name of the output file. If not specified, the report is written to standard output.
-s start_date
Specifies the beginning date for the log files. The format for start_date is yyyymmdd. If this option is omitted, the start date becomes the earliest file found.
-e end_date
Specifies the ending date for the log files. The format for end_date is yyyymmdd. If this option is omitted, the end date becomes the most recent file found.
-d
Deletes the accounting files after the pdaccount command has completed. Note that this option only deletes files that have been processed by this run of pdaccount, not any other accounting files.
-a
Indicates the output file should include both job and document attributes. If this option is not specified, the output file includes job attributes only.
-g
PDACCOUNT
-p accounting_log_path
Specifies the path to the account log data. When the database for the spooler is initially set up using the pdmakedb command, an optional switch (-p accounting_log_path) can be used to tell the server where to store accounting log files. When the server is first started, the directories that make up this path will be created.
Note: If the -p switch is not included in the command, the accounting log directory defaults to /var/pd/acct/.
-O oid_database_path
Specifies the path to the object identifier database (OID).
spooler_name
The name of the spooler that collects the accounting data.
PDACCOUNT
Usage
By default, the spooler automatically collects job information, writes it to the accounting file, and keeps the file for three days. The administrator can disable or enable this feature for a specific physical printer by using the pdset command on the supervisor to set the printer's accounting-enabled attribute to no (accounting- enabled=no).
A PrintXchange administrator can send a set (pdset) command to a spooler to construct an accounting profile with the accounting- profile attribute. The accounting profile identifies the job and document attributes that the spooler collects for the accounting log.
If the accounting-profile attribute is not specified, the spooler collects data for the attributes contained in the attribute default- accounting-profile. (Refer to Appendix A of the PrintXchange Command Line Interface Reference Guide for further details on accounting attributes.)
Table 2-1 describes the content of the default accounting data record collected for each job. The attributes that are logged may differ from those shown in the table if the administrator set values for the accounting-profile attribute.
Table 2-1. pdaccount output Object Attribute name Description
Job accounting-information The account to be charged for any services rendered.
Job completion-time The time at which the job completed printing.
Job document-sheets The auxiliary sheets the server inserts in the job.
Job impressions-completed The total number of impressions the printer placed on the media for the job, including repeated impressions due to multiple copies.
Job job-comment Text associated with the job that is meant to print on separator pages.
Job job-copies-completed The number of copies of the job that have been printed.
Job job-fault-count The counter which increments each time the job is returned by the supervisor due to a crash of the spooler or supervisor.
Job job-finishing The finishing process applied to each job copy of the printed output.
Job job-identifier A number, generated by the spooler, that uniquely identifies the job.
PDACCOUNT
Job media-sheets-completed The total number of media sheets the printer completed printing for the job, including repeated pages due to multiple copies.
Job number-of-documents The number of documents contained in the job.
Job pages-completed The total number of pages the printer completed printing, including repeated pages due to multiple copies.
Job printer-name-requested The logical printer that was used for the print request.
Job printers-assigned The physical printer that printed the job.
Job results-delivery-method The delivery method for notification results and output results.
Job started-printing-time The time the job started printing.
Job submission-time The time the last print request was made for the job.
Job total-job-octets The size of the job, in bytes, including all copies.
Job user-name The person requesting access to the pdpr command.
Document copies-completed The number of complete copies of the document that were printed.
Document document-file-name The name of the document file, if any, with complete path.
Document document-format The data syntax used to encode the final printed form of a document.
Document document-type Indicates if the document processed by the print operation was a printable document, a font, or a resource.
Document finishing The finishing process applied to the document.
Document number-up The number of page images imposed on a single instance of a selected medium.
Document plex Indicates if page images were conditioned for one or two sided printing.
Document print-colour-type-used The color specified in the document.
Object Attribute name Description
PDACCOUNT
3. pdclean
Name
pdclean - remove jobs from a queue or spooler.
Synopsis
pdclean-c class_name [-m message_text]
[-x extended_attribute_string ... ] [-X attribute_filename ... ] object_instance ...
Use this command to display help about pdclean.
pdclean -h
Description
Use the pdclean command to remove (delete) all the jobs on any specified spooler or queue. Consider the following items when using this command:
• Before the command can be executed, the queue or spooler to be cleaned must be disabled.
• The queue or spooler cannot be enabled during the clean process.
• The pdclean command is equivalent to entering a pdls command on the queue or spooler followed by a pddelete of all the jobs found.
• Back up any jobs that should not be deleted as follows:
— Resubmit all the jobs to another queue or spooler.
— If resubmitting is not possible, notify all users to retain a copy of their job.
• The pdclean command deletes all jobs, including those in a retained state.
• Jobs cannot be removed from a supervisor.
• Removing a particular job may be rejected if the job is already printing at the associated physical printer.
• If a notification-profile was set up for the spooler, a "clean complete" event is delivered to the client when the pdclean command is complete.
PDCLEAN
access level Operator
Note: An administrator uses this command as an emergency measure to fix a problem.
Options
The following options are supported for pdclean.
-c class_name
Specifies the class, or type, of object from which you are removing jobs.
argument The following values are allowed for class_name.
• server
• queue
Note: There is no default; either queue or server must be specified. If you do not specify class_name, PrintXchange returns an error (can't find printer).
If you use the -x extended_attribute_string string option or the -X attribute_filename file option, the comparable client attribute type and value is the following:
class=class_name
-m message_text
Use this option to include a message about the queue or spooler that you are cleaning. For example, when a spooler is to be cleaned the message attached to the spooler might be:
-m "Cleaning. Big-Spooler down for 10 minutes"
If you use the -x extended_attribute_string option or the -X
attribute_filename option in the pdclean command, the comparable client attribute type and value is the following:
message=message_text
PDCLEAN
-x extended_attribute_string
Use this option to specify a series of attribute=value pairs on the command line that will be processed by the pdclean command.
attributes Object attributes cannot be used in the -x option.
You can specify the following client attributes:
• attributes
• class
• message
syntax Follow the syntax rules for attribute value strings, listed in the Overview chapter of the PrintXchange Command Line Interface Reference Guide.
Note: You can produce the same result by including the
extended_attribute_string in an attributes file and identifying that file as the attribute_filename in the -X option.
-X attribute_filename
The -X option identifies an attribute file to be read by the command.
When the pdclean command executes, the attribute data included in the file is processed at the current point in the command line as though it had been specified with the -x option.
attributes Object attributes cannot be used in the -X option. Refer to the -x section for a list of the client attributes that may be used.
Note: Refer to the Overview chapter of the PrintXchange Command Line Interface Reference Guide for information on developing an attribute file.
Operands
The value of the object_instance in the operand is based on the value of the -c class_name option or the class=class_name attribute.
spooler_name When the class of the object is server, the value of spooler_name is the name of the specific spooler to be cleaned.
queue_name When class of the object is queue, the value of queue_name is the name of the specific queue to be cleaned.
PDCLEAN
Examples
1. Remove all jobs from the spooler named bob.
pdclean -c server bob
2. Delete all jobs from the spooler named bob, using the class attribute instead of the class option.
pdclean -x "class=server" bob
3. Remove all jobs currently in the queue named central, on the spooler named big-spooler.
pdclean -c queue big-spooler:central
4. pdcreate
Name
pdcreate - create a printer, queue, initial-value-job, or initial-value- document.
Synopsis
pdcreate [-c class_name] [-g] [-m message_text] [-r requested_attributes] [-s style_name]
[-x extended_attribute_string ... ]
[-X attribute_filename ... ]object_instance ...
Use this command to display help about pdcreate.
pdcreate -h
Description
Use the pdcreate command to create a logical printer, physical printer, queue, initial value job, or initial value document object.
Consider the following items when using this command:
• The new object is permanent and remains in place after shutdown and restart operations.
• NameSpace considerations:
— When creating printers or queues, the command will fail if an object of the same name already exists in the Name Service, even if the object is of a different class.
— In the Windows NT environment:
— For PrintXchange Name Service, the name is automatically registered with the Name Service.
PDCREATE
— In the UNIX environment:
— In the Local File environment, the administrator must propagate the change throughout the network since the object name is only added to the Local File NameSpace of the current host issuing the pdcreate command.
— In the NIS environment, the administrator must manually add a new printer to the NIS NameSpace database (printers.conf.byname) and communicate this change throughout all the NIS servers operating in the same domain.
• You can set the values of attributes in the pdcreate command.
Note: You can also use the pdset command to assign values to attributes.
• When creating a physical printer:
— The new printer is created within a supervisor and initialized as disabled (enabled=no).
— A supervisor must be available that can support the connectivity attributes of the new printer. Refer to the PrintXchange System Administration and Operations Guide for details on connectivity support for the Xerox and Reference Supervisors.
— Use a printer attribute file (paf) which contains the connectivity attributes required for the new printer. For example, use the following command to create a physical printer object for an HP LaserJet IIISi printer:
— pdcreate -c printer -X HP_LaserJetIIISi_Level1PS.paf supervisor_name:printer_name
— The two attributes required when creating a physical printer are: printer-model and printer-name.
— The associated-queue and printer-address attributes are required in order to enable the physical printer. If not specified during pdcreate, they need to be added via pdset before pdenable.
— The supervisor automatically updates its physical- printers-supported attribute to acknowledge the new printer.
— The pdcreate command fails if the command line includes
PDCREATE
• When creating a logical printer:
— The new printer is created within a spooler and initialized as disabled (enabled=no). Perform a pdenable on the printer to start accepting print requests.
— The spooler automatically updates its logical-printers- supported attribute to acknowledge the new printer.
— The command fails if the command line includes the printer-initial-value-job or the printer-initial-value- document attribute and the object specified by the attribute does not exist.
— If you include the copy-from=copy_object_instance attribute, the attribute values of the copied logical printer are used as the initial values of the new logical printer. Both the copied object and the new object must reside on the same spooler.
• When creating a queue:
— The initial state of the new queue is disabled and new jobs are not accepted. Use the pdenable command to enable the new queue to start accepting jobs.
— The queues-supported attribute for the spooler is updated to acknowledge the presence of the new queue.
— If you include the copy-from=copy_object_instance attribute, the attribute values of the copied queue are used as the initial values of the new queue. Both the copied object and the new object must reside on the same spooler.
• When creating an initial-value-job:
— A new object is created within the default spooler if a specific spooler name is not included in the object instance.
— An initial-value-job is used by a logical printer. It can also be used as part of a pdpr command.
— If you include the copy-from=copy _object_instance attribute, the attribute values of the copied object are used as the initial values of the new object. Both must reside on the same spooler.
— After the initial-value-job has been created, one of the following commands must be used to associate it with a logical printer:
— If the logical printer already exists, perform a pdset on the printer to set the printer-initial-value-job attribute to the initial-value-job that you just created.
— If the logical printer does not exist, use pdcreate to create a new one. Include the printer-initial-value-job attribute, with the values set to the name of the initial- value-job that you just created.
PDCREATE
• When creating an initial-value-document:
— The new object is created within the default spooler if a specific spooler name is not included in the object instance.
— An initial-value-document can be used as part of the pdpr command.
— If you include the copy-from=copy_object_instance attribute, the attribute values of the copied object are used as the initial values of the new object. Both must reside on the same spooler.
— After the object has been created, one of the following commands must be used to associate it with a logical printer:
— If the logical printer already exists, perform a pdset on the printer to set the printer-initial-value-document attribute to the initial-value-document that you just created.
— If the logical printer does not exist, use pdcreate to create a new one. Include the printer-initial-value- document attribute, with the value set to the name of the initial-value-document that you just created.
access level Administrator
Options
The following options are supported for pdcreate.
-c class_name
Specifies the class, or type, of object you are creating.
arguments The values allowed for class_name are the following:
• printer (This is the default.)
• queue
PDCREATE
-g
Use this option to omit line or column headings.
If you use the -x string option or the -X file option, the comparable client attribute is the following:
headings=no
-m message_text
Use this option to include a message about the object that you are creating. For example, when a queue is to be created, the message attached to the new queue might be:
-m "Queue2 will soon be accepting jobs."
If you use the -x extended-attribute-string option or the -X
attribute_filename option in the pdcreate command, the comparable client attribute type and value is the following:
message=message_text The option will look like this:
-x "message = 'Queue2 will soon be accepting jobs.' "
To retrieve a message of this type, use the pdls command, specify the object, and include the following option:
-r message
-r requested_attributes
Use this option to specify the attributes that you want pdcreate to write to standard output to generate an attribute report.
arguments The values allowed for requested_attributes are the following:
• verbose
This value specifies that an expanded set of attributes is written to output.
• brief
This value specifies that a subset of the verbose list of attributes is written to output.
• all
This value specifies that all attributes with values are written to output.
• none
This value specifies that no attributes are written to output. This is the default.
Note: Refer to Appendix E of the PrintXchange Command Line Interface Reference Guide for the attributes that are included in the verbose and a brief listing for each print object.
PDCREATE
If you use the -x string option or the -X file option, the comparable attribute is the following:
requested-attributes=requested_attributes
-s style_name
Use this option to define how the output requested with the -r requested_attributes option is to be formatted.
arguments The values allowed for style_name are the following:
• column
The output displays a separate column for each requested attribute. This is the default for every value of the -r requested_attributes option except all.
• line
The output displays a separate line for each requested attribute.
This is the default for the all value of the -r requested_attributes option.
If you use the -x string option or the -X file option, the comparable attribute is the following:
style=style_name
-x extended_attribute_string
Use this option to specify a series of attribute=value pairs on the command line that will be processed by the pdcreate command.
attributes All attributes identified as settable may be used:
Note: Refer to Appendix A of the PrintXchange Command Line Interface Reference Guide for a complete listing of all supported object attributes.
The following client attributes may be used with the -x and the -X option:
• attributes
• requested-attributes
PDCREATE
syntax When you specify the string of attribute=value pairs, follow the syntax rules for attribute value strings listed in the Overview chapter of the PrintXchange Command Line Interface Reference Guide.
Note: You can produce the same result by including the
extended_attribute_string in an attribute file and identifying that file as the attribute_filename in the -X option.
-X attribute_filename
The -X option identifies an attribute file to be read by the command.
When the pdcreate command executes, the attribute data included in the file is processed at the current point in the command line as though it had been specified with the -x option.
attributes Object attributes cannot be used in the -X option. Refer to the -x section for a list of the client attributes that may be used.
Note: Refer to the Overview chapter of the PrintXchange Command Line Interface Reference Guide for information on developing an attribute file.
Operands
The value of the object_instance in the operand is based on the value of the -c class_name option or the class=class_name attribute.
Note: If [spooler_name:] is not specified, the pdcreate command is performed on the default spooler.
[spooler_name:]printer_name When class equals printer, the value of printer_name is the name of the printer to be created. For logical printers, the spooler associated with the new printer assigns the value logical to the printer attribute printer-realization. For physical printers, the supervisor associated with the new printer assigns the value physical to the printer attribute printer-realization.
[spooler_name:]queue_name When class equals queue, the value of queue_name is the name of the queue to be created.
[spooler_name:]ivj_name When class equals initial-value-job, the value of ivjob_name is the name of the initial-value-job object to be created. The object sets default attributes for the jobs that pass through an associated logical printer. A specific job can identify an initial-value-job object to be used for attribute defaults.
[spooler_name:]ivdoc_name When class equals initial-value-document, the value of
ivdoc_name is the name of the initial-value-document object to be created. The object sets default attributes for the documents that pass through an associated logical printer. A specific document can identify an initial-value-document object to be used for attribute defaults.
PDCREATE
Note: If [server_name:] is not specified, the pdcreate command is performed on the server that supports the printer named in the PDPRINTER environment variable.
Examples
1. Create a logical printer named dngbat on the default spooler.
The media supported by this printer is iso-a4-white and a- white.
pdcreate -x "media-supported=iso-a4-white a- white" dngbat
2. Create a physical printer named X4517PS.pp on the supervisor named big-super.
pdcreate -c printer -X /usr/pd/cap/Xerox4517- Level2ps.paf big-super:X4517PS.pp
3. Create a logical printer named dngbat on the default spooler with two supported document formats, PostScript and PCL.
pdcreate -c printer -x "document-formats- supported='PostScriptPCL'" dngbat
4. Create a physical printer named X4517PS_rm3520.pp from the existing printer X4517PS.pp on the supervisor named big- super.
pdcreate -c printer -x copy-
from=big_super:X4517PS.pp X4517PS_rm3520.pp
5. pddelete
Name
pddelete - delete a print object.
Synopsis
pddelete [-c class_name] [-m message_text] [-x extended_attribute_string ... ]
[-X attribute_filename ... ]object_instance ...
Use this command to display help about pddelete.
pddelete -h
Description
Use the pddelete command to delete a logical printer, physical printer, job, queue, initial-value-job, initial-value-document, or server.
The following items should be considered when using this command:
• When multiple objects are specified, they must all be the same class.
• Spoolers, supervisors, queues, logical and physical printers must be disabled before they can be deleted.
• The deleted object is removed from the object database.
• NameSpace database considerations when deleting spoolers, supervisors,queues, logical and physical printers:
— In the Windows NT environment:
— For PrintXchange Name Service, the object entry is automatically removed from the Name Service.
— In the UNIX environment:
— For Local File and NIS, you must propagate the change throughout the network.
— In the NIS environment, the network administrator must remove the object from the NIS NameSpace database (printers.conf.byname) and propagate the information throughout the NIS servers operating in that domain.
PDDELETE
• Deletion of spoolers, supervisors, queues, logical and physical printers performs immediate updates on the server that controls the object to be deleted. Updates to associated objects that are controlled by a different server occur immediately if the
associated server is running; otherwise, the updates occur when the server is started.
• When the object to be deleted is a logical printer:
— The printer-associated-printers attributes for the associated physical printers are updated.
— The logical-printers-supported attributes for the associated server and queue are updated.
• When the object to be deleted is a physical printer,
— The spooler associated with the physical printer must be running.
— All currently active jobs must be deleted or you must wait for them to complete.
— An unregister-printer event is sent to the associated spooler, which updates all affected queues and logical printers.
— The physical-printers-supported attributes for the supervisor, spooler, and queue are updated.
— The printers-ready and printer-associated-printers attributes for the associated logical printers are updated.
— If the specified printer is the only physical printer associated with a queue, the spooler stops scheduling jobs in that queue until it is associated with another physical printer.
— Jobs in the spooler specifying the deleted printer via the physical-printers-requested attribute will remain in a pending state. These jobs must have the physical- printers-requested attribute modified before they can be rescheduled for a different printer.
• When the object to be deleted is a spooler:
— All jobs currently on the spooler must be deleted (i.e., disable and then clean the spooler).
— All associated spooler objects (queues, logical printers, initial-value-jobs, initial-value-documents, and the spooler itself) are deleted.
PDDELETE
• When the object to be deleted is a supervisor:
— All jobs currently in the supervisor must be deleted.
— An unregister-printer event is sent to the associated spooler for each affected physical printer. The spooler removes the printers from all mapping attributes, updating the affected queues and logical printers.
— All physical printers are deleted.
— All dynamic data files that are created and maintained by the supervisor, such as the temporary job data file and object data files, are deleted.
• When the object to be deleted is a job:
— The specified job (and all documents contained in the job) is deleted, regardless of its state.
— The specified job is canceled if it was already delivered to the supervisor and the job stops printing as soon as possible.
— The value of the job-retention-period attribute is set to zero, overriding its previous value, if any. The value of default-job-completion-period is ignored. (This differs from the pdrm command which honors the value of these attributes.)
— The job is removed from the system.
• When the object to be deleted is a queue:
— All jobs must be removed from the queue (i.e.,disable and then clean the queue) or wait until the queue empties.
— The queue is disassociated from its logical and physical printers (the logical and physical printer attributes associated-queue, printer-associated-printers, and printers-ready are set to empty).
— All associated printers are disabled.
— The queue is disassociated with its spooler. (The spooler removes the queue from its queues-supported attribute.)
• When the object to be deleted is an initial-value-job:
— The object is not removed from the printer-initial-value- job attribute on the logical printers. To manually remove the logical printer associations:
— Issue a pdls command for all logical printers on the same spooler to determine the associated logical printers.
— For each associated logical printer, issue a pdset command to associate the logical printer with an existing initial-value-job (set the logical printer’s printer-initial-value-job attribute).
PDDELETE
• When the object to be deleted is an initial-value-document:
— The object is not removed from the printer-initial-value- document attribute on the logical printers. To manually remove the logical printer associations:
— Issue a pdls command for all logical printers on the same spooler to determine the associated logical printers.
— For each associated logical printer, issue a pdset command to associate the logical printer with an existing initial-value-document (set the logical printer’s printer-initial-value-document attribute).
access level Administrator
Options
The following options are supported for pddelete.
-c class_name
Specifies the class, or type, of object you are deleting.
arguments The values allowed for class_name are the following:
• printer (This is the default.)
• job
• queue
• initial-value-document
• initial-value-job
• server
Note: The Operands section describes the specific object_instance associated with each class.
If you use the -x string option or the -X file option, the comparable
PDDELETE
-m message_text
Use this option to include a message about the object that you are deleting. For example, when a printer is to be deleted the message attached to the printer might be:
-m "Printer1 no longer available"
If you use the -x extended_attribute_string option or the -X
attribute_filename option in the pddelete command, the comparable client attribute type and value is the following:
For printers, queues, servers, initial value jobs and initial value documents:
message=message_text For jobs:
job-message-from-administrator=message_text The option will look like this:
-x "message='Printer1 no longer available' "
To retrieve a message of this type, use the pdls command, specify the object, and include the following option:
-r message
-x extended_attribute_string
Use this option to specify a series of attribute=value pairs on the command line that will be processed by the pddelete command.
attributes Object attributes cannot be used in the -x option.
The following client attributes can be used:
• attributes
• class
• message (The message will be deleted along with the object.)
syntax Follow the syntax rules for attribute value strings, listed in the Overview chapter of the PrintXchange Command Line Interface Reference Guide.
Note: You can produce the same result by including the
extended_attribute_string in an attribute file and identifying that file as the attribute_filename in the -X option.
PDDELETE
-X attribute_filename
The -X option identifies an attribute file to be read by the command.
When the pddelete command executes, the attribute data included in the file is processed at the current point in the command line as though it had been specified with the -x option.
attributes Object attributes cannot be used in the -X option. Refer to the -x section for a list of the client attributes that may be used.
Note: Refer to the Overview chapter of the PrintXchange Command Line Interface Reference Guide for information on developing an attribute file.
Operands
The value of the object_instance in the operand is based on the value of the -c class_name option or the class=class_name attribute.
Note: Before you delete the object, run a report on every object that is associated with it so that you can document all of the setup and initialization requirements. You can use this information if you need to create the object again.
printer_name ... When class equals printer, the value of printer_name is the name of the printer to be deleted. The printer to be deleted can be a logical or physical printer.
server_name ... When class equals server, the value of server_name is the name of the server to be deleted. The server to be deleted can be a supervisor or spooler.
[spooler_name:]job_id ... When class equals job, the value of job_id is the unique identifier that points to the job to be deleted.
queue_name ... When class equals queue, the value of queue_name is the name of the specific queue to be deleted.
[spooler_name:]ivjob_name ... When class equals initial-value-job, the value of ivjob_name is the name of the initial-value-job object to be deleted.
PDDELETE
Examples
1. Delete the printer named sams-printer. Notice the -c class_name option is not needed since the default class is printer.
pddisable sams-printer pddelete sams-printer
2. Delete the initial-value-job called ivj1 from big-spooler.
pddelete -c initial-value-job big-spooler:ivj1 3. Delete the queue called centralq from the default spooler.
pddisable -c queue centralq pddelete -c queue centralq
PDDELETE
