Document revision date: 30 March 2001

## OpenVMS System Manager's Manual

Previous | Contents | Index

### 14.6.8 Using Device Control Libraries

A device control library is a text library that contains user-written modules consisting of text or escape sequences. A device control library module can be used for the following purposes:

- With programmable printers, to insert device-dependent escape sequences that set up a printer for selected print options such as point size, character set, and bold or italic print
- With programmable and nonprogrammable printers, to insert text at specific points in the processing of a print job

The three types of device control library modules, distinguished by their placement in a print job, are:

Module Type | Placement
--- | ---
Setup | Inserted at the beginning of a file.
Page setup | Inserted at the beginning of each page.
Reset | Inserted at the end of each job. Use reset modules to reset a printer to a known state at the end of a job.

How to Perform This Task

To use device control library options, perform the following steps:

1. Create a library and insert modules.
2. Assign the device control library to a queue. (This step is not necessary if you use the default library name SYSDEVCTL.TLB.)
3. Create one or more forms with setup or page setup modules.
4. Assign reset modules to a queue.

Commands for Processing Print Jobs

You can use the following commands to set up device control library modules for processing print jobs:

Command | Description
--- | ---
DEFINE/FORM/SETUP | Specifies one or more modules that set up the device at the start of each file of a job.
DEFINE/FORM/[NO]PAGE_SETUP | Specifies one or more modules that set up the device at the start of each page of a job.
INITIALIZE/QUEUE/LIBRARY START/QUEUE/LIBRARY | Specifies the file name of the device control library.
INITIALIZE/QUEUE/SEPARATE=[NO]RESET START/QUEUE/SEPARATE=[NO]RESET SET QUEUE/SEPARATE=[NO]RESET | Specifies one or more device control library modules that contain the job reset sequence for the queue.
PRINT/FORM | Specifies the name or number of the form to be associated with the print job.

#### 14.6.8.1 Understanding the Order of Device Control Module Output

Device control modules are sent to the printer within a print job in the following order:

1. Reset modules assigned to the queue. (Reset modules are only used at this point for the first job printed after a queue is started.)
2. Setup modules specified in the form definition.
3. Page setup modules specified in the form definition.
4. Setup modules specified with the PRINT command.
5. Page 1 of file 1.
6. Page setup modules specified in the form definition.
7. Page 2 of file 1, and so forth.
8. Page setup modules specified in the form definition.
9. Last page of file 1.
10. Setup modules specified in the form definition.
11. Page setup modules specified in the form definition.
12. Setup modules specified with the PRINT command.
13. Page 1 of file 2.
14. Page setup modules specified in the form definition.
15. Page 2 of file 2, and so forth.
16. Page setup modules specified in the form definition.
17. Last page of file 2.
18. Reset modules assigned to the queue.

The following sections describe how to manage device control libraries.

#### 14.6.8.2 Creating a Device Control Library and Inserting Modules

To create a device control library and insert modules, perform the following steps:

1. Create a device control library by entering a command in the following format:

   `LIBRARY/CREATE/TEXT SYS$COMMON:[SYSLIB] filename.TLB`

2. Determine the contents of the module---either the text to be inserted or the escape sequences needed for the printer setup you want. To determine the proper escape sequences for a printer option, refer to the operation guide for the specific printer.
3. Create a module file and enter the appropriate escape sequences, carriage control characters, or text. Create and edit a module file as you would any other text file. Make sure your text editor does not insert a carriage return or line feed at the end of your file. This will affect your printer output.
4. Insert the module into the device control library by entering a command in the following format:

   `LIBRARY/INSERT/TEXT library-file module-file`

Note To add a module to or delete it from a library, you must stop all output queues assigned to that library.

Refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual for more information about creating libraries and inserting modules.

#### 14.6.8.3 Assigning a Library to a Queue

To assign a device control library to an output queue, use the /LIBRARY qualifier with INITIALIZE/QUEUE or START/QUEUE in the following format:

`INITIALIZE/QUEUE/LIBRARY=filename queue-name`

where filename is the name of the library file that contains the selected modules.

Libraries must be in SYS$LIBRARY and must have the file type .TLB. The default library is SYS$LIBRARY:SYSDEVCTL.TLB. Use the /LIBRARY qualifier to specify an alternate device control library. For example:

    $ INITIALIZE/QUEUE/LIBRARY=LN03DEVCTL LN03_A_QUE

Note If you specify a value for the /LIBRARY qualifier, do not include the directory, file type, or version number. The system assumes that the file is in SYS$LIBRARY and has the type .TLB. If you copy a library file from another node, be sure that the new library has a unique file name.

Operations that request a particular device control library module use the module from the library specified for the queue. Guidelines for using libraries follow:

- If you have a small configuration of printers and normally use only a few modules, you usually store all modules in a single library and assign that same library to each printer queue.
- If you use a single library to store modules for different types of printers, make sure that each module has a unique name.
- For sites with a large number of different printers, you usually create and assign a separate device control library for each type of printer. In this case, Compaq recommends that you give modules that perform the same function an identical name in all libraries, even though the modules contain escape sequences unique to the specific type of printer.

Example

If three libraries contained modules that set up a printer for landscape orientation, these modules might be named LANDSCAPE in all three libraries. This allows you to use the same form on any queue for which a library contains a module of the specified name, even though the modules might contain different device-specific sequences.

Use the following command format to display a listing of all modules contained within a specified library:

`LIBRARY/LIST/FULL SYS$LIBRARY:library-name.TLB`

#### 14.6.8.4 Creating Forms for Setup and Page Setup Modules

To specify a setup or page setup module for a queue, use the /SETUP=module or /PAGE_SETUP=module qualifier with DEFINE/FORM. The modules you specify with /SETUP are sent to the printer when the form is mounted, before each file of a job is printed. Similarly, the modules you specify with /PAGE_SETUP are sent to the printer before each page of a job.

Users can request the module by using one of the following qualifiers with the PRINT command:

- The /FORM qualifier in the following format:

  `PRINT/FORM=form /QUEUE=queue-name filespec`

  When the user enters PRINT/FORM, the form name is checked for validity.

- The /SETUP qualifier in the following format:

  `PRINT/SETUP=module filespec`

  When the user enters PRINT/SETUP, the module names are not checked until the job attempts to print. If there is an error in the module name, the job will not print and the user will not be notified unless the /NOTIFY qualifier was specified.

#### 14.6.8.5 Assigning a Reset Module to a Queue

To assign a module to an output execution queue to reset the printer to a known state at the end of each job, use the /SEPARATE=RESET=module qualifier with INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE.

Because the /SEPARATE qualifier specifies mandatory queue options, the RESET module you specify is sent to the queue at the end of every job. The user cannot override this option.

Examples

In the following example, the reset sequence contained in the module resets the printer at the end of each job. It also resets the printer when the queue is started to ensure that the first job prints correctly.

    $ INITIALIZE/QUEUE/LIBRARY=MYDEVCTL/SEPARATE=RESET=MODULE2 PDQ_QUE

The following example uses device control library modules to process a print job. Two device control modules are created and inserted into the library file MYDEVCTL.TLB. The escape sequence or text in the setup module named MODULE1 is sent to the printer to set up the printer before REPORT.TXT is printed and again before MEMO.TXT is printed. The escape sequence or text in the reset module named MODULE2 is sent to the printer only once after both files in job REPORT have printed.

    $ LIBRARY/CREATE/TEXT SYS$LIBRARY:MYDEVCTL.TLB
    $ EDIT MODULE1.TXT
        !enter printer escape sequences or text for module1
    $ EDIT MODULE2.TXT
        !enter printer escape sequences or text for module2
    $ LIBRARY/INSERT SYS$LIBRARY:MYDEVCTL.TLB/TEXT MODULE1
    $ LIBRARY/INSERT SYS$LIBRARY:MYDEVCTL.TLB/TEXT MODULE2
    $ INITIALIZE/QUEUE/START/ON=TTA9:/LIBRARY=MYDEVCTL PDQ_QUE
    $ SET QUEUE/SEPARATE=RESET=MODULE2 PDQ_QUE
    $ SHOW QUEUE/FULL PDQ_QUE
    Terminal queue PDQ_QUE, idle on TOAD::TTA9, mounted form DEFAULT
       /BASE_PRIORITY=4/DEFAULT=(FEED,FORM=DEFAULT)/LIBRARY=MYDEVCTL
       /OWNER=[1,4]/PROTECTION=(S:M,O:D,G:R,W:R)/SEPARATE=(RESET=(MODULE2))
    $ DEFINE/FORM/SETUP=MODULE1/STOCK=DEFAULT FORM1 1

    $ PRINT/FORM=FORM1 REPORT.TXT,MEMO.TXT/QUEUE=PDQ_QUE

    Job REPORT (Queue PDQ_QUE, entry 619) started on PDQ_QUE

## 14.7 Maintaining Queues

Once you set up your queues, you must monitor and modify them according to the needs of your site.

Also, setting up queues is not restricted to startup time. During normal operation, you can create and start queues as your needs dictate. If you decide to set up queues at a later time, refer to the instructions in Section 14.4.

If you create additional output queues at a later time, make sure to perform the following actions:

- Add commands to set device characteristics to the startup command procedure on the node on which the device is located.
- For devices attached to a LAT port, add commands to the startup procedures on all nodes with queues for the device.
- For additional nonautostart queues, add appropriate START/QUEUE commands to the startup command procedure on the node on which the queue will run. If you do not add appropriate START/QUEUE commands, the queues will not be started when the system reboots.

### 14.7.1 Using Queue Management Commands

Table 14-4 lists commands for creating and controlling queues and tells whether they have the same effect on all queues or if they have different effects on autostart and nonautostart queues.

Table 14-4 Effects of Queue Commands
Command | Effect on
--- | ---
| Autostart Queues | Nonautostart Queues
ASSIGN/MERGE | Moves jobs from one queue to another. | Moves jobs from one queue to another.
ASSIGN/QUEUE | Redirects jobs in a logical queue to an execution queue. | Redirects jobs in a logical queue to an execution queue
DELETE/QUEUE | Deletes a queue. | Deletes a queue.
DISABLE AUTOSTART/QUEUES | After allowing jobs to complete, fails over all autostart queues to the next available node in each queue's node list. If a queue has no list specified, the queue is stopped. | No effect.
ENABLE AUTOSTART/QUEUES | Starts all stopped, active autostart queues capable of running on the node. | No effect.
INITIALIZE/QUEUE | Creates the queue. The /AUTOSTART_ON qualifier specifies one or more nodes or nodes and devices on which the queue can run. | Creates the queue. The /ON qualifier specifies a single node or node and device on which the queue is to run.
INITIALIZE/QUEUE/START | Creates the queue and activates it for autostart. The /AUTOSTART_ON qualifier specifies one or more nodes or nodes and devices on which the queue can run. | Creates and starts the queue. The /ON qualifier specifies a single node or node and device on which the queue is to run.
SET QUEUE | Modifies a queue. | Modifies a queue.
SHOW QUEUE | Displays information about a queue. | Displays information about a queue.
START/QUEUE | Activates the queue for autostart. | Starts the queue.
STOP/QUEUE | Pauses a queue. | Pauses a queue.
STOP/QUEUES/ON_NODE | Aborts current jobs and stops all queues on a node without stopping the queue manager. | Aborts current jobs and stops all queues on a node without stopping the queue manager.
STOP/QUEUE/NEXT | Stops a queue after allowing the current jobs to complete, and deactivates the queue for autostart. | Stops a queue after allowing the current jobs to complete.
STOP/QUEUE/RESET | Stops a queue abruptly and deactivates the queue for autostart. | Stops a queue abruptly.

The following sections describe these tasks for managing queues:

Task | For More Information
--- | ---
Monitoring queue information | Section 14.7.1.1
Modifying a queue | Section 14.7.1.2
Pausing a queue | Section 14.7.1.3
Closing a queue | Section 14.7.1.4
Stopping a queue | Section 14.7.1.5
Preventing autostart queues from starting | Section 14.7.1.6
Disabling autostart on a node | Section 14.7.1.7
Stopping all queues on a node | Section 14.7.1.8
Stopping queues before shutting down a system | Section 14.7.1.9
Assigning a logical queue | Section 14.7.1.10
Moving all jobs from one queue to another | Section 14.7.1.11
Deleting a queue | Section 14.7.1.12

#### 14.7.1.1 Monitoring Queue Information

Use the SHOW QUEUE command to monitor the status of queues. To display queue information, enter SHOW QUEUE in the following format:

`SHOW QUEUE [/qualifier,...] [queue-name]`

If you do not specify a qualifier or a queue name, the system displays the status of all queues on the system and all jobs you own. The SHOW QUEUE qualifiers let you select the type of queue and the amount of information you want to display.

Use the following qualifiers to select the information you want to display:

Qualifier | Description
--- | ---
/BY_JOB_STATUS[= keyword-list] | Displays queues that contain jobs of the specified status. You can specify one or more of the following keywords: EXECUTING HOLDING PENDING RETAINED TIMED_RELEASE If no keyword is specified, by default the jobs of all status are displayed. For more information about job status, see Table 14-6.
/BATCH | Displays batch execution queues.
/DEVICE[= keyword-list] | Displays output execution queues. You can select a specific type of execution queue by entering one or more of the following keywords: PRINTER TERMINAL SERVER If no keywords are specified, all types of output queue are displayed.
/GENERIC | Displays the status of generic queues.

Use the following qualifiers to select the amount of information you want to display:

Qualifier | Description
--- | ---
/ALL_JOBS | Displays information about all jobs for the selected queues.
/BRIEF | Displays a brief listing of information about job entries in the queue. The brief listing is the default for the SHOW QUEUE command.
/FILES | Adds a list of files associated with each job to the display.
/FULL | Displays complete queue and job information (also displays any ACLs set for the queues).
/SUMMARY | Displays the total number of executing, pending, holding, retained, and timed release jobs. The jobs themselves are not displayed.

You can also combine certain qualifiers to further delineate the queue information you want to display.

Table 14-5 defines queue statuses returned by SHOW QUEUE.

Table 14-5 Queue Statuses Displayed in the SHOW QUEUE Command
Queue Status | Description
--- | ---
Aligning | Queue manager is processing a START/QUEUE/ALIGN command.
Autostart inactive | Queue was stopped and needs to be activated. For more information, see Section 14.8.4.
Available | Queue is processing at least one job but is capable of processing additional concurrent jobs.
Busy | Queue cannot process additional jobs because of one or more jobs in progress.
Closed | Queue is closed and will not accept new jobs until it is set open. For more information, see Section 14.7.1.4.
Device unavailable | Device to which the queue is assigned is not available.
Idle | Queue is not processing any jobs and is capable of doing so.
Paused | A STOP/QUEUE command has been executed.
Pausing | Queue manager is processing a STOP/QUEUE command.
Remote | Queue is assigned to a physical device that is not connected to the local system.
Resuming | Queue manager is processing a START/QUEUE command on a paused queue.
Server | Queue processing is directed to a server symbiont.
Stalled | Symbiont processing temporarily halted due to device-related problem.
Starting | Queue has been started, but the symbiont process is not yet active.
Stopped | Queue is stopped and will not process work until started.
Stop pending | Queue will be in the stopped state when current jobs have finished executing.
Stopping | Queue is being stopped.

To display the forms or characteristics available on a system, use the SHOW QUEUE/FORM or SHOW QUEUE/CHARACTERISTICS command.

You can further customize the type of queue information you want to monitor by writing a command procedure that uses the F$GETQUI lexical function. F$GETQUI invokes the $GETQUI system service to return information stored in the queue database.

You can use the F$GETQUI lexical function to obtain information about the following types of objects:

> Characteristics
> Forms
> Queues
> Jobs contained in queues
> Files of jobs contained in queues

For example, you could write a command procedure to display the total number of blocks of jobs in a pending state in all printer queues. You must have read access to the job or SYSPRV or OPER privilege to obtain job and file information.

For more information about the system service invoked by the F$GETQUI lexical function, refer to the description of the $GETQUI system service in the OpenVMS System Services Reference Manual.

Examples

1. The following example displays summary information for all printer and terminal queues:

       $ SHOW QUEUE/SUMMARY/DEVICE=(PRINTER,TERMINAL)
       Printer queue HERA_LPA0, busy, on HERA::LPA0, mounted form DEFAULT
         <Printer queue on node HERA for a line printer>

           Job summary:  1 executing

       Printer queue HERA_LPB0, busy, on HERA::LPB0, mounted form DEFAULT
         <Printer queue on node HERA for a line printer>

           Job summary:  1 executing

       Generic printer queue CLUSTER_PRINT
         <Generic printer queue for LPA0: and LPB0:>
           Job summary:  1 holding

       Terminal queue LQ_PRINT, stopped, on HERA::TXA7:,
         <Letter quality printer in Bob's office>
       mounted form PORTRAIT_INDENTED (stock=DEFAULT)

           Job summary:  2 pending (445 blocks),  1 holding

2. The following example displays the full status and options of all executing jobs:

   Previous | Next | Contents | Index

   | privacy and legal statement |
   6017PRO_062.HTML