OpenVMS System Services Reference Manual

Document revision date: 15 July 2002

OpenVMS System Services Reference Manual

Contents

Index

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

Returns physical page read I/O's.

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

RMI$_PREADS

Returns the number of pages read.

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

RMI$_PWRITES

Returns the number of pages written.

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

RMI$_PWRITIO

Returns physical page write I/O's.

This number is a longword, therefore 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$_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).

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.

$GETSYI

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:

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETSYI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length field is too small, $GETSYI truncates the data.

Item code A word containing a user-supplied symbolic code specifying the item of information that $GETSYI is to return. The $SYIDEF macro defines these codes. A description of each item code is given in the Item Codes section.

Buffer address A longword containing the user-supplied 32-bit address of the buffer into which $GETSYI is to write the information.

Return length address A longword containing the user-supplied 32-bit address of a word in which $GETSYI writes the length in bytes of the information it actually returned.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETSYI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length field is too small, $GETSYI truncates the data.
Item code	A word containing a user-supplied symbolic code specifying the item of information that $GETSYI is to return. The $SYIDEF macro defines these codes. A description of each item code is given in the Item Codes section.
Buffer address	A longword containing the user-supplied 32-bit address of the buffer into which $GETSYI is to write the information.
Return length address	A longword containing the user-supplied 32-bit address of a word in which $GETSYI writes the length in bytes of the information it actually returned.

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:

Descriptor Field Definition

MBO The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.

Item code A word containing a user-supplied symbolic code specifying the item of information that $GETSYI is to return. The $SYIDEF macro defines these codes. A description of each item code is given in the Item Codes section.

MBMO The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.

Buffer length A quadword containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETSYI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length is too small, $GETSYI truncates the data.

Buffer address A quadword containing the user-supplied 64-bit address of the buffer into which $GETSYI is to write the information.

Return length address A quadword containing the user-supplied 64-bit address of a word in which $GETSYI writes the length in bytes of the information it actually returned.

Descriptor Field	Definition
MBO	The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code	A word containing a user-supplied symbolic code specifying the item of information that $GETSYI is to return. The $SYIDEF macro defines these codes. A description of each item code is given in the Item Codes section.
MBMO	The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer length	A quadword containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETSYI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length is too small, $GETSYI truncates the data.
Buffer address	A quadword containing the user-supplied 64-bit address of the buffer into which $GETSYI is to write the information.
Return length address	A quadword containing the user-supplied 64-bit address of a word in which $GETSYI writes the length in bytes of the information it actually returned.

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

iosb

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

I/O status block to receive the final completion status. The iosb argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of the quadword I/O status block.

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, Compaq strongly recommends that you specify it, for the following reasons:

If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $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

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

AST service routine to be executed when $GETSYI completes. The astadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of this routine.

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

astprm

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

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

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

5 21164

6 21064A

7 21164A

8 21264

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.

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

Processor Code	Processor
2	21064
4	21066
5	21164
6	21064A
7	21164A
8	21264

SYI$_DECIMAL_EMULATED

Returns the number 1 if the decimal 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$_DECNET_FULLNAME

Returns, as a character string, the DECnet for OpenVMS full name of the node.

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

Returns the number 1 if the D_floating instructions are emulated on the CPU and 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$_DEF_PRIO_MAX

On Alpha systems, returns the maximum priority for the default scheduling policy.

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

SYI$_DEF_PRIO_MIN

On Alpha systems, returns the minimum priority for the default scheduling policy.

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

SYI$_ERLBUFFERPAGES

Returns the number of pages (on VAX systems) or pagelets (on Alpha systems) in an error log buffer.

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

SYI$_ERRORLOGBUFFERS

Returns the number of system pages (on VAX systems) or pagelets (on Alpha systems) in use as buffers for the error logger.

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

SYI$_F_FLOAT_EMULATED

Returns the number 1 if the F_floating instructions are emulated on the CPU and 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$_FREE_GBLPAGES

Returns the current number of free global pages. The system parameter GBLPAGES sets the number of global pages that can exist systemwide.

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

SYI$_FREE_GBLSECTS

Returns the current number of free global section table entries. The system parameter GBLSECTIONS sets the maximum number of global sections that can exist systemwide.

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

SYI$_G_FLOAT_EMULATED

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

Contents

Index

privacy and legal statement

4527PRO_064.HTML

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.

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

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

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)

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)