7    Managing Jobs and Documents

You need to consider various aspects of jobs and documents to be able to manage them properly in Advanced Printing Software. Generally, three types of attributes reflect the different aspects of job and document management:

7.1    Performing Job and Document Operations

Job and document operations that users perform on a regular basis can include the following:

Print a job
Print a job after a specified time
List job and document attributes
List the job queue
Modify job and document attributes
Remove or cancel a job
Resubmit a job
Promote a job
Specify job priority
Pause and resume a job
Hold a job
Retain a job
Discard a job
Include messages and even notification

It is important to understand the difference between a job and a document. A job can contain many documents and can contain a number of different processing instructions for each document.

For a detailed description of the commands discussed in this chapter, refer to the reference page for the command.

7.1.1    Printing a Job

A print operation creates the job object and the document objects from your print request to print one or more files. The spooler creates a job object for each print request and a document object for each file a user specifies as part of a single print request. A job object, therefore, contains one or more document objects.

For each job, the spooler assigns a unique job identifier (job-identifier) that is used to identify the job when job operations are performed, such as pausing the job.

Print requests are made using the pdpr command. The pdpr command has the following syntax:

pdpr [-f file_name] [-n copies] [-N notification_method] [-p logical_printer_name] [-t job_namefiles]

The following examples show how to use the pdpr command to submit print requests:

The pdpr command can also read document data from standard input, thereby allowing it to be used in a pipe expression.

7.1.2    Printing a Job After a Specified Time

You can submit a print request and specify that the job be printed after a specified date and time. You can also specify the print date and time with a set or modify operation.

You might want to specify a print date and time for a large job so that it prints during a low print volume period.

To specify a date and time, use the following syntax:

dd:mm:yyyy:hh:mm:ss

When you set a print date and time for a job, the spooler:

When the specified print date and time has passed, the spooler schedules the job and changes current-job-state to pending.

The following examples show how to specify a print time for a job:

7.1.3    Listing Job and Document Attributes

You can use the pdls command to display attributes and values of print system objects, such as printers, queues, jobs, documents, and server processes. You can use this command to list the following attributes:

The pdls command displays information only about an object for which you have sufficient access-control privilege. For jobs belonging to other users, the server returns only those attributes specified in the server job-attributes-visible-to-all attribute. The command writes its list of attributes to standard output.

The pdls command has the following syntax:

pdls [-c class_name] [-f filter_expression] [-F] [-g] [-r requested_attributes] [-s style_name] [-x extended_attribute_string...] [-X attribute_filename ...] [[object_instance]...]

The following examples show how to use the pdls command to display job attributes and values:

7.1.4    Listing a Job Queue

You can use the pdq command to query a logical printer for a list of jobs that are currently in the printer's queue. The list displays the jobs in the scheduled print order. The pdq command writes the list of jobs to standard output. If you do not use the -p option to specify a printer, pdq lists jobs in the queue of the printer specified by the PDPRINTER environment variable.

Thepdq command has the following syntax:

pdq [-f filter_expression] [-F] [-g] [-p printer_name] [-r requested_attributes] [-s style_name] [-x extended_attribute_string...] [-X attribute_filename...] [server_name:] [job_id[.doc_int]]

The following examples show how to use the pdq command to list job queues:

7.1.5    Modifying Job and Document Attributes

You can use the pdset and the pdmod commands to modify job and document attributes.

The pdset command sets, adds, or removes values of writable attributes of printers, queues, servers, jobs, documents, and initial-value objects. Changes you make to the attribute values of an object are persistent; they remain in place even after the system is restarted. The specified attribute values will be set for every object you include as a command operand.

Some object attributes make reference to other objects in your configuration. To set any of the following print attributes, the new value must refer to an object that already exists:

associated-queue

printer-initial-value-job

printer-initial-value-document

Administrators can set attribute values of any object in the system. An operator can set attributes of any job and values of the xxx-ready attributes for physical printers. An end user can set only attribute values of owned jobs.

The pdset command has the following syntax:

pdset [-c class_name] [-g] [-m message_text] [-r requested_attributes] [-s style_name] [-x extended_attribute_string...] [-X attribute_filename...] object_instance...

The following examples show how to use the pdset command:

The pdmod command modifies job and document attributes of a job that you have submitted for printing but that has not yet started to print. Changes you make to the job are persistent; that is, they remain in place after the system is restarted.

The job you are modifying does not lose its position in the queue; however, a resource check of the entire job or document attributes takes place again if you resubmit the print job.

The pdmod command has the following syntax:

pdmod [-g] [-m message_text] [-n copies] [-N notification_method] [-r requested_attributes] [-s style_name] [-t job_name] [-x extended_attribute_string...] [-X attribute_filename...] [server_name:] job_id [.doc_int]

The following examples show how to use the pdmod command:

7.1.6    Removing a Job

You can use the pdrm command to remove or cancel a job that was submitted for printing. If the job is currently printing, the spooler forwards the operation to the supervisor and printing is stopped as soon as possible.

The print job is retained, if you specify the -r retention_period option in the command line, or if the job-retention-period attribute has a nonzero value. Retained jobs can be resubmitted for printing later.

The pdrm command ihas the following syntax:

pdrm [-m message_text] [-r retention_period] [-x extended_attribute_string...] [-X attribute_filename...] [ server_name: ] job_id...

The following examples show how to use the pdrm command:

7.1.7    Resubmitting a Job

You can resubmit a submitted job for printing to a different printer on the same spooler.

A job must be in any of the following states to be resubmitted:

You cannot resubmit a job whose state is completed, processing, or printing.

The pdresubmit command has the following syntax:

pdresubmit logical_printer_namejob_id [job_id2]...

pdresubmit -c queuelogical_printer_name queue_name

The operand is either a job identifier or a queue name. You can resubmit individual jobs or you can resubmit all jobs in a queue to another logical printer.

The following examples show how to use the pdresubmit command to resubmit jobs:

Note that the pdresubmit command is asynchronous. The command returns a prompt before the server completes the operation.

7.1.8    Promoting a Job

You can move a job to the front of the queue. The job will be printed before jobs that have not been promoted, regardless of submission time. While you can promote only one job at a time, promoting several jobs in the same queue causes the most recently promoted job to be printed first.

The currently printing job continues normally at each of the physical printers associated with the queue containing the job to be promoted. The spooler assigns the most recently promoted job to the first physical printer that completes its current job and that can handle the promoted job.

You can promote jobs that have a current-job-state of pending or held. The queue state must be either ready or paused.

Administrators and operators can use the pdpromote command to promote a job. End users cannot promote jobs. The pdpromote command has the following syntax:

pdpromote [-m message_text] [server_name:] job_id

The following example shows how to use the pdpromote command:

7.1.9    Pausing a Job

You can pause a job before it is submitted to a physical printer for printing. Other jobs in the queue are submitted around the paused job.

Only pending or held jobs can be paused. That is, a job that has started to print cannot be paused. When you pause a job:

The pdpause command has the following syntax:

pdpause -c job [-m message_text] [server_name:] job_id

The following example shows how to use the pdpause command:

7.1.10    Resuming a Job

You can resume paused jobs with the pdresume command. When you resume a paused job, the job becomes available for scheduling and printing.

The pdresume command has the following syntax:

pdresume -c class_name [-m message_text] [server_name:] job_id

The following example shows how to use the pdresume command:

7.1.11    Holding a Job

You can hold a job so that the spooler does not schedule it for printing. You place a job on hold by setting the job-hold attribute to yes.

When you hold a job, the spooler:

Holding a job is similar to pausing a job, except the job remains on hold indefinitely unless one of the following events occurs:

The following examples show how to place a job on hold:

7.1.12    Retaining a Job

You can cause the spooler to retain a job for a specified period after the job completes printing. A retained job is available for possible resubmitting or examination.

When you retain a job, the spooler:

The job remains in the retained state until one of the following events takes place:

The pdmod, pdset, or pdrm command can cause a job to be retained when it completes. End users can set the retention period on their jobs with the pdmod and pdrm commands. Administrators and operators can use the pdset command to set the retention period of any job.

The following examples use these commands to retain a job:

7.1.13    Discarding a Job

You can specify that the spooler delete a job if the job is not printed by a certain time. The job-discard-time attribute specifies the time.

When the job discard time arrives, the spooler deletes the job whether or not it has printed and regardless of the job state.

To specify a job discard time, end users can use the pdmod command, and administrators and operators can use the pdset command.

The following examples show how to set a job discard time:

7.1.14    Including Messages

You can use the -m option with the following commands to include a message about a job or a document when you are altering or changing the state:

If you are an end user, you can include a message only for commands for which you have access; for example, the pdmod command. However, you can view a message included by an administrator by issuing the pdls command and specifying the job or documents.

The following examples show how to include a message:

7.1.15    Including Event Notification

You can receive notification when your job has completed by using the -N option of the pdpr command and specifying the notification method. The notification method is either e-mail, which sends you an e-mail message, or message, which sends a message to the console window.

The following example shows how to specify notification: