| Previous | Contents | Index |
The $GETQUI item codes and function codes can be specific to the type and class of the queue. For example, QUI$_LAST_PAGE applies only in the context of a printer or terminal execution queue, and QUI$_LOG_SPECIFICATION applies only to batch files.
The following information shows the two classes and the various types of queues, while the descriptions of the individual $GETQUI item codes and function codes indicate the associated queue class and queue type requirements:
The following table lists the Execution queue types:
| Type | Description |
|---|---|
| Batch execution queues | Batch execution queues accept only batch jobs. |
| Output execution queues |
Output execution queues accept jobs that a symbiont processes, and
include the following types:
|
The following table lists the Generic queue types:
| Type | Description |
|---|---|
| Generic batch queues | Generic batch queues direct jobs only to batch execution queues. |
| Generic output queues | Generic output queues direct jobs to any of the three types of output execution queues: print, terminal, or server. |
| Logical queues | Logical queues are a special type of generic output queue that transfers jobs to another output execution queue. |
For additional information, see the HP OpenVMS System Manager's Manual, Volume 1: Essentials.
You can specify the following function codes to return information for the object types listed:
| Function Code | Object Type |
|---|---|
| QUI$_DISPLAY_CHARACTERISTIC | Characteristic |
| QUI$_DISPLAY_FORM | Form |
| QUI$_DISPLAY_QUEUE | Queue |
| QUI$_DISPLAY_MANAGER | Queue manager |
| QUI$_DISPLAY_JOB | Job within a queue context |
| QUI$_DISPLAY_FILE | File within a job context |
| QUI$_DISPLAY_ENTRY | Job independent of queue |
Maintaining Context Across $GETQUI Calls
When you call the $GETQUI service, the queue manager establishes an internal GETQUI context block (GQC). The system uses the GQC to store information temporarily and to keep track of its place in a wildcard sequence of operations. The system provides any number of GQC blocks per process.
To allow you to obtain information either about a particular object in a single call or about several objects in a sequence of calls, $GETQUI supports three different search modes. The following search modes affect the disposition of the GQC in different ways:
The sections that follow describe how each of the three search methods affects $GETQUI's search for information; how you direct $GETQUI to undertake each method; and how each method affects the contents of the GQC.
In nonwildcard mode, $GETQUI can return information about the following objects:
To obtain information about a specific characteristic or form definition, you call $GETQUI using the QUI$_DISPLAY_CHARACTERISTIC or QUI$_DISPLAY_FORM function code. You need to specify either the name of the characteristic or form in the QUI$_SEARCH_NAME item code or the number of the characteristic or form in the QUI$_SEARCH_NUMBER item code. The name string you specify cannot include either of the wildcard characters (* or %). You can specify both the QUI$_SEARCH_NAME and QUI$_SEARCH_NUMBER item codes, but the name and number you specify must be associated with the same characteristic or form definition.
To obtain information about a specific queue definition, you specify the QUI$_DISPLAY_QUEUE function code and provide the name of the queue in the QUI$_SEARCH_NAME item code. The name string you specify cannot include the wildcard characters (* or %).
To obtain information about a specific queue manager, specify the QUI$_DISPLAY_MANAGER function code and provide the name of the queue manager in the QUI$_SEARCH_NAME item code. The name string you specify cannot include the wildcard characters (* or %).
To obtain information about a specific batch or print job, specify the QUI$_DISPLAY_ENTRY function code and provide the entry number of the job in the QUI$_SEARCH_NUMBER item code.
Finally, the $GETQUI service provides an option that allows a batch job to obtain information about the queue, job, or command file that the associated batch job is executing without first entering wildcard mode to establish a queue or job context. You can make a call from the batch job that specifies the QUI$_DISPLAY_QUEUE function code to obtain information about the queue from which the batch job was initiated; the QUI$_DISPLAY_JOB function code to obtain information about the batch job itself; or the QUI$_DISPLAY_FILE function code to obtain information about the command file for the batch job. For each of these calls, you must select the QUI$V_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code. When you select this option, $GETQUI ignores all other options in the QUI$_SEARCH_FLAGS item code.
In wildcard mode, the system saves the GQC between calls to $GETQUI so that you can make a sequence of calls to $GETQUI to get information about all characteristics, forms, queues, jobs, or queue managers contained in the queue database.
You can have several streams of operations open at one time. To use a stream, specify a unique longword value for the context argument for every call associated with that stream. If you do not specify the context argument, then context #0 will be used.
To set up a wildcard search for characteristic or form definitions, specify the QUI$_DISPLAY_CHARACTERISTIC or QUI$_DISPLAY_FORM function code and specify a name in the QUI$_SEARCH_NAME item code that includes one or more wildcard characters (* or %).
To set up a wildcard search for queues, use the QUI$_DISPLAY_QUEUE function code and specify a name in the QUI$_SEARCH_NAME item code that includes one or more wildcard characters (* or %). You can indicate the type of the queue you want to search for by specifying any combination of the following options for the QUI$_SEARCH_FLAGS item code:
QUI$V_SEARCH_BATCH
QUI$V_SEARCH_PRINTER
QUI$V_SEARCH_SERVER
QUI$V_SEARCH_TERMINAL
QUI$V_SEARCH_SYMBIONT
QUI$V_SEARCH_GENERIC
For example, if you select the QUI$V_SEARCH_BATCH option, $GETQUI returns information only about batch queues; if you select the QUI$V_SEARCH_SYMBIONT option, $GETQUI returns information only about output queues (printer, terminal, and server queues). If you specify none of the queue type options, $GETQUI searches all queues.
To set up a wildcard search for queue managers, specify the QUI$_DISPLAY_MANAGER function code and specify a name in the QUI$_SEARCH_NAME item code that includes one or more wildcard characters (* or %).
To set up a wildcard search for jobs, specify the QUI$_DISPLAY_ENTRY function code and the QUI$_SEARCH_WILDCARD option of the QUI$_SEARCH_FLAGS item code. When you specify this option, omit the QUI$_SEARCH_NUMBER item code. You can restrict the search to jobs having particular status or to jobs residing in specific types of queues, or both, by including any combination of the following options for the QUI$_SEARCH_FLAGS item code:
QUI$V_SEARCH_BATCH
QUI$V_SEARCH_EXECUTING_JOBS
QUI$V_SEARCH_HOLDING_JOBS
QUI$V_SEARCH_PENDING_JOBS
QUI$V_SEARCH_PRINTER
QUI$V_SEARCH_RETAINED_JOBS
QUI$V_SEARCH_SERVER
QUI$V_SEARCH_SYMBIONT
QUI$V_SEARCH_TERMINAL
QUI$V_SEARCH_TIMED_RELEASE_JOBS
You can also force wildcard mode for characteristic, form, or queue display operations by specifying the QUI$V_SEARCH_WILDCARD option of the QUI$_SEARCH_FLAGS item code. If you specify this option, the system saves the GQC between calls, even if you specify a nonwildcard name in the QUI$_SEARCH_NAME item code. Whether or not you specify a wildcard name in the QUI$_SEARCH_NAME item code, selecting the QUI$V_SEARCH_WILDCARD option ensures that wildcard mode is enabled.
Once established, wildcard mode remains in effect until one of the following actions causes the GQC to be released:
Note that wildcard mode is a prerequisite for entering nested wildcard mode.
In nested wildcard mode, the system saves the GQC between calls to $GETQUI so that you can make a sequence of calls to $GETQUI to get information about jobs that are contained in a selected queue or files of the selected job. Nested wildcard mode reflects the parent-child relationship between queues and jobs and between jobs and files. The $GETQUI service can locate and return information about only one object in a single call; however, queues are objects that contain jobs and jobs are objects that contain files. Therefore, to get information about an object contained within another object, you must first make a call to $GETQUI that specifies and locates the containing object and then make a call to request information about the contained object. The system saves the location of the containing object in the GQC along with the location of the contained object.
Note that the context number specified in the context argument must remain the same for each level of nesting.
Two of $GETQUI's operations, QUI$_DISPLAY_JOB and QUI$_DISPLAY_FILE, can be used only in a nested wildcard mode, with one exception. The exceptional use of these two operations involves calls made to $GETQUI from a batch job to find out more information about itself. This exceptional use is described at the end of the Nonwildcard Mode section.
You can enter nested wildcard mode from either wildcard display queue mode or from wildcard display entry mode. To obtain job and file information in nested wildcard mode, you can use a combination of QUI$_DISPLAY_QUEUE, QUI$_DISPLAY_JOB, and QUI$_DISPLAY_FILE operations. To obtain file information, you can use a combination of QUI$_DISPLAY_ENTRY and QUI$_DISPLAY_FILE operations as an alternative.
To set up a nested wildcard search for job and file information, you first perform one or more QUI$_DISPLAY_QUEUE operations in wildcard mode to establish the queue context necessary for the nested display job and file operations. Next you specify the QUI$_DISPLAY_JOB operation repetitively; these calls search the current queue until a call locates the job that contains the file or files you want. This call establishes the job context. Having located the queue and the job that contain the file or files, you can now use the QUI$_DISPLAY_FILE operation repetitively to request file information.
You can enter the nested wildcard mode for the display queue operation in two different ways: by specifying a wildcard name in the QUI$_SEARCH_NAME item code or by specifying a nonwildcard queue name and selecting the QUI$V_SEARCH_WILDCARD option of the QUI$_SEARCH_FLAG item code. The second method of entering wildcard mode is useful if you want to obtain information about one or more jobs or files within jobs for a specific queue and want to specify a nonwildcard queue name but still want to save the GQC after the queue context is established.
When you make calls to $GETQUI that specify the QUI$_DISPLAY_JOB function code, by default $GETQUI locates all the jobs in the selected queue that have the same user name as the calling process. If you want to obtain information about all the jobs in the selected queue, you select the QUI$V_SEARCH_ALL_JOBS option of the QUI$_SEARCH_FLAGS item code.
After you establish a queue context, it remains in effect until you either change the context by making another call to $GETQUI that specifies the QUI$_DISPLAY_QUEUE function code or until one of the actions listed at the end of the Wildcard Mode section causes the GQC to be released. An established job context remains in effect until you change the context by making another call to $GETQUI that specifies the QUI$_DISPLAY_JOB function code or $GETQUI returns a JBC$_NOMOREJOB or JBC$_NOSUCHJOB condition value. While the return of either of these two condition values releases the job context, the wildcard search remains in effect because the GQC continues to maintain the queue context. Similarly, return of the JBC$_NOMOREFILE or JBC$_NOSUCHFILE condition value signals that no more files remain in the current job context; however, these condition values do not cause the job context to be dissolved.
To set up a nested wildcard search for file information for a particular entry, you first perform one or more QUI$_DISPLAY_ENTRY operations in wildcard mode to establish the desired job context. Next you call $GETQUI iteratively with the QUI$_DISPLAY_FILE function code to obtain file information for the selected job.
When you make calls to $GETQUI that specify the QUI$_DISPLAY_ENTRY function code, by default $GETQUI locates all jobs that have the same user name as the calling process. If you want to obtain information about jobs owned by another user, you specify the user name in the QUI$_SEARCH_USERNAME item code.
You can use the QUI$_SEARCH_FREEZE_CONTEXT option of the QUI$_SEARCH_FLAGS item code in any wildcard or nested wildcard call to prevent advancement of context to the next object on the list. This allows you to make successive calls for information about the same queue, job, file, characteristic, or form.
The caller must have manage (M) access to the queue, read (R) access to the job, or SYSPRV or OPER privilege to obtain job and file information.
If the caller does not have the privilege required to access a job specified in a QUI$_DISPLAY_JOB or QUI$_DISPLAY_FILE operation, $GETQUI returns a successful condition value. However, it sets the QUI$V_JOB_INACCESSIBLE bit of the QUI$_JOB_STATUS item code and returns information only for the following item codes:
QUI$_AFTER_TIME
QUI$_COMPLETED_BLOCKS
QUI$_ENTRY_NUMBER
QUI$_INTERVENING_BLOCKS
QUI$_INTERVENING_JOBS
QUI$_JOB_SIZE
QUI$_JOB_STATUS
AST limit quota must be sufficient.
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR, $TRNLNM
SS$_NORMAL The service completed successfully. SS$_ACCVIO The item list or input buffer cannot be read by the caller; or the return length buffer, output buffer, or status block cannot be written by the caller. SS$_BADCONTEXT Context does not exist or must be called from a more privileged mode. SS$_BADPARAM The function code is invalid; the item list contains an invalid item code; a buffer descriptor has an invalid length; or the reserved parameter has a nonzero value. SS$_DEVOFFLINE The job controller process is not running. SS$_EXASTLM The astadr argument was specified, and the process has exceeded its ASTLM quota. SS$_ILLEFC The efn argument specifies an illegal event flag number. SS$_INSFMEM The space for completing the request is insufficient. SS$_MBFULL The job controller mailbox is full. SS$_IVLOGNAM The device name string has a length of 0 or has more than 63 characters. SS$_MBTOOSML The mailbox message is too large for the job controller mailbox. SS$_UNASEFC The efn argument specifies an unassociated event flag cluster.
JBC$_NORMAL The service completed successfully. JBC$_INVFUNCOD The specified function code is invalid. JBC$_INVITMCOD The item list contains an invalid item code. JBC$_INVPARLEN The length of a specified string is outside the valid range for that item code. JBC$_INVQUENAM The queue name is not syntactically valid. JBC$_JOBQUEDIS The request cannot be executed because the system job queue manager has not been started. JBC$_MISREQPAR An item code that is required for the specified function code has not been specified. JBC$_NOJOBCTX No job context has been established for a QUI$_DISPLAY_FILE operation. JBC$_NOMORECHAR No more characteristics are defined, which indicates the termination of a QUI$_DISPLAY_CHARACTERISTIC wildcard operation. JBC$_NOMOREENT There are no more job entries for the specified user or current user name, which indicates termination of a QUI$_DISPLAY_ENTRY wildcard operation. JBC$_NOMOREFILE No more files are associated with the current job context, which indicates the termination of a QUI$_DISPLAY_FILE wildcard operation for the current job context. JBC$_NOMOREFORM No more forms are defined, which indicates the termination of a QUI$_DISPLAY_FORM wildcard operation. JBC$_NOMOREJOB No more jobs are associated with the current queue context, which indicates the termination of a QUI$_DISPLAY_JOB wildcard operation for the current queue context. JBC$_NOMOREQMGR No more queue managers are defined, which indicates the termination of a QUI$_DISPLAY_MANAGER wildcard operation. JBC$_NOMOREQUE No more queues are defined, which indicates the termination of a QUI$_DISPLAY_QUEUE wildcard operation. JBC$_NOQUECTX No queue context has been established for a QUI$_DISPLAY_JOB or QUI$_DISPLAY_FILE operation. JBC$_NOSUCHCHAR The specified characteristic does not exist. JBC$_NOSUCHENT There is no job with the specified entry number, or there is no job for the specified user or current user name. JBC$_NOSUCHFILE The specified file does not exist. JBC$_NOSUCHFORM The specified form does not exist. JBC$_NOSUCHJOB The specified job does not exist. JBC$_NOSUCHQMGR The specified queue manager does not exist. JBC$_NOSUCHQUE The specified queue does not exist.
| #1 |
|---|
! Declare system service related symbols
INTEGER*4 SYS$GETQUIW,
2 LIB$MATCH_COND,
2 STATUS
INCLUDE '($QUIDEF)'
! Define item list structure
STRUCTURE /ITMLST/
UNION
MAP
INTEGER*2 BUFLEN, ITMCOD
INTEGER*4 BUFADR, RETADR
END MAP
MAP
INTEGER*4 END_LIST
END MAP
END UNION
END STRUCTURE
! Define I/O status block structure
STRUCTURE /IOSBLK/
INTEGER*4 STS, ZEROED
END STRUCTURE
! Declare $GETQUIW item list and I/O status block
RECORD /ITMLST/ GETQUI_LIST(4)
RECORD /IOSBLK/ IOSB
! Declare variables used in $GETQUIW item list
CHARACTER*31 QUEUE_NAME
INTEGER*2 QUEUE_NAME_LEN
INTEGER*4 SEARCH_FLAGS,
2 ENTRY_NUMBER
! Initialize item list
GETQUI_LIST(1).BUFLEN = 4
GETQUI_LIST(1).ITMCOD = QUI$_SEARCH_FLAGS
GETQUI_LIST(1).BUFADR = %LOC(SEARCH_FLAGS)
GETQUI_LIST(1).RETADR = 0
GETQUI_LIST(2).BUFLEN = 4
GETQUI_LIST(2).ITMCOD = QUI$_ENTRY_NUMBER
GETQUI_LIST(2).BUFADR = %LOC(ENTRY_NUMBER)
GETQUI_LIST(2).RETADR = 0
GETQUI_LIST(3).BUFLEN = 31
GETQUI_LIST(3).ITMCOD = QUI$_QUEUE_NAME
GETQUI_LIST(3).BUFADR = %LOC(QUEUE_NAME)
GETQUI_LIST(3).RETADR = %LOC(QUEUE_NAME_LEN)
GETQUI_LIST(4).END_LIST = 0
SEARCH_FLAGS = QUI$M_SEARCH_THIS_JOB
! Call $GETQUIW service to obtain job information
STATUS = SYS$GETQUIW (,
2 %VAL(QUI$_DISPLAY_JOB),,
2 GETQUI_LIST,
2 IOSB,,)
IF (LIB$MATCH_COND (IOSB.STS, %LOC(JBC$_NOSUCHJOB))) THEN
! The search_this_job option can be used only by
! a batch job to obtain information about itself
TYPE *, '<<< this job is not being run in batch mode>>>'
ENDIF
IF (STATUS) STATUS = IOSB.STS
IF (STATUS) THEN
! Display information
TYPE *, 'Job entry number = ', ENTRY_NUMBER
TYPE *, 'Queue name = ', QUEUE_NAME(1:QUEUE_NAME_LEN)
ELSE
! Signal error condition
CALL LIB$SIGNAL (%VAL(STATUS))
ENDIF
END
|
This Fortran program demonstrates how a batch job can obtain information about itself from the system job queue file by using the $GETQUIW system service. Use of the QUI$M_SEARCH_THIS_JOB option in the QUI$_SEARCH_FLAGS input item requires that the calling program run as a batch job; otherwise, the $GETQUIW service returns a JBC$_NOSUCHJOB error.
| #2 |
|---|
! Declare system service related symbols
INTEGER*4 SYS$GETQUIW,
2 STATUS_Q,
2 STATUS_J,
2 NOACCESS
INCLUDE '($QUIDEF)'
! Define item list structure
STRUCTURE /ITMLST/
UNION
MAP
INTEGER*2 BUFLEN, ITMCOD
INTEGER*4 BUFADR, RETADR
END MAP
MAP
INTEGER*4 END_LIST
END MAP
END UNION
END STRUCTURE
! Define I/O status block structure
STRUCTURE /IOSBLK/
INTEGER*4 STS, ZEROED
END STRUCTURE
! Declare $GETQUIW item lists and I/O status block
RECORD /ITMLST/ QUEUE_LIST(4)
RECORD /ITMLST/ JOB_LIST(6)
RECORD /IOSBLK/ IOSB
! Declare variables used in $GETQUIW item lists
CHARACTER*31 SEARCH_NAME
CHARACTER*31 QUEUE_NAME
CHARACTER*39 JOB_NAME
CHARACTER*12 USERNAME
INTEGER*2 SEARCH_NAME_LEN,
2 QUEUE_NAME_LEN,
2 JOB_NAME_LEN,
2 USERNAME_LEN
INTEGER*4 SEARCH_FLAGS,
2 JOB_SIZE,
2 JOB_STATUS
! Solicit queue name to search; it may be a wildcard name
TYPE 9000
ACCEPT 9010, SEARCH_NAME_LEN, SEARCH_NAME
! Initialize item list for the display queue operation
QUEUE_LIST(1).BUFLEN = SEARCH_NAME_LEN
QUEUE_LIST(1).ITMCOD = QUI$_SEARCH_NAME
QUEUE_LIST(1).BUFADR = %LOC(SEARCH_NAME)
QUEUE_LIST(1).RETADR = 0
QUEUE_LIST(2).BUFLEN = 4
QUEUE_LIST(2).ITMCOD = QUI$_SEARCH_FLAGS
QUEUE_LIST(2).BUFADR = %LOC(SEARCH_FLAGS)
QUEUE_LIST(2).RETADR = 0
QUEUE_LIST(3).BUFLEN = 31
QUEUE_LIST(3).ITMCOD = QUI$_QUEUE_NAME
QUEUE_LIST(3).BUFADR = %LOC(QUEUE_NAME)
QUEUE_LIST(3).RETADR = %LOC(QUEUE_NAME_LEN)
QUEUE_LIST(4).END_LIST = 0
! Initialize item list for the display job operation
JOB_LIST(1).BUFLEN = 4
JOB_LIST(1).ITMCOD = QUI$_SEARCH_FLAGS
JOB_LIST(1).BUFADR = %LOC(SEARCH_FLAGS)
JOB_LIST(1).RETADR = 0
JOB_LIST(2).BUFLEN = 4
JOB_LIST(2).ITMCOD = QUI$_JOB_SIZE
JOB_LIST(2).BUFADR = %LOC(JOB_SIZE)
JOB_LIST(2).RETADR = 0
JOB_LIST(3).BUFLEN = 39
JOB_LIST(3).ITMCOD = QUI$_JOB_NAME
JOB_LIST(3).BUFADR = %LOC(JOB_NAME)
JOB_LIST(3).RETADR = %LOC(JOB_NAME_LEN)
JOB_LIST(4).BUFLEN = 12
JOB_LIST(4).ITMCOD = QUI$_USERNAME
JOB_LIST(4).BUFADR = %LOC(USERNAME)
JOB_LIST(4).RETADR = %LOC(USERNAME_LEN)
JOB_LIST(5).BUFLEN = 4
JOB_LIST(5).ITMCOD = QUI$_JOB_STATUS
JOB_LIST(5).BUFADR = %LOC(JOB_STATUS)
JOB_LIST(5).RETADR = 0
JOB_LIST(6).END_LIST = 0
! Request search of all jobs present in output queues; also force
! wildcard mode to maintain the internal search context block after
! the first call when a non-wild queue name is entered--this preserves
! queue context for the subsequent display job operation
SEARCH_FLAGS = (QUI$M_SEARCH_WILDCARD .OR.
2 QUI$M_SEARCH_SYMBIONT .OR.
2 QUI$M_SEARCH_ALL_JOBS)
! Dissolve any internal search context block for the process
STATUS_Q = SYS$GETQUIW (,%VAL(QUI$_CANCEL_OPERATION),,,,,)
! Locate next output queue; loop until an error status is returned
DO WHILE (STATUS_Q)
STATUS_Q = SYS$GETQUIW (,
2 %VAL(QUI$_DISPLAY_QUEUE),,
2 QUEUE_LIST,
2 IOSB,,)
IF (STATUS_Q) STATUS_Q = IOSB.STS
IF (STATUS_Q) TYPE 9020, QUEUE_NAME(1:QUEUE_NAME_LEN)
STATUS_J = 1
! Get information on next job in queue; loop until error return
DO WHILE (STATUS_Q .AND. STATUS_J)
STATUS_J = SYS$GETQUIW (,
2 %VAL(QUI$_DISPLAY_JOB),,
2 JOB_LIST,
2 IOSB,,)
IF (STATUS_J) STATUS_J = IOSB.STS
IF ((STATUS_J) .AND. (JOB_SIZE .GE. 500)) THEN
NOACCESS = (JOB_STATUS .AND. QUI$M_JOB_INACCESSIBLE)
IF (NOACCESS .NE. 0) THEN
TYPE 9030, JOB_SIZE
ELSE
TYPE 9040, JOB_SIZE,
2 USERNAME(1:USERNAME_LEN),
2 JOB_NAME(1:JOB_NAME_LEN)
ENDIF
ENDIF
ENDDO
ENDDO
9000 FORMAT (' Enter queue name to search: ', $)
9010 FORMAT (Q, A31)
9020 FORMAT ('0Queue name = ', A)
9030 FORMAT (' Job size = ', I5, ' <no read access privilege>')
9040 FORMAT (' Job size = ', I5,
2 ' Username = ', A, T46,
2 ' Job name = ', A)
END
|
Previous Next Contents Index