What Is DQS Software?

The standard OpenVMS queue system enables you to use the OpenVMS PRINT command to print files on output devices that are connected to your local OpenVMS node.

The DQS software is an OpenVMS layered product that extends the standard OpenVMS queue system to a distributed system environment. The DQS software enables you to use the OpenVMS PRINT command to print files on output devices that are connected to remote OpenVMS nodes in your network. You can also delete, and obtain or change the status of your DQS print jobs.

Why Use DQS Software?

Installing and configuring the DQS software in your network can provide:

Understanding DQS Clients and Servers

The DQS software is based on a client/server design, which consists of two cooperating software components (client and server).

The following terms are associated with DQS servers:

Server nodes: Nodes in your network that have connections to output devices (for example, printers) that you want to make available to the users on other nodes (client nodes) in your network.

Remote queue: DQS queue on the server node that directs print jobs from client nodes to the connected printer. (Standard OpenVMS print queues are queues that direct print jobs to printers connected to the local node.)

Server software: DQS software that you must install and configure on server nodes.

The following terms are associated with DQS clients:

Client nodes: Nodes whose users are able to print files on printing devices that are connected to remote DQS server nodes.

Client queue: DQS queue on the client node that directs print jobs to the associated remote queue on the DQS server node.

Client software: DQS software that you must install and configure on client nodes.

A node can be only a client, or both a client and a server. Each client can be configured to send print jobs to any server. Similarly, each server can be configured to accept print jobs from any client. Chapter 2, Configuring and Managing a DQS Server and Chapter 3, Configuring and Managing a DQS Client describe the procedures for configuring servers and clients, respectively.

Using DQS Software in a Cluster

In a VMScluster environment, a server is potentially every node in a cluster. Similarly, a client is potentially every node in a cluster. Therefore, if a user logs on to different cluster members at different times, the DQS software is always available.

To use the DQS software in a cluster environment:

While DQS software can be used on selected nodes of a cluster, doing so does not take advantage of the flexibility of a cluster.

Network Requirements for DQS Software

DQS software uses the DECnet network to communicate between clients and servers and to perform its functions. The DQS software requires:

Phase IVand Phase V Networks

The DQS software can be used in both DECnet Phase IV and DECnet/OSI Phase V networks. DQS software also operates in properly configured networks that use both networking products. DECnet/OSI systems can be set up to use synonyms to communicate with Phase IV systems.

DECnet Phase IV networks limit node names to six characters. DECnet/OSI Phase V networks allow the use of an expanded node name (full names). DQS clients and servers can handle node names with up to 150 characters with no embedded blank spaces.

Overview

The major functions of the DQS software are initiated by the PRINT, QSHOW, QSET/ENTRY, and QDELETE/ENTRY commands. DQS software uses:

Primary Functions

Figure 1.1, “Overview: Primary Function of the DQS Software” shows the primary functions of the DQS software.

The Process

The stages shown in Figure 1.1, “Overview: Primary Function of the DQS Software” are summarized as follows:

Summary of DQS Commands

Most of the standard OpenVMS command qualifiers are fully supported for the DQS versions of the PRINT, SHOW, SET, and DELETE commands. Table 1.1, “Summary of DQS Commands” summarizes the DQS commands.

Refer to Distributed Queuing Service for OpenVMS Systems User's Guide for more information on the DQS commands and their qualifiers.

PRINT Command Functions

Figure 1.2, “The DQS PRINT Command Process” shows the functions of the PRINT command using a DQS queue.

The Process

The stages in the PRINT process are summarized as follows:

After the printer prints the file, the DQS$NOTIFIER process on a server deletes the file from the DQS server account (see the section titled The DQS Server Account). If a user requests notification of job com pletion, the DQS$NOTIFIER attempts to notify the user before it deletes the files associated with the print job.

Other DQS Commands

Figure 1.3, “DQS QSHOW, QSET/ENTRY, and QDELETE/ENTRY Commands Processes” shows the functions of the QSHOW, QSET/ENTRY, and QDELETE/ENTRY commands.

The Process

The stages in the DQS QSHOW, QSET/ENTRY, and QDELETE/ENTRY command processes are summarized as follows.

Commands with OpenVMS Queues

The DQS QSHOW, QSET/ENTRY, and QDELETE/ENTRY commands also work on standard OpenVMS print queues. For an entry in a standard OpenVMS queue, QSHOW, QSET/ENTRY, and QDELETE/ENTRY do not send information to a server.

Summary of Components

Table 1.2, “Functions of the DQS Software Components” summarizes the major software components of the DQS software and describes their functions.

Sending Messages to Users

If you specify /NOTIFY qualifier with the PRINT command, the notification service sends job completion messages when print jobs have completed.

DQS software returns two notification messages:

Deleting Jobs from Remote Queue

The notification process on the server node, DQS$NOTIFIER, also has the task of deleting completed print jobs from the remote queue. The DQS$SERVER program submits all DQS print jobs with the /RETAIN=ALWAYS qualifier. DQS print jobs remain in DQS queues after the job is printed until the DQS$NOTIFIER deletes them.

If a user requests notification of job com pletion, DQS$NOTIFIER attempts to notify the user before it deletes the files associated with the user’s print job.

How It Works

Figure 1.4, “Function of the DQS Notification Service” shows how the DQS notification service works.

The Notification Process

The DQS notification process shown in Figure 1.4, “Function of the DQS Notification Service” works like this:

For more information on using the /NOTIFY qualifier with the PRINT command, refer to the "Printing Files Using DQS Software" chapter in DEC Distributed Queuing Service for OpenVMS Systems User's Guide and the OpenVMS DCL Dictionary.

Overview

The DQS software contains two symbionts DQS$SMB and DQS$PRTSMB, which are described in this section.

DQS$SMB

DQS$SMB runs on client systems. The symbiont takes DQS print jobs from client queues and transfers them to the associated server node.

DQS$PRTSMB

DQS software provides its own print symbiont, DQS$PRTSMB, which is a modified version of the standard OpenVMS print symbiont, PRTSMB. (The DQS$PRTSMB symbiont is upwardly compatible with the OpenVMS PRTSMB symbiont.) DQS$PRTSMB causes the client job number, the client node name, and the time a print job was queued on the client to be printed on the flag, burst, and trailer pages of DQS print output. With the DQS print symbiont controlling each remote queue on a server, the users of that server see the same job information on their print output that they saw displayed when they entered the print request on the client node.

If the standard OpenVMS print symbiont does not handle banner pages to your satififaction, replace it with the DQS print symbiont, DQS$PRTSMB. If DQS$PRTSMB does not control a remote queue on a server, the standard OpenVMS print symbiont prints the job number of the print job in the remote queue, as well as the time that the print job was queued on the server on the DQS print output.

DQS$PRTSMB can only replace the OpenVMS print symbiont.

For a description of the procedures for enabling the DQS print symbiont to control remote queues, see Chapter 2, Configuring and Managing a DQS Server.

Refer to Appendix B, Using DQS With Various Symbionts for information on how DQS$PRTSMB relates to other symbionts.

Overview

You must define all forms that you intend to specify on both the client and its associated servers. To synchronize form definitions on your clients and servers, you can run the DQS$CLIENT program on the client system (see Chapter 3, Configuring and Managing a DQS Client).

No Form on Server

If you attempt to print using a form that is not defined on the associated server, the client queue accepts the job and the system prompt returns ($). However, your print job remains in the client queue with the error status %DQS-F-NOSUCHFORM. A QSHOW command specifying the client queue where you queued the job shows the retained job and the error message.

Different Values

Because DQS software transfers only a form’s name from a client to its server, a form may have different values on different DQS systems. When the same form is defined differently throughout your network, the server’s form definition is used to print a job.

VSI strongly recommends that you give forms with the same name the same definitions throughout your network. However, you may want to have different form definitions because it enables users on client systems to maintain their local form definitions to use when printing locally.

Chapter 3, Configuring and Managing a DQS Client describes the procedures for synchronizing form definitions.

Overview

The DQS installation procedure creates a DQS account, DQS$SERVER, and its associated directory [DQS$SERVER] on all DQS client and server nodes.

On a Server

A DQS server process is run from the DQS$SERVER account when a connection request is received from a client node. The directory associated with this account [DQS$SERVER] stores files received from client nodes until the files are printed on the server node’s output device. After a print job completes, the files associated with the job are deleted from the server account directory.

On a Client

The DQS$SERVER account is located on clients to receive job com pletion messages from the DQS$NOTIFIER process on the server. DQS$SERVER on a client broadcasts job com pletion messages to each user who owns a completed print job, if the user specified /NOTIFY on the PRINT command.

Overview

The OpenVMS PRINT command allows you to pass from one to eight optional parameters with a print job. DQS software uses parameter 8 to store print job information. Place your print parameter values in parameter 1 to parameter 7.

Use in DQS Printing

DQS software uses the information in parameter 8 to:

The information stored in parameter 8 includes:

Error Messages

DQS software issues an error (%DQS-E-P8RE SERVED) if you attempt to specify parameter 8 with either a PRINT or a QSET/ENTRY command.

For more information about:

Client and Server Installation

When you run the DQS installation procedure, you are asked whether you want to install DQS server software. You are given this option because not all DQS nodes in your network require server software (for example, those nodes without connections to output devices). However, most or all nodes in your network require client software so that their users can have access to remote printing resources. Therefore, client software is always installed when you install DQS software.

Client and Server Configuration

A client must be configured to work with its corresponding servers (and vice versa) in order for DQS software to function. You can configure a server to serve as many clients as you want.

Similarly, you can configure a client to use the services of any number of servers. There are no restrictions on the number of DQS servers or clients that you can have in your network.

Restrictions to DQS Configurations

The DQS software is suitable for all OpenVMS nodes in DECnet networks. DQS software can be used in small networks consisting of two nodes and in large networks consisting of many nodes. DQS software operates in either local area networks or wide area networks.

DQS software is limited only by the ability of DQS servers to accept and maintain a large number of simultaneous network connections (that is, logical links) to DQS clients. The maximum number of logical links that a server can support is a parameter that you can define using the Network Control Program (NCP) on DECnet Phase IV systems and the Network Control Language (NCL) on DECnet/OSI Phase V systems. The value of this parameter depends upon many factors, such as the server’s processor speed and its typical work load.

Each logical link from a client creates one process on a server. A server must be configured to allow for enough processes. (See the section entitled Processes Created by DQS Software, which describes the processes created by the DQS software on both clients and servers.)

In addition to handling its other network applications, a server should be able to accept simultaneous connections from all clients that it serves. However, all clients trying to access the server at the same time is unlikely. Any client that attempts to print on the server after the maximum number of logical links is reached, automatically attempts to reconnect to the server after a short wait. The QSHOW, QSET/ENTRY, and QDELETE/ENTRY command functions do not attempt this automatic reconnection.

Purpose

You can configure the DQS software in your network so that a client queue corresponds to a remote queue, which in turn, corresponds to another remote queue on another server. This configuration is called daisy-chained queues. You can daisy-chain queues across as many servers as you want.

Benefits

Daisy-chained queues are useful when a printer on a server becomes temporarily unavailable. Users who want to send jobs to the disabled server can still do so if the server’s system manager sets up the remote queue to redirect their print output to another server’s output device. No change is made to the user’s client system, and the users may not even know that the printer was unavailable.

Daisy-chained queues are also useful when a network link from a client to its server is only occasionally available. With daisy-chained queues you can effect a "store and forward" function, where a job is transferred to a reachable, intermediate server that stores the job until the desired server is reachable.

Example

Figure 1.5, “Daisy-Chained Queues” depicts a daisy-chained queue configuration.

Process

The daisy-chain process shown in Figure 1.5, “Daisy-Chained Queues” works as follows:

Avoiding Loops

Avoid creating a loop when configuring daisy-chained queues. If you configure a daisy-chained queue to direct a job back to the system where the job was originally queued, the job terminates on that system with the error, %DQS-E-LOOP.

For More Information

Refer to Distributed Queuing Service for OpenVMS Systems Installation Guide for more information on the installation of DQS software.

Chapter 2, Configuring and Managing a DQS Server and Chapter 3, Configuring and Managing a DQS Client, respectively, describe the procedures for configuring servers and clients after installation of the software.

Chapter 2, Configuring and Managing a DQS Server describes the procedures for setting up daisy-chained queues.

Error Detection

When DQS software detects an error condition, the error is sent to the OpenVMS operator communication process (OPCOM). If an error is detected in a server process, it is also written to a NETSERVER.LOG log file on the server.

Types of Errors

There are three basic types of errors that can occur in DQS printing.

Examples

Example 1.1, “A DQS Error That Prevents a Print Job From Transferring” shows an error detected by the client symbiont, DQS$SMB. The error does not affect the operation of the symbiont but causes the job responsible for the error to terminate with error status. The affected job remains in the client queue with the error status "Retained on error." In this case, you must either requeue or delete the print job. In Example 1.1, “A DQS Error That Prevents a Print Job From Transferring”, the client node has a form defined that is not defined on the server. This prevents the print job from transferring. A QSHOW command specifying the client queue where the job was queued shows the retained job and the specific reason for the error.

$ QSHOW QUEUE1 Return
** Remote queue - [ QUEUE1 => SYS$PRINT, on NODEB:: ]
Terminal queue SYS$PRINT, on NODEB::
==============================to be transferred==============================
Server queue QUEUE1, on NODEA::, mounted form DEFAULT
Jobname Username Entry Blocks Status
------- -------- ----- ------ ------
JOB PAUL 925 1 Retained on error
%JBC-E-NOSUCHFORM, no such form

Example 1.2, “A DQS Error That Stops a Client Queue” shows an error detected by the client symbiont, DQS$SMB, that caused the client queue to stop. The DQS$STATUS_queue-name logical name is defined to be the error status. This action makes it easy to see the reason for the error by issuing a QSHOW command for the client queue. In

Example 1.2, “A DQS Error That Stops a Client Queue”, the server node name is not known on the client. Therefore, the symbiont cannot process any jobs for that queue and stops the queue.

Note

Remember to deassign the DQS$STATUS_queue-name logical name when you restart the queue.

$ DEASSIGN/SYSTEM/USER DQS$STATUS_queue-name Return 

$ QSHOW QUEUE1 Return
***** Remote queue NODEB::QUEUE1 not accessible *****
%SYSTEM-F-NOSUCHNODE, remote node is unknown
==============================to be transferred==============================
Server queue QUEUE1, stopped, on NODEA::, mounted form DEFAULT 
       remote system error: remote node is unknown
   Jobname     Username    Entry    Blocks    Status
   -------     --------    -----    ------    ------  
   LOGIN        YOUNG        571         2    Pending

Refer to Chapter 4, Troubleshooting for guidelines on how to troubleshoot error conditions that involve DQS software.

Restricting Access

By default, all client nodes have access to a server.

You can restrict access to a server node only by client system, not by individual client users.

Chapter 2, Configuring and Managing a DQS Server describes the procedures for granting or denying client access to a server.

On a Client

On a client node, every client queue that you create (that is not a generic or logical queue) results in the creation of one process.

Also, while a user is being notified of print job completion, a process is temporarily created.

On a Server

For server nodes, every incoming connection from a client node results in the creation of one process. Also, the notification process on a server uses one permanent process.

Supported Devices

DQS software does not run devices; rather, it places print jobs in queues for processing. DQS software supports devices by placing jobs in queues, if the device

DQS software does not support symbionts that require job information outside of that stored or maintained by the OpenVMS queue system.

DQS software supports the queuing of print jobs for processing on remote nodes in your network. It does not support the queuing of batch jobs.

Do not configure batch queues to be DQS printer queues. DQS software does not prevent you from configuring batch queues, but the security of the system decreases if you do so.

Main Tasks

Configuring and managing a DQS server primarily involves:

The SYS$STARTUP:DQS$STARTUP.COM procedure

Do not edit SYS$STARTUP:DQS$STARTUP.COM.

Using SYSMAN

When directed to restart DQS software in a VMScluster, you can use one of the following methods:

Procedure

To make permanent changes to your server configuration in the DQS$SYSTARTUP.COM file, do the following:

$ DEFINE/SYSTEM/EXECUTIVE_MODE
_$ logical-name values Return

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$PRIORITY 5 Return

Adding the logical name definitions to the SYS$MANAGER:DQS$SYSTARTUP.COM file ensures that the logical name is defined each time your server reboots or each time the SYS$STARTUP:DQS$STARTUP.COM procedure is executed on a cluster member.

Precaution

Do not execute the DQS$STARTUP.COM procedure unless it is necessary. Executing DQS$STARTUP.COM terminates any DQS network operations in progress. This may cause files transferred from a client to be left on the server with no association to the client job. When this happens, the server directory clean-up process, DQS$CLEANSRV.COM, detects and deletes the stray files left on the server disk. (DQS$STARTUP.COM submits the DQS$CLEANSRV.COM procedure at start-up time.)

Changes at DCL Prompt

You can also define some DQS server logical names by entering the definition at the DCL prompt. These changes to server configuration:

Logical Names

For changes to the following logical name definitions to take effect, you must make your changes in the site-specific startup file DQS$SYSTARTUP.COM and restart all server processes:

Restarting Server Processes

To restart the server processes, execute the DQS$STARTUP.COM command procedure.

$ @SYS$STARTUP:DQS$STARTUP Return

Executing DQS$STARTUP.COM terminates any DQS network operations in progress.

Ensure Queues Exist

A queue must exist before you can set up the queue as a DQS remote queue. You can use existing queues or create (or initialize) new queues. (Refer to the OpenVMS System Manager’s Manual for information on how to initialize a queue.)

For New Installations

If you are installing this product for the first time, the DQS installation provides the following server configuration file to which you need to add your queue configurations:

SYS$MANAGER:DQS$SERVER_CONFIG.TXT 

For Product Upgrades

If you are upgrading from a version previous to Version 1.3, the installation procedure:

Compare the queue definitions in the DQS$SERVER_CONFIG.TXT file to those in DQS$STARTUP.COM_OLD. You may need to edit DQS$SERVER_CONFIG.TXT to ensure that your queue definitions are as you want them.

Keywords

You enable network access to queues and control authorization to the server node and remote queues by using the following keywords in the DQS$SERVER_CONFIG.TXT file:

QUEUE: Declares a queue as a DQS network accessible queue. You must specify this keyword to allow network printing.

You also use the QUEUE keyword to specify which authorized client nodes have access to the queue.

DENY_NODE: Denies a client node authorization to the DQS servers on the server node. This keyword takes precedence over all other keywords.

ALLOW_NODE: Grants only the client nodes you specify authorization to the DQS servers on the server node. All other nodes are denied authorization.

The QUEUE keyword differs from the other keywords. QUEUE controls access to queues, whereas ALLOW_NODE and DENY_ NODE authorize access to the DQS servers on the server node.

Client Authorization Process

Figure 2.1, “Checking a Client Node’s Authorization” shows how the configuration file checks that the client node is authorized to access the server node and remote queue.

Features of the File

When you edit the DQS$SERVER_CONFIG.TXT file, notice the following:

Setting up remote queues involves editing DQS$SERVER_CONFIG.TXT and:

The following sections explain how to do these tasks.

Procedure

Enable network access to the queues with the QUEUE keyword. (This step is required.)

Specify one QUEUE entry for each remote queue on your system. This allows the remote queue to be DQS network accessible to authorized client nodes.

By default, all client nodes in your network are authorized to access the DQS servers on your node.

Unlimited Queue Access

You can use the asterisk (*) as a wildcard to allow all authorized client nodes access to the print queues.

Example

For example, the following entry allows all authorized client nodes access to the print queue Q_CHICAGO:

QUEUE Q_CHICAGO *

Limited Queue Access

To allow only certain authorized client nodes access to your queue, enter a QUEUE entry for each node that you want to allow access to that particular queue.

Example

For example, the following entries allows authorized client nodes APPLE, BANANA, and CHERRY access to Q_PARIS:

QUEUE Q_PARIS APPLE      ! Allow authorized client nodes APPLE,
QUEUE Q_PARIS BANANA     ! BANANA, and CHERRY access to
QUEUE Q_PARIS CHERRY     ! my queue Q_PARIS

Where to Go from Here

Enabling network queue access is the only required step. If you want to grant or deny certain client nodes authorization to DQS servers on your server node, continue to the next sections. Otherwise, see the section titled "Making Your Changes Take Effect."

Purpose

Denying client nodes authorization to the DQS servers is primarily intended to shut out clients that inappropriately and repeatedly establish connections to a server. Denied authorization takes precedence over any other form of client access control.

Procedure

To deny a client node authorization to a DQS server on the server node, specify the name of the client node as the first argument to the DENY_NODE keyword.

Example

For example, the following entry denies client node APPLE from accessing DQS servers on the server node:

DENY_NODE APPLE 

Denying All Clients

To deny all client nodes authorization to the DQS servers, add an entry with the asterisk ( * ) as the first argument to the keyword:

DENY_NODE *         ! Deny authorization to all nodes 

This restricts all client nodes access to your DQS servers.

Purpose

You can grant certain client nodes authorization to DQS servers on a server node. This method is useful when you want to allow a subset of client nodes access to the DQS servers on the server node.

Reminder

If you use ALLOW_NODE, keep in mind:

Procedure

Add the names of the client nodes to which you want to grant authorization to the DQS server as the argument to the ALLOW_ NODE keyword.

Example

For example, the following entries allow client nodes APPLE and CHERRY access to the DQS server:

ALLOW_NODE APPLE
ALLOW_NODE CHERRY 

Using ALLOW_NODE with QUEUE

You can use the ALLOW_NODE and QUEUE keywords together as a filter in restricting access to the DQS server and queues. First you specify which clients nodes have access to the queue, then you specify which client nodes can access the DQS server.

Procedure

Use the following procedure to set up restricted access:

Result

The combination of the ALLOW_NODE and QUEUE entries allows only a subset of client nodes (APPLE and GRAPE) access to queues Q_OHIO, Q_KANSAS, and Q_SHANNON.

Note

When using controlled access between two DQS server nodes that also act as client nodes, make sure each DQS server node is authorized access to the other node. Otherwise, notification messages may not be delivered.

Procedure

When you are finished adding keywords to the configuration file, exit from the file and execute DQS$SERVER_UPDATE_CONFIG.COM to establish your changes:

$ @SYS$MANAGER:DQS$UPDATE_SERVER_CONFIG Return

Changes to the DQS$SERVER_CONFIG.TXT data file take effect the next time the client establishes a new connection to the server.

Methods

You can determine how and when clients access a particular server by doing any of the following:

Checking for Client Access

You can check the NETSERVER.LOG log files in the server account directory for records of client node access. However, these files are periodically purged. Example 2.1, “Viewing NETSERVER.LOG Information” shows how to view this file.

$ TYPE SYS$COMMON:[DQS$SERVER]NETSERVER.LOG Return

If you moved the directory, the log files might not be in SYS$COMMON.

Logging Client Access to a Server

DQS software counts each occurrence of a client connecting to a server if you define the DQS$LOG_ACCE SS logical name on the server. With DQS$LOG_ACCE SS defined, the server process creates a file in the [DQS$SERVER.NODES] subdirectory of the server account. This file has the name of the client. If the [DQS$SERVER.NODES] subdirectory does not already exist, the server process creates it.

Procedure

To define the DQS$LOG_ACCE SS logical:

Examples

Example 2.2, “Logging Client Access to a Server” defines the DQS$LOG_ACCE SS logical name to be the arbitrary value ENABLED.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$LOG_ACCESS ENABLED Return

Example 2.3, “Looking at DQS$SERVER.NODES” shows a sample directory listing of the [DQS$SERVER.NODES] subdirectory that contains the names of the clients that accessed the server.

$ Directory SYS$COMMON:[DQS$SERVER.NODES] Return
Directory SYS$COMMON:[DQS$SERVER.NODES]
SMEDLY.;78    BUGSBY.;1407    JAZZY.;3    RAZBRY.;2
STENCL.;397   STIKNY.;24      TOKYO.;25
Total of 7 files.

Because there is a one-version limit for the [DQS$SERVER.NODES] subdirectory, only one file per client is created. The version number of the file corresponds to the number of logical-link connections received from the client.

Node names displayed in this file are trimmed to 8 characters. Some characters may be converted to underscores.

Enabling Client Accounting Information

With the DQS$ACCOUNTING_BY_SYST EM logical name defined on the server, the DQS software includes the client’s node name as the Account field in the server’s accounting record.

User node names written to this record are trimmed to 8 characters. Some characters may be converted to underscores.

Example with Logical Defined

For example:

$ RUN AUTHORIZE Return
UAF> SHOW MACOMBER Return
Username: MACOMBER                    Owner: Ted Macomber
Account: DEVELOPMENT                  UIC: [100,1] ([MACOMBER])
. . .
UAF> EXIT Return
$ ACCOUNTING/TYPE=PRINT/FULL Return
Username:          MACOMBER       UIC:                [DQS$SERVER]
Account:           SMEDLY         Finish time:        14-FEB-1994 11:49:29.88
Process ID:        00000D9A       Start time:         14-FEB-1994 11:49:24.59
Owner ID:                         Elapsed time:                 0 00:00:05.29
Terminal name:                    Processor time:               0 00:00:00.00
Remote node addr:                 Priority:           100
Remote node name:                 Privilege <31-00>:  00000000
Remote ID:                        Privilege <63-32>:  00000000
Remote full name:
Queue entry:       721            Final status code:  00040001
Queue name:        SERVER
Job name:          ACCOUNTING
Final status text: %JBC-S-NORMAL, normal successful completion
GETs from source:           180
QIOs to printer:              5
Pages printed:                5

Example with Logical Undefined

If you do not define this logical, the DQS client software uses the Account field specified in the client’s User Authorization File (UAF) on the client for the user who issued the PRINT command. For example:

$ ACCOUNTING/TYPE=PRINT/FULL Return
PRINT   Job   Termination
---------------------
Username:           MACOMBER          UIC:              [DQS$SERVER]
Account:            DEVELOPMENT       Finish time:      14-FEB-1994 11:49:07.65
Process ID:         00000D9A          Start time:       14-FEB-1994 11:49:02.36
Owner ID:                             Elapsed time:               0 00:00:05.29
Terminal name:                        Processor time:             0 00:00:00.00
Remote node addr:                     Priority:          100
Remote node name:                     Privilege <31-00>: 00000000
Remote ID:                            Privilege <63-32>: 00000000
Remote full name:
Queue entry:        717               Final status code: 00040001
Queue name:         SERVER
Job name:           ACCOUNTING
Final status text:  %JBC-S-NORMAL,    normal successful completion
GETs from source:          180
QIOs to printer:             5
Pages printed:               5

Procedure

To define the DQS$ACCOUNTING_BY_SYST EM logical name:

$ DEFINE/SYSTEM/EXECUTIVE_MODE - Return
_$ DQS$ACCOUNTING_BY_SYSTEM ENABLE Return

Example

Example 2.4, “Enabling Client Accounting Information” defines the DQS$ACCOUNTING_BY_SYST EM logical name to be the arbitrary value ENABLED.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$ACCOUNTING_BY_SYSTEM ENABLED Return

Banner Page Note

The DQS software makes use of a print attribute to place a note on the banner page of a print job when logical names are defined in the DQS$SYSTARTUP.COM file. On the server, this logical name definition provides the default text ‘‘Print Job processed by DQS Vn.n’’. The note defined by this logical name prints on the banner page of a print job if:

The note that prints on the banner page of a print job follows this order of precedence:

Options

You have the following options:

To Turn Off the Default

To turn off the DQS default note on the server system, do the following:

$! $ DEASSIGN/SYSTEM/EXEC DQS$SERVER_DEFAULT_JOB_NOTE

The change takes effect the next time the SYS$STARTUP:DQS$STARTUP.COM is executed.

To Change Note Text

To change the text of the note that prints on the banner page, do the following:

$!   $ DEFINE/SYSTEM/EXEC DQS$SERVER_DEFAULT_JOB_NOTE -
$!         "Place your text here"

The next time the SYS$STARTUP:DQS$STARTUP.COM is executed and the note is not specified by the user or the client, your customized note prints on the job banner page.

Purpose

You can define the DQS$STATUS_queue-name logical name so that a status message is displayed each time a user enters a QSHOW comman d for the specified queue (or any DQS queue that points to that queue). This function is useful for displaying printer status messages, such as "Q_PRINTER is down until 1PM for repair."

Procedure

To define the DQS$STATUS_queue-name logical name:

$ DEFINE/SYSTEM/EXECUTIVE_MODE -
_$ DQS$STATUS_queue-name "Message" Return

When you change the value of the DQS$STATUS_queue-name logical name, the next display of the queue shows the new message.

Example

Example 2.5, “Defining a Status Message for a Queue” specifies that the status message "Down for repairs" displays each time a user enters a QSHOW command for the remote queue Q_PARIS.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$STATUS_Q_PARIS "Down for repairs" Return

$ DEASSIGN/SYSTEM/EXECUTIVE_MODE DQS$STATUS_Q_PARIS Return
$ DEASSIGN/SYSTEM/USER DQS$STATUS_Q_PARIS Return

Why Use the DQS Symbiont?

DQS software supplies its own print symbiont, DQS$PRTSMB, which you can use to replace the standard OpenVMS print symbiont on a server unless you use the DECprint Supervisor for OpenVMS software. The DQS print symbiont writes client- specific job information on the burst, flag, and trailer pages of DQS print output. If you do not like the way the standard OpenVMS symbiont handles banner pages, enable the DQS print symbiont DQS$PRTSMB.

Procedure to Enable

To enable the DQS print symbiont to control a remote queue, do the following:

Example

Example 2.6, “Enabling the DQS Print Symbiont” shows how to enable the DQS print symbiont DQS$PRTSMB to control the remote queue Q_PARIS.

$ STOP/QUEUE/RESET Q_PARIS Return
$ INIT/QUEUE/PROC=DQS$PRTSMB Q_PARIS Return
$ START/QUEUE Q_PARIS Return
$ SET QUEUE/RETAIN=ERROR Q_PARIS Return

Refer to Chapter 1, Understanding the Distributed Queuing Service for more information on the DQS$PRTSMB symbiont.

Appendix B, Using DQS With Various Symbionts describes how the DQS software works with other print symbionts.

About the Notifier

The DQS software supplies a process on server nodes, DQS$NOTIFIER, that can send notification messages to users after their print jobs com plete. DQS$NOTIFIER runs as a detached process on a server and is started by the SYS$STARTUP:DQS$STARTUP.COM procedure at system start-up time. This process periodically scans remote queues to determine which print jobs are complete.

Procedure

You can specify the interval at which the server notification process scans the remote queue by defining the DQS$NOTIFY_CYCLE_TIME logical name to be a time in OpenVMS delta time format. By default, the notify cycle time is five minutes.

To specify the DQS$NOTIFY_CYCLE_TIME logical name:

If you change the default time, consider the following:

Example

Example 2.7, “Specifying the Scanning Interval for DQS$NOTIFIER” defines the interval at which DQS$NOTIFIER scans the remote queues to be every 10 minutes. The DQS$NOTIFIER process is stopped and restarted to effect this change.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$NOTIFY_CYCLE_TIME "0 00:10:00.0" Return

$ @SYS$STARTUP:DQS$STARTUP.COM Return

Overview

If your Print Server software supports the return of log files from DQS print jobs, you can specify a directory into which the log files can be placed.

You specify a directory for the Print Server log files by defining the DQS$LOG_AREA logical name to be the name of the directory.

Procedure

To specify a directory for Print Server software log files:

$ DEFINE/SYSTEM/EXECUTIVE_MODE
_$ DQS$LOG_AREA device:[directory] Return

If you want this logical name to be permanent, define the logical name in the SYS$MANAGER:DQS$SYSTARTUP.COM.

If this logical name is not defined, the Print Server software does not write log files for DQS print jobs.

Example

Example 2.8, “Specifying a Directory for PrintServer Log Files” specifies the directory [PRINTSERVER] on device $1$DUA0: on the server as the directory for Print Server log files.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$LOG_AREA $1$DUA0:[PRINTSERVER] Return

For more information on logging options for the Print Server Software, refer to the Print Server Software for OpenVMS Management Guide.

Procedure

You can specify the priority at which the server process runs by defining the DQS$PRIORITY logical name to be the desired priority. Be aware that redefining the DQS$PRIORITY logical name affect s scheduling algorithms on the OpenVMS system and changes overall system performance.

Example

Example 2.9, “Specifying the Priority of the Server Process” shows the command to add to the SYS$MANAGER:DQS$SYSTARTUP.COM file to set the server process to run at priority 5.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$PRIORITY 5 Return

The next time a server process is started, the server process runs at the specified priority.

Procedure

You can specify the maximum priority at which a print job can be queued or set by a user, by defining the DQS$MAX_PRIORITY logical name.

Example

Example 2.10, “Specifying the Maximum Priority for Queuing Print Jobs” specifies that print jobs can be queued at no higher than priority 42.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$MAX_PRIORITY 42 Return

Overview

You can specify the duration that a server maintains logical links to inactive clients. A client is considered inactive if it is not sending print jobs to a server.

Procedure

You specify the duration of logical links by defining the DQS$IDLE_TIME logical name to be the time duration in minutes in OpenVMS delta time format.

When you redefine the DQS$IDLE_TIME logical name, con sider the following:

Example

Example 2.11, “Specifying the Duration of Links to Inactive Clients” specifies that the server maintains logical links to idle clients for at least 45 minutes.

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$IDLE_TIME "0 00:45:00.0" Return

Idle Time Exceeded

The DQS software responds as follows:

Storage Space

The amount of storage space required for the server account directory varies depending on the following:

The DQS server installation sets the default device for the server account to SYS$COMMON:. You can use the DQS$SERVER_CHANGE_DEFAULT_DEVICE.COM procedure to change the default to another disk or back to SYS$COMMON:.

Procedure

If you want to move the server account directory to a device other than the system disk, execute the DQS$SERVER_CHANGE_ DEFAULT_DEVIC E.COM procedure by entering the following command at the DCL prompt:

$ @SYS$MANAGER:DQS$SERVER_CHANGE_DEFAULT_DEVICE Return

DQS$SERVER_CHANGE_DEFAULT_DEVIC E.COM asks you for the device for the account storage.

Enter device for the DQS$SERVER account: 

Enter the name of the device to use for the server account. For example, if your server account is to be on device USERDISK, enter USERDISK:.

Enter device for the DQS$SERVER account:USERDISK: Return

After you enter the device name, you see a series of status messages, such as the following:

User record(s) updated
DQS$SERVER directory is now located on device USERDISK:
To start DQS, enter following:
      $ @SYS$STARTUP:DQS$STARTUP.COM
In VMScluster environment, you need to start DQS on each node
in a cluster.
$

In an OpenVMScluster environment, you can configure:

When you configure different sets of queues, you need to:

The following sections explain how to configure different sets of queues.

Requirement

When you configure different sets of queues for different groups of nodes, you must define the same notifier lock name on all cluster members that share a particular set of queues.

Procedure

To ensure that each set of queues is associated with a common and unique notifier lock, define the DQS$NOTIFY_LOCK logical name to be the same, unique lock name on all cluster nodes that share the same set of queues.

By default, the DQS installation names the notifier lock to be DQS$NOTIFIER.

Example

For example:

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$NOTIFY_LOCK DQS$NOTIFIER_2 Return

Recommended Configuration

VSI recommends that you use the same DQS server configuration for all nodes within your cluster. The DQS installation sets up the DQS software on your system with this recommended configuration in mind. As a result, the default values for the locations of the DQS server configuration files are both specifically located in the SYS$COMMON areas of your clusters file system.

The DQS software uses VMS logical names to locate the server configuration files.

Location of Configuration Data

The location of the server configuration text is controlled by the logical DQS$SERVER_CONFIG_TXT_FILE. The default value for this logical is SYS$COMMON:[SYSMGR]DQS$SERVER_CONFIG.TXT.

The location of the encoded file that the DQS$SERVER.EXE program uses to validate a client’s request for access to a particular server queue is controlled by the logical DQS$SERVER_CONFIG_DAT_FILE. The default value for this logical is SYS$COMMON:[SYS EXE]DQS$SERVER_CONFIG.DAT.

Specifying Multiple Server Configuration Files

DQS can support multiple server configuration files within a cluster. If your cluster cannot use the default configuration, you can use the DQS$SERVER_CONFIG_TXT_FILE and DQS$SERVER_CONFIG_DAT_FILE logical names to provide multiple, separate, DQS server configurations within the same cluster.

Procedure

To modify the logicals, use the following procedure:

Execute the Start-up Procedure

If you specify remote queues on any node in a VMScluster system, you must execute the SYS$STARTUP:DQS$STARTUP.COM procedure on each cluster member. If you do not, DQS connections to the cluster fail randomly because not all nodes in the cluster are configured as DQS servers.

The cluster should have an incoming cluster alias defined so that clients can direct their print jobs to that cluster alias.

Benefits

Daisy-chained queues are useful when a server’s output device becomes unavailable. In this case, you can define the remote queue for the unavailable device also to be a client queue that directs print jobs to yet another remote queue on another DQS server node.

Defining

To define a remote queue as a daisy-chained queue, define the remote queue to be a DQS client queue, using any of the methods described in Chapter 3, Configuring and Managing a DQS Client:

Beware of Loops

The DQS software does not prevent you from creating a loop in your daisy-chained queues. Be sure not to set up daisy-chained queues where print jobs ultimately are directed back to the queue from which they were forwar ded.

Fixing Looping Errors

Perform the following procedure to eliminate a loop:

Table 2.1, “QSET/ENTRY Command Qualifiers That Function Differently with DQSPrinting” lists the management tasks and how the task is performed for the DQS server.

Management Tasks

Configuring and managing a DQS client primarily involves defining DQS client queues to direct print jobs to associated remote queues on server systems. You can also modify and delete DQS client queue definitions.

DQS software provides the following methods of defining and managing client queues:

Executing the DQS Startup Procedure

To start or restart client queues, you must use the SYS$STARTUP:DQS$STARTUP.COM procedure. This procedure invokes the required procedures to define client queues on the system.

Overview

On a client node, every client queue that you create (that is not a generic or a logical queue) results in the creation of one process.

One Client; One Process

If you do not anticipate a problem with the number of processes on your client node, then you can use either of the following procedures to create client queues:

Both result in the creation of a process for each client queue.

Reducing Processes

If you do not want to create as many processes as client queues, then you can create either of the following types of client queues:

Generic and logical queues direct jobs to other client execution queues that actually process the job. Therefore, fewer processes are created on your client node.

A Basic Method

The most basic way to create DQS client queues is to invoke the DQS$IMPORT.COM comman d procedure.

The DQS$IMPORT.COM procedure provides a way to permanently define client queues. The queue definition is automatically added to the DQS$SYSTARTUP.COM comman d file. This ensures that the client queue starts with the proper definition each time the client system is rebooted.

Before You Start

Before you can define a client queue with the DQS$IMPORT command procedure:

Procedure

Create a client queue with the DQS$IMPORT.COM procedure as follows:

$ @SYS$MANAGER:DQS$IMPORT server-node::remotequeue
Return

DQS$IMPORT.COM then does the following:

Example

Example 3.1, “Creating a Client Queue with DQS$IMPORT.COM” shows how to use DQS$IMPORT.COM to create a client queue Q_CHICAGO that uses the name of the correspon ding remote queue Q_CHICAGO on the server node APPLES.

$ @SYS$MANAGER:DQS$IMPORT APPLES::Q_CHICAGO Return

DQS$IMPORT.COM adds this client queue definition to the DQS$SYSTARTUP.COM file.

Note

DQS$IMPORT.COM adds an invocation of the DQS$DEFINE.COM procedure to the SYS$MANAGER:DQS$SYSTARTUP.COM file for each client queue and executes the DQS$DEFINE.COM procedure to actually create the queue. When you use DQS$IMPORT.COM to create a client queue, the client queue and the remote queue have the same name.

Advanced Methods

More advanced methods of creating client queues are as follows:

Method 1: Using DQS$DEFINE

Creating a client queue with the DQS$DEFINE.COM procedure is useful when you want the name of a client queue to be different from its associated remote queue name.

Procedure

$!-------------------------------------------
$! DQS Client Queues Definitions
$!--------------------------------------------.

DQS$DEFINE.COM is the procedure that actually creates a DQS client queue. When you edit the SYS$MANAGER:DQS$SYSTARTUP.COM file, you should insert your invocation of DQS$DEFINE.COM exactly as shown in Example 3.2, “Creating Client Queues With DQS$DEFINE.COM”.

Example

In Example 3.2, “Creating Client Queues With DQS$DEFINE.COM”, SYS$MANAGER:DQS$SYSTARTUP.COM is edited to contain an invocation of the DQS$DEFINE.COM procedure that associates the client queue CQ_ILLINOIS with the remote queue Q_CHICAGO on server node APPLE.

$ EDIT/EDT SYS$MANAGER:DQS$SYSTARTUP.COM Return
     1      $! IDENT=V1.3
*FIND ’DQS Client Queues Definitions’ Return
     113    $! DQS Client Queues Definitions
$!
*INSERT Return
    $ @SYS$MANAGER:DQS$DEFINE CQ_ILLINOIS -         ! Queue being defined
               APPLE -                              ! Server node
               Q_CHICAGO -                          ! Queue on server node
               0 -                                  ! Unit number of pseudo-device
               /NOENABLE_GENERIC                    ! Optional qualifiers on local queue
Ctrl/Z
      113    $! DQS Client Queue Definitions
*EXIT
SYS$COMMON:[SYSMGR]DQS$SYSTARTUP.COM;6   119 lines
$

Method 2: Defining Generic Client Queues

You can define client queues to be generic queues, which direct print jobs to execution queues on the client for processing. Defining generic queues gives you many independently targeted queues processed by a single symbiont. In this way, you trade off parallel job transfers for fewer processes on your client node.

Procedure

To define generic client queues, perform the following steps:

$ @SYS$MANAGER:DQS$DEFINE execution-queue -
_$ server-node remote-queue
_$ 0 /ENABLE_GENERIC[/qualifiers]

$ DEFINE/SYSTEM/EXECUTIVE_MODE -
_$ DQS$REMOTE_client-queue server-node::remote-queue

$ INITIALIZE/QUEUE/START/GENERIC=execution-queue -
_$ client-queue

If the DQS$REMOTE_client-queue logical name is not defined for a generic queue, the logical name definition for the execution queue is used to establish the associated server node and remote queue.

Example

Example 3.3, “Defining Generic Client Queues” shows how to define a generic client queue.

$ @SYS$MANAGER:DQS$DEFINE D NODEC QUEUE4 0 /ENABLE_GENERIC Return
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_A NODEA::QUEUE1 Return
$ INITIALIZE/QUEUE/START/GENERIC=D A Return
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_B NODEB::QUEUE2 Return
$ INITIALIZE/QUEUE/START/GENERIC=D B Return
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_C NODEA::QUEUE3 Return
$ INITIALIZE/QUEUE/START/GENERIC=D C Return

Example 3.3, “Defining Generic Client Queues” defines the generic queues A, B, and C, which direct print jobs to the client execution queue D. There is a single symbiont running for queue D.

Efficiency Suggestion

An execution queue connects to the associated server for each of its generic queues. However, defining generic queues with the same associated server to direct jobs to the same execution queue is most efficient.

Refer to the OpenVMS System Manager’s Manual for more information on generic queues.

Method 3: Defining Logical Client Queues

Logical queues are similar to generic queues in that each can have its own remote queue, independent of the execution queue. The difference is that you use the ASSIGN/QUEUE comman d to associate the logical queue with its execution queue.

The DQS software determines the associated server node and remote queue by looking for a DQS$REMOTE_client-queue logical name for each logical queue.

Procedure

To define logical client queues, perform the following steps:

$ STOP/QUEUE/RESET client-queue Return

$ DEFINE/SYSTEM/EXECUTIVE_MODE -
_$ DQS$REMOTE_client-queue server-node::remote-queue Return

$ ASSIGN/QUEUE execution-queue logical-queue Return

$ START/QUEUE logical-queue Return

If DQS$REMOTE_client-queue is not defined for the logical queue, the DQS software uses the logical name definition for the execution queue.

Example

Example 3.4, “Defining Logical Client Queues” shows how to define a logical queue.

$ STOP/QUEUE/RESET QUEUE_A Return
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_QUEUE_A NODEX::QUEUE_Y Return
$ ASSIGN/QUEUE QUEUE_D QUEUE_A Return
$ START/QUEUE QUEUE_A Return

Example 3.4, “Defining Logical Client Queues” assigns the logical client queue QUEUE_A to direct print jobs to the execution queue QUEUE_D, which is a DQS queue. QUEUE_D processes jobs queued to QUEUE_A and directs them to the server NODEX, remote queue QUEUE_Y.

Refer to the OpenVMS System Manager’s Manual for more information on logical queues.

Overview

The DQS software determines a client queue’s associated server node and remote queue by translating the DQS$REMOTE_client-queue logical name to be the associated server and remote queue. The DQS$REMOTE_client-queue logical name is defined for a client queue by both the DQS$IMPORT.COM and the DQS$DEFINE.COM procedures.

Procedure

To temporarily change the target of a client queue:

$ STOP/QUEUE/RESET client-queue Return

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_clientqueue
server-node::remote-queue Return

$ START/QUEUE queue-name Return

This temporary definition of the client queue is lost the next time the client system reboots because the logical name definition was not added to the SYS$MANAGER:DQS$SYSTARTUP.COM file.

Example

Example 3.5, “Temporarily Changing the Remote Queue” shows how to change the definition of a client queue temporarily. This example stops the client queue CQ_ILLINOIS, redefines its remote node to be server node CHERRY, remote queue Q_OHIO, and restarts the client queue.

$ STOP/QUEUE/RESET CQ_ILLINOIS Return
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$REMOTE_CQ_ILLINOIS CHERRY::Q_OHIO Return
$ START/QUEUE CQ_ILLINOIS Return

Procedure

To delete a client queue, perform the following steps:

$ STOP/QUEUE/RESET client-queue Return

$ QDELETE/ENTRY=job-entry-numbers client-queue Return

$ DELETE/QUEUE client-queue Return

$ DEASSIGN/SYSTEM/USER DQS$REMOTE_queue-name Return

Execute Startup File

You must execute the SYS$STARTUP:DQS$STARTUP.COM command file on each cluster member to define the required DQS logical names on each cluster member. This action makes available the DQS software to users in the cluster regardless of the cluster node.

Cluster Alias

You should use an outgoing cluster alias as the name of your client system. This makes the cluster appear to be one system to its server(s). If you do not define and use this cluster alias, users may switch cluster members and may not be able to show, modify, or delete print jobs that they own.

About the DQS$CLIENT Program

You should synchronize form definitions between your client and server systems. Do this by running the DQS client program SYS$SYSTEM:DQS$CLIENT.EXE. This requires OPER, TMPMBX, and NETMBX privileges.

The DQS$CLIENT program looks at the queues on a client. For each queue, it queries the associated server(s) to determine what forms are defined there. DQS$CLIENT then defines all the server forms on the client system.

Procedure

To synchronize forms on your DQS client and server systems:

$ RUN SYS$SYSTEM:DQS$CLIENT Return

DQS$CLIENT synchronizes client forms with the server forms in alphabetical order of the client queue names. Each server is queried only once, regardless of the number of client queues associated with remote queues on that server.

Conflicting Server Forms Definitions

If DQS$CLIENT finds conflicting form definitions on different servers, it is not able to define both forms on a DQS client. For example, if one DQS server defines form 3 as X and another defines 3 as Y, form 3 can be defined as either X or Y at a DQS client. No practical way exists to determine which case of form 3, X or Y, occurs at the client.

If DQS$CLIENT encounter s more than one form number for a given form name, you may not get the results you desire.

Form Definition Override

For DQS$CLIENT to override the local form definition with its value on the server, you must define the DQS$FORM_ OVERRIDE logical name on the client system to be an arbitrary value.

If you do not define DQS$FORM_OVERRIDE on your client node, your local form definitions are maintained.

When you run DQS$CLIENT, you are notified that your local form definition is superseded by the server’s definition (with DQS$FORM_OVERRIDE defined) or remains the same (DQS$FORM_OVERRIDE not defined).

Procedure

To allow the server form definition to supersede the client definition:

$! Form Synchronization:

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$FORM_OVERRIDE
_$ TRUE Return

Procedure

To spool to a DQS client queue, you must associate a LAT port with the DQS client queue. To do so, perform the following steps:

A user-written program can then output to the specified LAT port device. The program output is written to a disk and queued to the specified output queue when the file is closed.

Note

If the LAT software is not started, enter the following command at the OpenVMS DCL prompt:

$ @SYS$STARTUP:LAT$STARTUP.COM Return

Example

Example 3.6, “Setting Up a LAT Port Device” shows how to set up a LAT port device.

$ MCR LATCP Return
LATCP> CREATE PORT LTA999: Return
LATCP> SHOW PORT Return
Port Name   Port Type      Status       Remote Target (Node/Port/Service)
--------- ----------- ------------- -----------------------------------------
_LTA999:    Application    Inactive     //
LATCP> EXIT Return
$ SET DEVICE LTA999:/SPOOLED=QUEUE_Z Return

You can spool this LTA999 device to only one DQS client queue at a time. Example 3.7, “Changing Client Queue Spooled to LTA999: Device” shows how to change the DQS client queue that is spooled to the LTA9999: device, by entering the following DCL commands where new_queue_name is the name of the new DQS client queue:

$ SET DEVICE LTA999/NOSPOOLED Return
$ SET DEVICE LTA999/SPOOLED=new_queue_name Return

Example 3.8, “Spooling to a LAT Port Device” shows how to use the LAT port with a FORTRAN program. In this example, the FOR$PRINT logical is associated with the LTA999: device. In this case, the LTA999: device is spooled to a DQS client queue QUEUE_Z (see Example 3.6, “Setting Up a LAT Port Device”). When the program runs, the output is directed through the FOR$PRINT logical to the LTA999: device, and from there to the spooled queue, QUEUE_Z.

$ DEFINE FOR$PRINT LTA999: Return
$ SHOW QUEUE QUEUE_Z Return
     Server queue QUEUE_Z, stopped, on YOUNG::, mounted from DEFAULT
$ TYPE EXAMPLE.FOR Return
           print *,’This is a test.’
           end
$ RUN EXAMPLE Return
$ SHOW QUEUE QUEUE_Z Return
Server queue    QUEUE_Z,    stopped,    on YOUNG::,    mounted from DEFAULT
Jobname    Username    Entry    Blocks    Status
-------    --------    -----    ------    ------
FORPRINT   YOUNG         573        1     Pending
FORPRINT   YOUNG         573        1    Pending
$

This example shows QUEUE_Z as stopped to show the submitted job in the DQS server queue.

How the Note is Printed

The DQS software makes use of a print attribute to place a note on the banner page of a print job when logical names are defined in the DQS$SYSTARTUP.COM file. On the client node, this logical name definition provides the default text ‘‘Print Job transported by DQS Vn.n’’. The note defined by this logical name prints on the banner page of a print job if the /NOTE qualifier is not specified by the client node user on the PRINT command.

The note that prints on the banner page of a print job follows this order of precedence:

Options

You have the following options:

To Turn Off the Default

To turn off the DQS default note on the client system, do the following:

$! $ DEASSIGN/SYSTEM/EXEC DQS$CLIENT_DEFAULT_JOB_NOTE

The change takes efect the next time the SYS$STARTUP:DQS$STARTUP.COM is executed.

To Change Note Text

To change the text of the note that prints on the banner page, do the following:

$! $ DEFINE/SYSTEM/EXEC DQS$CLIENT_DEFAULT_JOB_NOTE -
$!      "Place your text here"

The next time the SYS$STARTUP:DQS$STARTUP.COM is executed and the note is not specified by the user, your customized note prints on the job banner page.

The Forms Change Timer

A part of the DQS software known as the forms change timer periodically checks DQS client queues to see if an operator or the software, itself, has properly changed forms.

The DQS software requires a match of form types between the one mounted on a DQS client queue and the one specified for each of the queue’s jobs.

Logical Names

Regulating the forms change timer component requires editing the SYS$MANAGER:DQS$SYSTARTUP.COM file and adding logical name definitions:

Procedure

To regulate forms checking, do the following:

$! Forms Change Timer:

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$NO_FORMS "TRUE"

$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$FORM_queue_name "TRUE"

$ @SYS$STARTUP:DQS$STARTUP.COM Return

Example

Example 3.9, “Regulating Forms Checking on Many Client Systems” shows how to add logical names to regulate forms checking on VMScluster systems with 50 clients or more. This examples turns off the forms change timer for all client queues and allows client queues LNO6_ROOM23A, LPS17_NUM016, and LPS17_600_BLUE to accept print jobs regardless of the forms mounted on them.

$!
$!     Forms Change Timer:
$!
$!     Uncomment the following logical if you desire to turn off the forms
$!     change timer. Digital recommends that you do this on VMScluster
$!     systems with 50 or more DQS client queues.
$!
! DEFINE/SYSTEM/EXECUTIVE_MODE DQS$NO_FORMS TRUE
$!
$! Ignoring forms definitions on specific client queues:
$!
$!   You can disable certain client queues from rejecting print jobs when
$!   the form mounted on the client queue differs from the form mounted
$!   on the remote queue. Define a logical of the form DQS$FORM_queue_name .
$!   This allows the client queue, ’queue_name’ , to accept and process jobs,
$!   regardless of the form mounted on the remote queue. For example:
$!
$!
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$FORM_LNO6_ROOM23A "TRUE"
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$FORM_LPS17_NUM016 "TRUE"
$ DEFINE/SYSTEM/EXECUTIVE_MODE DQS$FORM_LPS17_600_BLUE "TRUE"

After adding these logical name definitions to the site-specific startup file DQS$SYSMANAGER:DQS$SYSTARTUP.COM and executing the DQS startup procedure SYS$STARTUP:DQS$STARTUP, the DQS software no longer checks for forms mismatches between each named queue and its jobs.

What To Do First

If something fails to work with the DQS software, check these first:

Command

You can execute the Installation Verification Procedure (IVP) to check if the DQS software is running properly. To run the IVP, enter:

$ @SYS$TEST:DQS$IVP.COM Return

IVP on a Client Node

Following is a sample of an IVP run on a node with the DQS client software configured.

DQS V1.3 Installation Verification Procedure

Restricted Rights: Use, duplication, or disclosure by the U.S. Government
is subject to restrictions as set forth in subparagraph (c)(1)(ii) of
DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as
applicable.

This software is proprietary to and embodies the confidential technology
of Digital Equipment Corporation. Possession, use, or copying of this
software and media is authorized only pursuant to a valid written license
from Digital or an authorized sublicensor.

For a client-only node, the following prompt is displayed:

It is necessary to test the DQS client with a remote DQS server node.
Enter remote server NODE::QUEUE:

Enter the name of a server node and a remote queue on that node. For example, to test the proper operation of server queue Q_CHICAGO on node APPLE, enter the following:

Enter remote server NODE::QUEUE APPLES::Q_CHICAGO RETURN

For the IVP to succeed on a client-only installation, the following must exist:

Then, if the DQS software is working properly. the IVP displays a series of messages (this may take several minutes), such as:

%DQS-I-CRESRVQUE Creating remote queue
%DQS-I-CRECLIQUE Creating client queue
%DQS-I-CHKCLIQUE Checking client queue
%DQS-I-ENTJOB Entering test job in client queue
%DQS-I-CHECKJOB Checking test job in client queue
%DQS-I-SNDJOB Sending job to remote queue
%DQS-I-CHKSRVQUE Checking test job in remote queue
%DQS-I-DELJOB Deleting job from remote queue
%DQS-I-CHKDEL Checking that job is gone from remote queue
%DQS-I-CLEANUP Cleaning up, deleting IVP queues
%DQS-I-QUESUCCESS IVP test successful

IVP on a Server Node

Following is a sample of an IVP run on a node with the DQS server software configured.

DQS V1.3 Installation Verification Procedure

Restricted Rights: Use, duplication, or disclosure by the U.S. Government
is subject to restrictions as set forth in subparagraph (c)(1)(ii) of
DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as
applicable.

This software is proprietary to and embodies the confidential technology
of Digital Equipment Corporation. Possession, use, or copying of this
software and media is authorized only pursuant to a valid written license
from Digital or an authorized sublicensor.

Then, if the DQS software is working properly. the IVP displays a series of messages (this may take several minutes), such as:

%DQS-I-CRESRVQUE Creating remote queue
%DQS-I-CRECLIQUE Creating client queue
%DQS-I-CHKCLIQUE Checking client queue
%DQS-I-ENTJOB Entering test job in client queue
%DQS-I-CHECKJOB Checking test job in client queue
%DQS-I-SNDJOB Sending job to remote queue
%DQS-I-CHKSRVQUE Checking test job in remote queue
%DQS-I-DELJOB Deleting job from remote queue
%DQS-I-CHKDEL Checking that job is gone from remote queue
%DQS-I-CLEANUP Cleaning up, deleting IVP queues
%DQS-I-QUESUCCESS IVP test successful

If the DQS IVP encountered problems, the procedure displays error messages. Refer to Appendix A, DQS System Manager Messages, DQS System Manager Messages for an explanation of specific error messages.

Action

If remote notification is not working check for the following:

Action

The DQS$NOTIFIER searches the node for all known DQS server queues when it starts. If you define a new queue as a valid DQS server queue, you must stop and restart the DQS$NOTIFIER process to enable print job com pletion messages of jobs submitted to the new queue. The simpliest way to do this is to restart DQS.

If the DQS$NOTIFIER is not restarted:

Action

Information You Need

To determine why a print job does not appear to be printing, you need to determine the following for the job:

Using the QSHOW Command

To obtain this information, issue a QSHOW command at the client system of the client queue to which the job was queued for printing. The output of the QSHOW command provides information on both the status and the location of the print job.

Examining the QSHOW Display

The output of the QSHOW command is designed to provide all the information you need to determine the status and location of a print job. The command output usually appears as follows, showing the location of the job on either the client or the server system:

** Remote queue - [ CQ_EUROPE => Q_PARIS, on CHERRY:: ]
Terminal queue Q_PARIS
==============================to be transferred===================
Server queue CQ_EUROPE, mounted form DEFAULT
   Jobname    Username    Entry    Blocks    Status
   -------    --------    -----    ------    ------
   JOB        GUENTHER     2737         1    Printing

Understanding Location Information

Note that the client queue and remote queue are referred to in the command output as the "Server queue" and the "Remote queue," respectively. This terminology is tied to the OpenVMS concept of served queues. For the DQS QSHOW command,

When the QSHOW command output contains information for both the client and remote queues (as shown in the preceding display) you should first decide whether the job is in the client queue, in the remote queue, or neither.

Location: Neither Node

If the job is not in either the client or the remote queue, then the following possibilities exist:

If you suspect a DQS problem, examine the NETSERVER.LOG files in the DQS server account’s directory or, if OpenVMS accounting is enabled, check the accounting files.

Location: Server Node

If the job is located on the server node, then the DQS software has functioned properly. If the job still is not printing, then the following possibilities exist:

Check that the printer is on line, powered on, and has paper in it.

Location: Client Node

If the job is still located on the client node, then examine the status of the client queue in the QSHOW output. The queue status is either stopped or stalled.

Understanding Status Information

You see the following status if there is a problem:

Any of the following indicate that the client queue is operational and running:

Possible reasons for a pending status are the following:

The Remote Queue Display

Issuing a QSHOW comman d for a client queue sometimes does not show job status information because either the remote queue or the server node is inaccessible. In these cases, you see the following in the QSHOW command output:

Missing Remote Queue Information

When the remote queue information does not display when you issue a QSHOW comman d, it means that the DQS software does not view the client queue as a valid DQS queue. The command output would appear as follows:

Server queue CQ_EUROPE, mounted form DEFAULT
Jobname   Username   Entry   Blocks   Status
-------   --------   -----   ------   ------
JOB       CHO         2744        1   Pending

In this case, you should issue a QSHOW/FULL comman d for the queue. If the command output contains the information /PROCESSOR=DQS$SMB, invoke the DQS$STARTUP.COM file to define the queue as a valid DQS queue.

You can also check the DQS$REMOTE_client-queue logical name definition for the client queue. It should be defined system wide and in executive mode to be the corresponding server node and remote queue.

Error Messages in the Remote Queue Display

In some cases, the QSHOW command output contains an error message that cites a reason why the remote queue is not accessible. The command output would appear as follows:

***** Remote queue CHERRY::Q_PARIS not accessible *****
      %SYSTEM-F-UNREACHABLE, remote node is not currently reachable
==============================to be transferred========================
Server queue CQ_EUROPE, mounted form DEFAULT

The following is a list of error messages that might be displayed when a remote queue is inaccessible:

About the Problem

A part of the DQS software known as the forms change timer periodically checks DQS client queues to see if an operator or the software has properly changed forms. The DQS software requires a match of form types between the one mounted on a DQS client queue and the one specified for each of the queue’s jobs. This checking can slow down the overall performance of a VMScluster system with 50 or more DQS client queues.

Action

To increase performance of systems with many DQS client queues, you can turn off the forms change timer component of the DQS software. As a result, the software cuts forms-checking operations to a minimum and performance is improved. VSI recommends that you do this on VMScluster systems with 50 or more DQS client queues.

Regulating the forms change timer component requires editing the SYS$MANAGER:DQS$SYSTARTUP.COM file and adding logical name definitions DQS$NO_FORMS and DQS$FORM_ queue_name. For information, refer to the section titled

Regulating Forms Checking in Chapter 3, Configuring and Managing a DQS Client.