HP OpenVMS System Services Reference Manual


Previous Contents Index

The string returned is the log file specification that was provided to the $SNDJBC service to create the job. Therefore, to determine whether a log file is to be produced, testing this item code for a zero-length string is insufficient; instead, you need to examine the QUI$V_JOB_LOG_NULL bit of the QUI$_JOB_FLAGS item code.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_MANAGER_NAME

Returns, as a character string, the queue manager name. Because a queue manager name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_MANAGER_NODES

Returns, as a comma separated list, the names of the nodes on which this queue manager runs.

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_MANAGER_STATUS

Returns the specified queue manager's status flags, which are contained in a longword bit vector. The $QUIDEF macro defines the following symbolic names for these flags:
Symbolic Name Description
QUI$V_MANAGER_FAILOVER Queue manager is in the process of failing over to another node.
QUI$V_MANAGER_RUNNING Queue manager is running.
QUI$V_MANAGER_START_PENDING Queue manager can start up whenever a node on which it can run is booted.
QUI$V_MANAGER_STARTING Queue manager is in the process of starting up.
QUI$V_MANAGER_STOPPING Queue manager is in the process of shutting down.
QUI$V_MANAGER_STOPPED Queue manager is stopped.

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_NOTE

Returns, as a character string, the note that is to be printed on the job flag and file flag pages of the specified job. Because the note can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes). This item code is meaningful for batch and output execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_OPERATOR_REQUEST

Returns, as a character string, the message that is to be sent to the queue operator before the specified job begins to execute. Because the message can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes). This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_OWNER_UIC

Returns the owner UIC as a longword value in standard UIC format.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PAGE_SETUP_MODULES

Returns, as a comma-separated list, the names of the text modules to be extracted from the device control library and copied to the printer before each page of the specified form is printed. Because a text module name can include up to 31 characters and is separated from the previous text module name by a comma, the buffer length field of the item descriptor should specify 32 (bytes) for each possible text module. This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_PARAMETER_1 through QUI$_PARAMETER_8

Returns, as a character string, the value of the user-defined parameters that in batch jobs become the value of the DCL symbols P1 through P8 respectively. Because these parameters can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PENDING_JOB_BLOCK_COUNT

Returns, as a longword integer value, the total number of blocks for all pending jobs in the queue (valid only for output execution queues).

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PENDING_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queue in a pending state.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PENDING_JOB_REASON

Returns, as a longword bit vector, the reason that the job is in a pending state. The $QUIDEF macro defines the following symbolic names for the flags:
Symbolic Name Description
QUI$V_PEND_CHAR_MISMATCH Job requires characteristics that are not available on the execution queue.
QUI$V_PEND_JOB_SIZE_MAX Block size of job exceeds the upper block limit of the execution queue.
QUI$V_PEND_JOB_SIZE_MIN Block size of job is less than the lower limit of the execution queue.
QUI$V_PEND_LOWERCASE_MISMATCH Job requires lowercase printer.
QUI$V_PEND_NO_ACCESS Owner of job does not have access to the execution queue.
QUI$V_PEND_QUEUE_BUSY Job is pending because the number of jobs currently executing on the queue equals the job limit for the queue.
QUI$V_PEND_QUEUE_STATE Job is pending because the execution queue is not in a running, open state as indicated by QUI$_QUEUE_STATUS.
QUI$V_PEND_STOCK_MISMATCH Stock type required by the job's form does not match the stock type of the form mounted on the execution queue.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PRIORITY

Returns the scheduling priority of the specified job, which is a longword integer value in the range 0 through 255.

Scheduling priority affects the order in which jobs assigned to a queue are initiated; it has no effect on the base execution priority of a job. The lowest scheduling priority value is 0, the highest is 255; that is, if a queue contains a job with a scheduling priority of 10 and a job with a scheduling priority of 2, the queue manager initiates the job with the scheduling priority of 10 first.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PROCESSOR

Returns, as an OpenVMS RMS file name component, the name of the symbiont image that executes print jobs initiated from the specified queue. The file name assumes the device and directory name SYS$SYSTEM and the file type .EXE. Because an RMS file name can include up to 39 characters, the buffer length field of the item descriptor should specify 39 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_PROTECTION

When you specify QUI$_PROTECTION, $GETQUI returns, as a word, the specified queue's protection mask.

The following diagram illustrates the protection mask:


Bits 0 through 15 specify the protection value---the four types of access (read, submit, manage, and delete) to be granted to the four classes of user (System, Owner, Group, World). Set bits deny access and clear bits allow access.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_QUEUE_DESCRIPTION

Returns, as a character string, the text that describes the specified queue. Because the text can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes).

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_QUEUE_DIRECTORY

Returns a string containing the device and directory specification of the queue database directory for this queue manager.

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_QUEUE_FLAGS

Returns, as a longword bit vector, the processing options that have been selected for the specified queue. Each processing option is represented by a bit. When $GETQUI sets a bit, the jobs initiated from the queue are processed according to the corresponding processing option. Each bit in the vector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:
Symbolic Name Description
QUI$V_QUEUE_ACL_SPECIFIED An access control list has been specified for the queue. You cannot retrieve a queue's ACL through the $GETQUI service; instead, you must use the $GET_SECURITY service.
QUI$V_QUEUE_AUTOSTART Queue is designated as an autostart queue.
QUI$V_QUEUE_BATCH Queue is a batch queue or a generic batch queue.
QUI$V_QUEUE_CPU_DEFAULT A default CPU time limit has been specified for all jobs in the queue.
QUI$V_QUEUE_CPU_LIMIT A maximum CPU time limit has been specified for all jobs in the queue.
QUI$V_QUEUE_FILE_BURST Burst and flag pages precede each file in each job initiated from the queue.
QUI$V_QUEUE_FILE_BURST_ONE Burst and flag pages precede only the first copy of the first file in each job initiated from the queue.
QUI$V_QUEUE_FILE_FLAG Flag page precedes each file in each job initiated from the queue.
QUI$V_QUEUE_FILE_FLAG_ONE Flag page precedes only the first copy of the first file in each job initiated from the queue.
QUI$V_QUEUE_FILE_PAGINATE Output symbiont paginates output for each job initiated from this queue. The output symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUI$V_QUEUE_FILE_TRAILER Trailer page follows each file in each job initiated from the queue.
QUI$V_QUEUE_FILE_TRAILER_ONE Trailer page follows only the last copy of the last file in each job initiated from the queue.
QUI$V_QUEUE_GENERIC The queue is a generic queue.
QUI$V_QUEUE_GENERIC_SELECTION The queue is an execution queue that can accept work from a generic queue.
QUI$V_QUEUE_JOB_BURST Burst and flag pages precede each job initiated from the queue.
QUI$V_QUEUE_JOB_FLAG A flag page precedes each job initiated from the queue.
QUI$V_QUEUE_JOB_SIZE_SCHED Jobs initiated from the queue are scheduled according to size, with the smallest job of a given priority processed first (meaningful only for output queues).
QUI$V_QUEUE_JOB_TRAILER A trailer page follows each job initiated from the queue.
QUI$V_QUEUE_PRINTER The queue is a printer queue.
QUI$V_QUEUE_RAD (Alpha and Integrity servers) Indicates if the RAD processing option attribute is specified for the batch queue. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
QUI$V_QUEUE_RECORD_BLOCKING The symbiont is permitted to concatenate, or block together, the output records it sends to the output device.
QUI$V_QUEUE_RETAIN_ALL All jobs initiated from the queue remain in the queue after they finish executing. Completed jobs are marked with a completion status.
QUI$V_QUEUE_RETAIN_ERROR Only jobs that do not complete successfully are retained in the queue.
QUI$V_QUEUE_SECURITY_INACCESSIBLE The requestor does not have access to security information.
QUI$V_QUEUE_SWAP Jobs initiated from the queue can be swapped.
QUI$V_QUEUE_TERMINAL The queue is a terminal queue.
QUI$V_QUEUE_WSDEFAULT Default working set size is specified for each job initiated from the queue.
QUI$V_QUEUE_WSEXTENT Working set extent is specified for each job initiated from the queue.
QUI$V_QUEUE_WSQUOTA Working set quota is specified for each job initiated from the queue.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_QUEUE_NAME

Returns, as a character string, the name of the specified queue or the name of the queue that contains the specified job. Because a queue name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE, QUI$_TRANSLATE_QUEUE function codes)

QUI$_QUEUE_STATUS

Returns the specified queue's status flags, which are contained in a longword bit vector. Some of these bits describe the queue's state, others provide additional status information.

The $QUIDEF macro defines the following symbolic names for these flags:
Symbolic Name Description
QUI$V_QUEUE_ALIGNING Queue is printing alignment pages.
QUI$V_QUEUE_AUTOSTART_INACTIVE Autostart queue is stopped due to failure or manual intervention and needs to be manually started.
QUI$V_QUEUE_AVAILABLE 1 Queue is processing work but is capable of processing additional work.
QUI$V_QUEUE_BUSY 1 Queue cannot process additional jobs because of work in progress.
QUI$V_QUEUE_CLOSED Queue is closed and will not accept new jobs until the queue is put in an open state.
QUI$V_QUEUE_DISABLED 1 Queue is not capable of being started or submitted to.
QUI$V_QUEUE_IDLE 1 Queue contains no job requests capable of being processed.
QUI$V_QUEUE_LOWERCASE Queue is associated with a printer that can print both uppercase and lowercase characters.
QUI$V_QUEUE_PAUSED 1 Execution of all current jobs in the queue is temporarily halted.
QUI$V_QUEUE_PAUSING 1 Queue is temporarily halting execution.
QUI$V_QUEUE_REMOTE Queue is assigned to a physical device that is not connected to the local node.
QUI$V_QUEUE_RESETTING Queue is resetting and stopping.
QUI$V_QUEUE_RESUMING 1 Queue is restarting after pausing.
QUI$V_QUEUE_SERVER Queue processing is directed to a server symbiont.
QUI$V_QUEUE_STALLED 1 Physical device to which queue is assigned is stalled; that is, the device has not completed the last I/O request submitted to it.
QUI$V_QUEUE_STARTING 1 Queue is starting.
QUI$V_QUEUE_STOP_PENDING Queue will be stopped when work currently in progress has completed.
QUI$V_QUEUE_STOPPED 1 Queue is stopped.
QUI$V_QUEUE_STOPPING 1 Queue is stopping.
QUI$V_QUEUE_UNAVAILABLE Physical device to which queue is assigned is not available.


1Bit describes the current state of the queue. Only one of these bits can be set at any time.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_RAD (Alpha and Integrity servers)

Returns the value of the RAD attribute attached to a queue or a job. The item code expects a 32-bit buffer in which to write the value of the RAD. A value of -1 is returned to the buffer if no RAD is specified for the queue or the job.

RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE function codes)

QUI$_REQUEUE_QUEUE_NAME

Returns, as a character string, the name of the queue to which the specified job is reassigned. This item code only has a value if the QUI$V_JOB_ABORTING bit is set in the QUI$_JOB_STATUS longword, and the job is going to be requeued to another queue.

Because a queue name can include up to 31 characters, the buffer length of the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_RESTART_QUEUE_NAME

Returns, as a character string, the name of the queue in which the job will be placed if the job is restarted.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_RETAINED_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queue retained after successful completion plus those retained on error.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_SCSNODE_NAME

Returns, as a character string, the name of the node on which the specified execution queue or queue manager is located. Because the node name can include up to 6 characters, the buffer length field of the item descriptor should specify 6 (bytes).

(Valid for QUI$_DISPLAY_QUEUE, QUI$_DISPLAY_MANAGER function codes)

QUI$_SEARCH_FLAGS

When you specify QUI$_SEARCH_FLAGS, an input value item code, it specifies a longword bit vector wherein each bit specifies the scope of $GETQUI's search for objects specified in the call to $GETQUI. The $QUIDEF macro defines symbols for each option (bit) in the bit vector.

The following table contains the symbolic names for each option and the function code for which each flag is meaningful:
Symbolic Name Function Code Description
QUI$V_SEARCH_ALL_JOBS QUI$_DISPLAY_JOB $GETQUI searches all jobs included in the established queue context. If you do not specify this flag, $GETQUI only returns information about jobs that have the same user name as the caller.
QUI$V_SEARCH_BATCH QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects batch queues.
QUI$V_SEARCH_EXECUTING_JOBS QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
Selects executing jobs, or queues with executing jobs.
QUI$V_SEARCH_FREEZE_CONTEXT QUI$_DISPLAY_CHARACTERISTIC
QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_FILE
QUI$_DISPLAY_FORM
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
QUI$_DISPLAY_MANAGER
Does not advance wildcard context on completion of this service call.
QUI$V_SEARCH_GENERIC QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects generic queues.
QUI$V_SEARCH_HOLDING_JOBS QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
Selects jobs on unconditional hold, or queues with jobs on unconditional hold.
QUI$V_SEARCH_PENDING_JOBS QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
Selects pending jobs, or queues with pending jobs.
QUI$V_SEARCH_PRINTER QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects printer queues.
QUI$V_SEARCH_RETAINED_JOBS QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
Selects jobs being retained, or queues with jobs being retained.
QUI$V_SEARCH_SERVER QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects server queues.
QUI$V_SEARCH_SYMBIONT QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects output queues.
QUI$V_SEARCH_TERMINAL QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_QUEUE
Selects terminal queues.
QUI$V_SEARCH_THIS_JOB QUI$_DISPLAY_FILE
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
$GETQUI returns information about the calling batch job, the command file being executed, or the queue associated with the calling batch job. $GETQUI establishes a new queue and job context based on the job entry of the caller; this queue and job context is dissolved when $GETQUI finishes executing. If you specify QUI$V_SEARCH_THIS_JOB, $GETQUI ignores all other QUI$_SEARCH_FLAGS options.
QUI$V_SEARCH_TIMED_RELEASE_JOBS QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_JOB
QUI$_DISPLAY_QUEUE
Selects jobs on hold until a specified time, or queues with jobs on hold until a specified time.
QUI$V_SEARCH_WILDCARD QUI$_DISPLAY_CHARACTERISTIC
QUI$_DISPLAY_ENTRY
QUI$_DISPLAY_FORM
QUI$_DISPLAY_QUEUE
$GETQUI performs a search in wildcard mode even if QUI$_SEARCH_NAME contains no wildcard characters.

QUI$_SEARCH_JOB_NAME

QUI$_SEARCH_JOB_NAME is an input value item code that specifies a 1- to 39-character string that $GETQUI uses to restrict its search for a job or jobs. $GETQUI searches for job names that match the job name input value for the given user name. Wildcard characters are acceptable.

(Valid for QUI$_DISPLAY_ENTRY function code)

QUI$_SEARCH_NAME

QUI$_SEARCH_NAME is an input value item code that specifies, as a 1- to 31-character string, the name of the object about which $GETQUI is to return information. The buffer must specify the name of a characteristic, form, or queue.

To direct $GETQUI to perform a wildcard search, you specify QUI$_SEARCH_NAME as a string containing one or more of the wildcard characters (% or *).

(Valid for QUI$_DISPLAY_CHARACTERISTIC, QUI$_DISPLAY_FORM, QUI$_DISPLAY_MANAGER, QUI$_DISPLAY_QUEUE, QUI$_TRANSLATE_QUEUE function codes)

QUI$_SEARCH_NUMBER

QUI$_SEARCH_NUMBER is an input value item code that specifies, as a longword integer value, the number of the characteristic, form, or job entry about which $GETQUI is to return information. The buffer must specify a longword integer value.

(Valid for QUI$_DISPLAY_CHARACTERISTIC, QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_FORM function codes)

QUI$_SEARCH_USERNAME

QUI$_SEARCH_USERNAME is an input value item code that specifies, as a 1- to 12-character string, the user name for $GETQUI to use to restrict its search for jobs. By default, $GETQUI searches for jobs whose owner has the same user name as the calling process.

(Valid for QUI$_DISPLAY_ENTRY function code)

QUI$_SUBMISSION_TIME

Returns, as a quadword absolute time value, the time at which the specified job was submitted to the queue.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_TIMED_RELEASE_JOB_COUNT

Returns, as a longword value, the number of jobs in the queue on hold until a specified time.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_UIC

Returns, in standard longword format, the UIC of the owner of the specified job.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_USERNAME

Returns, as a character string, the user name of the owner of the specified job. Because the user name can include up to 12 characters, the buffer length field of the item descriptor should specify 12 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_WSDEFAULT

Returns, in pagelets , the default working set size specified for the specified job or queue, which is a longword integer in the range 1 through 65,535. This value is meaningful only for batch jobs and execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE function codes)

QUI$_WSEXTENT

Returns, in pagelets , the working set extent for the specified job or queue, which is a longword integer in the range 1 through 65,535. This value is meaningful only for batch jobs and execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE function codes)

QUI$_WSQUOTA

Returns, in pagelets , the working set quota for the specified job or queue, which is a longword integer in the range 1 through 65,535. This value is meaningful only for batch jobs and execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE function codes)


Description

The Get Queue Information service returns information about queues and the jobs initiated from those queues. The $GETQUI and $SNDJBC services together provide the user interface to the queue manager and job controller processes. See the Description section of the $SNDJBC service for a discussion of the different types of jobs and queues.

The $GETQUI service completes asynchronously; that is, it returns to the caller after queuing the request, without waiting for the operation to complete. For synchronous completion, use the Get Queue Information and Wait ($GETQUIW) service. The $GETQUIW service is identical to $GETQUI in every way except that $GETQUIW returns to the caller after the operation has completed.

Classes and Types of Queues


Previous Next Contents Index