Document revision date: 15 July 2002

Certain account privileges allow users to access a queue in spite of UIC-based and ACL-based protection. The following table lists these account privileges and the type of access they allow on a queue:

Privilege	Access
OPER	Manage and control access to all queues.
BYPASS	Manage and control access to all queues.
READALL	Read access to all jobs and to queue security information.
SYSPRV	The access specified for users with system UICs.
GRPPRV	The access specified for users with system or group UICs.

14.6.2 Using Job Retention Options

Job retention options allow users to retain a job in a queue after the job completes. System managers can use job retention options to keep information about all jobs in the queue after the jobs complete; this is helpful when tracking jobs submitted by other users.

14.6.2.1 Setting Job Retention

Users can set job retention, as can system managers. The following sections explain how each can perform this task.

User Commands

Users can request that a job be retained in a queue after the job completes by using the /RETAIN qualifier with the PRINT or SUBMIT command. For example:

PRINT/RETAIN SUBMIT/RETAIN

System Manager Commands

By default, no job retention option is set on a queue. To specify a job retention option, use one of the following commands:

INITIALIZE/QUEUE/RETAIN=option START/QUEUE/RETAIN=option SET QUEUE/RETAIN=option

You can specify one of the following options:

Option	Description
ALL	Holds all jobs in the queue after execution (default).
ERROR	Holds jobs in the queue only if they complete unsuccessfully.

The following command specifies that the queue retain all jobs that complete with a status other than success:

$ SET QUEUE/RETAIN=ERROR BATCH_QUE

For example, if you need to know all batch jobs that do not complete successfully on a specific queue, set the queue to retain jobs that complete with an error status. You can enter SHOW QUEUE to display a list of jobs (including their completion status) that completed unsuccessfully. If a job completes unsuccessfully, this message helps determine why. The displays also include the date and time at which a retained job completed.

The job retention option you specify on a queue overrides any job retention option requested by a user for a job in that queue. Figure 14-10 shows how job retention affects a job submitted to a generic queue.

Figure 14-10 Determining Job Retention

The following factors determine whether and where a job is retained:

• The retention setting on the execution queue in which the job executes
• The retention setting on the generic queue (if the job is submitted to a generic queue)
• The completion status of the job
• The retention requested by the user upon submitting the job (if retention was requested)

If jobs are retained in queues, periodically delete the jobs that no longer need to be retained.

14.6.2.2 Specifying Timed Job Retention

Users can specify timed job retention. For example:

$ SUBMIT/RETAIN=UNTIL=19-MAY-2000:07:31:0.0 MYFILE.DAT

This eliminates the need to delete retained jobs from queues. Encourage users who include the /RETAIN qualifier to also use timed retention.

14.6.2.3 Changing Job Retention

To change the user-specified retention policy for a job, use the /RETAIN=option qualifier with the SET ENTRY command in the following format:

SET ENTRY/RETAIN=option entry-number

You can specify one of the following options:

Option	Description
ALWAYS	Holds the job in the queue regardless of the job's completion status.
DEFAULT	Holds the job in the queue as specified by the queue's retention option. If no option has been set on the queue, the job is not retained.
ERROR	Holds the job in the queue only if the job completes unsuccessfully.
UNTIL= time-value	Holds the job in the queue for a specified length of time, regardless of the job's completion status. This lets you retain the job in the queue only as long as the job is needed and eliminates the need to delete the job from the queue later. The time value you specify is interpreted first as a delta time, then as a combination time, and finally as an absolute time. For information about specifying time values, refer to the OpenVMS User's Manual.

For example, the following command retains job 172 in the queue until 3 hours after the job completes. At that time, the job will automatically be deleted from the queue.

$ SET ENTRY/RETAIN=UNTIL="+3:00" 172

To remove a job retention option from a queue, use the /NORETAIN qualifier with INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE.

14.6.3 Specifying Queue Characteristics

A characteristic is any attribute of a print or batch job that is relevant to your environment. For example, characteristics for a printer could refer to the color of the ink, the type of paper, or the location of the printer. Once you define the characteristics for a queue, users can specify the characteristics they want to associate with their job when they enter the PRINT or SUBMIT command.

A print job can be processed on an execution queue if the job's characteristics are a subset of the queue's characteristics. However, if any of the characteristics associated with the job are not associated with the queue, the job remains pending until you correct the characteristic mismatch as explained in Section 14.8.2.2.

How to Perform This Task

To specify queue characteristics, perform the following steps:

1. Create characteristics with DEFINE/CHARACTERISTIC.
2. Assign characteristics to a queue.

Example

You manage three LN03 printers in each of the four corners of a building. A generic queue LN03$PRINT feeds execution queues for each printer. You can define the characteristics EAST, WEST, NORTH, and SOUTH.

When a user submits a print job to LN03$PRINT with the EAST characteristic, the job prints on the first idle LN03 printer in the eastern corner of the building. If the system has queues for printers on multiple floors, you can further define a characteristic for each floor, for example, FIRST, SECOND, and THIRD.

Commands for Specifying Queue Characteristic Options

Use the following commands when working with characteristics:

Command	Description
DEFINE/CHARACTERISTIC	Creates a characteristic and assigns a name and number.
DELETE/CHARACTERISTIC	Deletes a characteristic.
SHOW QUEUE/CHARACTERISTICS	Displays information about characteristics defined for the system.
INITIALIZE/QUEUE/CHARACTERISTICS SET QUEUE/CHARACTERISTICS START/QUEUE/CHARACTERISTICS	Specifies one or more characteristics for processing jobs on a queue.
SHOW QUEUE/FULL	Displays information about a queue, including any characteristics assigned to the queue.
PRINT/CHARACTERISTICS SUBMIT/CHARACTERISTICS SET ENTRY/CHARACTERISTICS	Specifies the name or number of one or more characteristics to be associated with the job.

The following sections describe how to specify queue characteristics.

14.6.3.1 Defining Characteristics

No characteristics are defined by default. To define a characteristic, use the DEFINE/CHARACTERISTIC command in the following format:

DEFINE/CHARACTERISTIC characteristic-name characteristic-number

You cannot define more than one characteristic name to a number.

If your queue configuration requires more than one characteristic name for a single number, you can define logical names to achieve the same result.

In an OpenVMS Cluster environment, you must define the logical names on every node that requires them.

Example

In the following example, the characteristic name SECOND_FLOOR is assigned to characteristic number 2. The logical names SALES_FLOOR and SALES_DEPT are defined as equivalent to the characteristic name SECOND_FLOOR. As a result, the logical names SALES_FLOOR and SALES_DEPT are equivalent to the characteristic name SECOND_FLOOR and characteristic number 2. These logical names can be specified as the characteristic-name value for any /CHARACTERISTIC=characteristic-name qualifier.

$ DEFINE/CHARACTERISTIC SECOND_FLOOR 2 $ DEFINE/SYSTEM/EXECUTIVE_MODE SALES_FLOOR SECOND_FLOOR $ DEFINE/SYSTEM/EXECUTIVE_MODE SALES_DEPT SECOND_FLOOR

14.6.3.2 Displaying Characteristics Defined on a System

To see the characteristics defined on a system, enter SHOW QUEUE/CHARACTERISTICS.

Example

$ SHOW QUEUE/CHARACTERISTICS Characteristic name Number ------------------- ------ EAST 1 WEST 2 NORTH 3 SOUTH 4

14.6.3.3 Assigning Characteristics to a Queue

No characteristics are assigned to a queue by default. To assign characteristics to a queue, include the /CHARACTERISTICS qualifier with INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE.

Example

$ SET QUEUE/CHARACTERISTICS=(EAST) LN03_1

14.6.3.4 Displaying Characteristics Assigned to a Queue

To determine the characteristics defined for a queue, enter SHOW QUEUE/FULL.

Example

$ SHOW QUEUE/FULL LN03_1 Printer queue LN03_1, idle, on HERA::TTA3, mounted form DEFAULT <Printer queue on node HERA for an LN03 printer> /BASE_PRIORITY=4 /CHAR=(1) /DEFAULT=(FLAG=ONE,FORM=LN03$PORTRAIT (stock=DEFAULT)) /LIBRARY=LN03LIBRARY Lowercase /OWNER=[SYSTEM] /PROCESSOR=LATSYM /PROTECTION=(S:M,O:D,G:R,W:R) /SEPARATE=(RESET=(ANSI$RESET))

14.6.3.5 Canceling Characteristics Assigned to a Queue

To cancel characteristics assigned to a queue, specify the /NOCHARACTERISTICS qualifier with INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE.

14.6.3.6 Deleting Characteristics

To delete a characteristic definition, enter DELETE/CHARACTERISTIC. You must specify the characteristic-name with DELETE/CHARACTERISTIC.

If you know the number assigned to the characteristic but do not know the name, enter SHOW QUEUE/CHARACTERISTICS to display the names and numbers assigned to characteristics on the system.

If the system displays the following messages, a queue or job refers to the characteristic:

%DELETE-E-NOTDELETED, error deleting characteristic -JBC-E-REFERENCED, existing references prevent deletion

You must remove all references to the characteristic before you can delete the characteristic. For information about removing references to a characteristic, see Section 14.8.5.

14.6.4 Specifying Batch Processing Options

You can use queue options to control batch job performance and the use of system resources by processes executing batch jobs.

Use the following qualifiers with INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE to set these queue options:

Qualifier	Description
/JOB_LIMIT= n	Specifies the number of jobs that can execute concurrently in the queue.
/[NO]DISABLE_SWAPPING	Specifies whether the processes running jobs on the queue can be swapped in and out of memory.
/CPUDEFAULT= time	Specifies the default CPU time limit for all jobs in the queue. The time cannot exceed the time limit set with the /CPUMAXIMUM qualifier.
/CPUMAXIMUM= time	Specifies the maximum CPU time limit for all jobs in the queue.
/RAD= n	Specifies the RAD number on which to run batch jobs assigned to the queue.

Although the following qualifiers are not specific to batch queues, they are commonly used to control batch job performance and the use of system resources by batch processes:

Option	Description
/BASE_PRIORITY= n	Specifies the base process priority at which jobs are initiated from a batch queue.
/WSDEFAULT= n	Specifies the default working set size for jobs executed in a batch queue. (For output queues, specifies the default working set size for symbiont processes.)
/WSEXTENT= n	Specifies the working set extent for jobs executed in a batch queue. (For output queues, specifies the working set extent for symbiont processes.)
/WSQUOTA= n	Specifies the working set quota for jobs executed in a batch queue. (For output queues, specifies the working set quota for symbiont processes.)

For more information about these limits, quotas, and priorities, refer to the following manuals:

• The INITIALIZE/QUEUE command in the OpenVMS DCL Dictionary
• The OpenVMS Performance Management

By default, a process running a batch job uses values taken from the UAF record of the user submitting the job or from system parameter settings. If you specify values for any of these options, processes for jobs executed in the queue will use the values you set unless the user specifies values when the job is submitted. (A user can specify values for CPU time and for the working set options default, quota, and extent.)

A user-specified value cannot exceed the value you set for the queue. If you did not specify a value, the user-specified value cannot exceed the value specified in the associated UAF limit or system parameter.

The following sections provide guidelines for choosing values for these options:

Option	For More Information
Base process priority	Section 14.6.4.1
Job limit	Section 14.6.4.2
Working set default, quota, and extent	Section 14.6.4.3
CPU default and maximum	Section 14.6.4.4
Swapping	Section 14.6.4.5
Options for memory-constrained systems	Section 14.6.4.6
Optimizing for the Sort/Merge utility	Section 14.6.4.7

14.6.4.1 Base Process Priority

Choose a value based on how quickly you will allow batch jobs to progress. If you choose a value equal to the system parameter value DEFPRI (typically 4), jobs in this queue will progress at the same rate as typical interactive jobs. This choice might be appropriate for systems that have an abundance of available CPU time.

If you choose a value less than DEFPRI, jobs in this queue will potentially progress more slowly than the typical interactive job. CPU time will be allocated to jobs in this queue only after servicing jobs of DEFPRI priority.

If a queue is defined for a very special purpose---for example, high-priority jobs---a value greater than DEFPRI (for example, 5) might be appropriate. However, this choice can have a significant negative effect on the performance of other users and batch jobs.

14.6.4.2 Job Limit

Keep this value low when using a base process priority of DEFPRI or greater, because each batch job can affect the performance of interactive jobs.

14.6.4.3 Working Set Default, Quota, and Extent

If you do not specify values for these options, a job uses the value specified in its owner's user authorization file (UAF) record.

Process Limit	Description
Working set default	The value to which the working set returns at the exit of each image. The value should be relatively small and is usually best left at the value specified in the user's UAF record.
Working set quota	The value that approximates the amount of physical memory used by each batch job in the queue in a memory-constrained system.
Working set extent	The value that approximates the amount of physical memory in a memory-rich system. You should set this to a high value. The working set extent value is an upper limit for the size of the working set; the working set cannot be expanded beyond this value even if more memory is required by the job. If you set this value too low, a job might page fault heavily even if the system has plenty of memory available. To be safe, choose a working set extent value equal to the system parameter value of WSMAX, which specifies the maximum working set size possible for your system.

In general, the working set quota and extent values specified in the UAF record for each user are sufficient. However, you can specify more generous or stringent values for a queue, depending on the purpose of the queue. For example, you can encourage users to submit large jobs (such as compiling and linking large programs) as batch jobs to reserve interactive use of the system for jobs that do not require extensive resources, as follows:

• Set a large working set size for batch jobs by specifying larger WSQUOTA and WSEXTENT values when you create the batch queue.
• Restrict the working set size of interactive jobs by providing smaller WSQUOTA and WSEXTENT values in users' UAF records.

	privacy and legal statement
6017PRO_061.HTML