Difference between revisions of "$GETQUI"

From VSI OpenVMS Wiki
Jump to: navigation, search
(→‎Item Codes)
m
 
Line 925: Line 925:
 
| QUI$_DISPLAY_FORM
 
| QUI$_DISPLAY_FORM
 
|}
 
|}
 +
 +
[[Category:System Services]]

Latest revision as of 12:47, 28 November 2019

$GETQUI, or Get Queue Information, is a system service that returns information about queues and the jobs initiated from those queues. The $GETQUI service completes asynchronously; for synchronous completion, use the Get Queue Information and Wait ($GETQUIW) service.

Syntax

SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]

SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]

C prototype:

int sys$getqui (unsigned int efn, unsigned short int func, unsigned int *context, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

Arguments

efn

OpenVMS usage: ef_number
Type: longword (unsigned)
Access: read only
Mechanism: by value

Number of the event flag to be set when $GETQUI completes. The efn argument is a longword containing this number; however, $GETQUI uses only the low-order byte. The efn argument is optional. When the request is queued, $GETQUI clears the specified event flag (or event flag 0 if efn was not specified). Then, when the operation completes, $GETQUI sets the specified event flag (or event flag 0).

func

OpenVMS usage: function_code
Type: word (unsigned)
Access: read only
Mechanism: by value

Function code specifying the function that $GETQUI is to perform. The func argument is a word containing this function code. The $QUIDEF macro defines the names of each function code. You can specify only one function code in a single call to $GETQUI. Most function codes require or allow for additional information to be passed in the call. You pass this information by using the itmlst argument, which specifies a list of one or more item descriptors. Each item descriptor in turn specifies an item code, which either describes the specific information to be returned by $GETQUI, or otherwise affects the action designated by the function code.

You can use wildcard mode to make a sequence of calls to $GETQUI to get information about all characteristics, form definitions, queues, or jobs contained in the system job queue file. For information on using wildcard mode, see the Description section.

context

OpenVMS usage: context
Type: longword (unsigned)
Access: modify
Mechanism: by reference

Address of a longword containing the number of a context stream for this call to the $GETQUI system service. If the argument is unspecified or 0, the service uses the default context stream (#0). To generate a new context stream, the specified longword must contain --1. $GETQUI then modifies the longword to hold the context number for that stream of operation. The context is marked with the caller's mode (user, supervisor, executive, or kernel). Any attempt to use that context in successive calls is checked and no call from a mode outside the recorded mode is allowed access.

To clean up a context, make a $GETQUI call using the QUI$_CANCEL_OPERATION function code and specify the address of the context number as the context argument.

itmlst

OpenVMS usage: item_list_3
Type: longword (unsigned)
Access: read only
Mechanism: by reference

Item list supplying information to be used in performing the function specified by the func argument. The itmlst argument is the address of the item list. The item list consists of one or more item descriptors, each of which contains an item code. The item list is terminated by an item code of 0 or by a longword of 0.

Structure of a $GETQUI item descriptor

The following table defines the item descriptor fields:

Descriptor Field Definition
Buffer length A word specifying the length of the buffer; the buffer either supplies information to $GETQUI or receives information from $GETQUI. The required length of the buffer varies, depending on the item code specified, and is given in the description of each item code.
Item code A word containing an item code, which identifies the nature of the information supplied for $GETQUI or which is received from $GETQUI. Each item code has a symbolic name; the $QUIDEF macro defines these symbolic names.
Buffer address Address of the buffer that specifies or receives the information.
Return length address Address of a word to receive the length of information returned by $GETQUI.

The item codes' symbolic names have the following format: QUI$_code.

There are two types of item code:

  • Input value item code. The $GETQUI service has only five input value item codes: QUI$_SEARCH_FLAGS, QUI$_SEARCH_JOB_NAME, QUI$_SEARCH_NAME, QUI$_SEARCH_NUMBER, and QUI$_SEARCH_USERNAME. These item codes specify the object name or number for which $GETQUI is to return information and the extent of $GETQUI's search for these objects. Most function codes require that you specify at least one input value item code. The function code or codes for which each item code is valid are shown in parentheses after the item code description.

For input value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field must be zero. Specific buffer length requirements are given in the description of each item code.

  • Output value item code. Output value item codes specify a buffer for information returned by $GETQUI. For output value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be zero or nonzero. Specific buffer length requirements are given in the description of each item code.

Several item codes specify a queue name, form name, or characteristic name to $GETQUI or request that $GETQUI return one of these names. For these item codes, the buffer must specify or be prepared to receive a string containing from 1 to 31 characters, exclusive of spaces, tabs, and null characters, which are ignored. Allowable characters in the string are uppercase alphabetic characters, lowercase alphabetic characters (which are converted to uppercase), numeric characters, the dollar sign ($), and the underscore (_).

See Item Codes for a description of the $GETQUI item codes.

iosb

OpenVMS usage: io_status_block
Type: quadword (unsigned)
Access: write only
Mechanism: by reference

I/O status block into which $GETQUI writes the completion status after the requested operation has completed. The iosb argument is the address of the I/O status block. At request initiation, $GETQUI sets the value of the quadword I/O status block to 0. When the requested operation has completed, $GETQUI writes a condition value in the first longword of the I/O status block. It writes the value 0 into the second longword; this longword is unused and reserved for future use.

The condition values returned by $GETQUI in the I/O status block are condition values from the JBC facility, which are defined by the $JBCMSGDEF macro. The condition values returned from the JBC facility are listed in the section Condition Values Returned in the I/O Status Block section.

Though this argument is optional, Compaq strongly recommends that you specify it, for the following reasons:

  • If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
  • If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
  • The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $GETQUI service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $GETQUI, you must check the condition values returned in both R0 and the I/O status block.

astadr

OpenVMS usage: ast_procedure
Type: longword (unsigned)
Access: read only
Mechanism: by value

AST service routine to be executed when $GETQUI completes. The astadr argument is the address of this routine.

If specified, the AST routine executes at the same access mode as the caller of $GETQUI.

astprm

OpenVMS usage: user_parm
Type: longword (unsigned)
Access: read only
Mechanism: by value

AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument is this longword parameter.

Function Codes

This section lists each of the $GETQUI function codes, describes the function, and lists the related item codes.

Function Code Description
QUI$_CANCEL_OPERATION This request terminates a wildcard operation that might have been initiated by a previous call to $GETQUI by releasing the $GETQUI context block (GQC) associated with the specified context stream.

A specific context stream can be selected and other streams are unaffected.

QUI$_DISPLAY_CHARACTERISTIC This request returns information about a specific characteristic definition, or the next characteristic definition in a wildcard operation.

A successful QUI$_DISPLAY_CHARACTERISTIC wildcard operation terminates when the $GETQUI service has returned information about all characteristic definitions included in the wildcard sequence. The $GETQUI service indicates termination of this sequence by returning the condition value JBC$_NOMORECHAR in the I/O status block. If the $GETQUI service does not find any characteristic definitions, it returns the condition value JBC$_NOSUCHCHAR in the I/O status block.

For more information on how to request information about characteristics, see the Description section.

You must specify one of the following input value item codes; you can specify both:

  • QUI$_SEARCH_NAME
  • QUI$_SEARCH_NUMBER

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

  • QUI$_CHARACTERISTIC_NAME
  • QUI$_CHARACTERISTIC_NUMBER
QUI$_DISPLAY_ENTRY This request returns information about a specific job entry, or the next job entry that matches the selection criteria in a wildcard operation. You use the QUI$_SEARCH_NUMBER item code to specify the job entry number.

In wildcard mode, the QUI$_DISPLAY_ENTRY operation also establishes a job context for subsequent QUI$_DISPLAY_FILE operations. The job context established remains in effect until you make another call to the $GETQUI service that specifies either the QUI$_DISPLAY_ENTRY or QUI$_CANCEL_OPERATION function code.

A successful QUI$_DISPLAY_ENTRY wildcard operation terminates when the $GETQUI service has returned information about all job entries for the specified user (or the current user name if the QUI$_SEARCH_USERNAME item code is not specified). The $GETQUI service signals termination of this sequence by returning the condition value JBC$_NOMOREENT in the I/O status block. If the $GETQUI service does not find a job with the specified entry number, or does not find a job meeting the search criteria, it returns the condition value JBC$_NOSUCHENT in the first longword of the I/O status block.

You can specify the following input value item codes:

  • QUI$_SEARCH_FLAGS
  • QUI$_SEARCH_JOB_NAME
  • QUI$_SEARCH_NUMBER
  • QUI$_SEARCH_USERNAME

You can specify the following output value item codes:

  • QUI$_ACCOUNT_NAME
  • QUI$_AFTER_TIME
  • QUI$_ASSIGNED_QUEUE_NAME
  • QUI$_CHARACTERISTICS
  • QUI$_CHECKPOINT_DATA
  • QUI$_CLI
  • QUI$_COMPLETED_BLOCKS
  • QUI$_CONDITION_VECTOR
  • QUI$_CPU_LIMIT
  • QUI$_ENTRY_NUMBER
  • QUI$_FILE_COUNT
  • QUI$_FORM_NAME
  • QUI$_FORM_STOCK
  • QUI$_JOB_COMPLETION_QUEUE
  • QUI$_JOB_COMPLETION_TIME
  • QUI$_JOB_COPIES
  • QUI$_JOB_COPIES_DONE
  • QUI$_JOB_FLAGS
  • QUI$_JOB_NAME
  • QUI$_JOB_PID
  • QUI$_JOB_RETENTION_TIME
  • QUI$_JOB_SIZE
  • QUI$_JOB_STATUS
  • QUI$_LOG_QUEUE
  • QUI$_LOG_SPECIFICATION
  • QUI$_NOTE
  • QUI$_OPERATOR_REQUEST
  • QUI$_PARAMETER_1 through 8
  • QUI$_PENDING_JOB_REASON
  • QUI$_PRIORITY
  • QUI$_PROCESSOR
  • QUI$_QUEUE_FLAGS
  • QUI$_QUEUE_NAME
  • QUI$_QUEUE_STATUS
  • QUI$_REQUEUE_QUEUE_NAME
  • QUI$_RESTART_QUEUE_NAME
  • QUI$_SUBMISSION_TIME
  • QUI$_UIC
  • QUI$_USERNAME
  • QUI$_WSDEFAULT
  • QUI$_WSEXTENT
  • QUI$_WSQUOTA
QUI$_DISPLAY_FILE This request returns information about the next file defined for the current job context. You normally make this request as part of a nested wildcard sequence of queue-job-file operations or a nested wildcard sequence of entry-file operations; that is, before you make a call to $GETQUI to request file information, you have already made a call to the $GETQUI service to establish the job context of the job that contains the files in which you are interested.

The $GETQUI service signals that it has returned information about all the files defined for the current job context by returning the condition value JBC$_NOMOREFILE in the I/O status block. If the current job context contains no files, $GETQUI returns the condition value JBC$_NOSUCHFILE in the I/O status block.

A batch job can make a call to the $GETQUI service to request information about the command file that is currently executing without first making calls to the service to establish a queue and job context. To do this, the batch job specifies the QUI$V_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code. The system does not save the queue or job context established in such a call.

For more information about how to request file information, see the Description section.

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

  • QUI$_FILE_COPIES
  • QUI$_FILE_COPIES_DONE
  • QUI$_FILE_FLAGS
  • QUI$_FILE_IDENTIFICATION
  • QUI$_FILE_SETUP_MODULES
  • QUI$_FILE_SPECIFICATION
  • QUI$_FILE_STATUS
  • QUI$_FIRST_PAGE
  • QUI$_LAST_PAGE
QUI$_DISPLAY_FORM This request returns information about a specific form definition, or the next form definition in a wildcard operation.

A successful QUI$_DISPLAY_FORM wildcard operation terminates when the $GETQUI service has returned information about all form definitions included in the wildcard sequence. The $GETQUI service signals termination of this wildcard sequence by returning the condition value JBC$_NOMOREFORM in the I/O status block. If the $GETQUI service finds no form definitions, it returns the condition value JBC$_NOSUCHFORM in the I/O status block.

For more information on how to request information about forms, see the Description section.

You must specify one of the following input value item codes. You can specify both:

  • QUI$_SEARCH_NAME
  • QUI$_SEARCH_NUMBER

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

  • QUI$_FORM_DESCRIPTION
  • QUI$_FORM_FLAGS
  • QUI$_FORM_LENGTH
  • QUI$_FORM_MARGIN_BOTTOM
  • QUI$_FORM_MARGIN_LEFT
  • QUI$_FORM_MARGIN_RIGHT
  • QUI$_FORM_MARGIN_TOP
  • QUI$_FORM_NAME
  • QUI$_FORM_NUMBER
  • QUI$_FORM_SETUP_MODULES
  • QUI$_FORM_STOCK
  • QUI$_FORM_WIDTH
  • QUI$_PAGE_SETUP_MODULES
QUI$_DISPLAY_JOB This request returns information about the next job defined for the current queue context. You normally make this request as part of a nested wildcard queue-job sequence of operations; that is, before you make a call to $GETQUI to request job information, you have already made a call to the $GETQUI service to establish the queue context of the queue that contains the job in which you are interested.

In wildcard mode, the QUI$_DISPLAY_JOB operation also establishes a job context for subsequent QUI$_DISPLAY_FILE operations. The job context established remains in effect until another call is made to the $GETQUI service that specifies the QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE, or QUI$_CANCEL_OPERATION function code.

The $GETQUI service signals that it has returned information about all the jobs contained in the current queue context by returning the condition value JBC$_NOMOREJOB in the I/O status block. If the current queue context contains no jobs, $GETQUI returns the condition value JBC$_NOSUCHJOB in the first longword of the I/O status block.

A batch job can make a call to the $GETQUI service to request information about itself without first making a call to the service to establish a queue context. To do this, the batch job must specify the QUI$V_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code. The system does not save the queue or job context established in such a call.

For more information about how to request job information, see the Description section.

You can specify the following input value item code:

QUI$_SEARCH_FLAGS 

You can specify the following output value item codes:
  • QUI$_ACCOUNT_NAME
  • QUI$_AFTER_TIME
  • QUI$_CHARACTERISTICS
  • QUI$_CHECKPOINT_DATA
  • QUI$_CLI
  • QUI$_COMPLETED_BLOCKS
  • QUI$_CONDITION_VECTOR
  • QUI$_CPU_LIMIT
  • QUI$_ENTRY_NUMBER
  • QUI$_FILE_COUNT
  • QUI$_FORM_NAME
  • QUI$_FORM_STOCK
  • QUI$_INTERVENING_BLOCKS
  • QUI$_INTERVENING_JOBS
  • QUI$_JOB_COMPLETION_QUEUE
  • QUI$_JOB_COMPLETION_TIME
  • QUI$_JOB_COPIES
  • QUI$_JOB_COPIES_DONE
  • QUI$_JOB_FLAGS
  • QUI$_JOB_NAME
  • QUI$_JOB_PID
  • QUI$_JOB_RETENTION_TIME
  • QUI$_JOB_SIZE
  • QUI$_JOB_STATUS
  • QUI$_LOG_QUEUE
  • QUI$_LOG_SPECIFICATION
  • QUI$_NOTE
  • QUI$_OPERATOR_REQUEST
  • QUI$_PARAMETER_1 through 8
  • QUI$_PENDING_JOB_REASON
  • QUI$_PRIORITY
  • QUI$_QUEUE_NAME
  • QUI$_REQUEUE_QUEUE_NAME
  • QUI$_RESTART_QUEUE_NAME
  • QUI$_SUBMISSION_TIME
  • QUI$_UIC
  • QUI$_USERNAME
  • QUI$_WSDEFAULT
  • QUI$_WSEXTENT
  • QUI$_WSQUOTA
QUI$_DISPLAY_MANAGER This request returns information about a specific queue manager, or the next queue manager in a wildcard operation.

The $GETQUI service indicates that it has returned information about all the queue managers contained in the current wildcard sequence by returning the condition value JBC$_NOMOREQMGR in the I/O status block. If no queue manager matching the name string is found, $GETQUI returns the condition value JBC$_NOSUCHQMGR in the first longword of the I/O status block.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

  • QUI$_MANAGER_NAME
  • QUI$_MANAGER_NODES
  • QUI$_MANAGER_STATUS
  • QUI$_QUEUE_DIRECTORY
  • QUI$_SCSNODE_NAME
QUI$_DISPLAY_QUEUE This request returns information about a specific queue definition, or the next queue definition in a wildcard operation.

In wildcard mode, the QUI$_DISPLAY_QUEUE operation also establishes a queue context for subsequent QUI$_DISPLAY_JOB operations. The queue context established remains in effect until another call is made to the $GETQUI service that specifies either the QUI$_DISPLAY_QUEUE or QUI$_CANCEL_OPERATION function code.

The $GETQUI service indicates that it has returned information about all the queues contained in the current wildcard sequence by returning the condition value JBC$_NOMOREQUE in the I/O status block. If no queue is found, $GETQUI returns the condition value JBC$_NOSUCHQUE in the first longword of the I/O status block.

A batch job can make a call to the $GETQUI service to request information about the queue in which it is contained without first making a call to the service to establish a queue context. To do this, the batch job must specify the QUI$V_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code. The system does not save the queue context established in such a call.

For more information about how to request queue information, see the Description section.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

  • QUI$_ASSIGNED_QUEUE_NAME
  • QUI$_BASE_PRIORITY
  • QUI$_CHARACTERISTICS
  • QUI$_CPU_DEFAULT
  • QUI$_CPU_LIMIT
  • QUI$_DEFAULT_FORM_NAME
  • QUI$_DEFAULT_FORM_STOCK
  • QUI$_DEVICE_NAME
  • QUI$_EXECUTING_JOB_COUNT
  • QUI$_FORM_NAME
  • QUI$_FORM_STOCK
  • QUI$_GENERIC_TARGET
  • QUI$_HOLDING_JOB_COUNT
  • QUI$_JOB_LIMIT
  • QUI$_JOB_RESET_MODULES
  • QUI$_JOB_SIZE_MAXIMUM
  • QUI$_JOB_SIZE_MINIMUM
  • QUI$_LIBRARY_SPECIFICATION
  • QUI$_OWNER_UIC
  • QUI$_PENDING_JOB_BLOCK_COUNT
  • QUI$_PENDING_JOB_COUNT
  • QUI$_PROCESSOR
  • QUI$_PROTECTION
  • QUI$_QUEUE_DESCRIPTION
  • QUI$_QUEUE_FLAGS
  • QUI$_QUEUE_NAME
  • QUI$_QUEUE_STATUS
  • QUI$_RETAINED_JOB_COUNT
  • QUI$_SCSNODE_NAME
  • QUI$_TIMED_RELEASE_JOB_COUNT
  • QUI$_WSDEFAULT
  • QUI$_WSEXTENT
  • QUI$_WSQUOTA
QUI$_TRANSLATE_QUEUE This request translates a logical name for a queue to the equivalence name for the queue. The logical name is specified by QUI$_SEARCH_NAME. The translation is performed iteratively until the equivalence string is found or the number of translations allowed by the system has been reached.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following output value item code:

QUI$_QUEUE_NAME

Item Codes

Item Code Description Function Codes
QUI$_ACCOUNT_NAME Returns, as a character string, the account name of the owner of the specified job. Because the account name can include up to 8 characters, the buffer length field of the item descriptor should specify 8 (bytes).
  • QUI$_DISPLAY_ENRY
  • QUI$_DISPLAY_JOB
QUI$_AFTER_TIME Returns, as a quadword absolute time value, the system time at or after which the specified job can execute; however, if the time specified at submission has passed, the job executes immediately and $GETQUI returns the system time at which the job was submitted.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_ASSIGNED_QUEUE_NAME Returns, as a character string, the name of the execution queue to which the logical queue specified in the call to $GETQUI is assigned. Because the queue name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_QUEUE
QUI$_AUTOSTART_ON When you specify QUI$_AUTOSTART_ON for a batch queue, $GETQUI returns, as a character string in a comma-separated list, the names of the nodes on which the specified autostart queue can be run. Each node name is followed by a double colon (::).

When you specify QUI$_AUTOSTART_ON for an output queue, $GETQUI returns, as a character string in a comma-separated list, the names of the nodes and devices to which the specified autostart queue's output can be sent. Each node name is followed by a double colon (::). Each device name can be followed by the optional colon [:].

QUI$_DISPLAY_QUEUE
QUI$_BASE_PRIORITY Returns, as a longword value in the range 0 to 15, the priority at which batch jobs are initiated from a batch execution queue or the priority of a symbiont process that controls output execution queues. QUI$_DISPLAY_QUEUE
QUI$_CHARACTERISTIC_NAME Returns, as a character string, the name of the specified characteristic. Because the characteristic name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes). QUI$_DISPLAY_CHARACTERISTIC
QUI$_CHARACTERISTIC_NUMBER Returns, as a longword value in the range 0 to 127, the number of the specified characteristic. QUI$_DISPLAY_CHARACTERISTIC
QUI$_CHARACTERISTICS Returns, as a 128-bit string (16-byte field), the characteristics associated with the specified queue or job. Each bit set in the bit mask represents a characteristic number in the range 0 to 127.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
  • QUI$_DISPLAY_QUEUE
QUI$_CHECKPOINT_DATA Returns, as a character string, the value of the DCL symbol BATCH$RESTART when the specified batch job is restarted. Because the value of the symbol can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes).
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_CLI Returns, as an OpenVMS RMS file name component, the name of the command language interpreter used to execute the specified batch job. The file specification returned assumes the logical name SYS$SYSTEM and the file type .EXE. Because a file name can include up to 39 characters, the buffer length field in the item descriptor should specify 39 (bytes). This item code is applicable only to batch jobs.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_COMPLETED_BLOCKS Returns, as a longword integer value, the number of blocks that the symbiont has processed for the specified print job. This item code is applicable only to print jobs.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_CONDITION_VECTOR Returns the vector of three longwords. The first longword gives the completion status of the specified job. The second and third longwords give additional status about the print job.
  • QUI$_DISPLAY ENTRY
  • QUI$_DISPLAY_JOB
QUI$_CPU_DEFAULT Returns, as a longword integer value, the default CPU time limit specified for the queue in 10-millisecond units. This item code is applicable only to batch execution queues. QUI$_DISPLAY_QUEUE
QUI$_CPU_LIMIT Returns, as a longword integer value, the maximum CPU time limit specified for the specified job or queue in 10-millisecond units. This item code is applicable only to batch jobs and batch execution queues.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
  • QUI$_DISPLAY_QUEUE
QUI$_DEFAULT_FORM_NAME Returns, as a character string, the name of the default form associated with the specified output queue. Because the form name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes). QUI$_DISPLAY_QUEUE
QUI$_DEFAULT_FORM_STOCK Returns, as a character string, the name of the paper stock on which the specified default form is to be printed. Because the name of the paper stock can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes). QUI$_DISPLAY_QUEUE
QUI$_DEVICE_NAME Returns, as a character string, the name of the device on which the specified output execution queue is located. Because the device name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes). QUI$_DISPLAY_QUEUE
QUI$_ENTRY_NUMBER Returns, as a longword integer value, the queue entry number of the specified job.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_EXECUTING_JOB_COUNT Returns, as a longword integer value, the number of jobs in the queue that are currently executing. QUI$_DISPLAY_QUEUE
QUI$_FILE_COPIES Returns the number of times the specified file is to be processed, which is a longword integer value in the range 1 to 255. This item code is applicable only to output execution queues. QUI$_DISPLAY_FILE
QUI$_FILE_COPIES_DONE Returns the number of times the specified file has been processed, which is a longword integer value in the range 1 to 255. This item code is applicable only to output execution queues. QUI$_DISPLAY_FILE
QUI$_FILE_COUNT Returns, as a longword integer value, the number of files in a specified job.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_FILE_FLAGS Returns, as a longword bit vector, the processing options that have been selected for the specified file. Each processing option is represented by a bit. When $GETQUI sets a bit, the file is 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_FILE_BURST Burst and flag pages are to be printed preceding the file.
QUI$V_FILE_DELETE File is to be deleted after execution of request.
QUI$V_FILE_DOUBLE_SPACE Symbiont formats the file with double spacing.
QUI$V_FILE_FLAG Flag page is to be printed preceding the file.
QUI$V_FILE_TRAILER Trailer page is to be printed following the file.
QUI$V_FILE_PAGE_HEADER Page header is to be printed on each page of output.
QUI$V_FILE_PAGINATE Symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUI$V_FILE_PASSALL Symbiont prints the file in PASSALL mode.
QUI$_DISPLAY_FILE
QUI$_FILE_IDENTIFICATION Returns, as a 28-byte string, the internal file-identification value that uniquely identifies the selected file. This string contains (in order) the following three file-identification fields from the RMS NAM block for the selected file: the 16-byte NAM$T_DVI field, the 6-byte NAM$W_FID field, and the 6-byte NAM$W_DID field. QUI$_DISPLAY_FILE
QUI$_FILE_SETUP_MODULES Returns, as a comma-separated list, the names of the text modules that are to be extracted from the device control library and copied to the printer before the specified file is printed. Because a text module name can include up to 31 characters and is separated from the previous text module name with 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. QUI$_DISPLAY_FILE
QUI$_FILE_SPECIFICATION Returns the fully qualified OpenVMS RMS file specification of the file about which $GETQUI is returning information. Because a file specification can include up to 255 characters, the buffer length field of the item descriptor should specify 255 (bytes).

Note: The file specification is the result of an RMS file-passing operation that occurs at the time you submit the job. If you renamed the file or created the job as a result of copying a file to a spooled device, then you cannot use this file specification to access the file through RMS. You use QUI$_FILE_IDENTIFICATION to obtain a unique identifier for the file.

QUI$_DISPLAY_FILE
QUI$_FILE_STATUS Returns file status information as a longword bit vector. Each file status condition is represented by a bit. When $GETQUI sets the bit, the file status corresponds to the condition represented by the bit. Each bit in the vector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:

Symbolic Name Description
QUI$V_FILE_CHECKPOINTED File is checkpointed.
QUI$V_FILE_EXECUTING File is being processed.
QUI$_DISPLAY_FILE
QUI$_FIRST_PAGE Returns, as a longword integer value, the page number at which the printing of the specified file is to begin. This item code is applicable only to output execution queues. QUI$_DISPLAY_FILE
QUI$_FORM_DESCRIPTION Returns, as a character string, the text string that describes the specified form. Because the text string can include up to 255 characters, the buffer length field in the item descriptor should specify 255 (bytes). QUI$_DISPLAY_FORM
QUI$_FORM_FLAGS Returns, as a longword bit vector, the processing options that have been selected for the specified form. Each processing option is represented by a bit. When $GETQUI sets a bit, the form is 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_FORM_SHEET_FEED Symbiont pauses at the end of each physical page so that another sheet of paper can be inserted.
QUI$V_FORM_TRUNCATE Printer discards any characters that exceed the specified right margin.
QUI$V_FORM_WRAP Printer prints any characters that exceed the specified right margin on the following line.
QUI$_DISPLAY_FORM
QUI$_FORM_LENGTH Returns, as a longword integer value, the physical length of the specified form in lines. This item code is applicable only to output execution queues. QUI$_DISPLAY_FORM
QUI$_FORM_MARGIN_BOTTOM Returns, as a longword integer value, the bottom margin of the specified form in lines. QUI$_DISPLAY_FORM
QUI$_FORM_MARGIN_LEFT Returns, as a longword integer value, the left margin of the specified form in characters. QUI$_DISPLAY_FORM
QUI$_FORM_MARGIN_RIGHT Returns, as a longword integer value, the right margin of the specified form in characters. QUI$_DISPLAY_FORM
QUI$_FORM_MARGIN_TOP Returns, as a longword integer value, the top margin of the specified form in lines. QUI$_DISPLAY_FORM
QUI$_FORM_NAME Returns, as a character string, the name of the specified form or the mounted form associated with the specified job or queue. Because the form name can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_FORM
  • QUI$_DISPLAY_JOB
  • QUI$_DISPLAY_QUEUE
QUI$_FORM_NUMBER Returns, as a longword integer value, the number of the specified form. QUI$_DISPLAY_FORM
QUI$_FORM_SETUP_MODULES Returns, as a comma-separated list, the names of the text modules that are to be extracted from the device control library and copied to the printer before a file is printed on the specified form. 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. QUI$_DISPLAY_FORM
QUI$_FORM_STOCK

Returns, as a character string, the name of the paper stock on which the specified form is to be printed. Because the name of the paper stock can include up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).

  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_FORM
  • QUI$_DISPLAY_JOB
  • QUI$_DISPLAY_QUEUE
QUI$_FORM_WIDTH Returns, as a longword integer value, the width of the specified form in characters. QUI$_DISPLAY_FORM
QUI$_GENERIC_TARGET Returns, as a comma-separated list, the names of the execution queues that are enabled to accept work from the specified generic queue. Because a queue name can include up to 31 characters and is separated from the previous queue name with a comma, the buffer length field of the item descriptor should specify 32 (bytes) for each possible queue name. A generic queue can send work to up to 124 execution queues. This item code is meaningful only for generic queues. QUI$_DISPLAY_QUEUE
QUI$_HOLDING_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queue being held until explicitly released.

QUI$_DISPLAY_QUEUE
QUI$_INTERVENING_BLOCKS Returns, as a longword integer value, the size (in blocks) of files associated with pending jobs in the queue that were skipped during the current call to $GETQUI. These jobs were not reported because they did not match the selection criterion in effect for the call to $GETQUI.

The value of QUI$_INTERVENING_BLOCKS is 0 when (1) the job is not a pending job, or (2) the job that matches the selection criterion is the first pending job in the queue, or (3) the preceding pending job in the queue was reported in the previous call to $GETQUI.

This item code applies only to output queues.

In a wildcard sequence of calls to $GETQUI using the QUI$_DISPLAY_JOB function code, only information about jobs that match the $GETQUI selection criteria is returned.

QUI$_DISPLAY_JOB
QUI$_INTERVENING_JOBS Returns, as a longword integer value, the number of pending jobs in the queue that were skipped during the current call to $GETQUI. These jobs were not reported because they did not match the selection criterion in effect for the call to $GETQUI.

The value of QUI$_INTERVENING_JOBS is 0 when (1) the job is not a pending job, or (2) the job that matches the selection criterion is the first pending job in the queue, or (3) the preceding pending job in the queue was reported in the previous call to $GETQUI.

This item code applies only to output queues.

In a wildcard sequence of calls to $GETQUI using the QUI$_DISPLAY_JOB function code, only information about jobs that match the $GETQUI selection criteria is returned.

QUI$_DISPLAY_JOB
QUI$_JOB_COMPLETION_QUEUE Returns, as a character string, the name of the queue on which the specified job executed. Because a queue name can include up to 31 characters, the buffer length of the item descriptor should specify 31 (bytes).

This item code has a value only if the QUI$_JOB_RETAINED bit is set in the QUI$_JOB_STATUS longword item code.

  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_COMPLETION_TIME Returns, as a quadword absolute time value, the system time at which the execution of the specified job completed.

This item code has a value only if the QUI$_JOB_RETAINED bit is set in the QUI$_JOB_STATUS longword item code.

  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_COPIES

Returns, as a longword integer value, the number of times the specified print job is to be repeated.

  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_COPIES_DONE Returns, as a longword integer value, the number of times the specified print job has been repeated.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_FLAGS Returns, as a longword bit vector, the processing options that have been selected for the specified job. Each processing option is represented by a bit. When $GETQUI sets a bit, the job is processed according to the corresponding processing option. Each bit in the vector has a symbolic name.
Symbolic Name Description
QUI$V_JOB_CPU_LIMIT CPU time limit for the job.
QUI$V_JOB_ERROR_RETENTION The user requested that the job be retained in the queue, if the job completes unsuccessfully. If the queue is set to retain all jobs because the QUI$V_QUEUE_RETAIN_ALL bit of the QUI$_QUEUE_FLAGS item code is set, the job might be held in the queue even if it completes successfully.

For more information about user-specified job retention, see the /RETAIN qualifier for the PRINT or SUBMIT command in the OpenVMS DCL Dictionary.

QUI$V_JOB_FILE_BURST Burst and flag pages precede each file in the job.
QUI$V_JOB_FILE_BURST_ONE Burst and flag pages precede only the first copy of the first file in the job.
QUI$V_JOB_FILE_FLAG Flag page precedes each file in the job.
QUI$V_JOB_FILE_FLAG_ONE Flag page precedes only the first copy of the first file in the job.
QUI$V_JOB_FILE_PAGINATE Symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUI$V_JOB_FILE_TRAILER Trailer page follows each file in the job.
QUI$V_JOB_FILE_TRAILER_ONE Trailer page follows only the last copy of the last file in the job.
QUI$V_JOB_LOG_DELETE Log file is deleted after it is printed.
QUI$V_JOB_LOG_NULL No log file is created.
QUI$V_JOB_LOG_SPOOL Job log file is queued for printing when job is complete.
QUI$V_JOB_LOWERCASE Job is to be printed on printer that can print both uppercase and lowercase letters.
QUI$V_JOB_NOTIFY Message is broadcast to terminal when job completes or aborts.
QUI$V_JOB_REQUEUE Job will requeue after a system failure or can be requeued during execution.
QUI$V_JOB_RESTART Job will restart after a system failure or can be requeued during execution.
QUI$V_JOB_RETENTION The user requested that the job be retained in the queue regardless of the job's completion status.
QUI$V_JOB_WSDEFAULT Default working set size is specified for the job.
QUI$V_JOB_WSEXTENT Working set extent is specified for the job.
QUI$V_JOB_WSQUOTA Working set quota is specified for the job.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_LIMIT Returns the number of jobs that can execute simultaneously on the specified queue, which is a longword integer value in the range 1 to 255. This item code is applicable only to batch execution queues. QUI$_DISPLAY_QUEUE
QUI$_JOB_NAME Returns, as a character string, the name of the specified job. Because the job name can include up to 39 characters, the buffer length field of the item descriptor should specify 39 (bytes).
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_PID Returns the process identification (PID) of the executing batch job in standard longword format.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_RESET_MODULES Returns, as a comma-separated list, the names of the text modules that are to be extracted from the device control library and copied to the printer before each job in the specified queue 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. QUI$_DISPLAY_QUEUE
QUI$_JOB_RETENTION_TIME Returns, as a quadword time value, the system time until which the user requested the job be retained in the queue. The system time can be expressed in either an absolute or delta time format.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_SIZE Returns, as a longword integer value, the total number of disk blocks in the specified print job.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_JOB_SIZE_MAXIMUM Returns, as a longword integer value, the maximum number of disk blocks that a print job initiated from the specified queue can contain. This item code is applicable only to output execution queues. QUI$_DISPLAY_QUEUE
QUI$_JOB_SIZE_MINIMUM Returns, as a longword integer value, the minimum number of disk blocks that a print job initiated from the specified queue can contain. This item code is applicable only to output execution queues. QUI$_DISPLAY_QUEUE
QUI$_JOB_STATUS Returns the specified job'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_JOB_ABORTING System is attempting to abort execution of job.
QUI$V_JOB_EXECUTING Job is executing or printing.
QUI$V_JOB_HOLDING Job will be held until it is explicitly released.
QUI$V_JOB_INACCESSIBLE Caller does not have read access to the specific job and file information in the system queue file. Therefore, the QUI$_DISPLAY_JOB and QUI$_DISPLAY_FILE operations can return information for only the following output value item codes:
  • QUI$_AFTER_TIME
  • QUI$_COMPLETED_BLOCKS
  • QUI$_ENTRY_NUMBER
  • QUI$_INTEVENING_BLOCKS
  • QUI$_INTEVENING_JOBS
  • QUI$_JOB_SIZE
  • QUI$_JOB_STATUS
QUI$V_JOB_PENDING Job is pending. See QUI$_PENDING_JOB_REASON for the reason the job is in a pending state.
QUI$V_JOB_REFUSED Job was refused by symbiont and is waiting for symbiont to accept it for processing.
QUI$V_JOB_RETAINED Job has completed, but it is being retained in the queue.
QUI$V_JOB_STALLED Execution of the job is stalled because the physical device on which the job is printing is stalled.
QUI$V_JOB_STARTING The job has been scheduled for execution. Confirmation of execution has not been received.
QUI$V_JOB_SUSPENDED Execution of the job is suspended because the queue on which it is executing is paused.
QUI$V_JOB_TIMED_RELEASE Job is waiting for specified time to execute.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_LAST_PAGE Returns, as a longword integer value, the page number at which the printing of the specified file should end. This item code is applicable only to output execution queues. QUI$_DISPLAY_FILE
QUI$_LIBRARY_SPECIFICATION Returns, as an OpenVMS RMS file name component, the name of the device control library for the specified queue. The library specification assumes the device and directory name SYS$LIBRARY and a file type of .TLB. Because a file name can include up to 39 characters, the buffer length field of the item descriptor should specify 39 (bytes). This item code is meaningful only for output execution queues. QUI$_DISPLAY_QUEUE
QUI$_LOG_QUEUE Returns, as a character string, the name of the queue into which the log file produced for the specified batch job is to be entered for printing. This item code is applicable only to batch jobs. Because a queue name can contain up to 31 characters, the buffer length field of the item descriptor should specify 31 (bytes).
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_LOG_SPECIFICATION Returns, as an OpenVMS RMS file specification, the name of the log file to be produced for the specified job. Because a file specification 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 batch jobs.

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.

  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
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). QUI$_DISPLAY_MANAGER
QUI$_MANAGER_NODES Returns, as a comma separated list, the names of the nodes on which this queue manager runs. QUI$_DISPLAY_MANAGER
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.
QUI$_DISPLAY_MANAGER
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.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
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.
  • QUI$_DISPLAY_ENTRY
  • QUI$_DISPLAY_JOB
QUI$_OWNER_UIC Returns the owner UIC as a longword value in standard UIC format.
  • QUI$_DISPLAY_QUEUE
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. QUI$_DISPLAY_FORM
Retrieved from "https://wiki.vmssoftware.com/index.php?title=$GETQUI&oldid=1561"