HP OpenVMS Systems Documentation

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.

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);

Returns system performance information about the local system.

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:

iosb

astadr

astprm

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.

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

RMI$_COMO

Returns the number of outswapped processes in the computable state.

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

RMI$_CPUEXEC

Returns the amount of time, in 10-millisecond units, spent by all CPUs in executive mode.

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

RMI$_CPUID

Returns the primary CPU ID.

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

RMI$_CPUIDLE

Returns the amount of time, in 10-millisecond units, spent by all CPUs in idle mode.

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

RMI$_CPUINTSTK

Returns the amount of time, in 10-millisecond units, spent by all CPUs in processing interrupts.

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

RMI$_CPUKERNEL

Returns the amount of time, in 10-millisecond units, spent by all CPUs in kernel mode.

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

RMI$_CPUMPSYNCH

Returns the amount of time, in 10-millisecond units, spent by the primary CPU in synchronization mode.

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

RMI$_CPUSUPER

Returns the amount of time, in 10-millisecond units, spent by all CPUs in supervisor mode.

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

RMI$_CPUUSER

Returns the amount of time, in 10-millisecond units, spent by all CPUs in user mode.

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

RMI$_CUR

Returns the number of currently-executing processes.

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

RMI$_CWPSBYTESIN

Returns the number of clusterwide process services (CWPS) message bytes received by the system.

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

RMI$_CWPSBYTESOUT

Returns the number of CWPS message bytes sent by the system.

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

RMI$_CWPSJPISIN

Returns the number of CWPS $GETJPI requests received by the system.

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

RMI$_CWPSJPISOUT

Returns the number of CWPS $GETJPI requests sent by the system.

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

RMI$_CWPSMSGSIN

Returns the number of CWPS messages received by the system.

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

RMI$_CWPSMSGSOUT

Returns the number of CWPS messages sent by the system.

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

RMI$_CWPSPCNTRLIN

Returns the number of CWPS PCNTRL requests received by the system.

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

RMI$_CWPSPCNTRLOUT

Returns the number of CWPS PCNTRL requests sent by the system.

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

RMI$_CWPSRSRCIN

Returns the number of CWPS resource-fail messages received by the system.

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

RMI$_CWPSRSRCOUT

Returns the number of CWPS resource-fail messages sent by the system.

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

RMI$_DDTM_ABORTS

Returns the accumulated systemwide count of transactions aborted (planned and unplanned).

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

RMI$_DDTM_ADDS

Returns the accumulated systemwide count of transaction branches added on the local node.

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

RMI$_DDTM_BAD_LINKS

Returns the total number of bad message links received.

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

RMI$_DDTM_BAD_PARTS

Returns the number of invalid part IDs found.

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

RMI$_DDTM_BAD_TYPECODE

Returns the total number of bad message type codes received.

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

RMI$_DDTM_BRANCHS

Returns the accumulated systemwide count of transaction branches started on the local node.

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

RMI$_DDTM_BUCKETS1

Returns the accumulated systemwide count of transactions with a duration of less than 1 second.

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

RMI$_DDTM_BUCKETS2

Returns the accumulated systemwide count of transactions with a duration of 1 to 2 (1.99) seconds.

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

RMI$_DDTM_BUCKETS3

Returns the accumulated systemwide count of transactions with a duration of 2 to 3 (2.99) seconds.

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

RMI$_DDTM_BUCKETS4

Returns the accumulated systemwide count of transactions with a duration of 3 to 4 (3.99) seconds.

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

RMI$_DDTM_BUCKETS5

Returns the accumulated systemwide count of transactions with a duration of 4 to 5 (4.99) seconds.

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

RMI$_DDTM_BUCKETS6

Returns the accumulated systemwide count of transactions with a duration of at least 5 seconds.

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

RMI$_DDTM_DECLARES

Returns the total number of $DECLARE_RMs.

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

RMI$_DDTM_DISC_COMP

Returns the number of disconnected complete events.

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

RMI$_DDTM_ENDS

Returns the accumulated systemwide count of transactions ended.

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

RMI$_DDTM_FOR_UNLINKS

Returns the number of forced unlinks.

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

RMI$_DDTM_FORGETS

Returns the total number of $FORGET_RMs.

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

RMI$_DDTM_JOINS

Returns the total number of $JOIN_RMs.

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

RMI$_DDTM_LOG_COMMITS

Returns the total number of commit records written.

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

RMI$_DDTM_LOG_FORGETS

Returns the total number of forget records written.

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

RMI$_DDTM_LOG_PREPARES

Returns the total number of prepare records written.

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

RMI$_DDTM_ONE_PHASE

Returns the accumulated systemwide count of 1-phase commit events initiated.

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

RMI$_DDTM_PREPARES

Returns the accumulated systemwide count of transactions that have been prepared.

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

RMI$_DDTM_SEQNO

Returns the total number of XCBs created.

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

RMI$_DDTM_STARTS

Returns the accumulated systemwide count of transactions successfully started.

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

RMI$_DDTM_TWOPHASE_ACKRCV

Returns the accumulated systemwide count of 2-phase commit ACK messages received.

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

RMI$_DDTM_TWOPHASE_ACKSNT

Returns the accumulated systemwide count of 2-phase commit ACK messages sent.

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

RMI$_DDTM_TWOPHASE_CANRCV

Returns the accumulated systemwide count of 2-phase commit cancel messages received.

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

RMI$_DDTM_TWOPHASE_CANSNT

Returns the accumulated systemwide count of 2-phase commit cancel messages sent.

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

RMI$_DDTM_TWOPHASE_COMMITS

Returns the accumulated systemwide count of 2-phase commit events initiated.

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

RMI$_DDTM_TWOPHASE_RDYRCV

Returns the accumulated systemwide count of 2-phase commit ready messages received.

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

RMI$_DDTM_TWOPHASE_RDYSNT

Returns the accumulated systemwide count of 2-phase commit ready messages sent.

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

RMI$_DDTM_TWOPHASE_REQRCV

Returns the accumulated systemwide count of 2-phase commit requests received.

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

RMI$_DDTM_TWOPHASE_REQSNT

Returns the accumulated systemwide count of 2-phase commit requests sent.

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

RMI$_DDTM_VOL_UNLINKS

Returns the number of voluntary unlinks.

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

RMI$_DDTM_WRITES_FORKED

Returns the total number of forked writes.

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

RMI$_DDTM_WRITES_STARTED

Returns the total number of writes started.

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

RMI$_DEPLOCPK

Returns the accumulated systemwide count of departing local DECnet packets.

Because 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$_DEQIN

Returns the accumulated systemwide count of unlock (dequeue) lock requests 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$_DEQLOC

Returns the accumulated systemwide count of unlock (dequeue) requests 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$_DEQOUT

Returns the accumulated systemwide count of unlock (dequeue) requests 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$_DIRDATA_HIT

Returns the systemwide count of directory data cache hits.

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

RMI$_DIRDATA_MISS

Returns the systemwide count of directory data cache misses.

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

RMI$_DIRFCB_HIT

Returns the systemwide count of directory FCB cache hits.

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

RMI$_DIRFCB_MISS

Returns the systemwide count of directory FCB cache misses.

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

RMI$_DIRIN

Returns the accumulated systemwide count of directory operations serviced by the local system that originated on remote systems.

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

RMI$_DIROUT

Returns the accumulated systemwide count of directory operations that originated on the local system and were serviced by remote systems.

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

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

RMI$_DLCK_INCMPLT

Returns the accumulated systemwide count of incomplete 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$_DLCKMSGS_IN

Returns the systemwide count of incoming deadlock detection messages.

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

RMI$_DLCKMSGS_OUT

Returns the accumulated systemwide count of outgoing deadlock detection messages.

Because 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$_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$_ENQCVTIN

Returns the accumulated systemwide count of lock conversion requests 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$_ENQCVTLOC

Returns the accumulated systemwide count of lock conversion requests 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$_ENQCVTOUT

Returns the accumulated systemwide count of lock conversion requests 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$_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$_ENQNEWIN

Returns the accumulated systemwide count of new lock requests 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$_ENQNEWLOC

Returns the accumulated systemwide count of new lock requests 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$_ENQNEWOUT

Returns the accumulated systemwide count of new lock requests 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$_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$_EXEFAULTS

Returns the number of execute page faults.

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

RMI$_EXTHIT

Returns the systemwide count of extent cache hits.

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

RMI$_EXTMISS

Returns the systemwide count of extent cache misses.

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.

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$_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$_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$_FCPCREATE

Returns the number of new files created since the system was booted.

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

RMI$_FCPERASE

Returns the number of erase I/O operations issued.

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 file I/O transfers for which no disk access was required.

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$_FCPTURN

Returns the number of file-map window misses.

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$_FIDHIT

Returns the systemwide count of File ID cache hits.

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

RMI$_FIDMISS

Returns the systemwide count of File ID cache misses.

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

RMI$_FILHDR_HIT

Returns the systemwide count of file header cache hits.

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

RMI$_FILHDR_MISS

Returns the systemwide count of file header cache misses.

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

RMI$_FPG

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

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 free list.

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

RMI$_GBP_CURMAP - Alpha Only

Returns the count of global pages currently mapped.

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

RMI$_GBP_CURMAP_GRP - Alpha Only

Returns the count of group global pages currently mapped.

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

RMI$_GBP_CURMAP_GRPWRT - Alpha Only

Returns the count of writable group global pages currently mapped.

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

RMI$_GBP_CURMAP_SYS - Alpha Only

Returns the count of system global pages currently mapped.

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

RMI$_GBP_CURMAP_SYSWRT - Alpha Only

Returns the count of writable system global pages currently mapped.

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

RMI$_GBP_MAXMAP - Alpha Only

Returns the maximum count of global pages simultaneously mapped.

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

RMI$_GBS_CURMAP - Alpha Only

Returns the count of global sections currently mapped.

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

RMI$_GBS_CURMAP_GRP - Alpha Only

Returns the count of group global sections currently mapped.

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

RMI$_GBS_CURMAP_GRPWRT - Alpha Only

Returns the count of writable group global sections currently mapped.

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

RMI$_GBS_CURMAP_SYS - Alpha Only

Returns the count of system global sections currently mapped.

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

RMI$_GBS_CURMAP_SYSWRT - Alpha Only

Returns the count of writable system global sections currently mapped.

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

RMI$_GBS_MAXMAP - Alpha Only

Returns the maximum count of global sections simultaneously mapped.

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

RMI$_GBS_NOREF - Alpha Only

Returns the current count of global sections not mapped to a process (reference count is 0).

Because this number is a longword, 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$_HDRINSWAPS

Returns the accumulated systemwide count of process header inswap operations.

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

RMI$_HDROUTSWAPS

Returns the accumulated systemwide count of process header outswap operations.

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

RMI$_HIB

Returns the number of processes in the hibernate state.

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

RMI$_HIBO

Returns the number of outswapped processes in the hibernate state.

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

RMI$_IOPAGCNT

Returns the systemwide count of pages in transit to disk from the modified page list.

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$_ISWPCNTPG

Returns the accumulated systemwide count of pages inswapped.

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

RMI$_LCKMGR_CPU

Returns the ID of the CPU on which the lock manager process runs.

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

RMI$_LCKMGR_PID

Returns the PID of the lock manager process.

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

RMI$_LCKMGR_REQCNT

Returns the accumulated count of requests handled by the lock manager.

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

RMI$_LCKMGR_REQTIME

Returns the accumulated time spent by the lock manager servicing requests.

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

RMI$_LCKMGR_SPINCNT

Returns the accumulated count of times the lock manager entered a spin loop.

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

RMI$_LCKMGR_SPINTIME

Returns the accumulated spin time, in cycles, of the lock manager.

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

RMI$_LEF

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

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

RMI$_LEFO

Returns the number of outswapped processes in the local event flag wait state.

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

RMI$_LOCK_MAX

Returns the lock ID table length.

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

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

RMI$_LPZ_ALLOC2

Returns the number of allocations from other than the first page of the lock manager's pool zone.

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

RMI$_LPZ_ALLOCF

Returns the number of failed allocations from the lock manager's pool zone.

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

RMI$_LPZ_EMPTY

Returns the number of empty pages in the lock manager's pool zone.

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

RMI$_LPZ_EXPCNT

Returns the accumulated number of expansions of the lock manager's pool zone.

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

RMI$_LPZ_HITS

Returns the number of hits for the lock manager's pool zone.

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

RMI$_LPZ_MAXPAG

Returns the maximum number of pages in the lock manager's pool zone.

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

RMI$_LPZ_MISSES

Returns the number of misses for the lock manager's pool zone.

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

RMI$_LPZ_PAGCNT

Returns the number of pages currently in the lock manager's pool zone.

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

RMI$_LPZ_PAKSIZ

Returns the packet size for the lock manager's pool zone.

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

RMI$_MBREADS

Returns the number of mailbox reads.

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

RMI$_MBWRITES

Returns the number of mailbox writes.

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

RMI$_MCHKERRS

Returns the accumulated count of machine checks since the system was booted.

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

RMI$_MEMERRS

Returns the accumulated count of memory errors since the system was booted.

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

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

RMI$_MSCP_EVERYTHING

Returns all the performance data items in the following order:

MSCP_BUFAVL	Current number of free MSCP buffers
MSCP_BUFSMALL	Smallest MSCP buffer size allowed
MSCP_BUFWAITCUR	Number of requests currently queued waiting for MSCP buffer memory
MSCP_BUFWAITPEAK	Maximum number of requests simultaneously queued waiting for MSCP buffer
MSCP_DSKSRV	Number of MSCP served disks
MSCP_HSTSRV	Number of MSCP served hosts
MSCP_LB_FAILCNT	MSCP server's count of failed load-balancing requests
MSCP_LB_INITCNT	MSCP server's count of load-balancing requests sent
MSCP_LB_LMLOAD1	MSCP server's previous interval's load 1 value
MSCP_LB_LMLOAD2	MSCP server's previous interval's load 2 value
MSCP_LB_LMLOAD3	MSCP server's previous interval's load 3 value
MSCP_LB_LMLOAD4	MSCP server's previous interval's load 4 value
MSCP_LB_LOAD	MSCP server's target load for load-balancing requests
MSCP_LB_LOAD_AVAIL	MSCP server's current load available value
MSCP_LB_LOAD_CAP	MSCP server's load capacity value
MSCP_LB_MONINT	MSCP server's load-monitoring interval size
MSCP_LB_MONTIME	The time that the last load-balancing monitor pass was made
MSCP_LB_REQCNT	MSCP server's count of load-balancing requests received from other servers
MSCP_LB_REQTIME	The time that the last load-balancing request was sent
MSCP_LB_RESPCNT	MSCP server's count of load-balancing requests to which it responded
MSCP_LB_RESP	MSCP server's load available from another server
MSCP_OPCOUNT	Count of I/O transfer requests by remote processors
MSCP_VCFAIL	Count of virtual cache failures on MSCP-served requests
MSCP_READ	Count of Read I/O transfer requests by remote processors
MSCP_WRITE	Count of Write I/O transfer requests by remote processors
MSCP_FRAGMENT	Count of extra fragments issued by the MSCP server
MSCP_SPLITXFER	Count of fragmented requests issued by the MSCP server
MSCP_BUFWAIT	Count of requests that had to wait for MSCP buffer memory
MSCP_SIZE1	Count of MSCP-served I/O requests with a length of 1 block
MSCP_SIZE2	Count of MSCP-served I/O requests with a length of 2-3 blocks
MSCP_SIZE3	Count of MSCP-served I/O requests with a length of 4-7 blocks
MSCP_SIZE4	Count of MSCP-served I/O requests with a length of 8-15 blocks
MSCP_SIZE5	Count of MSCP-served I/O requests with a length of 16-31 blocks
MSCP_SIZE6	Count of MSCP-served I/O requests with a length of 32-63 blocks
MSCP_SIZE7	Count of MSCP-served I/O requests with a length of 64 or more blocks

Because this an array of 35 longwords, the buffer length field in the item descriptor should specify 4 times 35 (bytes).

RMI$_MWAIT

Returns the number of processes in the miscellaneous resource wait state.

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

RMI$_NP_POOL_ALLOC

Returns the accumulated count of nonpaged pool allocation requests.

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

RMI$_NP_POOL_ALLOCF

Returns the accumulated count of unsuccessful nonpaged pool allocation requests.

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

RMI$_NP_POOL_EXP

Returns the accumulated count of successful expansions of nonpaged pool.

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

RMI$_NP_POOL_EXPF

Returns the accumulated count of unsuccessful attempts to expand nonpaged pool.

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.

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

RMI$_NUMRES

Returns the total number of resources.

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

RMI$_OPENS

Returns the systemwide count of files opened.

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

RMI$_OSWPCNT

Returns the accumulated systemwide count of process outswap operations.

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

RMI$_OSWPCNTPG

Returns the accumulated systemwide count of pages outswapped.

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

RMI$_PFW

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

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

RMI$_PG_POOL_ALLOC

Returns the accumulated count of paged pool allocation requests.

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

RMI$_PG_POOL_ALLOCF

Returns the accumulated count of unsuccessful paged pool allocation requests.

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

RMI$_PG_POOL_EXPF

Returns the accumulated count of paged pool failures.

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

RMI$_PREADIO

Returns physical page read I/Os.

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

RMI$_PREADS

Returns the number of pages read.

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

RMI$_PROCBALSETCNT

Returns the number of processes in the balance set.

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

RMI$_PROCBATCNT

Returns the number of batch processes known to the system.

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

RMI$_PROCCNTMAX

Returns the maximum number of concurrent processes seen by the system.

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

RMI$_PROCINTCNT

Returns the number of interactive processes known to the system.

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

RMI$_PROCLOADCNT

Returns the accumulated systemwide count of process context load operations.

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

RMI$_PROCNETCNT

Returns the number of network processes known to the system.

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

RMI$_PROCS

Returns the number of processes currently known to the system.

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

RMI$_PROCSWITCHCNT

Returns the number of switches from the currently-executing process.

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

RMI$_PWRITES

Returns the number of pages written.

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

RMI$_PWRITIO

Returns physical page write I/Os.

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

RMI$_QUOHIT

Returns the systemwide count of quota cache hits.

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

RMI$_QUOMISS

Returns the systemwide count of quota cache misses.

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

RMI$_RCVBUFFL

Returns the accumulated systemwide count of DECnet receiver buffer failures.

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

RMI$_RDFAULTS

Returns the number of fault-on-read page faults.

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

RMI$_RML_ACQUIRE

Returns the accumulated systemwide count of lock trees moved to this node.

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

RMI$_RML_BETTER

Returns the accumulated systemwide count of lock trees moved from this node to a cluster node with a higher value for the system parameter LOCKDIRWT.

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

RMI$_RML_MORE_ACT

Returns the accumulated systemwide count of lock trees moved from this node due to higher locking activity on another node in the cluster.

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

RMI$_RML_MSGRCV

Returns the accumulated systemwide count of remaster messages received by this node.

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

RMI$_RML_MSGSENT

Returns the accumulated systemwide count of remaster messages sent from this node.

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

RMI$_RML_NOQUOTA

Returns the accumulated systemwide count of remaster operations that failed due to a lack of quota.

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

RMI$_RML_NOTAKER

Returns the accumulated systemwide count of remaster operations that were proposed and declined.

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

RMI$_RML_OPCNT

Returns the accumulated systemwide count of remaster operations that have been completed.

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

RMI$_RML_RBLDMSGRCV

Returns the accumulated systemwide count of remaster rebuild messages received by this node.

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

RMI$_RML_RBLDMSGSENT

Returns the accumulated systemwide count of remaster rebuild messages sent from this node.

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

RMI$_RML_SINGLE

Returns the accumulated systemwide count of lock trees moved from this node to another cluster node because that node is the only one with locks remaining on the tree.

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

RMI$_RML_UNLOAD

Returns the accumulated systemwide count of lock trees moved from this node.

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

RMI$_SMP_CURMAP - Alpha Only

Returns the count of global pages currently mapped for Galaxy shared memory.

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

RMI$_SMP_CURMAP_GRP - Alpha Only

Returns the count of group global pages currently mapped for Galaxy shared memory.

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

RMI$_SMP_CURMAP_GRPWRT - Alpha Only

Returns the count of writable group global pages currently mapped for Galaxy shared memory.

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

RMI$_SMP_CURMAP_SYS - Alpha Only

Returns the count of system global pages currently mapped for Galaxy shared memory.

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

RMI$_SMP_CURMAP_SYSWRT - Alpha Only

Returns the count of writable system global pages currently mapped for Galaxy shared memory.

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

RMI$_SMS_CURMAP - Alpha Only

Returns the count of global sections currently mapped for Galaxy shared memory.

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

RMI$_SMS_CURMAP_GRP - Alpha Only

Returns the count of group global sections currently mapped for Galaxy shared memory.

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

RMI$_SMS_CURMAP_GRPWRT - Alpha Only

Returns the count of writable group global sections currently mapped for Galaxy shared memory.

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

RMI$_SMS_CURMAP_SYS - Alpha Only

Returns the count of system global sections currently mapped for Galaxy shared memory.

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

RMI$_SMS_CURMAP_SYSWRT - Alpha Only

Returns the count of writable system global sections currently mapped for Galaxy shared memory.

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

RMI$_SMS_NOREF - Alpha Only

Returns the current count of global sections for Galaxy shared memory that are not mapped to a process (reference count is 0).

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

RMI$_STORAGMAP_HIT

Returns the systemwide count of storage bitmap cache hits.

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

RMI$_STORAGMAP_MISS

Returns the systemwide count of storage bitmap cache misses.

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

RMI$_SUSP

Returns the number of processes in the suspended state.

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

RMI$_SUSPO

Returns the number of outswapped processes in the suspended state.

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

RMI$_SYNCHLCK

Returns the systemwide count of directory- or file-synch locks.

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

RMI$_SYNCHWAIT

Returns the systemwide count of times the XQP waited for a directory- or file-synch lock.

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

RMI$_SYSFAULTS

Returns the number of system page faults.

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

RMI$_TMSCP_EVERYTHING

Returns all the performance data items in the following order:

TMSCP_BUFWAIT	Count of requests that had to wait for TMSCP buffer memory
TMSCP_HSTSRV	Number of TMSCP served hosts
TMSCP_TAPSRV	Number of TMSCP served tapes
TMSCP_OPCOUNT	Total operations count
TMSCP_ABORTCNT	Total abort operations count
TMSCP_BUFAVAIL	Free TMSCP pool bytes
TMSCP_ONLINCNT	Count of online tapes
TMSCP_ACCESSCNT	Total access count
TMSCP_FLUSHCNT	Total flush count
TMSCP_RDCOUNT	Count of read I/O requests by remote processors
TMSCP_WRCOUNT	Count of write I/O requests by remote processors
TMSCP_VCFAIL	Number of virtual cache failures on TMSCP served requests in location 23
TMSCP_FRAGMENT	Extra fragments
TMSCP_SIZE1	Count of TMSCP served I/O requests with a length of 1 block
TMSCP_SIZE2	Count of TMSCP served I/O requests with a length of 2-3 blocks
TMSCP_SIZE3	Count of TMSCP served I/O requests with a length of 4-7 blocks
TMSCP_SIZE4	Count of TMSCP served I/O requests with a length of 8-15 blocks
TMSCP_SIZE5	Count of TMSCP served I/O requests with a length of 16-31 blocks
TMSCP_SIZE6	Count of TMSCP served I/O requests with a length of 32-63 blocks
TMSCP_SIZE7	Count of TMSCP served I/O requests with a length of 64 or more blocks

Because this is an array of 20 longwords, the buffer length field in the item descriptor should specify 4 times 20 (bytes).

RMI$_TQESYSUB

Returns the accumulated systemwide count of timer requests made by the OpenVMS operating system.

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

RMI$_TQETOTAL

Returns the accumulated systemwide count of timer requests.

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

RMI$_TQEUSRTIMR

Returns the accumulated systemwide count of timer requests made by application programs through the SYS$SETIMR system service.

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

RMI$_TQEUSRWAKE

Returns the accumulated systemwide count of timer requests made by application programs through the SYS$SCHDWK system service.

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

RMI$_TRANSFLTS

Returns the accumulated systemwide count of transition (release pending or read-in-progress) faults.

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

RMI$_TRCNGLOS

Returns the accumulated systemwide count of DECnet packets lost due to transit congestion.

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

RMI$_TTREADCNT

Returns the accumulated systemwide count of characters read from terminals.

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

RMI$_TTREADS

Returns the accumulated systemwide count of reads from terminals.

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

RMI$_TTWRITECNT

Returns the accumulated systemwide count of characters written to terminals.

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

RMI$_TTWRITES

Returns the accumulated systemwide count of writes to terminals.

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

RMI$_USERPAGES

Returns the number of pages available for use by applications.

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

RMI$_VCPUTICKS - VAX Only

Returns the accumulated systemwide count of virtual balance slot clock ticks (10-millisecond units).

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

RMI$_VMSPAGES

Returns the number of pages actually allocated to OpenVMS.

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

RMI$_VOLLCK

Returns the accumulated systemwide count of volume-synch locks.

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

RMI$_VOLWAIT

Returns the number of times the XQP entered a wait state due to volume lock contention.

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

RMI$_VRBS_TRAN - VAX Only

Returns the accumulated systemwide count of faults from virtual balance slots to real balance slots.

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

RMI$_WRTFAULTS

Returns the number of fault-on-write page faults.

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

RMI$_WRTINPROG

Returns the number of page faults from a write in progress.

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

RMI$_XQPCACHEWAIT

Returns the systemwide count of times the XQP waited for free space in a cache.

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

Description

The Get Resource Monitor Information service returns performance information about the local system.

Required Access or Privileges

None.

Required Quota

This service uses the process's AST limit quota (ASTLM).

Related Services

None.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The caller cannot read the item list, cannot write to the buffer specified by the buffer address field in the item descriptor, or cannot write to the return length address field in an item descriptor.
SS$_BADPARAM	The item list contains an invalid item code.
SS$_EXASTLM	The process has exceeded its AST limit quota.

Returns information about the local system or about other systems in an OpenVMS Cluster system. The $GETSYI service completes asynchronously; for synchronous completion, use the Get Systemwide Information and Wait ($GETSYIW) service.

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

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$GETSYI [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb] [,astadr] [,astprm]

C Prototype

int sys$getsyi (unsigned int efn, unsigned int *csidadr, void *nodename, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), unsigned __int64 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 the $GETSYI request completes. The efn argument is a longword containing this number; however, $GETSYI uses only the low-order byte.

Upon request initiation, $GETSYI clears the specified event flag (or event flag 0 if efn was not specified). Then, when the request completes, the specified event flag (or event flag 0) is set.

csidadr

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS Cluster system identification of the node about which $GETSYI is to return information. The csidadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a longword containing this identification value.

The cluster-connection software assigns the OpenVMS Cluster system identification of a node. You can obtain this information by using the DCL command SHOW CLUSTER. The value of the cluster system identification for a node is not permanent; a new value is assigned to a node whenever it joins or rejoins the cluster.

You can also specify a node to $GETSYI by using the nodename argument. If you specify csidadr, you need not specify nodename, and vice versa. If you specify both, they must identify the same node. If you specify neither argument, $GETSYI returns information about the local node; however, for wildcard operations, you must use the csidadr argument.

If you specify csidadr as --1, $GETSYI assumes a wildcard operation and returns the requested information for each node in the cluster, one node per call. In this case, the program should test for the condition value SS$_NOMORENODE after each call to $GETSYI and should stop calling $GETSYI when SS$_NOMORENODE is returned.

nodename

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the node about which $GETSYI is to return information. The nodename argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a character string descriptor pointing to this name string.

The node name string must contain from 1 to 15 characters and must correspond exactly to the node name; no trailing blanks or abbreviations are permitted.

You can also specify a node to $GETSYI by using the csidadr argument. See the description of csidadr.

itmlst

OpenVMS usage:	32-bit item_list_3 or 64-bit item_list_64b
type:	longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Item list specifying which information is to be returned about the node or nodes. The itmlst argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a list of item descriptors, each of which describes an item of information. An item list in 32-bit format is terminated by a longword of 0; an item list in 64-bit format is terminated by a quadword of 0. All items in an item list must be of the same format---either 32-bit or 64-bit.

The following diagram depicts the 32-bit format of a single item descriptor:

The following table defines the item descriptor fields for 32-bit item list entries:

The following diagram depicts the 64-bit format of a single item descriptor:

The following table defines the item descriptor fields for 64-bit item list entries:

See the Item Codes section for a description of the various $GETSYI item codes.

iosb

When you specify the iosb argument, $GETSYI sets the quadword to 0 upon request initiation. Upon request completion, a condition value is returned to the first longword; the second longword is reserved for future use.

Though this argument is optional, HP 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 $GETSYI 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 $GETSYI, you must check the condition values returned in both R0 and the I/O status block.

astadr

If you specify astadr, the AST routine executes at the same access mode as the caller of the $GETSYI service.

astprm

Item Codes

SYI$_ACTIVE_CPU_MASK

On Alpha systems, returns a value that represents a CPU-indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's active set - those currently participating in the OpenVMS SMP scheduling activities.

SYI$_ACTIVECPU_CNT

Returns a count of the CPUs actively participating in the current boot of the symmetric multiprocessing (SMP) system.

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

SYI$_ARCHFLAG

Returns the architecture flags for the system.

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

SYI$_ARCH_NAME

Returns, as a character string, the name of the CPU architecture on which the process is executing. Currently, either of two strings is returned: "Alpha" for Alpha or "VAX" for VAX.

Because this name can include up to 15 characters, the buffer length field in the item descriptor should specify 15 (bytes).

SYI$_ARCH_TYPE

Returns the type of CPU architecture on which the process is executing. SYI$_ARCH_TYPE returns 1 on VAX or 2 on Alpha.

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

SYI$_AVAIL_CPU_MASK

On Alpha systems, returns a value that represents a CPU-indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's configure set - those owned by the partition and controlled by the issuing instance.

SYI$_AVAILCPU_CNT

Returns the number of CPUs available in the current boot of the symmetric multiprocessing (SMP) system.

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

SYI$_BOOTTIME

Returns the time when the node was booted.

Because the returned time is in the standard 64-bit absolute time format, the buffer length field in the item descriptor should specify 8 (bytes).

SYI$_CHARACTER_EMULATED

Returns the number 1 if the character string instructions are emulated on the CPU and the value 0 if they are not.

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_CLUSTER_EVOTES

Returns the number of votes expected to be found in the OpenVMS Cluster system. The cluster determines this value by selecting the highest number from all of the following: each node's system parameter EXPECTED_VOTES, the sum of the votes currently in the cluster, and the previous value for the number of expected votes.

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

SYI$_CLUSTER_FSYSID

Returns the system identification of the founding node, which is the first node in the OpenVMS Cluster system to boot.

The cluster management software assigns this system identification to the node. You can obtain this information by using the DCL command SHOW CLUSTER. Because the system identification is a 6-byte hexadecimal number, the buffer length field in the item descriptor should specify 6 (bytes).

SYI$_CLUSTER_FTIME

Returns the time when the founding node is booted. The founding node is the first node in the OpenVMS Cluster system to boot.

Because the returned time is in the standard 64-bit absolute time format, the buffer length field in the item descriptor should specify 8 (bytes).

SYI$_CLUSTER_MEMBER

Returns the membership status of the node in the OpenVMS Cluster system. The membership status specifies whether the node is currently a member of the cluster.

Because the membership status of a node is described in a 1-byte bit field, the buffer length field in the item descriptor should specify 1 (byte). If bit 0 in the bit field is set, the node is a member of the cluster; if it is clear, then it is not a member of the cluster.

SYI$_CLUSTER_NODES

Returns the number (in decimal) of nodes currently in the OpenVMS Cluster system.

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

SYI$_CLUSTER_QUORUM

Returns the number (in decimal) that is the total of the quorum values held by all nodes in the OpenVMS Cluster system. Each node's quorum value is derived from its system parameter EXPECTED_VOTES.

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

SYI$_CLUSTER_VOTES

Returns the total number of votes held by all nodes in the OpenVMS Cluster system. The number of votes held by any one node is determined by that node's system parameter VOTES.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

SYI$_COMMUNITY_ID

On Alpha systems, returns the hardware community ID for the issuing instance within the hard partition. Supported only on AlphaServer systems that support partitioning.

SYI$_CONTIG_GBLPAGES

Returns the maximum number of free, contiguous global CPU-specific pages. This number is the largest size global section that can be created.

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

SYI$_CPU

On VAX systems, returns the CPU processor type, as represented in the processor's system identification (SID) register.

For example, the integer 1 represents a VAX--11/780 system and the integer 6 represents a VAX 8530, VAX 8550, VAX 8700, or VAX 8800 system.

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

The $PRDEF macro defines the following symbols for the processor types:

Processor	Symbol
VAX-11/730	PR$_SID_TYP730
VAX-11/750	PR$_SID_TYP750
VAX-11/780, 785	PR$_SID_TYP780
VAXstation II, II/GPX, and MicroVAX II	PR$_SID_TYPUV2
VAXstation 2000/MicroVAX 2000	PR$_SID_TYP410
VAX 8200, 8250, 8300, 8350	PR$_SID_TYP8SS
VAX 8530, 8550, 8810 (8700), and 8820-N (8800)	PR$_SID_TYP8NN
VAX 8600, 8650	PR$_SID_TYP790
VAX 8820, 8830, 8840	PR$_SID_TYP8PS
VAXft 3000 Model 310	PR$_SID_TYP520
VAXstation, MicroVAX 3100 series	PR$_SID_TYP420
MicroVAX 3300, 3400, 3500, 3600, 3800, 3900	PR$_SID_TYP650
VAXstation 3520, 3540	PR$_SID_TYP60
VAX 4000-300	PR$_SID_TYP670
VAX 6000-200, 6000-300 series	PR$_SID_TYP9CC
VAX 6000-400 series	PR$_SID_TYP9RR
VAX 9000-200, 9000-400 series	PR$_SID_TYP9AQ

On Alpha systems, $GETSYI returns PR$_SID_TYP_NOTAVAX.

For information about extended processor type codes, see the description for the SYI$_XCPU item code.

SYI$_CPU_AUTOSTART

On Alpha systems, returns a list of zeroes and ones, separated by commands and indexed by CPU ID. Any entry with a value of one indicates that specific CPU will be brought into the OpenVMS active set if it transitions into the current instance from outside, or is powered up while already owned.

SYI$_CPU_FAILOVER

Returns list of numeric partition IDs, separated by commas and indexed by CPU ID, that define the destination of the processor if the current instance should crash. Supported only on AlphaServer systems that support partitioning.

SYI$_CPUCAP_MASK

On Alpha systems, returns an array of quadword user capability masks for all CPUs in the system. This array is indexed by CPU ID and contains as many elements as the amount of space specified by the buffer length field in the item descriptor.

To minimize wasted space, a prior call to $GETSYI with SYI$_MAX_CPUS will provide the number of CPUs that need to be retrieved. Multiplying that value by 8 bytes for each quadword provides the value to be written in the buffer length field of the item descriptor.

SYI$_CPUCONF

On Alpha systems, returns the CPU Configuration bit mask: 0 through 31.

SYI$_CPUTYPE

On Alpha systems, returns the processor type, as stored in the hardware restart parameter block (HWRPB).

For example, the value of 2 represents a DECchip 21064 processor. Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

The following table shows the processor codes and processors:

Processor Code	Processor
2	21064
4	21066, 21068, 21066A, 21068A
5	21164
6	21064A
7	21164A
8	21264
11	21264A
12	21264C
13	21264B
14	21264D
15	21364
16	21364

SYI$_CWLOGICALS

Returns the number 1 if the clusterwide logical name database has been initialized on the CPU, or the value 0 if it has not been initialized. Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_DAY_OVERRIDE

Returns the number 1 if the SET DAY command has been used to override the default primary and secondary day types in the user authorization file that are used to control user logins. $GETSYI returns the number 0 if no override is currently in effect, and the contents of user authorization file records for each user are being honored.

SYI$_DAY_SECONDARY

Returns the number 1 if any override with the SET DAY command has been used to specify that the current day is to be considered a Secondary day for user login purposes. $GETSYI returns the number 0 if any override with the SET DAY command has been used to specify that the current day is to be considered a Primary day for user login purposes.

If $GETSYI returns the number 0 for SYI$_DAY_OVERRIDE, the number returned for SYI$_DAY_SECONDARY is meaningless.

SYI$_DECIMAL_EMULATED

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_DECNET_FULLNAME

Because the DECnet for OpenVMS full name of a node can contain up to 255 characters, the buffer length field in the item descriptor should specify 255 (bytes).

SYI$_D_FLOAT_EMULATED

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_DEF_PRIO_MAX

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

SYI$_DEF_PRIO_MIN

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

SYI$_ERLBUFFERPAGES

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

SYI$_ERRORLOGBUFFERS

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

SYI$_F_FLOAT_EMULATED

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_FREE_GBLPAGES

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

SYI$_FREE_GBLSECTS

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

SYI$_G_FLOAT_EMULATED

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_GALAXY_ID

SYI$_GALAXY_MEMBER

SYI$_GALAXY_PLATFORM

SYI$_GALAXY_SHMEMSIZE

SYI$_GH_RSRVPGCNT

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

SYI$_GLX_FORMATION

SYI$_GLX_MAX_MEMBERS

SYI$_GLX_MBR_MEMBER

SYI$_GLX_MBR_NAME

SYI$_GLX_TERMINATION

SYI$_H_FLOAT_EMULATED

Because this number is a Boolean value (1 or 0), the buffer length field in the item descriptor should specify 1 (byte).

SYI$_HP_ACTIVE_CPU_CNT

SYI$_HP_ACTIVE_SP_CNT

SYI$_HP_CONFIG_SBB_CNT

SYI$_HP_CONFIG_SP_CNT

SYI$_HW_MODEL

An integer greater than 1023 indicates an Alpha node.

An integer less than or equal to 1023 indicates a VAX node.

The $ALPHADEF and $VAXDEF macros in SYS$LIBRARY:STARLET define the model type integers. See the tables under the SYI$_HW_NAME item code for the VAX processor names and the corresponding model types.

Because SYI$_HW_MODEL is a word, the buffer length field in the item descriptor should specify 2 (bytes).

SYI$_HW_NAME

Because SYI$_HW_NAME can include up to 60 characters plus one for the byte count, the buffer length field in the item descriptor should specify 61 (bytes).

The following table lists the Alpha model processor names and the corresponding model types:

The following table lists the VAX model processor names and the corresponding model types:

SYI$_IO_PREFER_CPU

SYI$_ITB_ENTRIES

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

SYI$_MAX_CPUS

SYI$_MAX_PFN

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

SYI$_MEMSIZE

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

SYI$_NODE_AREA

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

SYI$_NODE_CSID

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

SYI$_NODE_EVOTES

Because the number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

SYI$_NODE_HWVERS

Because the hardware version is a 12-byte hexadecimal number, the buffer length field in the item descriptor should specify 12 (bytes).

SYI$_NODE_NUMBER

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

SYI$_NODE_QUORUM

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

SYI$_NODE_SWINCARN

Because the software incarnation of the node is an 8-byte hexadecimal number, the buffer length field in the item descriptor should specify 8 (bytes).

SYI$_NODE_SWTYPE

Because the software type is a 4-byte ASCII string, the buffer length field in the item descriptor should specify 4 (bytes).

SYI$_NODE_SWVERS

Because the software version is a 4-byte ASCII string, the buffer length field in the item descriptor should specify 4 (bytes).

SYI$_NODE_SYSTEMID

The OpenVMS Cluster management software assigns this system identification to the node. You can obtain this information by using the DCL command SHOW CLUSTER. Because the system identification is a 6-byte hexadecimal number, the buffer length field in the item descriptor should specify 6 (bytes).

SYI$_NODE_VOTES

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

SYI$_NODENAME

Because this name can include up to 15 characters, the buffer length field in the item descriptor should specify 15 (bytes).

SYI$_PAGEFILE_FREE

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

SYI$_PAGEFILE_PAGE

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

SYI$_PAGE_SIZE

On VAX systems, $GETSYI always returns 512.

On Alpha systems, CPU page size varies from system to system.

On Alpha and VAX systems, because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes).

SYI$_PARTITION_ID

SYI$_PFN_MEMORY_MAP

The first longword of the physical memory contains a count of descriptors. This number is equal to the value returned when the SYI$_PMD_COUNT item code is specified.

Each descriptor contains at least 3 longwords: a word containing the length of the descriptor (always use PMM$C_LENGTH when determining descriptor size); a flags word (whose bits are defined in the following table); and the starting PFN for that physical memory cluster and the number of PFNs in that cluster.

The structure definition for the physical memory descriptor resides in PMMDEF.H.

Because the size of the physical memory map returned by $GETSYI can vary from system to system, HP recommends using the following steps when using this item code:

1. Call $GETSYI first using the SYI$_PMD_COUNT to obtain the number of physical memory descriptors.
2. Dynamically create a buffer to which $GETSYI can copy the physical memory map. The size of the buffer can be computed with the following formula:

   map_buffer_size = (PMM$C_LENGTH * ret-val) + 4

   
   where:
   • PMM$C_LENGTH is the size of an individual physical memory descriptor.
   • ret-val is the return value from a call to $GETSYI specifying the SYI$_PMD_COUNT item code.
   • 4 is the number of bytes occupied by the descriptor count in the physical memory map.

SYI$_PHYSICALPAGES

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

SYI$_PMD_COUNT

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

SYI$_POTENTIAL_CPU_MASK

SYI$_POTENTIALCPU_CNT

SYI$_POWERED_CPU_MASK

SYI$_POWEREDCPU_CNT

SYI$_PRESENT_CPU_MASK

SYI$_PRESENTCPU_CNT

SYI$_PRIMARY_CPUID

SYI$_PROCESS_SPACE_LIMIT

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

SYI$_PSXFIFO_PRIO_MAX

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

SYI$_PSXFIFO_PRIO_MIN

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

SYI$_PSXRR_PRIO_MAX

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

SYI$_PSXRR_PRIO_MIN

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

SYI$_PT_BASE

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

SYI$_PTES_PER_PAGE

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

SYI$_RAD_CPUS

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

SYI$_RAD_MEMSIZE

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

SYI$_RAD_MAX_RAD

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

SYI$_RAD_SHMEMSIZE

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

SYI$_REAL_CPUTYPE

See the SYI$_CPUTYPE item code for a list of symbols and processors.

SYI$_SCSNODE

SYI$_SCS_EXISTS

SYI$_SERIAL_NUMBER

SYI$_SHARED_VA_PTES

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

SYI$_SID

On Alpha systems, SYI$_SID returns a value in which all fields are 0 except the CPU-type field, which always contains the value 256.

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

SYI$_SWAPFILE_FREE

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

SYI$_SWAPFILE_PAGE

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

SYI$_SYSTEM_RIGHTS

Allocate a buffer that is sufficient to hold the system rights list, because $GETSYI returns only as much of the list as will fit in the buffer.

SYI$_SYSTYPE

SYI$_VERSION

Because the version number is 8-byte blank-filled, the buffer length field in the item descriptor should specify 8 (bytes).

SYI$_VECTOR_EMULATOR

SYI$_VP_MASK

SYI$_VP_NUMBER

SYI$_XCPU

You should obtain the general processor type value first by using the SYI$_CPU item code. For some of the general processor types, extended processor type information is provided by the item code, SYI$_XCPU. For other general processor types, the value returned by the SYI$_XCPU item code is currently undefined.

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

On VAX systems, the $PRDEF macro defines the following symbols for the extended processor types:

SYI$_XSID

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

SYI$_xxxx

The buffer must specify a longword into which $GETSYI writes the value of the specified system parameter. For a list and description of all system parameters, refer to the HP OpenVMS System Management Utilities Reference Manual.

Description

The Get Systemwide Information service returns information about the local system or about other systems in an OpenVMS Cluster configuration.

Required Access or Privileges

None

Required Quota

This service uses the process's AST limit quota (ASTLM).

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The caller cannot read the item list, cannot write to the buffer specified by the buffer address field in an item descriptor, or cannot write to the return length address field in an item descriptor.
SS$_BADPARAM	The item list contains an invalid item code.
SS$_EXASTLM	The process has exceeded its AST limit quota.
SS$_NOMORENODE	You requested a wildcard operation, and $GETSYI has returned information about all available nodes.
SS$_NOSUCHNODE	The specified node does not exist or is not currently a member of the OpenVMS Cluster system.
SS$_UNREACHABLE	Remote node is not currently reachable.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

Example

/*  Defining __NEW_STARLET enables the program to benefit from better type
    checking for prototypes and structures provided by OpenVMS.             */

#define     __NEW_STARLET       1

#include    <efndef>            /*  No Event Flag Event Flag  */
#include    <iledef>            /*  Item List Entry Definitions  */
#include    <iosbdef>           /*  I/O Status Block Structure Definition  */
#include    <starlet>           /*  Function Prototypes for System Services  */
#include    <stdio>             /*  C Standard I/O Functions  */
#include    <string>            /*  memset Prototype  */
#include    <syidef>            /*  $GETSYI Item Code Definitions  */

#define     NUM_ILE              3
#define     BUFFER_SIZE         20


/*  Macro to initialize a 32-bit item_list_3.                               */

#define init_ile32(ile, length, code, bufaddr, retlen_addr) \
{   (ile)->ile3$w_length = (length);           \
    (ile)->ile3$w_code = (code);         \
    (ile)->ile3$ps_bufaddr = (bufaddr); \
    (ile)->ile3$ps_retlen_addr = (retlen_addr); }


/*  Simple status checking macro.                                           */

#define bad_status(status) (((status) & 1) != 1)

main ()
{
char
    node_name [BUFFER_SIZE],
    version_string [BUFFER_SIZE];

int
    status;

unsigned short
    node_name_length,
    version_string_length;

ILE3
    syi_ile [NUM_ILE];

IOSB
    iosb;


/*  Zeroing the item list has the effect of creating the terminating entry. */

    memset (syi_ile, 0, ILE3$K_LENGTH*NUM_ILE);


/*  Initialize the item list entries to fetch the operating system version
    and the node name.                                                      */

    init_ile32 (
        &syi_ile [0],
        BUFFER_SIZE,
        SYI$_VERSION,
        version_string,
        &version_string_length);

    init_ile32 (
        &syi_ile [1],
        BUFFER_SIZE,
        SYI$_NODENAME,
        node_name,
        &node_name_length);

    status = sys$getsyiw (
        EFN$C_ENF,
        NULL,
        NULL,
        &syi_ile,
        &iosb,
        NULL,
        0);

    if (bad_status (status)) return status;
    if (bad_status (iosb.iosb$w_status)) return iosb.iosb$w_status;


/*  Zero terminate the strings before displaying them.                      */

    version_string [version_string_length] = '\0';
    node_name [node_name_length] = '\0';

    printf ("Version:  %s    Node Name:  %s\n",
        version_string,
        node_name);
}

      

This example C program demonstrates how to use $GETSYIW to obtain the operating system version number string and the node name.

Returns information about the local system or about other systems in a cluster.

The $GETSYIW service completes synchronously; that is, it returns to the caller with the requested information. For asynchronous completion, use the Get Systemwide Information ($GETSYI) service; $GETSYI returns to the caller after queuing the information request, without waiting for the information to be returned. In all other respects, these services are identical; refer to the documentation about $GETSYI for information about the $GETSYIW service.

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

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$GETSYIW [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb] [,astadr] [,astprm]

C Prototype

int sys$getsyiw (unsigned int efn, unsigned int *csidadr, void *nodename, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

You must specify either the csidadr or the nodename argument, but not both. For wildcard operations, however, you must use the csidadr argument.

Returns the current system time in a 64-bit format.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$GETTIM timadr

C Prototype

int sys$gettim (struct _generic_64 *timadr);

Argument

timadr

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a quadword to receive the current time in 64-bit format.

Description

The Get Time service returns the current system time in 64-bit format. The quadword is the number of nanoseconds since November 17, 1858. Based upon system time initialization, all bits in the time quadword are valid.

On VAX systems, system time is updated every 10 milliseconds.

On Alpha systems, the frequency at which system time is updated varies, depending on the clock frequency of the Alpha processor, or approximately 1 millisecond.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $NUMTIM, $SCHDWK, $SETIME, $SETIMR

For additional information about the system time, refer to the HP OpenVMS System Manager's Manual.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The quadword to receive the time cannot be written by the caller.

Returns authorization information about a specified user.

Format

SYS$GETUAI [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg] ,[nullarg] ,[nullarg]

C Prototype

int sys$getuai (unsigned int efn, unsigned int *contxt, void *usrnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

Arguments

nullarg

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

Placeholding argument reserved to HP.

efn

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

Placeholding argument reserved to HP.

contxt

OpenVMS usage:	longword
type:	longword (unsigned)
access:	modify
mechanism:	by reference

An optional longword used to maintain an open channel to the authorization file. The contxt argument is the address of a longword to receive a $GETUAI context value. If the contxt argument is specified on the initial call, this longword should contain the value --1, and on subsequent calls, the value of the contxt argument from the previous call should be passed back in.

usrnam

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Name of the user about whom $GETUAI returns authorization information. The usrnam argument is the address of a descriptor pointing to a character text string containing the user name. The user name string can contain a maximum of 12 alphanumeric characters.

itmlst

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item list specifying which information from the specified user's user authorization file (UAF) record is to be returned. The itmlst argument is the address of a list of one or more item descriptors, each of which specifies an item code. The item list is terminated by an item code value of 0 or by a longword value of 0.

The following diagram depicts the structure of a single item descriptor:

The following table defines the item descriptor fields:

The symbolic codes have the following format:

See the Item Codes section for descriptions of the various $GETUAI item codes.

iosb

astadr

astprm

Item Codes

UAI$_ACCOUNT

Returns, as a blank-filled 32-character string, the account name of the user.

An account name can include up to 8 characters. Because the account name is a blank-filled string, however, the buffer length field of the item descriptor should specify 32 (bytes).

UAI$_ASTLM

Returns the AST queue limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_BATCH_ACCESS_P

Returns, as a 3-byte value, the range of times during which batch access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_BATCH_ACCESS_S

Returns, as a 3-byte value, the range of times during which batch access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_BIOLM

Returns the buffered I/O count.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_BYTLM

Returns the buffered I/O byte limit.

Because the buffered I/O byte limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).

UAI$_CLITABLES

Returns, as a character string, the name of the user-defined CLI table for the account, if any.

Because the CLI table name can include up to 31 characters in addition to a size-byte prefix, the buffer length field of the item descriptor should specify 32 (bytes).

UAI$_CPUTIM

Returns the maximum CPU time limit (per session) for the process in 10-millisecond units.

Because the maximum CPU time limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).

UAI$_DEFCLI

Returns, as an RMS file name component, the name of the command language interpreter used to execute the specified batch job. The file specification returned assumes the device name and directory SYS$SYSTEM and the file type .EXE.

Because a file name can include up to 31 characters in addition to a size-byte prefix, the buffer length field in the item descriptor should specify 32 (bytes).

UAI$_DEFDEV

Returns, as a 1- to 31-character string, the name of the default device.

Because the device name string can include up to 31 characters in addition to a size-byte prefix, the buffer length field in the item descriptor should specify 32 (bytes).

UAI$_DEFDIR

Returns, as a 1- to 63-character string, the name of the default directory.

Because the directory name string can include up to 63 characters in addition to a size-byte prefix, the buffer length field in the item descriptor should specify 64 (bytes).

UAI$_DEF_PRIV

Returns the default privileges for the user.

Because the default privileges are returned as a quadword value, the buffer length field in the item descriptor should specify 8 (bytes).

UAI$_DFWSCNT

Returns the default working set size in pages (on VAX systems) or pagelets (on Alpha systems).

Because the default working set size is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).

UAI$_DIOLM

Returns the direct I/O count limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_DIALUP_ACCESS_P

Returns, as a 3-byte value, the range of times during which dialup access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_DIALUP_ACCESS_S

Returns, as a 3-byte value, the range of times during which dialup access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_ENCRYPT

Returns one of the values shown in the following table, identifying the encryption algorithm for the primary password.

Because the encryption algorithm is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).

Symbolic Name	Description
UAI$C_AD_II	Uses a CRC algorithm and returns a longword hash value. It was used in VAX VMS releases prior to Version 2.0.
UAI$C_PURDY	Uses a Purdy algorithm over salted input. It expects a blank-padded user name and returns a quadword hash value. This algorithm was used during VAX VMS Version 2.0 field test.
UAI$C_PURDY_V	Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm was used in VMS releases prior to Version 5.4.
UAI$C_PURDY_S	Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This is the current algorithm that the operating system uses for all new password changes.

UAI$_ENCRYPT2

Returns one of the following values identifying the encryption algorithm for the secondary password:

• UAI$C_AD_II
• UAI$C_PURDY
• UAI$C_PURDY_V
• UAI$C_PURDY_S

Because the encryption algorithm is a byte in length, the buffer length field in the item descriptor should specify 1 byte.

UAI$_ENQLM

Returns the lock queue limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_EXPIRATION

Returns, as a quadword absolute time value, the expiration date and time of the account.

Because the absolute time value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

UAI$_FILLM

Returns the open file limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_FLAGS

Returns, as a longword bit vector, the various login flags set for the user.

Each flag is represented by a bit. The $UAIDEF macro defines the following symbolic names for these flags:

Symbolic Name	Description
UAI$V_AUDIT	All actions are audited.
UAI$V_AUTOLOGIN	User can only log in to terminals defined by the Automatic Login facility (ALF).
UAI$V_CAPTIVE	User is restricted to captive account.
UAI$V_DEFCLI	User is restricted to default command interpreter.
UAI$V_DISACNT	User account is disabled. Same as /FLAG = DISUSER qualifier in AUTHORIZE.
UAI$V_DISCTLY	User cannot use Ctrl/Y.
UAI$V_DISFORCE_PWD_CHANGE	User will not be forced to change expired passwords at login.
UAI$V_DISIMAGE	User cannot issue the RUN or MCR commands or use the foreign command mechanism in DCL.
UAI$V_DISMAIL	Announcement of new mail is suppressed.
UAI$V_DISPWDDIC	Automatic checking of user-selected passwords against the system dictionary is disabled.
UAI$V_DISPWDHIS	Automatic checking of user-selected passwords against previously used passwords is disabled.
UAI$V_DISRECONNECT	User cannot reconnect to existing processes.
UAI$V_DISREPORT	User will not receive last login messages.
UAI$V_DISWELCOME	User will not receive the login welcome message.
UAI$V_EXTAUTH	User is considered to be externally authenticated by their external user ID and password, and not by the SYSUAF user ID and password. The SYSUAF record is still used for checking login restrictions and quotas and for creating the user's OpenVMS process profile.
UAI$V_GENPWD	User is required to use generated passwords.
UAI$V_LOCKPWD	SET PASSWORD command is disabled.
UAI$V_MIGRATEPWD	User's SYSUAF password has been set using AUTHORIZE or SYS$SETUAI and is likely to be inconsistent with the user's external user password. If password migration is enabled, the system will attempt to update the external authentication service the next time the user attempts a login.
UAI$V_NOMAIL	Mail delivery to user is disabled.
UAI$V_PWD_EXPIRED	Primary password is expired.
UAI$V_PWD2_EXPIRED	Secondary password is expired.
UAI$V_RESTRICTED	User is limited to operating under a restricted account. (Refer to the HP OpenVMS Guide to System Security for a description of restricted and captive accounts.)

UAI$_JTQUOTA

Returns the initial byte quota with which the jobwide logical name table is to be created.

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

UAI$_LASTLOGIN_I

Returns, as a quadword absolute time value, the date of the last interactive login.

UAI$_LASTLOGIN_N

Returns, as a quadword absolute time value, the date of the last noninteractive login.

UAI$_LGICMD

Returns, as an OpenVMS RMS file specification, the name of the default login command file.

Because a file specification can include up to 63 characters in addition to a size-byte prefix, the buffer length field of the item descriptor should specify 64 (bytes).

UAI$_LOCAL_ACCESS_P

Returns, as a 3-byte value, the range of times during which local interactive access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_LOCAL_ACCESS_S

Returns, as a 3-byte value, the range of times during which batch access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_LOGFAILS

Returns the count of login failures.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_MAXACCTJOBS

Returns the maximum number of batch, interactive, and detached processes that can be active at one time for all users of the same account. The value 0 represents an unlimited number.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_MAXDETACH

Returns the detached process limit. A value of 0 represents an unlimited number.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_MAXJOBS

Returns the active process limit. A value of 0 represents an unlimited number.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_NETWORK_ACCESS_P

Returns, as a 3-byte value, the range of times during which network access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_NETWORK_ACCESS_S

Returns, as a 3-byte value, the range of times during which network access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight. For each hour the bit is set to 0, access is allowed. For each hour the bit is set to 1, access is denied.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_OWNER

Returns, as a character string, the name of the owner of the account.

Because the owner name can include up to 31 characters in addition to a size-byte prefix, the buffer length field of the item descriptor should specify 32 (bytes).

UAI$_PBYTLM

Returns the paged buffer I/O byte count limit.

Because the paged buffer I/O byte count limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).

UAI$_PGFLQUOTA

Returns the paging file quota in pages (on VAX systems) or in blocks (on Alpha systems).

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

UAI$_PRCCNT

Returns the subprocess creation limit.

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

UAI$_PRI

Returns the default base priority in the range 0 through 31.

Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).

UAI$_PRIMEDAYS

Returns, as a byte bit vector, the primary and secondary days of the week.

Each bit represents a day of the week, with the bit clear representing a primary day and the bit set representing a secondary day. The $UAIDEF macro defines the following symbolic names for these bits:

UAI$V_MONDAY
UAI$V_TUESDAY
UAI$V_WEDNESDAY
UAI$V_THURSDAY
UAI$V_FRIDAY
UAI$V_SATURDAY
UAI$V_SUNDAY

UAI$_PRIV

Returns, as a quadword value, the names of the privileges the user holds.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

UAI$_PWD

Returns, as a quadword value, the hashed primary password of the user.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

UAI$_PWD_DATE

Returns, as a quadword absolute time value, the date of the last password change.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

A value of --1 indicates that the password is marked as preexpired.

UAI$_PWD_LENGTH

Returns the minimum password length.

Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).

UAI$_PWD_LIFETIME

Returns, as a quadword delta time value, the password lifetime.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

A quadword of 0 means that none of the password mechanisms will take effect.

UAI$_PWD2

Returns, as a quadword value, the hashed secondary password of the user.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

UAI$_PWD2_DATE

Returns, as a quadword absolute time value, the last date the secondary password was changed.

Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).

A value of --1 indicates that the password could be marked as preexpired.

UAI$_QUEPRI

Returns the maximum job queue priority.

Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).

UAI$_REMOTE_ACCESS_P

Returns, as a 3-byte value, the range of times during which remote interactive access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_REMOTE_ACCESS_S

Returns, as a 3-byte value, the range of times during which remote interactive access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m. to bit 23 as 11 p.m. to midnight.

The buffer length field in the item descriptor should specify 3 (bytes).

UAI$_SALT

Returns the random password salt.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_SHRFILLM

Returns the shared file limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_TQCNT

Returns the timer queue entry limit.

Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).

UAI$_UIC

Returns, as a longword, the user identification code (UIC). For the format of the UIC, see the HP OpenVMS Guide to System Security.

UAI$_USER_DATA

Returns up to 255 bytes of information from the user data area of the system user authorization file (SYSUAF).

You can read information written to the user data area from previous versions of the operating system as long as the information written adheres to the guidelines described in the HP OpenVMS Guide to System Security.

UAI$_WSEXTENT

Returns the working set extent, in pages (on VAX systems) or pagelets (on Alpha systems), for the user of the specified queue or job.

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

UAI$_WSQUOTA

Returns the working set quota, in pages (on VAX systems) or pagelets (on Alpha systems), for the specified user.

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

Description

The Get User Authorization Information service returns authorization information about a specified user.

The contxt value returned by $GETUAI should never be used as a value to the $SETUAI system service.

You examine for a valid login by checking the bits of UAI$V_PWD_EXPIRED and UAI$V_DISUSER, and by doing a comparison of the UAI$_PWD_DATE item code against the UAI$_PWD_LIFETIME item code.

The UAI$V_PWD_EXPIRED bit is only set by the system when the bit UAI$V_DISFORCE_PWD_CHANGE is set in the user's SYSUAF record and the comparison between the UAI$_PWD_DATE and UAI$_PWD_LIFETIME indicates a password is past its valid life.

During a normal login when the UAI$V_DISFORCE_PWD_CHANGE bit is not set, the system compares VAI$_PWD_DATE against UAI$_PWD_LIFETIME and, if expired, forces the user to change the password. With this configuration, the UAI$V_PWD_EXPIRED bit is not set.

During a normal login when the VAI$V_DISFORCE_PWD_EXPIRED is set, the system compares UAI$_PWD_DATE against UAI$_PWD_LIFETIME and, if expired, sets the UAI$_PWD_EXPIRED bit and notifies the user to change the now-expired password. In this case, the user is not forced to change the password.

Required Access or Privileges

Use the following list to determine the privileges required to use the $GETUAI service:

• BYPASS or SYSPRV---Allows access to any record in the user authorization file (UAF).
• GRPPRV---Allows access to any record in the UAF whose UIC group matches that of the requester.
• No privilege---Allows access to any UAF record whose UIC matches that of the requester.
  You need read access to the UAF to look up any information other than your own.

Required Quota

None

Related Services

$SETUAI

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$_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$_NOGRPPRV	The user does not have the privileges required to examine the authorization information for other members of the UIC group.
SS$_NOSYSPRV	The user does not have the privileges required to examine the authorization information associated with the user or for users outside of the user's UIC group.
RMS$_RSZ	The UAF record is smaller than required; the caller's SYSUAF is probably corrupt.

This service can also return OpenVMS RMS status codes associated with operations on indexed files. For example, an inquiry about a nonexistent account returns RMS$_RNF, record not found status. For a description of RMS status codes that are returned by this service, refer to the OpenVMS Record Management Services Reference Manual.

Returns the current time in 128-bit UTC format.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$GETUTC utcadr

C Prototype

int sys$getutc (unsigned int *utcadr [4]);

Arguments

utcadr

OpenVMS usage:	coordinated universal time
type:	utc_date_time
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The 128-bit time value to be returned.

Description

The Get UTC Time service returns the current system time in 128-bit UTC format. System time is updated every 10 milliseconds.

On Alpha systems, the frequency at which system time is updated varies, depending on the clock frequency of the Alpha processor.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCUTC, $BINUTC, $NUMUTC, $TIMCON

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The argument was not accessible for write in the mode of the caller.

On Alpha systems, obtains data from the user image alignment fault buffer if buffered user alignment fault data reporting has been enabled.

This service accepts 64-bit addresses.

Format

SYS$GET_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size

C Prototype

int sys$get_align_fault_data (void *buffer, int buffer_size, int *return_size);

Arguments

buffer

OpenVMS usage:	address
type:	longword (unsigned)
access:	read/write
mechanism:	by 32- or 64-bit reference

The user buffer in which the alignment fault data is to be stored. The buffer is the 32- or 64-bit address of this user buffer.

buffer_size

OpenVMS usage:	byte count
type:	longword (signed)
access:	read
mechanism:	by value

The size, in bytes, of the buffer specified by the buffer argument.

return_size

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write
mechanism:	by 32- or 64-bit reference

The amount of data, in bytes, stored in the buffer. The return_size argument is the 32- or 64-bit address of a naturally aligned longword into which the service returns the size of the buffer. The return_size is set to 0 if there is no data in the buffer.

Description

The Get Alignment Fault Data service obtains data from the user image alignment fault buffer if buffered user alignment fault data reporting has been enabled.

When buffered user alignment fault data reporting is enabled, the operating system writes each alignment fault into a user-defined buffer. The user must poll this buffer periodically to read the data.

The user must call the $START_ALIGN_FAULT_REPORT service to enable buffered user alignment fault data reporting.

For more information about buffered user alignment fault data reporting, see the $START_ALIGN_FAULT_REPORT system service.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The buffer named in the buffer argument is not accessible.
SS$_AFR_NOT_ENABLED	Alignment fault reporting has not been enabled.
SS$_BADPARAM	The buffer size is smaller than the minimum defined by the AFR$K_USER_LENGTH symbol.

On Alpha systems, returns information about the exception context for a given arithmetic exception.

Format

SYS$GET_ARITH_EXCEPTION sigarg ,mcharg ,buffer

C Prototype

int sys$get_arith_exception (void *sigarg, void *mcharg, void *buffer);

Arguments

sigarg

OpenVMS usage:	signal array
type:	vector_longword_signed
access:	read only
mechanism:	by reference

Address of the signal array for the given arithmetic exception.

mcharg

OpenVMS usage:	mech array
type:	vector_quadword_unsigned
access:	read only
mechanism:	by reference

Address of the mechanism array for the given arithmetic exception.

buffer

OpenVMS usage:	vector_quadword
type:	vector_quadword_unsigned
access:	write only
mechanism:	by descriptor

Four-quadword buffer to receive additional exception context. The buffer argument is the address of a descriptor that points to this buffer.

Description

The Get Arithmetic Exception Information service returns, to the buffer specified by the buffer argument, the following information for a given arithmetic exception in an array of quadwords:

• First quadword, the PC of the triggering instruction in the trap shadow
• Second quadword, a copy of the triggering instruction
• Third quadword, the exception summary
• Fourth quadword, the register write mask

Required Access or Privilege

None

Required Quota

None

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The specified buffer cannot be written.
SS$_BADBUFLEN	The specified buffer length is invalid or out of range.

Returns the default transaction of the calling process.

Format

SYS$GET_DEFAULT_TRANS tid

C Prototype

int sys$get_default_trans (unsigned int tid [4]);

Arguments

tid

OpenVMS usage:	trans_id
type:	octaword (unsigned)
access:	write only
mechanism:	by reference

Address of an octaword in which the identifier (TID) of the default transaction of the calling process is returned.

Description

A precondition for the successful completion of $GET_DEFAULT_TRANS is that the calling process must have a default transaction.

$GET_DEFAULT_TRANS may fail for various reasons, including:

• The precondition was not met.
• The default transaction was being changed at the time of the call.

The postcondition on successful completion of $GET_DEFAULT_TRANS is described in Table SYS-44:

Table SYS-44 Postcondition When$GET_DEFAULT_TRANS Completes Successfully

Postcondition	Meaning
The identifier of the default transaction of the calling process is returned.	The identifier (TID) of the default transaction of the calling process is returned in the tid argument.

Required Privileges

None

Required Quotas

None

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL	The request was successful.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_NOCURTID	The calling process did not have a default transaction.
SS$_WRONGSTATE	The default transaction was being changed at the time of the call.

Returns "interesting" fields from the specified lock.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment. For more information about programming with OpenVMS Galaxy system services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

Format

SYS$GET_GALAXY_LOCK_INFO handle ,name ,timeout ,size ,ipl ,rank ,flags [,name_length]

C Prototype

int sys$get_galaxy_lock_info (unsigned __int64 lock_handle, char *name, unsigned int *timeout, unsigned int *size, unsigned int *ipl, unsigned int *rank, unsigned short int *flags unsigned short int *name_length);

Arguments

handle

OpenVMS usage:	handle for the galaxy lock
type:	quadword (unsigned)
access:	read
mechanism:	input by value

The 64-bit lock handle that identifies the lock on which to return information. This value is returned by SYS$CREATE_GALAXY_LOCK.

name

OpenVMS usage:	address
type:	zero-terminated string
access:	write
mechanism:	output by reference

Pointer to a buffer. This buffer must be large enough to receive the name of the lock. Locks names are zero-terminated strings with a maximum size of 16 bytes.

timeout

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is the timeout value of the lock.

size

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is the size of the lock in bytes.

ipl

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is the IPL of the lock.

rank

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is the rank of the lock.

flags

OpenVMS usage:	address
type:	word (unsigned)
access:	write
mechanism:	output by reference

Pointer to a word. The value returned is the word mask of lock flags.

name_length

OpenVMS usage:	address
type:	word (unsigned)
access:	write
mechanism:	output by reference

Length of the string returned in the name argument.

Description

This service returns all "interesting" fields from the specified lock. See the $CREATE_GALAXY_LOCK service for detailed information regarding these values.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_IVLOCKID	Invalid lock id.
SS$_IVLOCKTBL	Invalid lock table.

Returns the minimum and maximum size of an OpenVMS Galaxy lock.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment.

For more information about programming with OpenVMS Galaxy system services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

Format

SYS$GET_GALAXY_LOCK_SIZE min_size ,max_size

C Prototype

int sys$get_galaxy_lock_size (unsigned int *min_size, unsigned int *max_size);

Arguments

min_size

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is minimum legal size of a galaxy lock structure.

max_size

OpenVMS usage:	address
type:	longword (unsigned)
access:	write
mechanism:	output by reference

Pointer to a longword. The value returned is maximum legal size of a galaxy lock structure.

Description

This service returns the minimum and maximum size of an OpenVMS Galaxy lock. If a lock is created with the maximum size, the locking services will record acquire and release information in the lock.

The lock sizes can be used to determine the value of the section_size parameter to the $CREATE_GALAXY_LOCK_TABLE service.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $RELEASE_GALAXY_LOCK

Condition Values Returned

SS$_NORMAL

Normal completion.

On Alpha systems, gets information about a specified virtual region.

This service accepts 64-bit addresses.

Format

SYS$GET_REGION_INFO function_code ,region_id_64 ,start_va_64 ,nullarg ,buffer_length ,buffer_address_64 ,return_length_64

C Prototype

int sys$get_region_info (unsigned int function_code, struct _generic_64 *region_id_64, void *start_va_64, void *reserved, unsigned int buffer_length, void *buffer_address_64, unsigned int *return_length_64);

Arguments

function_code

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

Function code specifying how the information you are requesting should be looked up. All function codes return region summary information in the return buffer in the format of the Region Summary Buffer. The Region Summary Buffer format is shown in the table in the buffer_address_64 argument.

If less buffer space is specified than the length of the Region Summary Buffer, only the amount of information requested is returned. If more buffer space is specified than the length of the Region Summary Buffer, the service will fill in the buffer. The return length will reflect the amount of useful information written to the buffer, the size of the Region Summary Buffer.

The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each function code.

The following function codes are defined:

Symbolic Name	Description
VA$_REGSUM_BY_ID	Return the region summary information for the region whose ID is specified in the region_id_64 argument.
VA$_REGSUM_BY_VA	Return the region summary information for the region that contains the virtual address specified in the start_va_64 argument.
VA$_NEXT_REGSUM_BY_VA	Return the region summary information for the region containing the starting address. If the starting address is not in a region, return the region summary information for the next region with a starting address higher than the specified address. Note: For the VA$_NEXT_REGSUM_BY_VA function, OpenVMS checks for a start_va_64 argument in the inaccessible address range in P2 space. If it finds one, OpenVMS adjusts the address to account for the discontinuity. For more information about the layout of the 64-bit virtual address space, refer to the OpenVMS Programming Concepts Manual. This function code can be used for wildcard operations. See the description of the start_va_64 argument for information on how to program a wildcard operation on regions.

region_id_64

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The region ID associated with the region about which information is requested. This argument is read only if the function code VA$_REGSUM_BY_ID is specified.

The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each of the three default regions in P0, P1, and P2 space.

The following region IDs are defined:

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified.

start_va_64

OpenVMS usage:	input address
type:	quadword address
access:	read only
mechanism:	by value

Virtual address associated with region about which information is requested. This argument is read only if the function_code argument is VA$_REGSUM_BY_VA or VA$_NEXT_REGSUM_BY_VA.

If the function_code argument is VA$_REGSUM_BY_VA, this argument is a virtual address within the region about which you are requesting information.

To perform a wildcard search on all regions, specify VA$_NEXT_REGSUM_BY_VA as the function code and begin with the start_va_64 argument specified as -1. For subsequent calls, specify start_va_64 as the sum of the previous region's start address and length. Call the $GET_REGION_INFO service in a loop until the condition SS$_NOMOREREG is returned.

Note Before performing the lookup function, OpenVMS sign-extends the 64-bit starting address so that it represents a properly formed virtual address for the CPU.

nullarg

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

Placeholding argument reserved to HP.

buffer_length

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

Length of the buffer into which information is returned.

buffer_address_64

OpenVMS usage:	varying_arg
type:	unspecified
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a quadword-aligned buffer into which to return information if the buffer_length argument is nonzero.

This argument is ignored if the buffer_length argument is zero.

Table SYS-45 shows the format of the Region Summary Buffer:

Table SYS-45 Region Summary Buffer Format

Field name	Meaning	Field Size (Bytes)	Field Offset (Decimal)
VA$L_FLAGS	Flags used when region was created	4	8
VA$L_REGION_PROTECT	Create and owner mode of region	4	12
VA$Q_REGION_ID	Region identifier	8	0
VA$PQ_START_VA	Starting (lowest) virtual address of region	8	16
VA$Q_REGION_SIZE	Total length of region	8	24
VA$PQ_FIRST_FREE_VA	First free virtual address in region	8	32
VA$C_REGSUM_LENGTH	Length of Region Summary Buffer	constant	40

The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF MACRO in STARLET.MLB define the REGSUM structure.

return_length_64

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned longword into which the service returns the length of the information in bytes.

Description

The Get Information About a Specified Virtual Region service is a kernel mode service that can be called from any mode. This service gets the requested information about the specified region or the next region in a wildcard search. If the returned value of this service is not a successful condition value, a value cannot be returned in the memory locations pointed to by the buffer_address_64 or return_length_64 arguments.

Required Privileges

None

Required Quota

None

Related Services

$CREATE_REGION_64, $DELETE_REGION_64

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The buffer_address_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_BADPARAM	Unrecognized function code.
SS$_IVREGID	Invalid region ID specified in conjunction with the VA$_REGSUM_BY_ID function code.
SS$_NOMOREREG	No region at a higher address than specified in the start_va_64 argument, which was specified in conjunction with the wildcard function code VA$_NEXT_REGSUM_BY_VA.
SS$_PAGNOTINREG	The value specified in the start_va_64 argument is not within a region and was specified in conjunction with the function code VA$_REGSUM_BY_VA.

Retrieves the security characteristics of an object.

Format

SYS$GET_SECURITY [clsnam] ,[objnam] ,[objhan] ,[flags] ,[itmlst] ,[contxt] ,[acmode]

C Prototype

int sys$get_security (void *clsnam, void *objnam, unsigned int *objhan, unsigned int flags, void *itmlst, unsigned int *contxt, unsigned int *acmode);

Arguments

clsnam

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

Name of the object class. The clsnam argument is the address of a descriptor pointing to a string containing the name of the object class.

The following is a list of protected object class names:

CAPABILITY
COMMON_EVENT_CLUSTER
DEVICE
FILE
GLXSYS_GLOBAL_SECTION
GLXGRP_GLOBAL_SECTION
GROUP_GLOBAL_SECTION
ICC_ASSOCIATION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME

objnam

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

Name of the protected object whose associated security profile is going to be retrieved. The objnam argument is the address of a descriptor pointing to a string containing the name of the protected object.

The format of an object name is class specific. The following table lists object names and describes their formats:

Object Class	Object Name Format
CAPABILITY	A character string. Currently, the only capability object is VECTOR.
COMMON_EVENT_CLUSTER	Name of the event flag cluster, as defined in the Associate Common Event Flag Cluster ($ASCEFC) system service.
DEVICE	Standard device specification, described in the OpenVMS User's Manual.
FILE	Standard file specification, described in the OpenVMS User's Manual.
GROUP_GLOBAL_SECTION	Section name, as defined in the Create and Map Section ($CRMPSC) system service.
ICC_ASSOCIATION	ICC security object name node::association_name. The special node name, ICC$::, refers to entries in the clusterwide registry. For registry entries, the Access Access Type does not apply.
LOGICAL_NAME_TABLE	Table name, as defined in the Create Logical Name Table ($CRELNT) system service.
QUEUE	Standard queue name, as described in the Send to Job Controller ($SNDJBC) system service.
RESOURCE_DOMAIN	An identifier or octal string enclosed in brackets.
SECURITY_CLASS	Any class name shown in column 1, or a class name followed by a period (.) and the template name. Use the DCL command SHOW SECURITY to display possible template names.
SYSTEM_GLOBAL_SECTION	Section name, as defined in the Create and Map Section ($CRMPSC) system service.
VOLUME	Volume name or name of the device on which the volume is mounted.

objhan

OpenVMS usage:	object_handle
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Data structure identifying the object whose associated characteristics are going to be retrieved. The objhan argument is an address of a longword containing the object handle. You can use the objhan argument as an alternative to the objnam argument; for example, channel number clearly specifies the file open on the channel and can serve as an object handle.

The following table shows the format of the object classes:

Object Class	Object Handle Format
COMMON_EVENT_CLUSTER	Event flag number
DEVICE	Channel number
FILE	Channel number
RESOURCE_DOMAIN	Resource domain identifier
VOLUME	Channel number

flags

OpenVMS usage:	flags
type:	mask_longword
access:	read only
mechanism:	by value

Mask specifying processing options. The flags argument is a longword bit vector wherein a bit, when set, specifies the processing option. The flags argument requires the contxt argument.

The following table describes each flag:

Symbolic Name	Description
OSS$M_RELCTX	Release the context structure at the completion of this request.
OSS$M_WLOCK	Maintain a write lock on the security profile at the completion of this request. $GET_SECURITY ignores the flag if the context has already been established.

These symbolic names are defined in the $OSSDEF macro. You construct the flags argument by specifying the symbolic names of each flag.

itmlst

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item list specifying which information about the process or processes is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0.

With the item list, the user retrieves the protected object's characteristics. The user defines which security characteristics to retrieve. If this argument is not present, only the flags argument is processed. Without the itmlst argument, you can only manipulate the security profile lock or release contxt resources.

The following diagram depicts a single item descriptor:

The following table describes the item descriptor fields:

contxt

Because an active context block consumes process memory, be sure to release the context block by setting the RELCTX flag when the profile processing is complete. $GET_SECURITY sets the context argument to 0 once the context is released.

acmode

OSS$_ACCESS_NAMES

Returns the access name translation table in the buffer pointed to by the buffer address field of the item descriptor.

The access name translation table is a 32-quadword vector followed by a variable section containing the access names. Each bit in the vector represents a single access type. The contents of the quadword is a string descriptor that corresponds to the ASCII bitname string. Undefined access types have zero-length names. The return length, if present, returns the length of the table.

OSS$_ACCESS_NAMES_LENGTH

Returns the length of the access name translation table.

OSS$_ACL_FIND_ENTRY

Locates an ACE pointed to by the buffer address. OSS$_ACL_FIND_ENTRY sets the position within the ACL for succeeding ACL operations; for example, for a deletion or modification of the ACE. If the buffer address is 0, it returns SS$_ACCVIO.

OSS$_ACL_FIND_NEXT

Advances the current position to the next ACE in the ACL.

OSS$_ACL_FIND_TYPE

Returns an ACE of a particular type if there is one in the buffer pointed to by the buffer address. OSS$_ACL_FIND_TYPE sets the position within the ACL for succeeding ACL operations. If the buffer address is 0, it returns SS$_ACCVIO.

OSS$_ACL_GRANT_ACE

Returns the ACE in the object's ACL that grants or denies the user access to that object. OSS$_ACL_GRANT_ACE returns the ACE found in the buffer pointed to by the buffer address.

OSS$_ACL_LENGTH

Returns the size (in bytes) of the object's ACL. The buffer address field points to a longword that receives the size.

OSS$_ACL_POSITION_BOTTOM

Sets the ACL position to point to the bottom of the ACL.

OSS$_ACL_POSITION_TOP

Sets the ACL position to point to the top of the ACL.

OSS$_ACL_READ

Returns the portion of the object's ACL to the buffer pointed to by the buffer address.

OSS$_ACL_READ_ENTRY

Reads the ACE pointed to by the buffer address.

OSS$_CLASS_NAME

Returns the full object class name.

OSS$_FIRST_TEMPLATE

Returns the name of the first template profile for the object named in the objnam argument. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS$_NEXT_OBJECT

Returns the name of the next object. A return length of 0 indicates the end of the list. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS$_NEXT_TEMPLATE

Returns the name of the next template. This item code allows you to step through a list of an object's templates. A return length of 0 indicates the end of the list. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS_OBJECT_NAME

Returns the name of the object.

OSS$_OWNER

Returns the owner of the object.

OSS$_PROTECTION

Returns the protection code of the object.

Description

The Get Security service returns information about security characteristics of a selected object. Security characteristics include such information as the protection code, the owner, and the access control list (ACL). The security management services, $GET_SECURITY and $SET_SECURITY, maintain a single master copy of a profile for every security object in an OpenVMS Cluster environment. They also ensure that only one process at a time can modify an object's security profile.

There are different ways of identifying which protected object $GET_SECURITY should process:

• Whenever the contxt argument has a nonzero value, $GET_SECURITY uses the context to select the object and ignores the class name, object name, and object handle.
• With some types of objects, such as a file or a device, it is possible to select an object on the basis of its objhan and clsnam values.
• If neither a nonzero contxt argument nor an objhan argument is provided, $GET_SECURITY uses an object's class name (clsnam) and object name (objnam) to select the object.

When you call $GET_SECURITY, the service selects the specified protected object and fetches a local copy of the object's security profile.

The context for a security management operation can be established through either $GET_SECURITY or $SET_SECURITY. Whenever the context is set by one service, the other service can use it, provided the necessary locks are being held. If you intend to modify the profile, you must set the write lock flag (OSS$M_WLOCK) when you establish the context.

There are many situations in which the contxt argument is essential. By establishing a context for an ACL operation, for example, a caller can retain an ACL position across calls to $GET_SECURITY so that a set of ACEs can be read and modified sequentially. A security context is released by a call to $SET_SECURITY or $GET_SECURITY that sets the OSS$M_RELCTX flag. Once the context is released, the user-supplied context longword is set to 0.

Required Access or Privileges

Read or control access to the object is required.

Required Quota

None

Related Services

$SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The parameter cannot be read and the buffer cannot be written.
SS$_BADPARAM	You specified an invalid object, attribute code, or item size.
SS$_INSFARG	The clsnam and objnam arguments are not specified, the clsnam and objhan arguments are not specified, or the contxt argument is not specified.
SS$_INVCLSITM	The item code that you specified is not supported for the class.
SS$_NOCLASS	The named security class does not exist.
SS$_OBJLOCKED	The selected object is currently write locked.

On Alpha systems, obtains data from the system alignment fault buffer if buffered system alignment fault data reporting has been enabled.

This service accepts 64-bit addresses.

Format

SYS$GET_SYS_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size

C Prototype

int sys$get_sys_align_fault_data (void *buffer, int buffer_size, int *return_size);

Arguments

buffer

OpenVMS usage:	address
type:	longword (unsigned)
access:	read/write
mechanism:	by 32- or 64-bit reference

The user buffer in which the alignment fault data is to be stored. The buffer argument is the 32- or 64-bit virtual address of this buffer.

buffer_size

OpenVMS usage:	byte count
type:	longword (signed)
access:	read
mechanism:	by value

The size, in bytes, of the buffer specified by the buffer argument.

return_size

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write
mechanism:	by 32- or 64-bit reference

The amount of data, in bytes, stored in the buffer. The return_size argument is the 32- or 64-bit virtual address of a naturally aligned longword into which the service returns the amount of data, in bytes, stored in the buffer. The return_size argument is set to 0 if there is no data in the buffer.

Description

The Get System Alignment Fault Data service obtains data from the system alignment fault buffer if buffered system alignment fault data reporting has been enabled.

When buffered system alignment fault data reporting is enabled, the operating system writes each alignment fault into a system-allocated buffer. The user must poll this buffer periodically to read the data.

The user must call the $INIT_SYS_ALIGN_FAULT_REPORT service to enable buffered system alignment fault data reporting. For more information, see the $INIT_SYS_ALIGN_FAULT_REPORT service.

Required Access or Privileges

CMKRNL privilege is required.

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The buffer named in the buffer argument is not accessible.
SS$_AFR_NOT_ENABLED	Alignment fault reporting has not been enabled.
SS$_BADPARAM	The buffer size is smaller than the minimum defined by the AFR$K_VMS_LENGTH or the AFR$K_EXTENDED_LENGTH symbol.

On Alpha systems, reserves a user capability, indicating to other processes that the resource is in use.

This service accepts 64-bit addresses.

Format

SYS$GET_USER_CAPABILITY cap_num [,select_num] [,select_mask] [,prev_mask] [,flags]

C Prototype

int sys$get_user_capability (*cap_num, int *select_num, struct _generic_64 *select_mask, struct _generic_64 *prev_mask, struct _generic_64 *flags);

Arguments

cap_num

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Capability number to be reserved by the calling kernel thread. This number can range from 1 to 16 for an explicit request, or the symbolic constant CAP$K_GET_FREE_CAP can be specified to get the next available user capability. The cap_num argument is the 32- or 64-bit address of the longword containing the user capability number or symbolic constant.

select_num

OpenVMS usage:	longword
type:	longword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The number of the user capability selected by the service call. The select_num argument is the 32- or 64-bit address of a longword into which the system writes the user capability number. For an explicit numeric request, the value returned in this longword will match that specified in cap_num; otherwise, this cell contains the next available user capability.

select_mask

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

A quadword bit mask with a single bit position set, reflecting the user capability selected by the service. The select_mask argument is the 32- or 64-bit address of a quadword into which the system writes the selected user capability bit mask. This bit mask is the most efficient method for indicating the reserved user capability with the $CPU_CAPABILITIES and $PROCESS_CAPABILITIES services.

prev_mask

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The previous user capability reservation mask before execution of this service call. The prev_mask argument is the 32- or 64-bit address of a quadword into which the service writes a quadword bit mask specifying the previously reserved user capabilities taken from the global cell SCH$GQ_RESERVED_USER_CAPS.

flags

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Options selected for the user capability reservation. The flags argument is a quadword bit vector wherein a bit corresponds to an option.

Each option (bit) has a symbolic name, which the $CAPDEF macro defines. The flags argument is constructed by performing a logical OR operation using the symbolic names of each desired option.

At this time, all bits are reserved to HP and must be 0.

Description

The Reserve a User Capability service provides a way for discrete processes to communicate and synchronize their use of a user capability in the system. This service uses the global cell SCH$GQ_RESERVED_USER_CAPS to indicate that a particular user capability has been reserved. $GET_USER_CAPABILITY can also return the current reservation state of all user capabilities in the system.

Reservation of a user capability can be made for an explicit number or for the next available number. The selected user capability is returned to the caller through a numeric value in select_num or by a quadword bit mask in select_mask.

This service does not directly enforce unique use of the individual user capabilities; it simply provides a common informational and control resource for processes using the other capability scheduling services. Code threads that do not use this service to verify whether a user capability is available are still at risk if differing usages conflict.

Required Privileges

The caller must have both ALTPRI and WORLD privileges to call $GET_USER_CAPABILITY to reserve a user capability. No privileges are required if $GET_USER_CAPABILITY is called only to retrieve the current user capability reservation mask.

Required Quota

None

Related Services

$FREE_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_INSFARG	Fewer than the required number of arguments were specified, or no operation was specified.
SS$_NOPRIV	Insufficient privilege for the attempted operation.
SS$_NOSUCH_OBJECT	No more user capabilities are available.
SS$_OBJECT_EXISTS	A specifically requested user capability has already been reserved.
SS$_TOO_MANY_ARGS	Too many arguments were presented to the system service.

On Alpha systems, unwinds the call stack.

Format

SYS$GOTO_UNWIND target_invo ,target_pc ,[new_r0] ,[new_r1]

C Prototype

int sys$goto_unwind (void *target_invo, void *(*(target_pc)), unsigned __int64 *new_r0, unsigned __int64 *new_r1);

Arguments

target_invo

OpenVMS usage:	invo_handle
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, an exit unwind is initiated.

target_pc

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, a system-defined target PC is assumed and execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

new_r0

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains the value to place in the saved R0 location of the mechanism argument vector. The contents of this location are then loaded into the processor R0 register at the time that execution continues in the target invocation.

If the new_r0 argument is omitted, the contents of the processor R0 register at the time of the call to $GOTO_UNWIND are used.

new_r1

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Address of a location that contains the value to place in the saved R1 location of the mechanism argument vector. The contents of the location are then loaded into the processor R1 register at the time that execution continues in the target invocation.

If the new_r1 argument is omitted, the contents of the processor R1 register at the time of the call to $GOTO_UNWIND are used.

Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The specified target_invo, target_pc, new_r0, or new_r1 argument is not accessible.

On Alpha and I64 systems, unwinds the call stack.

Format

SYS$GOTO_UNWIND target_invo, target_pc, [NewRetVal], [NewRetVal2]

C Prototype

int sys$goto_unwind_64 (void *target_invo_64, void *(*(target_pc_64)), unsigned_int64 *new_retval, unsigned_int64 *newretval2);

Arguments

target_invo

OpenVMS usage:	invo_handle
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, the effect of the call is undefined.

target_pc

OpenVMS usage:	address
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

If the target_invo argument is omitted or the value is 0, the target_pc argument is ignored. In this case, a system-defined target PC is assumed.

NewRetVal

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains the value to place in the saved RetVal location of the mechanism argument vector. The contents of this location are then loaded into RetVal at the time that execution continues in the target invocation.

If the NewRetVal argument is omitted, the contents of RetVal at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R0 in SYS$GOTO_UNWIND for compatibility with Alpha.

NewRet2

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

The address of a location that contains the value to place in the saved RetVal2 location of the mechanism argument vector. The contents of the location are then loaded into RetVal2 at the time that execution continues in the target invocation.

If the NewRet2 argument is omitted, the contents of RetVal2 at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R1 in SYS$GOTO_UNWIND for compatibility with Alpha.

Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND

Condition Values Returned

SS$_ACCVIO

An invalid address was given.

Adds the specified identifier record to the rights list of the process or the system.

Format

SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

C Prototype

int sys$grantid (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name, unsigned int *prvatr, unsigned int segment);

Arguments

pidadr

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Process identification (PID) number of the process affected when $GRANTID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use --1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant. If you specify neither pidadr nor prcnam, your own process is used.

prcnam

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Process name on which $GRANTID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group. If you specify neither pidadr nor prcnam, your own process is used.

id

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	modify
mechanism:	by reference

Identifier and attributes to be granted when $GRANTID completes execution. The id argument is the address of a quadword containing the binary identifier code to be granted in the first longword and the attributes in the second longword.

Use the id argument to modify the attributes of the identifier.

Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the macro library ($KGBDEF):

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights database using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.

name

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Name of the identifier granted when $GRANTID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier. The identifier is granted as it is created. You must specify either id or name.

prvatr

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Previous attributes of the identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier if it was previously present in the rights list. If you added rather than modified the identifier, prvatr is ignored.

Description

The Grant Identifier to Process service adds the specified identifier to the rights list of the process or the system. If the identifier is already in the rights list, its attributes are modified to those specified. This service is meant to be used by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant to be used by the general system user.

The result of passing the pidadr or the prcnam argument, or both, to SYS$GRANTID is summarized in the following table:

prcnam	pidadr	Result
Omitted	Omitted	Current process ID is used; process ID is not returned.
Omitted	0	Current process ID is used; process ID is returned.
Omitted	Specified	Specified process ID is used.
Specified	Omitted	Specified process name is used; process ID is not returned.
Specified	0	Specified process name is used; process ID is returned.
Specified	Specified	Specified process ID is used and process name is ignored.

The result of passing the name or the id argument, or both, to SYS$GRANTID is summarized in the following table:

name	id	Result
Omitted	Omitted	Illegal. The INSFARG condition value is returned.
Omitted	Specified	Specified identifier value is used.
Specified	Omitted	Specified identifier name is used; identifier value is not returned.
Specified	0	Specified identifier name is used; identifier value is returned.
Specified	Specified	Specified identifier value is used and identifier name is ignored.

Note that a value of 0 in either of the preceding tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.

Required Access or Privileges

You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

SS$_WASCLR	The service completed successfully; the rights list did not contain the specified identifier.
SS$_WASSET	The service completed successfully; the rights list already held the specified identifier.
SS$_ACCVIO	The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; the name cannot be read; or prvatr cannot be written.
SS$_INSFARG	You did not specify either the id or the name argument.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.
SS$_IVLOGNAM	You specified an invalid process name.
SS$_NONEXPR	You specified a nonexistent process.
SS$_NOPRIV	The caller does not have CMKRNL privilege or is not running in executive or kernel mode, or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.
SS$_NOSUCHID	The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.
SS$_NOSYSNAM	The operation requires SYSNAM privilege.
SS$_RIGHTSFULL	The rights list of the process or system is full.
RMS$_PRV	The user does not have read access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

Applies the hash algorithm you select to an ASCII password string and returns a quadword hash value that represents the encrypted password.

Format

SYS$HASH_PASSWORD pwd ,alg ,[salt] ,usrnam ,hash

C Prototype

int sys$hash_password (void *pwd, unsigned char alg, unsigned short int salt, void *usrnam, struct _generic_64 *hash);

Arguments

pwd

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

ASCII password string to be encrypted. The pwd argument is the address of a character string descriptor pointing to the ASCII password. The password string can contain between 1 and 32 characters and use the uppercase characters A through Z, the numbers 0 through 9, the dollar sign ($), and the underscore (_).

The caller must validate the password string before calling $HASH_PASSWORD to ensure that only permitted characters are included.

alg

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by value

Algorithm used to hash the ASCII password string. The alg argument is an unsigned byte specifying the hash algorithm.

The operating system recognizes the following algorithms:

Symbolic Name	Description
UAI$K_AD_II	Uses a CRC algorithm and returns a longword hash value. This algorithm was used in releases prior to VAX VMS Version 2.0.
UAI$C_PURDY	Uses a Purdy algorithm over salted input. It expects a blank-padded user name and returns a quadword hash value. This algorithm was used during VAX VMS Version 2.0 field test.
UAI$C_PURDY_V	Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm was used in releases prior to VMS Version 5.4.
UAI$K_PURDY_S	Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm is used to hash all new passwords in VMS Version 5.4 and later.
UAI$C_PREFERED_ALGORITHM 1	Represents the latest encryption algorithm that the operating system uses to encrypt new passwords. Currently, it equates to UAI$C_PURDY_S. HP recommends that you use this symbol in source modules because it always equates with the most recent algorithm.

Values ranging from 128 to 255 are reserved for customer use; the constant UAI$K_CUST_ALGORITHM defines the start of this range.

You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with the $GETUAI system service to retrieve the primary and secondary password hash algorithms for a user.

salt

usrnam

hash

Description

The Hash Password service applies the hash algorithm you select to an ASCII password string and returns a quadword hash value that represents the encrypted password.

Other OpenVMS password services allow spaces, tabs, and other blank characters from the user, but they remove those spaces before passing the string to $HASH_PASSWORD. Before calling $HASH_PASSWORD, all white space must be removed from the password string to ensure proper comparison with passwords created by other services.

Required Access or Privileges

None

Required Quota

None

Related Services

$GETUAI, $SETUAI.

Use $GETUAI to get the values for the salt and alg arguments. Use $SETUAI to store the resulting hash using the item codes UAI$_PWD and UAI$_PWD2.

For more information, see the appendix on implementing site-specific security policies in the OpenVMS Programming Concepts Manual.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The input or output buffer descriptors cannot be read or written to by the caller.
SS$_BADPARAM	The specified hash algorithm is unknown or invalid.

Allows a process to make itself inactive but to remain known to the system so that it can be interrupted; for example, to receive ASTs.

Format

SYS$HIBER

C Prototype

int sys$hiber (void);

Arguments

None.

Description

The Hibernate service allows a process to make itself inactive but to remain known to the system so that it can be interrupted; for example, to receive ASTs. A hibernate request is a wait-for-wake-event request. When you call the Wake Process from Hibernation ($WAKE) service or when the time specified with the Schedule Wakeup ($SCHDWK) service occurs, the process continues execution at the instruction following the Hibernate call.

In VAX MACRO, you can call the Hibernate service only by using the $name_S macro.

A hibernating process can be swapped out of the balance set if it is not locked into the balance set.

An AST can interrupt the wait state caused by $HIBER if the access mode at which the AST is to execute is equal to or more privileged than the access mode from which the hibernate request was issued and the process is enabled for ASTs at that access mode.

When the AST service routine completes execution, the system reexecutes the $HIBER service on behalf of the process. If a wakeup request has been issued for the process during the execution of the AST service routine (either by itself or another process), the process resumes execution. If a wakeup request has not been issued, it continues to hibernate.

If one or more wakeup requests are issued for the process while it is not hibernating, the next hibernate call returns immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.

Although this service has no arguments, a Fortran function reference must use parentheses to indicate a null argument list, as in the following example:

ISTAT=SYS$HIBER()

Required Access or Privileges

None

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Responds to an incoming connection request. This call is used to complete an ICC connection from the server side.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_ACCEPT conn_handle ,[accept_buf] ,[accept_len] ,[user_context] ,[flags]

C Prototype

int sys$icc_accept (unsigned int conn_handle, char * accept_buf, unsigned int accept_len, unsigned int user_context, unsigned int flags);

Arguments

conn_handle

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

The handle of the requested connection.

accept_buf

OpenVMS usage:	byte_stream
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

A buffer of up to 1000 bytes of accept data that is sent to the source of the connection at the completion of the connection process.

accept_len

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

The actual number of bytes in accept_buf to be sent.

user_context

OpenVMS usage:	user_arg
type:	longword (unsigned) (VAX), quadword (Alpha)
access:	read only
mechanism:	by value

A user-specified value that is subsequently returned on any disconnect or data events on this connection.

flags

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

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, and that the AST will not be called.

Description

This service is used by a server to respond to an incoming connection request. The $ICC_ACCEPT service may only be called after receiving a connection request AST.

At the completion of the service, the connection is open and data can be exchanged. Once opened, there is no logical distinction between a connection opened by a client with the Connect service or a server with the Accept service.

A server can reject a Connection request by calling the $ICC_REJECT service.

Required Access or Privileges

None.

Required Quota

$ICC_ACCEPT changes the process BYTLM quota for the length of the accept_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.

Related Services

$ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_CLEARED	Remote association closed the link before it was accepted.
SS$_EXQUOTA	Exceeded BYTCNT/BYTLM.
SS$_INSFARG	Too few arguments supplied.
SS$_INSFMEM	Not enough system resources or process virtual memory available.
SS$_IVMODE	Attempted to accept a connection from a more privileged access mode than the requested association.
SS$_IVCHAN	Connection not found or Invalid connection handle.
SS$_LINKDISCON	The connection is valid, but the physical link has started to disconnect.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

Closes the application's association with ICC.

Format

SYS$ICC_CLOSE_ASSOC assoc_handle

C Prototype

int sys$icc_close_assoc (unsigned int assoc_handle);

Arguments

assoc_handle

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

The handle of the association to be closed.

Description

This service closes the application's association with ICC. If multiple associations are open, only the specified association is closed. When an association is closed, any active connections on that association are disconnected. If not explicitly closed by the application, associations opened in user mode will be closed at image exit; associations opened in inner modes will be closed at process termination.

All operations on an association must occur in the access mode at which the association was opened.

When an association is closed, the entry (if any) in the simple clusterwide association registry is removed.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$ICC_ACCEPT, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_INSFARG	The assoc_handle was not supplied.
SS$_IVCHAN	Invalid association handle.
SS$_IVMODE	Attempted to close an association from a more privileged access mode than the requested association.
SS$_TOO_MANY_ARGS	Too many arguments specified.

Establishes a connection to a remote application over an open association.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_CONNECT ios_icc ,[astadr] ,[astprm] ,assoc_handle ,conn_handle ,remote_assoc ,[remote_node] ,[user_context] ,[conn_buf] ,[conn_buf_len] ,[return_buf] ,[return_buf_len] ,[retlen_addr] ,[flags]

C Prototype

int sys$icc_connect (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle, void *remote_assoc, void *remote_node, unsigned int user_context, char *conn_buf, unsigned int conn_buf_len, char *return_buf, unsigned int return_buf_len, unsigned int *retlen_addr, unsigned int flags);

Arguments

ios_icc

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM, SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM, SS$_NOSUCHOBJ, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT, SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE

The second longword is undefined unless the completion code is SS$_REJECT. In this case, the application-defined rejection reason code is supplied by the server when $ICC_REJECT is called.

astadr

astprm

assoc_handle

conn_handle

remote_assoc

remote_node

user_context

conn_buf

conn_buf_len

return_buf

return_buf_len

retlen_addr

flags

Description

This service establishes a connection to a remote application over an open association. Connections must be opened in the same mode as their association. If the user provides the default association constant ICC$C_DFLT_ASSOC_HANDLE as its association handle, the default association will be used; it will be opened if it is not already open. Multiple connections are possible over a single association. When completion is signaled by the AST routine, the application must check the completion status field of the IOS_ICC to determine if the server has accepted or rejected the connection request. The number of connections is subject to process BYTLM quota.

At image exit, as a result of closing any open user mode associations, all user mode connections are disconnected. Inner mode connections are the responsibility of the inner mode code, but are disconnected at process termination when inner mode associations are closed. Connections are only visible to the mode in which they were opened.

A client opens connections with the $ICC_CONNECT service; a server opens connections with the $ICC_ACCEPT service.

Required Access or Privileges

SYSNAM, or access via ICC Security Object. Refer to the HP OpenVMS System Manager's Manual for more information.

Required Quota

$ICC_CONNECT changes the process BYTLM quota for the length of the conn_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.

If $ICC_OPEN_ASSOC is not called before $ICC_CONNECT, the default value of MAXFLOWBUFCNT is used (currently 5).

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_BUFFEROVF	Overflow on inbound accept or reject data.
SS$_EXQUOTA	Not enough AST quota (asynchronous request) or insufficient BYTLM/BYTCNT.
SS$_INSFARG	Too few arguments were supplied, or required arguments not supplied.
SS$_INSFMEM	Not enough system resources or process virtual memory available.
SS$_INSFP1POOL	Not enough process P1 space available.
SS$_IVBUFLEN	The length of the context data or the accept or reject data buffer is more than 1000 bytes.
SS$_IVCHAN	Invalid association handle.
SS$_IVMODE	Attempted to open a connection from a more privileged access mode than the requested association.
SS$_LINKABORT	The communications link to the target node was lost.
SS$_LINKDISCON	The communications link to the target node was lost.
SS$_NOLINKS	Too many connections open.
SS$_NOLOGNAM	The underlying layers failed to start properly during system initialization.
SS$_NOPRIV	No privilege to connect to the specified association. Connection access is granted either through an ICC security object or through the SYSNAM privilege. If no security object exists and the caller lacks the SYSNAM privilege, SS$_NOPRIV is returned rather than SS$_NOSUCHOBJ.
SS$_NOSUCHOBJ	The remote association name and/or node was not found.
SS$_NOSUCHNODE	The target node is not known.
SS$_PATHLOST	The communications link to the target node was lost.
SS$_REMRSRC	Insufficient resources at remote node.
SS$_REJECT	The remote association or node rejected the connection request.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_UNREACHABLE	Target node currently unreachable.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

Establishes a link between two ICC associations.

The $ICC_CONNECTW service completes synchronously; that is, it returns to the caller after the server has either accepted or rejected the connection request.

For asynchronous completion, use the $ICC_CONNECT service; $ICC_CONNECT returns to the caller as soon as the connection request has been sent to the server, without waiting for a response from the server.

On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_CONNECTW ios_icc, [astadr], [astprm], assoc_handle, conn_handle, remote_assoc, [remote_node], [user_context], [conn_buf], [conn_buf_len], [return_buf], [return_buf_len], [retlen_addr], [flags]

C Prototype

int sys$icc_connectw (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle, void *remote_assoc, void *remote_node, unsigned int user_context, char *conn_buf, unsigned int conn_buf_len, char *return_buf, unsigned int return_buf_len, unsigned int *retlen_addr, unsigned int flags);

Terminates the specified connection.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_DISCONNECT conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnect (unsigned int conn_handle, struct _iosb, *iosb, void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf, unsigned int disc_buf_len);

Arguments

conn_handle

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

The ID of the connection to be disconnected.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT

astadr

astprm

disc_buf

disc_buf_len

Description

This service must be called in the mode in which the association was opened.

This service terminates the specified connection. After this service is called, no further communication is possible over this connection. All outstanding data transmission and reception functions are terminated with an error before completion is signaled by calling the AST (if supplied).

A connection may be disconnected by either party. Proper programming procedure for network communications strongly recommends that the party that last received a message initiate the disconnection. If the party that last sent a message initiates the disconnection, there is no guarantee that the message was delivered.

Similarly, although this interface provides the ability to send disconnect data, only noncritical information should be transmitted with the disconnect data mechanism, because there is no guarantee that the data will have been received or acted upon by the other party to the connection.

Required Access or Privileges

None.

Required Quota

BYTLM (disc_buf)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_INSFMEM	Not enough nonpaged pool.
SS$_IVBUFLEN	The length of the disconnect data buffer is more than 1000 bytes.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to disconnect a connection from a more privileged access mode than the requested connection.
SS$_LINKDISCON	The remote association closed the connection before it was accepted or rejected.
SS$_TOO_MANY_ARGS	Too many arguments specified.

Terminates a link between two ICC associations.

The $ICC_DISCONNECTW service completes synchronously; that is, it returns to the caller after the connection has completely finished the disconnection request.

For asynchronous completion, use the $ICC_DISCONNECT service; $ICC_DISCONNECT returns to the caller as soon as the disconnection request has been sent to the transport layer, without waiting for notification that the disconnection has completed.

On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_DISCONNECTW conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnectw (unsigned int conn_handle, struct _iosb, *iosb, void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf, unsigned int disc_buf_len);

Declares an application association with ICC.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_OPEN_ASSOC assoc_handle ,[assoc_name] ,[logical_name] ,[logical_table] ,[conn_event_rtn] ,[disc_event_rtn] ,[recv_rtn] ,[maxflowbufcnt] ,[prot]

C Prototype

int sys$icc_open_assoc (unsigned int *assoc_handle, void *assoc_name, void *logical_name, void *logical_table, void (*conn_event_rtn)(__unknown_params), void (*disc_event_rtn)(__unknown_params), void (*recv_rtn)(__unknown_params), unsigned int maxflowbufcnt, unsigned int prot);

Arguments

assoc_handle

OpenVMS usage:	association_id
type:	longword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword into which $ICC_OPEN_ASSOC writes the handle assigned to the opened association.

assoc_name

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha)
mechanism:	by 32-bit descriptor (VAX)

An ASCII character string of up to 31 characters in length specifying the name of the application opening the association. Null (0 length), and empty or blank association names are not allowed. If this argument is omitted (that is, a zero is passed in by value), it signifies that the user wants to open the default association. This argument is case sensitive.

logical_name

OpenVMS usage:	logical name
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha)
mechanism:	by 32-bit descriptor (VAX)

A logical name in a clusterwide logical name table used to maintain the simple association registry. The logical name represents the name of the service provided by the application. Logical names are case sensitive.

logical_table

OpenVMS usage:	logical name table
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha)
mechanism:	by 32-bit descriptor (VAX)

The table containing the logical name logical_name. Logical name tables are converted to uppercase. Unless your application requires an application-specific logical name table, this argument should be either the default ICC Registry search list (ICC$REGISTRY), or the default registry table (ICC$REGISTRY_TABLE).

conn_event_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The address of the AST routine to be called for incoming connect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

You must have a conn_event_rtn to operate as a server.

disc_event_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The address of the AST routine to be called for incoming disconnect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode). The arguments, conn_event_rtn, and disc_event_rtn, may reference the same routine.

recv_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha)
mechanism:	by 32-bit reference (VAX)

The address of the AST routine to be called for incoming new data events.

If the user provides this routine, it indicates that the user will supply a buffer of the size required (specified in an argument to the recv_rtn at each call) each time one is requested. If the user supplies this routine, receive calls should only be issued after receive events arrive and sufficient buffer space has been allocated to handle the incoming data.

This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

maxflowbufcnt

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

The maximum number of pending inbound messages (per connection) that ICC will allow the user before initiating flow control. A message is pending if it is being held within ICC but no receive call(s) are outstanding from the user.

Default = 5 (Pass 0 to get the default)

prot

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

This argument is ignored for non-server applications.

The default protection scheme for this association is as follows:

0 - access for everyone (default)
1 - stops WORLD access
2 - stops both WORLD and GROUP access

Advanced access control is provided by ICC Security objects. Refer to the HP OpenVMS System Manager's Manual for information on ICC system management and security.

Description

This service declares an application association with ICC. Servers must make this call to declare or register their name and to indicate their readiness to receive incoming connections. Although a client is permitted to call this routine, it is unnecessary for simple applications. A client application that wishes to be notified of disconnection events or Receive Data events must call the $ICC_OPEN_ASSOC service.

A client can open a connection without specifying an open association; this automatically creates a default association name of ICC$PID_nnnnnnnn (where nnnnnnnn is a character representation of the Process ID).

NETMBX privilege is required to open any association.

The association name space is a controlled resource. Refer to the HP OpenVMS System Manager's Manual for information on managing this resource.

An attempt to open an association with a name not authorized as described in the HP OpenVMS System Manager's Manual will fail with the error SS$_NOPRIV returned to the caller. In addition to making entries in the system's local association name space, a call to $ICC_OPEN_ASSOC may also make an entry in a simple clusterwide registry of active associations.

An association may only be accessed from the mode in which it was opened. Inner modes are prevented from using the default association.

An application can open any number of associations subject to available process BYTLM quota. Currently, there is a systemwide limit of 512 open associations. There is no limit imposed clusterwide.

Description of User-Supplied Routines (ASTs)

When opening an association, the user may optionally supply a connect/disconnect AST and/or a Data Event AST. These routines will be used for all connections established over the specified association. In addition, for any of the asynchronous services (those provided with both an immediate return and a "W" form), a completion AST may be supplied by the user. This section describes these ASTs.

1. Connect and Disconnect AST

The user chooses the name of this routine and supplies the procedure name as an argument to the Open Association service. Seven arguments will be passed to the user.

The first argument notifies the user whether this is an incoming new connection or a disconnection of an existing connection. The second identifies the connection. The third and fourth provide access to incoming connect or disconnect data (if any) sent by the cooperating application. The fifth argument provides the number of bytes available for any optional Accept or Reject data (in the case of a connect request) or the disconnect reason supplied by the cooperating application (if any).

For connect events, the sixth and seventh arguments are the EPID and user name of the process requesting the connect, respectively.

The user has the choice of using and declaring a common routine or separate routines as specified when calling $OPEN_ASSOCIATION.

Format

ConnDiscRtn event_type ,conn_handle ,data_len ,data_bfr ,P5 ,P6 ,P7

C Prototype

void ConDiscRtn (unsigned int event_type, unsigned int conn_handle, unsigned int data_len, char *data_bfr, unsigned int P5, unsigned int P6, char *P7);

Arguments

event_type Type: longword (unsigned) Access: read only Mechanism: by value

This field will contain a code describing the type of event. The possible event codes are defined in ICCDEF:

ICC$C_EV_CONNECT - Connection event ICC$C_EV_DISCONNECT - Disconnection event

conn_handle Type: longword (unsigned) Access: read only Mechanism: by value

The handle of the connection associated with the event.

data_len Type: longword (unsigned) Access: read only Mechanism: by value

The length (in bytes) of the incoming data. This value specifies the length of the buffer data_bfr, and will be between 0 and 1000, with zero indicating no data.

data_bfr Type: character-coded text string Access: read only Mechanism: by 32-bit or 64-bit value (Alpha) by 32-bit value (VAX)

The 32-bit address of the P1-space buffer containing the data, or zero if no data is available. The length of this buffer is specified by the argument data_len.

Upon return from the AST, the address of the data is no longer valid. An application wishing to reference the Connection or Disconnection data after Return must copy the data from the supplied buffer to storage owned by the application.

P5 Type: longword (unsigned) Access: read only Mechanism: by value

The usage of this argument is dependent on the specified event type code (event_type).

For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the length (in bytes) of the buffer available for a reply.

For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined disconnect reason/status from the remote partner.

P6 Type: longword (unsigned) (VAX), quadword (Alpha) Access: read only Mechanism: by value

The usage of this argument is dependent on the specified event type code (event_type).

For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the EPID of the process requesting the connection, passed by value.

For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined user_context supplied when the connection was opened. For a client, the user_context is that supplied to the $ICC_CONNECT call. For a server, it is the value supplied to $ICC_ACCEPT.

P7 Type: character-coded text string Access: read only Mechanism: by reference

For connect events: Username, passed by reference (to P1 space buffer) as a 12-character, space-filled string.

The application must copy this information to local storage before exiting from the connect routine.

For disconnect events, this argument is zero (0).

2. Data Event Routine

This routine, if supplied by the user when opening the association, allows the user to be notified of any pending data events over any connections subsequently opened over that association.

If the user has supplied this routine, the Receive service must only be called in response to incoming data events signaled by this routine, and must be called with a buffer large enough to handle the message size specified.

Use of this routine obligates the user to allocate buffers up to the size requested by the cooperating application. The only recovery provided at this time if a sufficiently large buffer cannot be allocated is to disconnect the connection. Failure to issue a receive call or disconnect may stall all further communication on this connection.

Format

DataEventRtn message_size ,conn_handle ,user_context

C Prototype

void DataEventRtn (unsigned int message_size, unsigned int conn_handle, unsigned int user_context);

Arguments

message_size Type: longword (unsigned) Access: read only Mechanism: by value

This field will contain the number of bytes in the pending data event.

conn_handle Type: longword (unsigned) Access: read only Mechanism: by value

The handle of the connection associated with the event. This value should be used as the conn_handle argument to $ICC_RECEIVE.

user_context Type: longword (unsigned) (VAX), quadword (Alpha) Access: read only Mechanism: by value

The user-defined user_context supplied when the connection was opened. For a client, the user context is that supplied to the $ICC_CONNECT call. For a server, it is the value supplied to $ICC_ACCEPT.

3. Completion ASTs

Completion ASTs may be supplied to the $ICC_CONNECT[W], $ICC_DISCONNECT[W], $ICC_TRANSMIT[W], $ICC_RECEIVE[W], $ICC_TRANSCEIVE[W], and $ICC_REPLY[W] services. In all cases, they are called at the completion of the requested operation, with the single argument, the AST parameter supplied when the original service was called, passed by value.

Completion ASTs are not called if the service returns an error prior to initiating the operation. $ICC_CONNECT and $ICC_ACCEPT accept the flag ICC$V_SYNCH_MODE which indicates that the routines $ICC_TRANSMIT[W], $ICC_RECEIVE[W], and $ICC_REPLY[W] are permitted to return the status SS$_SYNCH, which will indicate that completion has already occurred and the AST will not be called.

Required Access or Privileges

Refer to the HP OpenVMS System Manager's Manual for more information.

Required Quota

BYTCNT, BYTLM

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_DUPLNAM	Specified association name is already registered (already exists), or default association is already open.
SS$_EXQUOTA	One or more process quotas has been exceeded (probably BYTCNT/BYTLM).
SS$_INSFARG	Too few arguments supplied.
SS$_INSFMEM	Not enough system resources or process virtual memory available.
SS$_IVMODE	Attempt to open default association from other than user mode.
SS$_NOLINKS	Too many associations open for this process.
SS$_NONETMBX	Request requires NETMBX privilege.
SS$_NOPRIV	No privilege for association name access or logical name table access if using the Registry.
SS$_SSFAIL	Transport association name table is full, systemwide.
SS$_TOO_MANY_ARGS	Too many arguments were specified. Any failures from the system services: $ENQ, $DEQ, $CRELNM, $TRNLNM.

Receives a single message over a connection.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_RECEIVE conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

sys$icc_receive (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *recv_buf, unsigned int recv_buf_len);

Arguments

conn_handle

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

The handle of the fully established connection.

ios_icc

OpenVMS usage:	io_status_block
type:	four longwords (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion codes:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL, SS$_ACCVIO

astadr

astprm

recv_buf

recv_buf_len

IOS_ICC Arguments:

recvlen (output)

request_handle (output)

reply_len (output)

Description

This service receives a single message over a connection. If a Request ID is returned at completion, the partner has used a Transceive system service and requires data to be returned with a Reply service.

For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional values are returned by the ios_icc data structure.

Required Access or Privileges

None.

Required Quota

BYTLM

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_EXBYTLM	Insufficient byte count quota.
SS$_EXQUOTA	One or more process quotas has been exceeded.
SS$_INSFARG	Too few arguments supplied.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to use a connection from a more privileged access mode than the mode in which it was opened.
SS$_LINKDISCON	The connection has been disconnected.
SS$_SYNCH	If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

The Intra-Cluster Communications Receive and Wait service queues a receive request to the specified connection.

The $ICC_RECEIVEW service completes synchronously; that is, it returns to the caller with data.

For asynchronous completion, use the $ICC_RECEIVE service; $ICC_RECEIVE returns to the caller as soon as the receive request is queued, without waiting for data on the connection.

On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_RECEIVEW conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

sys$icc_receivew (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *recv_buf, unsigned int recv_buf_len);

Refuses a connection request.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_REJECT conn_handle, [reject_buf], [reject_buf_len], [reason]

C Prototype

int sys$icc_reject (unsigned int conn_handle, char * reject_buf, unsigned int reject_buf_len, unsigned int reason);

Arguments

conn_handle

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

The handle of the requested connection.

reject_buf

OpenVMS usage:	byte_stream
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

A buffer of up to 1000 bytes of reject data to be sent to the source of the connection at the completion of the rejection process.

reject_buf_len

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

The number of bytes in reject_buf to be sent.

reason

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

User-specified reject reason code to be supplied to the remote application.

Default = SS$_REJECT

Description

This service is used by a server to refuse an incoming connection request. The $ICC_REJECT service may only be called after receiving a connection request AST. After the completion of the service, the client is notified that the connection was not opened.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_CLEARED	Remote association closed the link before it was rejected.
SS$_INSFARG	Too few arguments supplied.
SS$_IVCHAN	Connection not found or Invalid connection handle.
SS$_LINKDISCON	The transport layer has initiated disconnect before the Reject could be sent to the requester.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_WRONGSTATE	Connection is already open and cannot be rejected. To close the connection, call $ICC_DISCONNECT.

Sends a single message over a connection. This service is used in response to the reception of a Request Handle in a previous $ICC_RECEIVE system service.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_REPLY conn_handle ,ios_icc ,[astadr] ,[astprm] ,reply_buf ,reply_len

C Prototype

sys$icc_reply (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *reply_buf, unsigned int reply_len);

Arguments

conn_handle

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

The handle of the fully established connection.

ios_icc

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	modify
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON

astadr

astprm

reply_buf

reply_len

The maximum Reply length is the smaller of the Reply buffer size supplied in the $ICC_RECEIVE call, or 1MB.

IOS_ICC Argument:

request_handle (input)

Description

This service is almost identical to the $ICC_TRANSMIT system service in that it sends a single message over a connection. The only difference is that it is used in response to the reception of a Request Handle in a previous Receive Data system service.

When completion is signaled by calling the AST (if supplied), the data has been delivered to the communications system, but not necessarily to the application at the other end of the connection. The user can reuse the buffer after completion has been signaled.

Alternatively, if the synchronous completion option was requested at connection time, the service may return the optional success status, SS$_SYNCH. When SS$_SYNCH is returned, completion has occurred, and no AST will be delivered.

Required Access or Privileges

None.

Required Quota

BYTLM (for Reply buffer)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_EXBYTLM	Insufficient byte count quota.
SS$_INSFARG	Too few arguments supplied.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to use a connection from a more privileged access mode than the mode in which it was opened.
SS$_LINKDISCON	An Incoming disconnect event is already in progress.
SS$_NOSUCHID	The request_handle is invalid.
SS$_SYNCH	If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

The Intra-Cluster Communications Reply and Wait service transmits a single message over a connection in response to a $ICC_TRANSCEIVE[W] request.

The $ICC_REPLYW service completes synchronously; that is, it returns to the caller when the underlying transport layer has released use of the reply buffer.

For asynchronous completion, use the $ICC_REPLY service; $ICC_REPLY returns to the caller as soon as the transmission request has been queued to the transport layer, without waiting for notification that the transport layer has released control of the data buffer.

On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_REPLYW conn_handle, ios_icc, [astadr], [astprm], reply_buf, reply_len

C Prototype

sys$icc_replyw (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *reply_buf, unsigned int reply_len);

Sends a single message over a connection and then waits for a reply.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSCEIVE conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transceive (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

Arguments

conn_handle

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

The handle of the fully established (open) connection.

ios_icc

OpenVMS usage:	io_status_block
type:	five longwords (unsigned)
access:	modify
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_BUFOVFL, SS$_LINKABORT, SS$_LINKDISCON

astadr

astprm

send_buf

send_len

IOS_ICC Arguments:

returned_data_len (output)

reply_buf (input)

reply_buf_len (input)

Description

This service sends a single message over a connection and then waits for a reply. When completion is signaled by calling the AST (if supplied), the data has been delivered to the application at the other end of the connection and that application has delivered a reply, now present in the reply buffer. The user can reuse the send and reply buffers after completion.

For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional parameters are passed by the ios_icc data structure.

Required Access or Privileges

None.

Required Quota

BYTLM (Send and Reply buffers)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_EXBYTLM	Insufficient byte count quota.
SS$_INSFARG	Too few arguments were supplied.
SS$_INSFMEM	Insufficient process or system memory to complete the request.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to use a connection from a more privileged access mode than the mode in which it was opened.
SS$_LINKDISCON	An Incoming disconnect event is in progress.
SS$_SYNCH	If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.
SS$_TOO_MANY_ARGS	Too many arguments were specified.
SS$_WRONGSTATE	Connection is in wrong state for request.

Sends a single message over a connection and waits for a reply.

The $ICC_TRANSCEIVEW service completes synchronously; that is, it returns to the caller when the data from the reply is available.

For asynchronous completion, use the $ICC_TRANSCEIVE service; $ICC_TRANSCEIVE returns to the caller when the transmit portion of the tranceive request has been queued to the transport layer, but without waiting for notification that the transport layer has released control of the data buffer or for the reply data from the receiving end of the connection.

On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSCEIVEW

conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transceivew (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

Sends a single message over a connection.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSMIT conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transmit (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

Arguments

conn_handle

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

The handle of the fully established (open) connection to send the data over.

ios_icc

OpenVMS usage:	ios_status_block
type:	structure IOS_ICC
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON

astadr

astprm

send_buf