pdls(1)

NAME

pdls — lists selected attribute values

SYNOPSIS

pdls [-c ObjectClass] [ -f "FilterCriteria" ] [-F] [-g] [-j] [ -r "RequestedAttributes" ] [-s StyleName] [-U] [ -x "AttributeValuePairs" ] [-X AttributesFileName] [ServerName... | ServerName:InitialValueDocumentName... | ServerName:InitialValueJobName... | ServerName:LogName... | [ServerName:]PrinterName... | [ServerName:]QueueName... | LocalJobId[.DocNumber]... | GlobalJobId[.DocNumber]...]

pdls -h

DESCRIPTION

You enter the pdls command to request that selected attribute values be displayed for one or more print jobs or other HPDPS objects.

By default, a filter is created when listing jobs which only allows you to see your jobs. The jobs have a predefined value for the filter that is equal to the job attribute user-name; this value is your login identity when you submit a job.
You add to this filter to further restrict the jobs for which information is to be returned.
You must suppress the default filter by using the -U option or turn off all filtering with the -F option to see more than your own jobs.
If you only specify the ServerName as the command argument, the attribute values for all objects belonging to the object class you specify are displayed.
You can list the attribute values for specific jobs by using the local ID or the global ID. You must have submitted the job to use the local ID.

Note: There is a situation when you must use the global ID. If the client daemon responsible for mapping local ID to global ID is not available, HPDPS may not be able to tie the local ID to the global ID. If this situation exists, you must use the global ID, the name of the server (spooler), or an argument specification using global characters.

There is a possible situation that can occur if your administrator has set the PDIDTABLE environment variable to a low value, for example 10. You submit a series of jobs during a short time span such that the number of jobs you have in process is larger than the value set, say 14. You will have two jobs with the local IDs of 1, 2, 3, and 4. However, HPDPS no longer associates the first four jobs with a local ID because those local IDs have been given to the 11th, 12th, 13th, and 14th jobs. Therefore, you must use the global ID to take action for any of the first four jobs.

Options

pdls recognizes the following options:

-c ObjectClass

Specifies the object class of the object whose attributes you want listed. ObjectClass can be one of:

job (default)
document
initial-value-document
initial-value-job
log
printer
queue
server

This option is equivalent to the command-attribute class.

-f "FilterCriteria"

Specifies the filter criteria you want to use in selecting from the candidate objects. Among the candidate objects, only those matching the filter expression are returned. See the command-attribute filter for filter expression details. Using this option is equivalent to specifying the command-attribute filter.

-F: Turns off all filtering (both specified and default). See the -U option for suppressing only the default.

-g: Turns off headings. Using this option is equivalent to specifying the command-attribute headings=false.

-h: Displays a command-specific help message containing information about command syntax and options. This option cannot be used with another option or with an attribute.

-j: Use this option to display only job attributes.

-r "RequestedAttributes"

Specifies the group of attributes that you want displayed for the object class (see -c).

RequestedAttributes can be:

brief (default)
verbose
archive
"AttributesList" 
all
None

Within the valid classes, archive only displays settable and specifiable attributes. all lists all attributes listing first those that do not have values assigned and then those with values assigned.

These values are additive. This option is equivalent to the command-attribute requested-attributes.

-s StyleName

Specifies the format you want the attributes displayed in.

StyleName can be column (default) or line.

column is the default for -r brief and -r verbose.

line is the default for -r all, -r "AttributesList" and -r archive.

See the command-attribute style for detail explanation of the column and line formats. This option is equivalent to the command-attribute style.

-U

Suppresses the default user-name filter.

-x "AttributeValuePairs"

Specifies command attributes.

AttributeValuePairs consists of a single attribute string containing of one or more attribute-value pairs.

-X AttributesFileName

Specifies the designated attributes file to be read and inserted at the current point in the command line. This file contains attribute-value pairs that are used to expand on the command being entered. This option is equivalent to the command-attribute attributes.

Command Attributes

You can also specify these command attributes in a -x "AttributeValuePairs" string or in an attributes file designated with the -X AttributesFileName option.

attributes=AttributesFileName

class=ObjectClass

Specifies the object class you want for this command. ObjectClass can be one of:

job (default)
document
log
printer
queue
initial-value-job
initial-value-document
server

filter="FilterCriteria"

Specifies the selection criteria you want used to select a subset from the candidate objects (if you request attribute values for multiple objects). A filter is a logical expression consisting of relations of attributes to attribute values. Among the objects you specify, only objects whose attribute values match the filter expression are returned.

You can only use attributes for the object class you specify in the command (see the -c option or the class command attribute). The filter may contain an attribute other than one of those you are requesting.

FilterCriteria is a text string delimited by quotes. The filter syntax is one of the following:

1.

A filter item consisting of an "attribute operator value".

Table 1 shows the operators and the data formats they can be used with to separate the attribute and value.

Table 1. Attribute Operators for Filters

				`Time`
`Operation`	`Operator`	`Strings`	`Integers`	`Format`
Equal	`==`	X	X	X
Match first part of a value	`=*`	X	X	X
Match last part of a value	`*=`	X	X	X
Match any part of a value,
such as a substring	`=`	X	X	X
Attribute present (any value)	`==*`	X	X	X
(See Note 1)
Match approximately,
for case-insensitive substring	`~=`	X	-	-
(See Notes 2 and 3)
Match a value greater
than that specified	`>`	-	X	X
Match a value less
than that specified	`<`	-	X	X

Note 1: Testing for attribute present returns true when the attribute has a value, not just when the attribute exists. A false value may be needed to satisfy the requirement such as using quotes, as long as the false value conforms to the general syntax.

Note 2: An approximate match is when at least half of the target string, regardless of starting position, matches the filter value.

Note 3: A case insensitive match is when the target string may have a mix of upper- and lowercase characters, but the character do match.

2.

In the previous table the attribute present operation consists of an attribute name followed by the equality operator followed by an * in the place of an attribute value. For example:

-f "printers-assigned==*" 

If the attribute has no value, the filter item is evaluated as false. It evaluates as true if the attribute has been assigned any value.

3.

Each attribute in a filter item can be compared to only one attribute value. To compare an attribute to more than one value, or to filter on more than one attribute, separate the filter items with one of the following operators:

&&

AND operator, as in: filter-item && filter-item

The expression evaluates to true only if both filter-items evaluate to true.

||

OR operator, as in: filter-item || filter-item

The expression evaluates to true if either of the filter-items evaluate to true.

4.

To evaluate a filter item as false, use the NOT operator before the filter item and enclose the filter item in parentheses.

!

NOT operator, as in: ! (filter-item)

If filter-item evaluates to true, the expression is considered false, and vice versa.

5.

When you use multiple logical operators in a filter, they are evaluated in an order of precedence. You can override the order of precedence by using parentheses (()). See Table 2 for order of precedence.

Table 2 summarizes the filter syntax provided by the HPDPS command line interface. The operators are listed in the order of precedence from highest to lowest.

Table 2. Filter Syntax

`Operator`		`Placement`
`( )`	Parentheses	Around filter items
`> <`	Relational operators	Between attribute and value
`==`	Equality operators	Between attribute and value
`=* = =* ~=`	String matching	Between attribute and value
`!`	NOT Operator	Before (filter-item) only
`&&`	AND operator	Between two filter items
`\|\|`	OR operator	Between two filter items

headings=Boolean

Specifies whether you want the output displayed with or without headings; Boolean can be true (default) or false. See the command-attribute style for examples.

message-count=Number

When you request the log-messages log attribute, this specifies the Number of previous messages you want to see starting from the last message logged. The value you can specify for Number can be an integer from 1 through 2147483647.

Use this command attribute in conjunction with the log object log-messages attribute to query for error log information. For example:

pdls -c log -r log-messages -x "message-count=4" SPOOL1: 

displays the last four messages contained in the error log for server SPOOL1.

requested-attributes=AttributeType

Specifies the group of attributes you want displayed for the specified ObjectClass.

AttributeType can be: brief (default), verbose, archive, "AttributesList", all, or none.

archive: displays only settable and specifiable attributes.
all: lists all attributes, listing first those that do not have values assigned and then those with values assigned.

The following list shows the brief and the verbose attributes that are displayed for the specified object. The brief attributes are a subset of the verbose attributes and are identified in the following list with a ``B'' to the left of the attribute name.

The attributes and their values are displayed in the specified order.

Document Attributes

B: document-sequence-number
B: document-format
: octet-count
: copy-count
: sides
: document-type
B: document-file-name

Initial-Value-Document Attributes

B: initial-value-document-identifier
B: associated-server
B: logical-printers-ready
B: copy-count
B: sides
B: document-format

Initial-Value-Job Attributes

B: initial-value-job-identifier
B: associated-server
B: logical-printers-ready
B: printer-locations-requested
B: printer-models-requested
: job-retention-period

Job Attributes

B: job-client-id (local ID)
B: job-identifier (global ID)
B: job-name
B: current-job-state
: job-state-reasons
B: intervening-job (Only returned on the pdls and pdq commands.)
B: printer-name-requested (Logical printer name to which the job was submitted.)
B: printers-assigned (Physical printer name to which the job has been assigned, if such a scheduling decision has been made.)
: total-job-octets (Sum of all printable files and copies.)
: job-owner

Log Attributes

B: log-identifier
B: log-type
B: associated-server
B: enabled
: log-size
: log-wrap

Printer Attributes

B: printer-name
B: printer-realization
B: printer-state (physical printers)
: associated-server
: printer-locations
: printer-associated-printers (logical printers)
B: enabled
B: associated-queue

Queue Attributes

B: queue-name
B: queue-state
B: scheduler-ready
B: associated-server
: logical-printer-assigned
: physical-printer-assigned

Server Attributes

B: server-name
B: server-state
: logical-printers-supported (for spoolers)
: physical-printers-supported
B: server-type
: queues-supported

style=StyleName

The format in which you want the attributes displayed. StyleName may be either column (default) or line.

column is the default for:

requested-attributes=brief
requested-attributes=verbose

line is the default for:

requested-attributes=all 
requested-attributes="AttributesList" 

requested-attributes=archive

The following is an example of column style with headings for brief set of attributes for a physical printer object within a specified supervisor.

                                           Associated 
Name        Realization   State   Enabled  Queue 
--------    -----------   -----   -------  ---------- 
PhysPrt1    physical      Idle    True     Queue1 
PhysPrt2    physical      Idle    True     Queue1 
PhysPrt3    physical      Idle    True     Queue2 

The following is an example of column style without headings for brief set of attributes for a physical printer object within a specified supervisor.

PhysPrt1    physical      Idle    True  Queue1 
PhysPrt2    physcial      Idle    True  Queue1 
PhysPrt3    physical      Idle    True  Queue2 

The following is an example of line style with headings for brief set of attributes for a logical printer object within a specified spooler that contains a single logical printer.

LogPrt1: printer-name          =  LogPrt1 
LogPrt1: printer-realization   =  logical 
LogPrt1: printer-enabled       =  true 
LogPrt1: associated-queue      =  Queue1 

The following is an example of line style without headings for brief set of attributes for a logical printer object within a specified spooler that contains a single logical printer.

printer-name                  =  LogPrt1 
printer-realization           =  logical 
printer-enabled               =  true 
associated-queue              =  Queue1 

Object Attributes

There are no object attributes for this command.

Arguments

You use the argument value to identify the specific object you want the attributes displayed for. If you specify multiple objects, each must be separated by spaces.

You can use the following argument values with the pdls command:

ServerName
ServerName:InitialValueDocumentName
ServerName:InitialValueJobName
ServerName:LogName
[ServerName:]PrinterName
[ServerName:]QueueName
LocalJobId[.DocNumber]
GlobalJobId[.DocNumber]

Note: When you only specify ServerName as the argument of the command (without an object name), the attribute values are returned for all of the objects within the object class you specify for that server that meet the filter criteria.

EXAMPLES

Check on a Document

To find out as much as you can about the first document in a job; if the local ID is 13, enter the command:
pdls -r all 13.1
This will provide information about the job and the first document.
To find the minimum about the second document in a job; if the local ID is 13, enter the command:
pdls -c document 13.2
This will provide information only about the second document.

Determine Document Formats Supported by Given Printers

To find out the document formats supported by the logical printers in SPOOL1, enter one of the following commands:
pdls -c printer -r document-format-supported -s line SPOOL pdls -x "class=printer requested-attributes=document-format-supported style=line" SPOOL1
HPDPS will respond with information that looks something like this:
LogPrt1: document-formats-supported=document-format-ASCII document-format-postscript LogPrt2: document-formats-supported=document-format-ASCII document-format-HPL document-format-postscript

Using a Filter

To determine the logical printers, physical printers, and queues that support selected attributes on any server, enter one of the following commands:
pdls -c printer -f "content-orientation-supported==landscape && sides-supported==2" -r printer-realization,associated-queue "*:" pdls -x "class=printer filter= content-orientation-supported==landscape && sides-supported==2" requested-attributes=printer-realization associated-queue" "*:"
The system will return information that looks something like this:
LogPrtHi: Printer-name = LogPrtHi LogPrtHi: Printer-realization = logical LogPrtHi: associated-queue = HiResQ LogPrtLo: Printer-name = LogPrtLo LogPrtLo: Printer-realization = logical LogPrtLo: associated-queue = LoResQ PhysPrt1: Printer-name = PhysPrt1 PhysPrt1: Printer-realization = physical PhysPrt1: associated-queue = HiResQ PhysPrt2: Printer-name = PhysPrt2 PhysPrt2: Printer-realization = physical PhysPrt2: associated-queue = LoResQ
To list all jobs that are owned by Smith, enter one of the following commands:
pdls -f "job-owner==Smith" -U SPOOL1 pdls -f "j-ow==Smith" -U SPOOL1
To list all job that are not owned by Smith, enter the following command:
pdls -f !("job-owner==Smith") -U SPOOL1
To list jobs owned by someone with a given substring in their name (substring matching) use one of the following filters with the pdls command:
pdls -U -f "job-owner=*Jones" SPOOL1: # Initial string match pdls -U -f "job-owner*=*one" SPOOL1: # Any substring match pdls -U -f "job-owner*=nes" SPOOL1: # Final string match
All of these will return jobs owned by "Jones".
To list jobs owned by all users with a name close to "Jones" (approximate match), enter the command:
pdls -U -f "job-owner~=jones" SPOOL1:
To list all jobs which have requested more than one copy and that have been assigned to the lj4pp physical printer, enter the command:
pdls -U -f "copy-count>1 && printer-assigned==lj4pp" "*:"

To Determine the Server Associated with a Printer

To query for the name of the spooler containing logical printer LogPrt1, enter one of the following commands:
pdls -c printer -r associated-server LogPrt1 pdls -x "class=printer requested-attributes=associated-server" LogPrt1
HPDPS returns information similar to the following:
LogPrt1: associated-server=SPOOL1

To Determine the Attributes Specified in an IVO

To query for the attributes specified in the initial value document spl7ivd contained in SPOOL7, enter one of the following commands:
pdls -c initial-value-document -r all SPOOL7:spl7ivd pdls -x "class=initial-value-document requested-attributes=all" SPOOL17:spl17ivd
HPDPS returns information similar to the following:
spl7ivd: initial-value-document-identifier = spl7ivd spl7ivd: associated-server = SPOOL7 spl7ivd: object-class = initial-value-document spl7ivd: copy-count = 2 spl7ivd: document-format = line-data spl7ivd: descriptor = "IVD for SPOOL7"

List Job Attributes

To list all the attributes of jobs 10 and 12, enter the command:
pdls -r all 10 12
To list just the job attributes of jobs 10 and 12, enter the command:
pdls -j 10 12

A Combined Example

In the following examples, which show printers as the command arguments, assume that the logical printer named DepartPrt is your default logical printer as defined in your PDPRINTER environment variable and that it sends input to the queue associated with the physical printers LaserJet5 and 3825X.

List Status of All Jobs

To list the status of all jobs you have submitted to the logical printer DepartPrt, enter the command:
pdls -f "printer-name-requested==DepartPrt" SPOOL1:
The following is displayed:
Current Intervening Printer Printer Job ID Name State Jobs Requested Assigned --- -------------- ---------- --------- ----------- --------- -------- 4 SplX: 1099222204 Mthly-report processing 0 DepartPrt 3825X 5 SplX: 1114222205 Test-report processing 0 DepartPrt LaserJet3 6 SplX: 1224222206 Trip-report pending 2 DepartPrt 1 SplX: 0988222201 Dept-memo12 retained DepartPrt

List Status of All Pending Jobs

To list job status of all jobs that have been submitted to the logical printer DepartPrt and that are pending, enter the command:

pdls -f "printer-name-requested==DepartPrt && 
     current-job-state==pending" SPOOL1: 

The following is displayed:

                             Current    Printer    Printer 
Job   ID        Name         State      Requested  Assigned 
---- ---------- ------------ ---------- ---------  --------- 
5     SplX:1114 Trip-report  pending    DepartPrt 

List the Brief Attributes of a Logical Printer

To list the brief attributes of your default logical printer (assigned to the PDPRINTER environment variable), enter the following command:
pdls -c printer DepartPrt
It causes the following to be displayed:
Printer Realization Enabled Queue ------- ----------- ------- ----- DepartPrt logical true DepartQ
If you do not specify a printer name, the command will list the brief attributes of all the logical printers that share the same spooler with your default logical printer (as defined in your PDPRINTER environment variable.

List Document Formats Supported

To list the document-formats supported by the logical printer DepartPrt in the line style with headings (default style for an attribute list), enter the following command:
pdls -c printer -r document-format-supported DepartPrt
The following is an example of what might be displayed:
DepartPrt: document-formats-supported=document-format-ASCII =document-format-ps
To list the document-formats supported by the logical printer DepartPrt in the column style with headings, enter the following command:
pdls -c printer -r document-formats-supported -s column DepartPrt
The following is an example of what might be displayed:
Document Formats ----------- ASCII PostScript

Create an Archive File

To create an archive file for a spooler, enter the command:
pdls -c server -r archive SPOOL1 > /attr/SPOOL1.archive

STANDARDS CONFORMANCE

pdls:POSIX 1387.4