Document revision date: 15 July 2002 | |
Previous | Contents | Index |
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 |
This Fortran program demonstrates how any job can obtain information about other jobs from the system job queue file by using the $GETQUIW system service. This program lists all print jobs in output queues with a job size of 500 blocks or more. It also displays queue name, job size, user name, and job name information for each job listed.
Returns information about queues and jobs initiated from those queues. The $SNDJBC service is the major interface to the Job Controller, which is the queue and accounting manager. For a discussion of the different types of job and queue, see the Description section of $SNDJBC.The $GETQUIW service completes synchronously; that is, it returns to the caller with the requested information. For asynchronous completion, use the Get Queue Information ($GETQUI) service; $GETQUI returns to the caller after queuing the information request, without waiting for the information to be returned.
In all other respects, $GETQUIW is identical to $GETQUI. For more information about $GETQUIW, refer to the description of $GETQUI in this manual.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.
SYS$GETQUIW [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]
int sys$getquiw (unsigned int efn, unsigned short int func, unsigned int *context, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);
Returns system performance information about the local system.
SYS$GETRMI [efn] [,nullarg] [,nullarg] ,itmlst [,iosb] [,astadr] [,astprm]
int sys$getrmi (unsigned int efn, unsigned int nullarg, unsigned int nullarg, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of event flag to be set when the $GETRMI request completes. The efn argument is a longword containing this number; however, $GETRMI uses only the low order byte.nullarg
OpenVMS usage: null_arg type: longword (unsigned) access: read only mechanism: by value
Placeholding argument reserved to Compaq.nullarg
OpenVMS usage: null_arg type: longword (unsigned) access: read only mechanism: by value
Placeholding argument reserved to Compaq.itmlst
OpenVMS usage: item_list_3 type: longword (unsigned) access: read only mechanism: by reference
Item list specifying which information is to be returned about the local node. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of descriptors is terminated by a longword of 0.The following diagram depicts the structure of a single item descriptor:
The following table defines the item descriptor fields:
Descriptor Field | Definition |
---|---|
Buffer length | A word containing a user supplied integer specifying the length (in bytes) of the buffer in which $GETRMI is to write the information. The length of the buffer needed depends upon the item code specified in the item code field. If the buffer length is too small, $GETRMI truncates the data. |
Item code | A word containing a user-supplied code specifying the item of information that $GETRMI is to return. The RMIDEF macro defines these codes. A description of each item code is given in the item codes section. |
Buffer address | A longword containing the user-supplied address of a buffer in which $GETRMI returns the requested information. |
Return length address | A longword containing the user-supplied address of a word in which $GETRMI writes the length in bytes of the information returned. |
OpenVMS usage: | io_status_block |
type: | quadword (unsigned) |
access: | write only |
mechanism: | by reference |
OpenVMS usage: | ast_procedure |
type: | procedure value |
access: | call without stack unwinding |
mechanism: | by reference |
OpenVMS usage: | user_arg |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
RMI$_BLKAST
Returns the number of blocking ast's.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_BUFIO
Returns the number of buffered I/O'sBecause this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_DEQ
Returns the number of DEQ operations.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_DIRIO
Returns the number of direct I/O'sBecause this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_DLCKSRCH
Returns the number of deadlock searches.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_DLCKFND
Returns the number of deadlocks found.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_DZROFLTS
Returns the number of demand zero page faults.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_ENQCVT
Returns the number of ENQ conversion operations.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_ENQNEW
Returns the number of new ENQ operations.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_ENQNOTQD
Returns the number of ENQ operations not queued.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_ENQWAIT
Returns the number of ENQ operations forced to wait.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FAULTS
Returns the number of page faults since last system initialization.This number is a longword, therefore the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPCALLS
Returns the total number of calls to the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPCACHE
Returns the total number of cache hits by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPCPU
Returns the total number of CPU tics used by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPFAULT
Returns the number of FCP page faults.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPHIT
Returns the total number of window hits tics used by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPREAD
Returns the total number of disk reads by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPSPLIT
Returns the number of split transfers performed by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FCPWRITE
Returns the total number of disk writes by the FCP.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FREFLTS
Returns the number of page faults from the free list.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_FRLIST
Returns the number of pages on the freelist.This number is a longword, therefore the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_GVALFLTS
Returns the number of global valid page faults.Because this number is a longword the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_ISWPCNT
Returns the number of process inswaps.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_LOGNAM
Returns the number of logical name translationsBecause this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_MBREADS
Returns the number of mailbox readsBecause this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_MBWRITES
Returns the number of mailbox writesBecause this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_MODLIST
Returns the number of pages on the modified page list.This number is a longword, therefore the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_MFYFLTS
Returns the number of page faults from the modified list.Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
RMI$_NUMLOCKS
Returns the total number of locks.
Previous Next Contents Index
privacy and legal statement 4527PRO_063.HTML