Advanced Printing Software users are classified by their access and privilege levels. The ability to access certain commands depends on which access category the user is assigned. Users can be assigned End User, Operator, or Administrator privileges. The End User has access to only certain operations. The Administrator has access to all levels of operation. The Operator access falls in between the End User and the Administrator.
The following sections define the three types of Advanced Printing Software
users.
1.1.1 End User
As an end user you can perform the following operations:
Submit a print job to a printer.
List the names and values of print object attributes.
Request the status of print jobs that they submitted.
Modify or set job and document attributes of jobs that they previously submitted.
Remove, cancel, or delete print jobs or particular documents within a multi-document job that they previously submitted.
Request that print jobs that they submitted be resubmitted to another specified printer.
In addition to accessing all of the operations available to the end user, an operator may perform the following tasks:
Cause a specified print job to be moved forward to print next on the physical printer to which it was submitted.
Request that specified print jobs that have been accepted by a print server be resubmitted to another specified printer.
Enable the acceptance of new print jobs by the specified printer, queue, or server.
Disable the acceptance of new print jobs by the specified printer, queue, server.
Set
xxx-ready
attributes on printers.
Pause pending jobs, currently printing jobs, printers, queues or servers.
Resume paused jobs, printers, queues, or servers.
Shut down the specified printers.
In addition to those operations performed by end users and operators, an administrator can perform the following tasks:
Remove all the jobs currently scheduled on the specified server or queue.
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.
1.2 Command Syntax and Elements
The syntax for all command line utility operations has the format shown below.
utility-name -option-option option-argument object-instance
A command line operation consists of the following elements:
The command
Options and arguments
Operands
A utility is a CLI program that performs Advanced Printing Software functions. The name of the utility must be the first element of the command line. There are several types of utilities.
Table 1-1
lists the CLI utilities used by a system
administrator to create and manage objects in the print system.
Table 1-1: Administrator Utilities
Utility | Description |
pdcreate | Create an object and set its attributes. |
pddelete | Delete an object. |
pdmakedb | Create an object database for a print system supervisor or spooler. |
pdmoddb | Modify an existing object database. |
pdset | Set the attributes of printing objects. |
pdshowdb | Display an object database. |
Table 1-2
lists the CLI utilities used by an operator
to maintain the print system.
Table 1-2: Operator Utilities
Utility | Description |
pdclean |
Remove all jobs scheduled on a specified server, queue, or printer. |
pddisable |
Stop acceptance of print jobs by servers or printers. |
pdenable |
Allow acceptance of print jobs by servers or printers. |
pdpause |
Pause jobs, servers, or printers. |
pdpromote |
Promote a job to print next on a printer. |
pdresume |
Resume paused jobs, servers, or printers. |
pdset |
Set the attributes of printing objects. |
pdshutdown |
Shut down servers or physical printers. |
Table 1-3
lists the CLI utilities used by an end
user to submit jobs and obtain status of those jobs on the print systems.
Table 1-3: CLI End User Utilities
Utility | Description |
pdls |
List printing object attributes. |
pdmod |
Modify previously submitted jobs or documents. |
pdpr |
Submit a print job. |
pdq |
Report or obtain status of print jobs. |
pdresubmit |
Resubmit print jobs to another logical printer. |
pdrm |
Remove print jobs or documents. |
An option is part of a command used to modify the default behavior of a utility. As shown in the following example, options are preceded by a hyphen character ( - ).
command_name argument object_instance
In addition,
Option names consist of a single lowercase or uppercase letter.
All options must precede the operand.
The utility programs interpret options and option arguments in the order in which they appear on the command line.
Due to some repeated options, you must look at the detailed description of the utility to determine which option is valid for each command.
Table 1-4
lists all available options with a brief
functional description.
Table 1-4: Common Options and Arguments
Option | Description |
-c class_name |
Identifies the object class of the operand. |
-f filename |
Identifies a file that is to be printed as a document in a print job. |
-f filter_text |
Specifies the selection criteria to be used among candidate objects. |
-F |
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 |
Turns off column headings on output of requested attributes specified with the-r option. |
-h |
Writes a message to standard output on how to invoke the utility. |
-m message_text |
Attaches a human-readable message to the specified object. |
-n copies |
Specifies the number of copies of the print job that should be printed. |
-N notification_method |
Specifies how a user wishes to be notified of events that occur during print job processing. |
-p printer_name |
Specifies the printer to which the print job is to be submitted. |
-r requested_attributes |
Specifies those attributes the utility writes to standard output. |
-r retention_period |
Specifies the amount of time a server should keep a job in the retained state before deleting the job. |
-s style_name |
Determines the style (format) in which output is written to standard output. |
-t job_name |
Assigns a name to a new print job. |
-w when_time |
Specifies when you want the server to shut down. |
-x extended-attribute-string |
Identifies one or more attribute_type=valuepairs to be used by the utility. |
-X attribute_filename |
Identifies a file that contains attribute_type=value pairs to be used by the utility. |
Many options require arguments. Where applicable, the argument provides the specifics for a given switch. For example, -c queue specifies that the object to be manipulated is a queue rather than the system default for the operation.
As shown in
Table 1-4, not every option requires
an argument.
1.2.4 Attributes
The -x and the -r arguments include attributes. An object attribute is a property or characteristic of a print object. Client attributes specify parameters for the operation of CLI commands. This manual refers to two types of attributes:
Object attribute
Command attribute
Each print object is defined by a set of object attributes. The characteristics of each print object can be changed by setting the values of its attributes. For example:
The value of the printer attribute printer-state indicates the current state of the print object, such as idle or printing.
The value of the printer attribute media-supported identifies the specific media that the physical printer supports, such asiso-a4-white or iso-a4-transparent.
The value of the printer attribute printer-name is the name that uniquely identifies a specific printer.
The value of the document attribute sides can be set to 2 to indicate 2-sided printing is required.
Attributes can be applied to a print object in one or all of the following ways:
As system defaults.
Directly by specifying the attribute and value, called an extended attribute string, in the command line operation.
Command attributes specify parameters for the operation of CLI commands and provide additional capabilities to the user. Command attributes can be used to:
Format print object status and properties information.
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.
1.2.4.3 Attribute Representation
The representation for both object and command 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 = 'Lab A, Bldg. 21'"
1.2.4.4 Attribute Value String Syntax
Most of the CLI utility commands accept the -x option followed by a list of attributes and their values. This list is called an attribute value string. The following list defines the special quoting rules required when the -x option is used:
Double quotes can surround the entire attribute value string.
-x "attribute = value"
Multiple attribute value strings can be entered by either multiple instances of the -x option or by multiple attribute value strings following a single -x option.
-x "attribute1 = value1" -x "attribute2 = value2"
-x "attribute1 = value1 attribute2 = value2"
Attributes that have multiple values are specified by surrounding the entire attribute value string or only the value with quotes.
-x attribute = "value1 value2 value3"
-x "attribute = value1 value2 value3"
Attributes with text type syntax that include spaces must be surrounded by two levels of quotes.
-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'"
Quotes or apostrophes within an attribute value must be preceded by a back slash.
-x attribute = "'It\'s time to retire'"
-x "attribute = 'Bob\'s printer'"
White space (spaces, tabs) within attribute strings.
-x "attribute = 'Hello'"
Complex attributes are specified using braces { }. Each component of the complex attribute is enclosed with these braces as if it were itself an attribute.
-x finishing = {named-finishing=offline finishing-message
= 'Send out for special finishing' }
1.2.4.5 Abbreviating Attributes and Values
You can abbreviate attributes and standard identifier values by using only a few letters of each word in the name or value. For example, you can use the abbreviation j-s for the job-sheets attribute, j-c-s for the job-copy-start value, and specify the attribute=value pair as j-s=j-c-s.
The system accepts only unambiguous abbreviations. For example, abbreviating job-owner as j-o is not valid because it might be confused with job-originator. You need to specify enough of the attribute or value name such that it is unique. If you specify an ambiguous abbreviation, the command is rejected.
Examples of valid abbreviations are j-ow for job-owner, j-or for job-originator, and i-a3-w for iso-a3-white.
You cannot abbreviate name values that are not standard identifiers,
such as site-specific media or tray names.
1.2.4.5.1 Delta Time Syntax
When requesting attributes values that are epxressed in delta time, set all three of the attribute fields. Consider the following examples:
Retain job 2002 for 35 seconds before deleting it from spooler
server
casper
.
pdrm r 00:00:35 casper:2002
The value for minutes is a number 0 through 59. A number greater than 59 is invalid.
Retain job 346 for 4 minutes before deleting it from spooler
server
cheerio
.
pdrm r 00:04:00 cheerio:346
Retain job 663 for 1 hour before deleting is from spooler
server
waffles
.
pdrm r 01:00:00 waffles:663
Time value formats are locale-dependent and may vary from locale to
locale.
For example, a period (.) may be used rather than a colon (:) to separate
the attribute fields on the command line.
1.2.4.6 Attribute Modification Operations
You can include an operator with attribute=value pairs to indicate the type of modification to be done to the specified attribute. The three modification operators are:
+ (add value) - When you use attribute+=value, you add a value to the attribute. This can only be used with multi-valued attributes. If you add a value that already exists, the attribute contains the same value twice.
- (remove value) - When you use attribute-=value, you remove a value from the attribute. If the value is not present, pdset ignores the command. If you remove the last value for an attribute, pdset sets the value to the server. If a value to be removed occurs more than once, pdset removes all occurrences.
= (reset to default value) - When you use attribute==, you set the attribute value to its default. Do not include a value when resetting to the default value.
An attribute file is a user-written file that contains multiple attribute type=value pairs. You use a text editor to create an attribute file. The following rules apply to the use of attribute files:
A line in an attribute file has a maximum length of 1024 characters.
Each line in the file can contain one or more strings but one string cannot span multiple lines.
If the path to the attribute file is included in the attribute_filename, the specified file will be used by the utility. If the path is not included, the PDPATH environment variable is referenced.
Using the comment character (#) causes everything that appears after it on the line to be ignored.
The operand identifies the object on which the command is to be executed. For example; pdpr -p wiley cli.doc means to submit the file called cli.doc to the logical printer called Wiley. In this manual the operand is referred to as the object_instance.
The syntax and conditions of the object_instance are as follows:
[server_name:]object_name
The object in object_name must belong to the class specified in the -c class_name option included in the command line, or by the default. Table 1-5 details object classes and defines the operand associated with each class.
In some cases, the object instance can consist of the name of the server the object is associated with, and the name of the object itself, [server_name:]object name. When this is the case,
If the server name is included, the named object on the specified server is affected by the operation.
If the server name is not included, the named object on the default server is affected by the operation.
If multiple operands are specified in the command line, the order in which they appear may be important based on the specific utility.
Object Class | Definition |
server |
The name of the server the operation is affecting. |
printer |
The name of the printer the operation is affecting. |
queue |
The name of the queue the operation is affecting. |
job |
The system-assigned number that uniquely identifies the job the operation is affecting. |
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 operation is affecting. |
initial value job |
The name of the specific initial-value-job the operation is affecting. |
initial value document |
The name of the specific initial-value-document the operation is affecting. |
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 utilities use the current value of an environment value as the
default, unless you specifies a different value in a command line operation.
Table 1-6
lists four environment variables that, based on their
value, may affect the operation of the CLI.
Table 1-6: Environment Variables that Affect CLI Operations
Variable | Description |
NLSPATH |
The value of this variable becomes the path for CLI message files if the files are not stored in the standard directory. |
PDPATH |
The value of this variable consists of a colon-separated list of directories (the path) that are successively tried for the file that is named in the -X attributes_filename option. |
PDPRINTER |
The value of this variable is used as the default printer by the print client when the attribute printer-name-requested or the option -p printer_name is not included in the command line operation. This variable is also used to select a server for operations when a server is not specified since the server that contains this printer is viewed as the default server. |