.\" $Header:
.TA p
.TH pdpromote 1
.SH NAME
pdpromote \- advances a job to the top of a queue
.SH SYNOPSIS 
.tr ~"
.C pdpromote 
.RC [ -m \0\~\f2MessageText\f4~ \|\f1]
.RC [ -x \0\~\f2AttributeValuePairs\f4~ \|\f1]
.RC [ -X \0\f2AttributesFileName \|\f1]
.RI \f2LocalJobId \f1...\0|\0\f2GlobalJobId \f1...
.PP
.tr ~~
.C pdpromote -h
.PP
.SH DESCRIPTION
.PP
You use this administrative command 
.C \f2(\f4pdpromote\f2)\f4 
to move a pending job
before any currently-queued jobs.  The job becomes the first job in the
queue.  If another job is then promoted, it becomes the first job in the
queue (ahead of the job previously promoted).
.PP
A move to the beginning of the queue does not necessarily guarantee that
the job will be the next job printed.  The jobs currently printing on each
of the physical printers associated with the queue continue printing.  The
server assigns the promoted job to the first physical printer that becomes
available and is capable of handling the promoted job.
.PP
You must have authority to promote your own jobs as well as jobs belonging
to other people.
.PP
The priority level of a print job can be changed by setting the
.C job-priority 
attribute using the 
.C pdmod 
or the 
.C pdset 
command.  However, a
job is promoted to the top of the queue by the 
.C pdpromote 
command
regardless of it priority.
.PP
.SS Options
.PP
You can use the following options with the 
.C pdpromote 
command:
.PP
.TP
.C -h    
Displays a command-specific help message containing information
about command syntax and options.  This option is mutually
exclusive; cannot be used with another option or with an
attribute.
.PP
.TP
.tr ~"
.C -m \f2\~MessageText\f4~
.tr ~~
Specifies the message you want stored in the
.C job-message-from-administrator 
attribute.  You can use this
message to indicate why the job is being or has been promoted or
to provide other comments.  If the 
.C -m 
option is not specified, the
message already stored with the job remains unchanged.
.PP
.IP
You can list this message by specifying
.C requested-attributes=job-message-from-administrator 
with the
.C pdls 
command.
.PP
.IP
Using this option is equivalent to specifying the
command-attribute 
.CR message .
.PP
.TP
.tr ~"
.C -x \f2\~AttributeValuePairs\f4~
.tr ~~
A single attribute string, consisting of one or more
attribute-value pairs.
.PP
.TP
.C -X \f2AttributesFileName\f4
The name of a file containing attribute-value pairs you want
inserted at the current point in the command line.
Using this option is equivalent to specifying the
command-attribute 
.C attributes.
.PP
.SS Command Attributes
You may specify these attributes in a 
.C -x "\c
"\f2AttributeValuePairs\f4\c"
.ft
" string or
in an attributes file designated with the 
.C -X \f2AttributesFileName\f4
option.
.PP
.TP
.C attributes\f2=AttributesFileName\f4
Causes the designated attributes file to be read.
.PP
.TP
.tr ~"
.C message=\f2\~MessageText\f4~
.tr ~~
Specifies a message you want stored in the
.C job-message-from-administrator 
attribute.  You can use this
message to indicate why the job is being or has been promoted or
to provide other comments.  If the message attribute is not
specified, the message already stored with the job remains
unchanged.
.PP
.IP
You can list this message by specifying
.CR requested-attributes=job-message-from-administrator 
with the
.C pdls 
command.
.PP
.SS Object Attributes
.PP
There are no object attributes for this command.
.SS Argument
.PP
You use the argument values to identify the specific object you want
promoted.  You can use the following argument values with the 
.C pdpromote
command:
.PP
\f2LocalJobId\f4 or \f2GlobalJobId\f4
.PP
.IP
Specifies the job you want to promote.
.PP
.IP
You as an administrator would generally use the global job
identifier but you can promote your own jobs using the local job
identifier.
.PP
.IP
When a job is specified with the 
.C pdpromote 
command, it becomes the first
job in the queue.  If a another job is then promoted, it becomes the first
job in the queue (ahead of the job previously promoted).
.PP
.SH EXAMPLES
.PP
.C Promote Job
.PP
\(bu  To promote job 6450500001 on server DServe1, enter the command:
.PP
.C       pdpromote DServe1:6450500001
.PP
\(bu  To promote job 1099600001 on server SPOOL1, enter the command:
.PP
.C "pdpromote -m ""This job must be printed in 10 minutes"" SPOOL1:1099600001"
.PP
.SH SEE ALSO
pdclean(1), pdcreate(1), pddelete(1), pddisable(1), pdenable(1), pdls(1),
pdmod(1),
pdpause(1), pdpr(1), pdq(1), pdresubmit(1), pdresume(1), pdrm(1), pdset(1),
pdshutdown(1)
.PP
.SH STANDARDS CONFORMANCE
.CR pdpromote ": POSIX 1387.4"
.\" index@\f4pdpromote\f1 \- advances a job to the top of a queue@@@\f3pdpromote(1)\f1
.\" index@\f1advances a job to the top of a queue@@@\f3pdpromote(1)\f1
.\" index@\f1HP Distributed Printer System, advances a job to the top of a queue@@@\f3pdpromote(1)\f1
.\"
.\" toc@\f3pdpromote(1)\f1:\0\0\f4pdpromote\f1@@@advances a job to the top of a queue
.\"
.\"
.\"
