HP OpenVMS System Services Reference Manual


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.

Required Access or Privileges

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

Required Quota

AST limit quota must be sufficient.

Related Services

$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


Condition Values Returned

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.

Condition Values Returned in the I/O Status Block

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.

Examples

#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.


$GETQUIW

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, see the description of $GETQUI in this manual.

For additional information about system service completion, see the Synchronize ($SYNCH) service.


Format

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


C Prototype

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


$GETRMI

Returns system performance information about the local system. $GETRMI is an asynchronous system service and requires the $SYNCH service or another wait-state synchronous mechanism to guarantee that the required information is available. There is no synchronous wait form for this system service.

For additional information about system service completion, see the Synchronize ($SYNCH) service.


Format

SYS$GETRMI [efn] [,nullarg] [,nullarg] ,itmlst [,iosb] [,astadr] [,astprm]


C Prototype

int sys$getrmi (unsigned int efn, unsigned int nullarg, unsigned int nullarg, 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 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 HP.

nullarg


OpenVMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value

Placeholding argument reserved to HP.

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.

iosb


OpenVMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference

I/O status block to receive the final completion status. The iosb argument is the address of the quadword I/O status block.

astadr


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference

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

astprm


OpenVMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value

AST parameter to be passed to the AST service routine specified by the astadr argument.

Item Codes

RMI$_ACCESS

Returns the count of file name lookup operations in file directories.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_ACCLCK

Returns the systemwide count of access locks.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_ALLOC

Returns the number of QIO requests that caused allocation of disk space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_ARRLOCPK

Returns the accumulated systemwide count of arriving local DECnet packets.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_ARRTRAPK

Returns the accumulated systemwide count of arriving transit DECnet packets.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BADFLTS

Returns the accumulated systemwide count of bad-list faults.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BLKIN

Returns the accumulated systemwide count of blocking ASTs queued that originated on a remote system and were processed on the local system.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BLKLOC

Returns the accumulated systemwide count of blocking ASTs queued that originated and were processed on the local system.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BLKOUT

Returns the accumulated systemwide count of blocking ASTs queued that originated on the local system and were processed on a remote system.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BLKAST

Returns the number of blocking ASTs.

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/Os.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAG

Returns the number of buffer object physical pages currently allocated.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGPEAK

Returns the maximum number of buffer object physical pages currently allocated.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGS01

Returns the number of buffer object pages currently allocated in S0 and S1 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGS2

Returns the number of buffer object physical pages currently allocated in S2 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGMAXS01

Returns the available number of buffer object pages in S0 and S1 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGMAXS2

Returns the available number of buffer object pages in S2 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGPEAKS01

Returns the maximum number of buffer object pages currently allocated in S0 and S1 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPAGPEAKS2

Returns the maximum number of buffer object pages currently allocated in S2 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPGLTMAXS01

Returns the available number of buffer object pagelets in S0 and S1 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_BUFOBJPGLTMAXS2

Returns the available number of buffer object pagelets in S2 space.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_CEF

Returns the number of processes in the common event flag wait state.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_COLPG

Returns the number of processes in the collided page wait state.

Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

RMI$_COM

Returns the number of processes in the computable state.


Previous Next Contents Index