enq Command

AIX Version 4.3 Commands Reference, Volume 2

enq Command

Purpose

Enqueues a file.

Syntax

To Process a File

enq [ -B CharacterPair ] [ -c ] [ -C ] [ -j ] [ -m Text ] [ -M File ] [ -n ] [ -N Number ] [ -o Option ] [ -P Queue ] [ -r ] [ -R Number ] [ -t "User" ] [ -T Title ] [ -Y ] [ -Z Name ] File

To Change the Priority of Print Jobs

enq -a Number -# JobNumber

To Display Status

enq [ -q | -A ] [ -L | -W ] [ -e ] [ -# JobNumber ] [ -u Name ] [ -w Seconds ] [-s]

To Hold, Release or Move a Print Job to Another Queue

enq { -h | -p | -Q NewQueue } { -# JobNumber [ -P Queue ] | -u User | -P Queue }

To Queue and Hold a Print Job

enq -H File ...

Description

The enq command is a general-purpose utility for enqueuing requests to a shared resource, typically a printer device. Use the enq command to enqueue requests, cancel requests, alter the priority of a request, and display the status of queues and devices.

The enq command has five different syntax diagrams because all the flags are not meant to work together. Some of these flags are meant for file processing and accept FileName as an option. The other flags are used for changing the priority of a print job, displaying the status, changing the status of the queue or the queue daemon, and canceling a print job.

To enqueue files on a specific queue, use the -P flag (-P Queue). If more than one device services a queue, you can also request a particular device by specifying that device (:device) after the name of the queue. If you do not specify a device, the job is sent to the first available device. If you do not specify a file, the enq command copies standard input into a file and enqueues it for printing.

The enq command requests can have operator messages associated with them. This feature is useful in a distributed environment or on a system with many users. The messages are used to tell the printer operator such information as a request to load a special form or different color paper into the printer before allowing the job to print. These messages are specified with the -m and -M flags. The qdaemon command processes the enq command requests. When the qdaemon is ready to begin a request that has an associated message, the system displays the message on the console of the machine where the qdaemon process is running. The text of the message is accompanied by a prompt that tells the printer operator how to signal the request to continue or how to cancel the request.

The display generated by the enq -A command contains two entries for remote queues. The first entry contains the client's local queue and local device name and its status information. The second entry follows immediately; it contains the client's local queue name (again), followed by the remote queue name. Any jobs submitted to a remote queue are displayed first on the local side and are moved to the remote device as the job is processed on the remote machine.

Since the status commands communicate with remote machines, the status display may occasionally appear to hang while waiting for a response from the remote machine. The command will eventually time-out if a connection cannot be established between the two machines.

Notes:
Before you can enqueue a file, you must have read access to it. To remove a file, (see the -r flag) you must also have write access to the directory that contains the file.

If you want to continue changing the file after you issue the enq command but before it is printed, you must use the -c flag.

When enqueuing files on a printer, flags can be interspersed in any order.

The -d and -G flags are acted upon immediately. Syntax error appearing before these flags on the command line are reported. Syntax errors appearing after these flags on the command line are ignored.

Flags

File Processing Options

If you give the enq command a list of file names, it enqueues them all for file processing on the default device or on the specified device.

Causes the enq command to act as a filter. The enq command automatically reads standard input if you do not specify a file or files. However, if you do specify a file, you can also use the dash (-) to force the enq command to read standard input. The dash (-) is actually not a flag, but a special type of file name. Therefore, it must come after all other flags have been specified on the command line.

-B CharacterPair

Controls the printing of burst pages according to the value of CharacterPair as follows. (n = never, a = always, g = group. The first character is for header, the second character is for trailer.)

HT	Description
nn	No headers, no trailers
na	No headers, trailer on every file
ng	No header, trailer at the end of the job
an	Header on every file, no trailers
aa	Headers and trailers on every file in the job
ag	Header on every file, trailer after job
gn	Header at the beginning of job, no trailer
ga	Header at beginning of job, trailer after every file
gg	Header at beginning of job, trailer at end of job

The header and trailer stanzas in the /etc/qconfig file define the default treatment of burst pages.

Note: In a remote print environment, the default is to print a header page and not a trailer page.

-c

Copies the file. To save disk space, the enq command remembers the name of the file, but does not actually copy the file itself. Use the -c flag if you want to continue changing the file while you are waiting for the current copy to be printed.

-C

Specifies that the mail command be used instead of the write command for error messages and job completion notification. (Using this flag is useful for writing PostScript applications since it allows better feedback from the printer.) Error messages and job completion messages (both generated by the piobe command) and any data read from the printer are also sent back by mail.

The -C flag only applies to local print jobs. If you want to be notified when a job sent to a remote printer is completed, use the -n flag to receive a mail message.

Note: There are some messages that cannot be redirected from qdaemon and the printer backend in any way. These are system errors and are sent directly to the /dev/console file.

-j

Specifies that the message Job number is: nnn , where nnn is the assigned job number, be displayed to standard output. This occurs only if the job is submitted to a local print queue.

-m Text

Submits an operator message with an enq command request. The specified text contains the message.

-M File

Submits an operator message with an enq command request. The specified file contains the text of the message.

-n

Notifies you when your job is finished. If the -t flag is also used, the enq command also notifies the user for whom the request is intended (see the -t flag).

-N Number

Prints Number copies of the file. Normally, a file is printed only once.

-o Option

Specifies that flags specific to the backend be passed to the backend. Thus, for each queue there are flags not described in this article that can be included on the enq command line. See the piobe command for a list of these flags.

-P Queue

Specifies the queue to which the job is sent. A particular device on a queue can be specified by typing -P Queue:Device.

-r

Removes the file after it has been successfully printed.

-R Number

Sets the priority of the current job to Number. This flag is used at job submission time. Use the -a flag to alter priority after the job is submitted. Higher numbers assign higher priority. The default priority is 15. The maximum priority is 20 for most users and 30 for the users with root user authority.

-t "User"

Labels the output for delivery to User. Normally the output is labeled for delivery to the user name of the person issuing the enq command request. The value of User must be a single word meeting the same requirements of a regular user ID.

-T Title

Puts title on the header page and displays it when the -q flag is specified. Normally the job title is the name of the file. If the enq command reads from standard input, the job title is STDIN.# where # is the process ID of the enq command.

-Y

Tells the enq command to ignore the rest of the command line after this flag. This is useful for discovering whether a queue is valid (if it is in the /etc/qconfig file). For example, typing enq -P lp4 -Y returns with an exit value of 0 if the line printer lp4 is a valid queue; if otherwise, a nonzero value is returned. Using this flag is also good for forcing the qdaemon command to redigest the /etc/qconfig file.

-Z Name

Specifies originator of remote print jobs.

Print Job Priority Options

-a Number

Changes the priority of the named job to Number. The job must have been submitted for printing prior to entering the enq command with this flag. See the -R flag for a description of priorities. Use the -# flag to specify the job number. This flag is only valid for local print jobs.

-# JobNumber

Specifies the job number used by the enq -q command or the enq -a command, and displays only the job specified in status output.

Notes:
Specify the -P Queue to override the default destination printer.

If jobs 1, 2, and 3 are in the printer queue, and you specify that you want the status of job 3 while job 1 is running, the status information will show job 1 and job 3, not only job 3.

If you specify a job number that does not exist, the system displays the current job number on the queue instead of an error message.

Display Status Options

-A	Provides status for all queues. This is like running the enq -q command once for each queue in the qconfig file.
-L	Specifies the long status. This flag can be used with the -A flag or the -q flag. This flag cannot be used with the -W flag. If the -L flag and -W flag are used simultaneously, the first one specified takes precedence. Use the -L flag to show multiple files to be printed in a single print job.
-W	Specifies the wide status format with longer queue and device names. This flag can be used with the -A flag or the -q flag. It cannot be used with the -L flag. If the -L flag and -W flag are used simultaneously, the first one specified takes precedence. This flag only applies to AIX Version 4.2.1 or later.
-q	Displays the status of the default queue. The LPDEST and PRINTER environment variable control the name of the default printer. If the LPDEST environment variable contains a value, that value is always used first. If the LPDEST variable has no value, the enq command uses the PRINTER environment variable. If the PRINTER environment variable contains no value, then the enq command uses the system default. Notes: Use the -P Queue flag with the -q flag to display the status of a particular queue. Any destination command line options override both the LPDEST and the PRINTER environment variables.
-e	Excludes status information from queues that are not under the control of the qdaemon command. The status from such queues may be in different formats. The -e flag can be used with any combination of flags.
-u Name	Specifies the user name for which to print job status.
-w Seconds	Specifies continuous output of the queue status, updating the screen every Seconds specified until the queue is empty (see the lpq command). When the queue is empty, the process halts. This flag is only used with either the -q flag, or the -A flag, or the -L flag.

Change the queue and queue Daemon Status Options

-d	Runs the digest command on the /etc/qconfig file. Once the digest is completed, any changes to the /etc/qconfig file are reflected in the /etc/qconfig.bin file. A user must have root user authority to run this option.

In addition to the previous flags available to all users, the enq command accepts the following flags when they are entered by users that have root user authority. Root user authority means that you are root or you belong to the printq group.

Note: The following flags can only be used on local print jobs.

-D	Device DOWN. Turns off the device associated with the queue. The qdaemon process no longer send jobs to the device, and entering the enq -q command shows its status as DOWN. Any job currently running on the device is allowed to finish.
-G	Die GRACEFULLY. Ends the qdaemon process after all currently running jobs are finished. Use of this flag is the only clean way to bring the qdaemon process down. Use of the kill command may cause problems, such as jobs hanging up in the queue. If the qdaemon process is running under srcmstr (the default configuration), enq -G does not prevent qdaemon from being restarted automatically. You must use the chssys command, which changes the default configuration and prevents the automatic restart of the qdaemon process. The following command: chssys -s qdaemon -O issued prior to the enq -G command, prevents the automatic restart of qdaemon. The following command: startsrc -s qdaemon restarts the qdaemon process manually.
-K	Acts the same as the -D flag, except that all current jobs are KILLED. They remain in the queue, and are run again when the device is turned on.
-L	Specifies the long status. This flag can be used with the -A flag or the -q flag. Use the -L flag to show multiple files to be printed in a single print job.
-U	Brings UP the device associated with a queue. The qdaemon process sends jobs to it again and entering the enq -q command shows its status as READY.

Note: If more than one device is associated with a queue, you must specify the device as well as the queue when you use the -D flag, the -K flag, and the -U flags. For example, entering -P lp:lpd designates the same device only if there is no other device on that queue.

Cancel Options

-X	Cancels the printing of your jobs. If you have root user authority, all jobs on the specified queue are deleted. This flag is only valid on local print jobs.
-x Number	Cancels the printing of the specified job Number.
-P Printer	Specifies the Printer where either all jobs or the selected job number is to be canceled.

Attention: If you have root user authority and do not specify a queue, all jobs on all queues are deleted.

Holding and Releasing a Print Job Options

-# JobNumber	Designates the number of the print job to be held or released.
-h	Holds the specified print job.
-H	Queues and holds the file indicated with the File parameter.
-p	Releases the specified print job.
-P Queue	Designates the print queue to be held or released.
-u User	Designates the user whose print jobs are to be held or released.

Moving Print Job Options

-# JobNumber	Designates the number of the print job to be moved.
-P Queue	Designates the print queue to be moved. The value of the Queue variable can be a queue name or in the form queue:device name.
-Q NewQueue	Designates the target queue where the print job will be moved to. The value of the NewQueue variable can be in the form of a queue name or in the form queue:device name.
-u User	Designates the user whose print jobs are to be moved.

Security

Auditing Events:

Event	Information
ENQUE_admin	Queue name, device name, job name, user name

Examples

To print the file memo on the default printer, enter:
```
enq memo
```
To print the file prog.c with page numbers, enter:
```
pr prog.c | enq
```
The pr command puts a heading at the top of each page that includes the date the file was last modified, the name of the file, and the page number. The enq command then prints the file.
To print a file with page numbers, reading from standard input, enter:
```
pr x | enq -P bill -n -r fn1 - fn3
```
The dash (-) special file name tells the enq command to read from standard input. Normally the enq command will not read from standard input if there are file names on the command line. It also indicates the order in which to print things. The pr command creates a page numbered version of the file x and passes it to the enq command, which creates a temporary file containing that output in the /var/spool/qdaemon file.
The enq command creates a job with four files and submits it to the queue named bill . It will print the fn1 file twice. Then it will print whatever the output of the pr command was. Lastly it will print the file fn3 . The four files are treated as one job for the purposes of burst pages. Notification is sent (the -n flag) when the job is complete. Since the -r flag was specified, the fn1 and fn3 files are removed at job completion. The temporary file created by the dash (-) file is always deleted.

The pr command puts a heading at the top of each page that includes the date the file was last modified, the name of the file, and the page number. The enq command then prints the file.
To print the file report on the next available printer configured for the fred queue, enter:
```
enq -P fred report
```
To print several files beginning with the prefix sam on the next available printer configured for the fred queue, enter:
```
enq -P fred sam*
```
All files beginning with the prefix sam are included in one print job. Normal status commands show only the title of the print job, which in this case is the name of the first file in the queue unless a different value was specified with the -T flag. To list the names of all the files in the print job, use the long status command enq -A -L.
To check the print queue to see if a file is still waiting to be printed, enter:
```
enq -q
```
This command displays the status of the user's default queue. If the file is not yet printed, then it appears in the queue status listing. The system default queue is defined as the first queue in the /etc/qconfig[.bin] file. Users can have their own default override by setting and exporting the PRINTER environment variable.
To display the status of a nondefault queue, lp0 , enter:
```
enq -q -P lp0
```
To obtain the long queue status, enter:
```
enq -L
```
To obtain status on all queues, enter:
```
enq -A
```
To obtain long status on all queues, enter:
```
enq -A -L
```
To obtain the status of the default queue, in wide format, for AIX Version 4.2.1 or later, enter:
```
enq -W 
```
To obtain the wide status of all queues for AIX Version 4.2.1 or later, enter:
```
enq -W -A 
```
To stop printing a job (a job is one or more files), enter:
```
enq -x 413
```
This command cancels the request you made earlier to print a job. The number was obtained from the listing obtained by entering the enq -q command. If the job is currently being printed, the printer stops immediately. If the job has not been printed yet, it is removed from the queue so that it will not be printed. If the job is not in the queue, the enq command displays a message similar to the following:
```
no such request from you -- perhaps it's done?
```
To disconnect a printer from the queuing system, enter:
```
enq -P lp0:dlp0 -D
```
Entering this command stops the enq command requests from being sent to the printer that serves the lp0 queue. If a file is currently printing, it is allowed to finish. You must be able to execute the qadm command to run this command.
Note: The printers serving a given queue are named by the device stanza name as it appears in the /etc/qconfig[.bin] file.
To print a file with page numbers using the piobe command backend on the default printer, enter:
```
enq -o -p filename 
```
The -p flag is not looked at by the enq command. The -o flag tells the enq command to pass the next item, which can be in quotes, to the backend unchanged. So, the enq command passes the -p flag to the qdaemon process, which in turn passes it to the backend piobe. The -p flag causes piobe to execute the /usr/bin/pr filter to apply page numbers to the document before giving data to the device. Multiple options can be given in quotes preceded by one -o flag or without quotes and individually preceded by more than one -o flag.
Assuming a qconfig file with the following information:
```
qname:
               device = fred
fred:
               file = /tmp/hello
               backend = /usr/bin/sh /usr/bin/diff
```
And given the following commands:
```
rm /tmp/hello
touch /tmp/hello
pr /etc/hosts|enq -P qname:fred - /etc/hosts
```
The qdaemon process executes the /usr/bin/diff program with two arguments, one of which is a temporary file name and the other being the /etc/hosts file. The only difference between the two files is that one was run through the pr command. The /tmp/hello file will contain the differences between the two files. The qdaemon process does not create the /tmp/hello file if it does not exist.
The following command:
```
enq -m'i want pink paper for this job' /etc/passwd
```
sends the specified operator message to the operator's console just before the print job is to print. The operator must respond to this message to continue or cancel the job.
```
enq -M pink /etc/passwd
```
This command accomplishes the same thing, only the message is contained in a file called pink .
To cancel all jobs in the fred queue, enter:
```
enq -X -P fred
```
If the user who entered this command has root user authority, all the jobs from the fred queue are deleted. If the user does not have root user authority, only the users jobs are deleted from that queue.
To queue the file named MyFile and return the MyFile job number to the jdf file, enter:
```
enq -j MyFile
```
To hold print job number 310 , enter:
```
enq -h -#310
```
To release the hold on print job number 310 , enter:
```
enq -p -#310
```
To hold all the print jobs on queue lp0 , enter:
```
enq -h -P lp0
```
To release the lp0 queue, enter:
```
enq -p -P lp0
```
To hold all print jobs created by fred , enter:
```
enq -h -u fred
```
To release the print jobs created by fred , enter:
```
enq -p -u fred
```
To move job number 318 to queue lp0 , enter:
```
enq -Q lp0 -#318
```
The flags that control moving print jobs work in the same way as the flags that hold the print files. The hold flags and variables are illustrated in the preceding examples.

Files

/usr/sbin/ qdaemon	Queuing daemon.
/etc/qconfig	Queue configuration file.
/var/spool/lpd/qdir/*	Queue requests.
/var/spool/lpd/stat/*	Information on the status of the devices.
/var/spool/qdaemon/*	Temporary copies of enqueued files.
/etc/qconfig.bin	Digested, binary version of the /etc/qconfig file.

Related Information

The chquedev command, lsque command, mkque command, rmque command.

The qconfig file.

Changing / Showing Queue Characteristics in AIX Version 4.3 Guide to Printers and Printing.

Printer Overview for System Management in AIX Version 4.3 Guide to Printers and Printing.

Printer-Specific Information in AIX Version 4.3 Guide to Printers and Printing.

Printer Support in AIX Version 4.3 Guide to Printers and Printing.

Spooler Overview for System Management in AIX Version 4.3 Guide to Printers and Printing.

Virtual Printer Definitions and Attribute in AIX Version 4.3 Guide to Printers and Printing.

Printer Colon File Conventions in AIX Version 4.3 Guide to Printers and Printing.