What DQS Can Do for You

The Distributed Queuing Service for OpenVMS Systems is a software product that enables you to:

Using DQS software, you can:

What You Need to Know

If you know how to print files on OpenVMS systems, you know how to use most DQS features. The DQS commands (PRINT, QSHOW, QSET, and QDELETE) look and function the same as the Digital Command Language (DCL) PRINT, SHOW, SET, and DELETE commands.

To use DQS software, you do not need to log in to a remote system, copy files across a network, or have proxy access or special privileges. You do not need to consider whether a print queue is local or remote.

How DQS Works

This is what happens when you print using the DQS software:

Some DQS Terms

Some terms used in this guide in connection with the DQS software are:

DQS software moves print jobs from client queues (on clients) to corresponding remote queues (on servers).

For more information on the differences between DQS commands and corresponding DCL commands, use this manual or the OpenVMS HELP facility.

For more information on how to print files, refer to the descriptions of the PRINT, SHOW QUEUE, DELETE/ENTRY, and SET QUEUE /ENTRY commands in the OpenVMS DCL Dictionary .

The HELP Command

To get help with the DQS commands, you can use the standard OpenVMS HELP facility. Enter:

$ HELP command

Where, command is DQS or the PRINT, QSHOW, QDELETE, or QSET command verb.

Example

For example, if you enter the following command, text displays on your terminal that explains how to use the DQS QSHOW command.

$ HELP QSHOW Return
QSHOW

     Displays information about queues and jobs that are currently in
     queues. If the queue is a DQS client queue, QSHOW also displays the
     remote queues associated with the client queue.

     o Display characteristic names and numbers that are available on
        queues (see /CHARACTERISTICS).
     o Display form names and numbers that are available on queues (see
        /FORM).
  Format:
     QSHOW [queue-name]
Additional information available:   

Parameters Command_Qualifiers
/ALL      /BATCH     /BRIEF     /DEVICE     /FILES    /FULL    /OUTPUT
/CHARACTERISTICS    /FORM
QSHOW Subtopic?

Basic Network Example

Assume that your site has a network of two systems, APPLE and BANANA:

Without DQS Software

$ PRINT TRIP_REPORT.TXT/QUEUE=Q_CHICAGO Return

Node BANANA users cannot use the printer on node APPLE.

With DQS Software

If DQS software is installed on both nodes, node APPLE can function as a server; that is, APPLE’s printer can serve users of both systems. Node BANANA is then the DQS client.

Assume that your system manager defined a client DQS queue for node BANANA that correspon ds to the queue Q_CHICAGO on APPLE. From node BANANA, to queue your file to print on node APPLE, you enter the identical command line:

$ PRINT TRIP_REPORT.TXT/QUEUE=Q_CHICAGO Return

If the generic queue SYS$PRINT is defined as Q_CHICAGO, users can print files by entering PRINT file-name.

Basic Configuration

Figure 2.1, “Basic DQS Configuration” illustrates how the system manager configures DQS software in this basic network.

Multinode Network Example

DQS software can be installed on networks of any size.

Figure 2.2, “Multinode DQS Configuration” llustrates a slightly more complex DQS configuration consisting of three nodes: APPLE, BANANA, and CHERRY:

DQS can be installed on all three nodes. Nodes APPLE and CHERRY can function as servers; that is, their printers can serve users of other systems. All three nodes can be clients; that is, they can use the printers of the server systems.

Printing in Multinode Network

Your system manager can define client DQS queues for all three systems that send print jobs to the remote queues Q_CHICAGO and Q_PARIS. For example, your system manager can define the following (see Figure 2.2, “Multinode DQS Configuration”):

Then, from node APPLE, for example, you can queue your file to print on the LN06 printer on node CHERRY by entering:

$ PRINT TRIP_REPORT.TXT/QUEUE=CQ_EUROPE Return

From node BANANA you can queue your file to print on the LN06 printer on node CHERRY by entering:

$ PRINT TRIP_REPORT.TXT/QUEUE=CQ_FRANCE Return

In both examples, the print job, TRIP_REPORT.TXT, is sent to the remote queue Q_PARIS on the server node CHERRY for printing.

Multinode Configuration

Figure 2.2, “Multinode DQS Configuration” illustrates how the system manager configures DQS software in this multinode network.

Advantages of DQS Printing

With DQS software, you can choose to print files on the printer that is most convenient to your location. You can take advantage of different types of printers as necessary. You can also direct output to printers you know are idle.

Status Messages

When you queue a file to be printed, you receive one of two acknowledgment messages:

The messages list the client queue, in this case CLIENT, and the client job number.

As with the DCL software, these messages are sent by default. You can suppress default messages by using the /NOIDENTIFY qualifier with the PRINT command.

Print Job Entry Numbers

When you queue a file to print, the DQS software displays the job entry number of the client (that is, your) system. Job numbers printed on the header, burst, or trailer pages are client job numbers, if the DQS print symbiont or the DECprint Supervisor for OpenVMS software runs the server’s printer. Otherwise, the job numbers are server job numbers.

Requirements

Before the DQS software transfers a print job, it checks on the form being used.

If you queue a job with a form that is not mounted on the client, the queue manager mounts the form before the software transfers the job. This can take several minutes.

If you queue a job with a form that is not mounted on the server, the job does not print until the operator mounts the form.

DQS Qualifier Differences

Most of the qualifiers to the PRINT command function the same with DQS printing as they do with standard OpenVMS printing. Qualifiers that function differently with DQS printing are described in Table 2.1, “PRINT Command Qualifiers That Function Differently with DQS Printing”.

Examples

For example, to transfer a file to the printer queue on node CHERRY from the client queue CQ_EUROPE on node APPLE after 11:30 in the morning, use the /AFTER qualifier:

$ PRINT CHANGES.PS/QUEUE=CQ_EUROPE/AFTER=11:30 Return
Job CHANGES (queue CQ_EUROPE, entry 324) holding until 30-JUL-1994 11:30 

If you want to be notified after your print job is transferred and completes, use the /NOTIFY qualifier. For example:

$ PRINT CHANGES.PS/QUEUE=CQ_EUROPE/NOTIFY Return
Job CHANGES (queue CQ_EUROPE, entry 548) started on queue CQ_EUROPE
Job CHANGES (queue EUROPE, entry 548) completed

Print job CHANGES (queue CQ_EUROPE, entry 548) completed at 30-JUL-1994 10:24
$

Each "completed" message means something different.

The messages may not appear immediately; the actual timing depends on the system load and backlog in the queues.

Error Messages

If a DQS print job in a client queue fails to transfer to the server, the job remains in the client queue with the message "terminated with error status" and an associated error status. To examine the error status, use the QSHOW command (see Chapter 3, Viewing the Status of Print Jobs).

If you specify the /NOTIFY qualifier, you receive an error message when your print job fails to transfer. For example:

Job TRIP_REPORT (queue CQ_ILLINOIS, entry 341) terminated with error status 
 %status, message-text 

You must either delete the job or release it for another try. The QDELETE/ENTRY command (for deleting jobs from a queue) is described in Chapter 4, Deleting Print Jobs From a Queue.

Common DQS Error Messages

Following are some common DQS error messages with an explanation and a recovery action.

Refer to Appendix A, DQS User Messages for a complete list of messages.

Comparison with DCL Command

Using the DCL SHOW QUEUE command to view the status of a DQS client queue works, but it does not show the status of the associated remote queue. For that information, use the QSHOW command. You can use the QSHOW command to examine both client (local) and server (remote) queues.

QSHOW Command

To check the status of a print job, enter the following command at the DCL prompt on the client node:

$ QSHOW client-queue-name Return

Sample Output

The following examples use the same node names and queues used in the DQS client/server examples from Chapter 2, Printing Files Using DQS Software.

For example, you are working on node APPLE, and you queued the file TRIP_REPORT.P S to the client queue CQ_EUROPE to print on the printer on node CHERRY. To check the status of your print job, enter:

$ QSHOW CQ_EUROPE Return

The command output may look like this:

** Remote queue - [ CQ_EUROPE => Q_PARIS, on CHERRY:: ]
Printer queue Q_PARIS, on CHERRY::
    Jobname      Username     Entry     Blocks     Status
------- -------- ----- ------ ------
     (5 intervening jobs containing 2019 blocks)
TRIP_REPORT JONES 1229 98 Pending
=============================to be transferred===========================
Server queue CQ_EUROPE, on APPLE::, mounted form LN06_DEFAULT (stock=DEFAULT)

The information in this example tells you:

If you queue another job and check the status, you may get results like this:

$ QSHOW CQ_EUROPE Return

** Remote queue - [ CQ_EUROPE => Q_PARIS, on CHERRY:: ]
Printer queue Q_PARIS, on CHERRY::

Jobname     Username     Entry     Blocks     Status
------- -------- ----- ------ ------
=============================to be transferred===========================
Server queue CQ_EUROPE, on APPLE::, mounted form LN06_DEFAULT (stock=DEFAULT)
  TRIP_REPORT JONES 1234 98 Processing

This example indicates that your job is in the process of being transferred to the server node CHERRY. If jobs are ahead of yours in the client queue on node APPLE, the status is "Pending".

DQS QSHOW Qualifiers

The DQS QSHOW command uses the same qualifiers as the DCL SHOW QUEUE command, plus one more.

QSHOW also uses the qualifier /QUEUE= queue-name to support the /FORM and /CHARACTERISTICS qualifiers.

/FORM Qualifier

/FORM Example

In this example, CQ_EUROPE is used as the queue-name:

$QSHOW /QUEUE=CQ_EUROPE /FORM Return

You see output like the following:

Remote node CHERRY::
Form name                           Number    Description
---------                           ------    -----------
A4_12 (stock=PLAIN_PAPER)             1129    A4 12-Pitch with margins
DCPS$DEFAULT (stock=DEFAULT)          1115    DCPS default

Local node APPLE::
Form name                           Number    Description
---------                           ------    -----------
A4_12 (stock=PLAIN_PAPER)             1129    A4 12-Pitch with margins
DCPS$DEFAULT (stock=DEFAULT)          1115    DCPS default
DEFAULT                                  0    System-defined default
KPS$DEFAULT (stock=DEFAULT)           1183    KPS default
LANDSCAPE (stock=DEFAULT)               10    132 by 66 (landscape)
LASERWRITER (stock=DEFAULT)             30    APPLE LASERWRITER
LCG01$FORM (stock=DEFAULT)             455    LCG01
LN01S (stock=DEFAULT)                   60    64000 by 66 (LN0S )
LPS$$FORM                             1105    PostScript Default
LTR_10 (stock=PLAIN_PAPER)            1124    10-Pitch, no margins
LTR_12 (stock=PLAIN_PAPER)            1127    12-Pitch with margins
PORTRAIT (stock=DEFAULT)                20    80 by 60 (portrait)
PSBLASER (stock=DEFAULT)                47    postscript laser
PS_PLAIN (stock=PLAIN_PAPER)          1132    PostScript (Macintosh)
WPSPLUS (stock=DEFAULT)               1101    WPS-PLUS/VMS
$

The QSHOW command lists the forms mounted on both the client and the server nodes, referred to as "local" and "remote" nodes, respectively, in the command output.

QSHOW Error Messages

The DQS QSHOW command uses the same error messages as the DCL SHOW QUEUE command. In addition, the QSHOW command has its own messages for handling problems unique to the DQS software.

Server Unreachable

For example, if the server node is not currently reachable, the DQS software cannot check the status of the remote queue. You receive an explanation of the problem, like the following:

$ QSHOW CQ_EUROPE Return
***** Remote queue CHERRY::Q_PARIS not accessible *****
     %SYSTEM-F-UNREACHABLE, remote node is not currently reachable
==============================to be transferred==================
Server queue CQ_EUROPE, stalled, mounted form DEFAULT
     Jobname     Username    Entry    Blocks     Status
     -------     --------     -----   ------     ------
  TRIP_REPORT    JONES       1366       98      Processing
  Q2-FINANCIALS  JONES       1367        1      Pending

Invalid Remote Queue

Another possible error is that the remote queue is defined incorrectly. DQS software displays the following messages:

$ QSHOW CQ_EUROPE Return
%DQS-W-MSG_REMOTE, Remote system error:
-DQS-F-BADQUE, Specified queue not valid for DQS access.
==============================to be transferred==================
Server queue CQ_EUROPE, stopped, mounted form DEFAULT
  Remote system error: Specified queue not valid for DQS access.
     Jobname      Username      Entry      Blocks     Status
     -------      --------      -----      ------     ------
  Q2-FINANCIALS    JONES        1467         1        Pending

In this case, either the system manager on the server node must redefine the remote queue or the system manager on the client node must redirect the client queue to a valid remote queue.

Refer to Appendix A, DQS User Messages for a complete list of messages.

Comparison with DCL Command

The QDELETE/ENTRY command functions exactly like the DELETE/ENTRY command. (These commands do not delete files; they only remove jobs from a print queue.) You can use the DQS QDELETE/ENTRY command instead of the DCL DELETE/ENTRY command for all your print jobs.

To delete a print job, you must know:

The PRINT command displays this information by default when you queue a file for printing. You can also obtain this information by using the QSHOW command (see Chapter 3, Viewing the Status of Print Jobs).

Example

For example, if you queued the file TRIP_REPORT.P S to client queue CQ_EUROPE to print on node CHERRY, and the job is entry 1024, delete the print job by entering:

$ QDELETE/ENTRY=1024 CQ_EUROPE Return

The DQS software removes the job from the client queue. If the job has already transferred to the remote queue, the DQS software removes the job from the remote queue.

/NOTIFY Qualifier

If you specify the /NOTIFY qualifier when you queue the job for printing, the DQS software notifies you when the job is deleted.

$ QDELETE/ENTRY=341 CQ_EUROPE /NOTIFY Return
Print job TRIP_REPORT (queue CQ_EUROPE, entry 341) deleted

QDELETE Error Messages

The DQS QDELETE command uses the same error messages as the DCL DELETE command. In addition, the QDELETE command has its own messages for handling problems unique to the DQS software.

Server Unreachable

If the server node is not currently reachable, the QDELETE/ENTRY command fails and you receive an explanation, like the following:

$ QDELETE/ENTRY=1067 CQ_EUROPE Return
%DQS-I-NOJOBDELETED, No jobs deleted
%DQS-I-INACCESSIBLE, Remote queue CHERRY::Q_PARIS
is inaccessible

Invalid Remote Queue

If you use the QDELETE/ENTRY command to delete a job from a queue on a remote system that is not defined as a valid DQS remote queue, DQS software displays messages like the following:

$ QDELETE/ENTRY=1194 CQ_CANADA Return
%DQS-W-MSG_REMOTE, Remote system error:
-DQS-F-BADQUE, Specified queue not valid for DQS access.

In this case, either the system manager on the server node must redefine the remote queue or the system manager on the client node must redirect the client queue to a valid remote queue.

Refer to Appendix A, DQS User Messages for a complete list of messages.

Comparison with DCL Command

You can use the DQS QSET/ENTRY command for modifying all your print jobs. You must specify a queue name with the QSET/ENTRY command.

Before you can modify a print job, you need to know:

The DQS PRINT command displays this information by default when you queue a file for printing. You can also obtain this information by using the QSHOW command (described in Chapter 3, Viewing the Status of Print Jobs).

QSET/ENTRY Example

For example, you queued the file CHANGES.PS to client queue CQ_EUROPE to print on node CHERRY and requested two copies, as follows:

$ PRINT CHANGES.PS/QUEUE=CQ_EUROPE/COPIES=2 Return
Job CHANGES (queue CQ_EUROPE, entry 1324), pending

Now you change your mind and want three copies. You can modify the job by entering:

$ QSET/ENTRY=1324 CQ_EUROPE/COPIES=3 Return

The DQS software modifies the job in the client queue. If the job already transferred to the remote queue, the DQS software modifies the job in the remote queue. However, DQS software cannot modify a job that is moving from a client queue to a remote queue or a job that is actually printing.

QSET Qualifier Differences

Most of the qualifiers to the QSET/ENTRY command act the same as they do with the standard DCL SET/ENTRY command. Those qualifiers that have modified functions when used with the QSET/ENTRY command are described in Table 5.1, “QSET/ENTRY Command Qualifiers That Function Differently with DQSPrinting”.

QSET Error Messages

If the QSET/ENTRY command fails, the job’s specifications are unchanged and the DQS software returns an error message. Some common messages are:

Refer toAppendix A, DQS User Messages for a complete list of messages.