$GETSYI
$GETSYI, or Get Systemwide Information, is a system service that 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 and Integrity server systems, this service accepts 64-bit addresses.
Contents
Description
The Get Systemwide Information service returns information about the local system or about other systems in an OpenVMS Cluster configuration.
Syntax
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.
VSI strongly recommends the use of the EFN$C_ENF "no event flag" value as the event flag if you are not using an event flag to externally synchronize with the completion of this system service call. The $EFNDEF macro defines EFN$C_ENF. For more information, see the [VSI OpenVMS Programming Concepts Manual].
csidadr
| OpenVMS usage: | process_id |
| Type: | longword (unsigned) |
| Access: | modify |
| Mechanism: | by 32- or 64-bit reference |
Cluster identification of the node about which $GETSYI is to return information. The csidadr argument is the 32- or 64-bit address 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 |
Name of the node about which $GETSYI is to return information. The nodename argument is the 32- or 64-bit address 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.
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 |
Item list specifying which information is to be returned about the node or nodes. The itmlst argument is the 32- or 64-bit address 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 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 upon 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 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 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. |
iosb
| OpenVMS usage: | io_status_block |
| Type: | quadword (unsigned) |
| Access: | write only |
| Mechanism: | by 32- or 64-bit reference |
I/O status block to receive the final completion status. The iosb argument is the 32- or 64-bit address 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, VSI 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 |
AST service routine to be executed when $GETSYI completes. The astadr argument is the 32- or 64-bit address 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
| Item | Description | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SYI$_ACTIVE_CPU_BITMAP | The return argument is a bitmap with a bit indicating a member of the instance's active – those currently participating in the OpenVMS SMP scheduling activities.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: Use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_ACTIVE_CPU_MASK | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_ACTIVE_CPU_BITMAP instead.
On Alpha and Integrity server 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, one of three strings is returned: "Alpha" for Alpha, "VAX" for VAX, or "IA64" for Integrity servers. 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 , 2 on Alpha, and 3 on Integrity servers.
As this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_AVAIL_CPU_BITMAP | The return argument is a bitmap with a bit indicating a member of the instance's configure set — those owned by the partition and controlled by the issuing instance.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: Use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_AVAIL_CPU_MASK | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_AVAIL_CPU_BITMAP instead.
On Alpha and Integrity server 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$_BOOT_DEVICE | Returns the name of the device from which the system was booted as a character string. For a system with a shadowed system disk, SYI$_BOOT_DEVICE returns the name of the member device from which the shadow set was formed. | ||||||||||||||||||||||||||||||||||
| 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 and Integrity server 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 | As the processor type is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes). On Alpha and Integrity server 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 and Integrity server systems, returns a list of zeroes and ones, separated by commas 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 and Integrity server 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 | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_AVAIL_CPU_BITMAP instead.
On Alpha and Integrity server 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$_CPUTYPE | On Alpha and Integrity server 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:
| ||||||||||||||||||||||||||||||||||
| 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 | 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 and Integrity server 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 and Integrity server 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 pagelets 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 pagelets 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.
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 | On Alpha systems, returns the 128-bit Galaxy ID. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GALAXY_MEMBER | On Alpha systems, returns 1 if you are member of a Galaxy sharing community, 0 if you are not a member. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GALAXY_PLATFORM | On Alpha systems, returns 1 if you are running on a Galaxy platform, 0 if you are not running on a Galaxy platform. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GALAXY_SHMEMSIZE | On Alpha systems, returns the number of shared memory pages. If the current instance is not a member of a Galaxy, no shared memory is reported. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GH_RSRVPGCNT | On Alpha and Integrity server systems, returns the number of pages covered by granularity hints to reserve for use by the Install utility after system startup has completed.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_GLX_FORMATION | On Alpha systems, returns the a time-stamp string when the Galaxy configuration, of which this instance is a member, was created. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GLX_MAX_MEMBERS | On Alpha systems, returns the maximum count of instances that may join the current Galaxy configuration. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GLX_MBR_MEMBER | On Alpha systems, returns the 64-byte integer. Each 8 bytes represents a Galaxy member number, listed from 7 to 0. The value is 1 if the instance is currently a member, 0 if not a member. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_GLX_MBR_NAME | On Alpha systems, returns a string indicating the names that are known in the Galaxy membership. Returned names are separated by two spaces, with an additional two spaces following the last name in the list. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| YI$_GLX_TERMINATION | On Alpha systems, returns a time-stamp string when the Galaxy configuration, of which this instance last was a member, was terminated. Supported only on AlphaServer GS series systems. | ||||||||||||||||||||||||||||||||||
| SYI$_H_FLOAT_EMULATED | Returns the number 1 if the H_floating 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$_HP_ACTIVE_CPU_CNT | Returns the number of active CPUs in this hard partition that are not currently in firmware console mode. For OpenVMS, this implies that the CPU is in, or in the process of joining, the active set in one of the instances in the hard partition. Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_HP_ACTIVE_SP_CNT | Returns the count of active operating system instances currently executing within the hard partition.
Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_HP_CONFIG_SBB_CNT | Returns a count of the existing system building blocks within the current hard partition. Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_HP_CONFIG_SP_CNT | Returns the maximum count of soft partitions within the current hard partition. This count does not imply that an operating system instance is currently running within any given soft partition. Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_HW_MODEL | Returns a small integer that can be used to identify the model type of the node.
An integer greater than 1023 indicates an Alpha and Integrity servers 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. Because SYI$_HW_MODEL is a word, the buffer length field in the item descriptor should specify 2 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_HW_NAME | Returns the model name string of the node. The model name is a character string that describes the model of the node . The model name usually corresponds to the nameplate that appears on the outside of the CPU cabinet.
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). An example of an Integrity servers processor follows: HP rx4640 (1.10GHz/4.0MB) The following table lists the Alpha model processor names and the corresponding model types.
| ||||||||||||||||||||||||||||||||||
| SYI$_IO_PRCPU_BITMAP | The return argument is a bitmap with a bit indicating a preferred CPU -- one available for Fast Path operations.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_IO_PREFER_CPU | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_IO_PRCPU_BITMAP instead.
On Alpha and Integrity server systems, returns the bit mask of CPUs available to be Fast Path preferred CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. | ||||||||||||||||||||||||||||||||||
| SYI$_ITB_ENTRIES | On Alpha and Integrity server systems, returns the number of instruction stream translation buffer entries that support granularity hints to be allocated for resident code.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_MAX_CPUS | On Alpha and Integrity server systems, returns the maximum number of CPUs that could be recognized by this instance. | ||||||||||||||||||||||||||||||||||
| SYI$_MAX_PFN | Returns the highest numbered PFN in use by the operating system. The highest numbered PFN used by OpenVMS is influenced by the PHYSICAL_MEMORY system parameter.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_MEMSIZE | Returns the total number of pages of physical memory in the system configuration.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_NODE_AREA | Returns the DECnet area of the node.
Because the DECnet area is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_NODE_CSID | Returns the OpenVMS Cluster system ID (CSID) of the node. The CSID is a longword hexadecimal number assigned to the node by the cluster management software.
Because the CSID is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_NODE_EVOTES | Returns the number of votes the node expects to find in the OpenVMS Cluster system. This number is determined by the system parameter EXPECTED_VOTES.
Because the number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_NODE_HWVERS | When you specify SYI$_NODE_HWVERS, $GETSYI returns the hardware version of the node.
The high word of the buffer length contains the CPU type. The $VAXDEF and $ALPHADEF macros define the CPU types. 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 | Returns the DECnet for OpenVMS number of the node.
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 | Returns the value (in decimal) of the quorum held by the node. This number is derived from the node's 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$_NODE_SWINCARN | Returns the software incarnation of the node.
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 | Returns the software type of the node. The software type indicates whether the node is an Alpha or Integrity servers system, or an HSC storage controller.
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 | Returns the software version of the node.
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 | Returns the system identification of the node.
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 | Returns the number (in decimal) of votes held by the node. This number is determined by the node's system parameter VOTES.
Because this number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_NODENAME | Returns, as a character string, the name of the node in the buffer specified in the item list.
Because this name can include up to 15 characters, the buffer length field in the item descriptor should specify 15 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PAGEFILE_FREE | Returns the number of free pages in the currently installed page files.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PAGEFILE_PAGE | Returns the number of pages in the currently installed page files.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PAGE_SIZE | Returns the number of CPU-specific bytes per page in the system.
On Alpha and Integrity server systems, CPU page size varies from system to system. On Alpha and Integrity servers, because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PARTITION_ID | On Alpha and Integrity server systems, returns the soft partition ID. Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_PFN_MEMORY_MAP (Alpha Only) | Returns a map describing the system's use of physical memory. Figure 1 shows an example of a physical 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, VSI 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:
| ||||||||||||||||||||||||||||||||||
| SYI$_PFN_MEMORY_MAP_64 (Alpha and Integrity servers) | Returns a map describing the system's use of physical memory on Alpha and Integrity servers only.
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 PMM64$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, VSI 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 = (PMM64$C_LENGTH * ret-val) + 4 where:
| ||||||||||||||||||||||||||||||||||
| SYI$_PHYSICALPAGES | Returns the total number of PFNs that exist between the first PFN (typically PFN 0) and the highest numbered PFN.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PMD_COUNT | Returns the total number of physical memory descriptors defined by the system. The return value of this parameter can be used to determine the buffer size to use when specifying the SYI$_PFN_MEMORY_MAP item code.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_POTENTIAL_CPU_BITMAP | The return argument is a bitmap with a bit indicating a member of the instance's potential set. A CPU in the potential set implies that it could actively join the OpenVMS active set for this instance if it is ever owned by it. To meet this rule the CPU's characteristics must match hardware and software compatibility rules defined particularly for that instance.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: Use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_POTENTIAL_CPU_MASK | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_POTENTIAL_CPU_BITMAP instead.
On Alpha and Integrity server systems, returns a value that represents a CPU-indexed bit vector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's potential set. A CPU in the potential set implies that it could actively join the OpenVMS active set for this instance if it is ever owned by it. To meet this rule, the CPU's characteristics must match hardware and software compatibility rules defined particularly for that instance. | ||||||||||||||||||||||||||||||||||
| SYI$_POTENTIALCPU_CNT | On Alpha and Integrity server systems, returns the count of CPUs in the hard partition that are members of the potential set for this instance. A CPU in the potential set implies that it could actively join the OpenVMS active set for this instance if it is ever owned by it. To meet this rule the CPU's characteristics must match hardware and software compatibility rules defined particularly for that instance. | ||||||||||||||||||||||||||||||||||
| SYI$_POWERED_CPU_BITMAP | The return argument is a bitmap with a bit indicating a member of the instance's powered set – those CPUs physically existing within the hard partition and powered up for operation.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: Use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_POWERED_CPU_MASK | Note that this item code is becoming obsolete; VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_POWERED_CPU_BITMAP instead.
On Alpha and Integrity server 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 powered set – those CPUs physically existing within the hard partition and powered up for operation. | ||||||||||||||||||||||||||||||||||
| SYI$_POWEREDCPU_CNT | On Alpha and Integrity server systems, returns the count of CPUs in the hard partition that are physically powered up. | ||||||||||||||||||||||||||||||||||
| SYI$_PRESENT_CPU_BITMAP | The return argument is a bitmap with a bit indicating a member of the instance's present set – those CPUs physically existing within the hard partition. Being in the present set does not imply that it is part of the powered set.
The size of the returned bitmap is determined by the number of supported CPUs on the system. You can compute the number of bytes needed for the bitmap as follows: use the $GETSYI system service with an item code of SYI$_MAX_CPUS to find the minimum number of bits needed, round this number up to a multiple of 64, and divide the result by 8. | ||||||||||||||||||||||||||||||||||
| SYI$_PRESENT_CPU_MASK | Note that this item code is becoming obsolete, and VSI recommends that you not use it because it represents only up to 64 CPUs. The service continues to return the correct data for systems with up to 64 CPUs but fails for systems with more than 64 CPUs. For greater flexibility, use item code SYI$_PRESENT_CPU_BITMAP instead.
On Alpha and Integrity server 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 present set – those CPUs physically existing within the hard partition. Being in the present set does not imply that it is part of the powered set. | ||||||||||||||||||||||||||||||||||
| SYI$_PRESENTCPU_CNT | On Alpha and Integrity server systems, returns the count of CPUs in the hard partition that physically reside in a hardware slot. | ||||||||||||||||||||||||||||||||||
| SYI$_PRIMARY_CPUID | On Alpha and Integrity server systems, returns the CPU ID of the primary processor for this OpenVMS instance. | ||||||||||||||||||||||||||||||||||
| SYI$_PROCESS_SPACE_LIMIT | On Alpha and Integrity server systems, this item code returns the 64-bit virtual address succeeding the last available process private address. The value returned is the upper bound on the process private address space. The value returned is the same for every process on the system.
Because this number is a quadword, the buffer length field in the item descriptor should specify 8 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PSXFIFO_PRIO_MAX
On Alpha and Integrity server systems, returns the maximum priority for the POSIX FIFO scheduling policy. Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | |||||||||||||||||||||||||||||||||||
| SYI$_PSXFIFO_PRIO_MIN
On Alpha and Integrity server systems, returns the minimum priority for the POSIX FIFO scheduling policy. Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | |||||||||||||||||||||||||||||||||||
| SYI$_PSXRR_PRIO_MAX | On Alpha and Integrity server systems, returns the maximum priority for the POSIX round-robin scheduling policy.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PSXRR_PRIO_MIN | On Alpha and Integrity server systems, returns the minimum priority for the POSIX round-robin scheduling policy.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PT_BASE | On Alpha and Integrity server systems, returns the 64-bit virtual address of the base of the page tables. The value returned is the same for every process on the system.
Because this number is a quadword, the buffer length field in the item descriptor should specify 8 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_PTES_PER_PAGE | On Alpha and Integrity server systems, returns the maximum number of CPU-specific pages that can be mapped by one page table page.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_RAD_CPUS | On Alpha and Integrity server systems, returns a longword array of RAD/CPU pairs that can potentially be in this operating system instance. If there is no RAD support, all potential CPUs are in RAD 0. The array is terminated with a -1,-1 pair.
RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers. | ||||||||||||||||||||||||||||||||||
| SYI$_RAD_MEMSIZE | On Alpha and Integrity server systems, returns a longword array of RAD/page count pairs. The number of pages of private memory is returned. If there is no RAD support, all memory is reported in
RAD 0. The array is terminated with a -1,-1 pair. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers. | ||||||||||||||||||||||||||||||||||
| SYI$_RAD_MAX_RAD | On Alpha and Integrity server systems, returns the maximum number of RADs possible on this platform. If there is no RAD support, 1 is returned.
RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers. | ||||||||||||||||||||||||||||||||||
| SYI$_RAD_SHMEMSIZE | On Alpha and Integrity server systems, returns a longword array of RAD/page count pairs. The number of pages of shared memory is returned. If th ere is no RAD support, all shared memory is reported in RAD 0. If the current instance is not a member of a Galaxy, no shared memory is reported. The array is terminated with a -1,-1 pair.
RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers. | ||||||||||||||||||||||||||||||||||
| SYI$_REAL_CPUTYPE | Returns the actual CPU type of the primary CPU of the system.
See the SYI$_CPUTYPE item code for a list of symbols and processors. | ||||||||||||||||||||||||||||||||||
| SYI$_SCSNODE | Returns the Galaxy instance name. Supported only on AlphaServer systems that support partitioning. | ||||||||||||||||||||||||||||||||||
| SYI$_SCS_EXISTS | Returns a longword value that is interpreted as Boolean. If the value is 1, the System Communication Subsystem (SCS) is currently loaded on the node; if the value is 0, the SCS is not currently loaded. | ||||||||||||||||||||||||||||||||||
| SYI$_SERIAL_NUMBER | Returns the system serial number from out of the Hardware Restart Parameter Block (HWRPB). | ||||||||||||||||||||||||||||||||||
| SYI$_SHARED_VA_PTES | On Alpha and Integrity server systems, returns the 64-bit virtual address of the PTE that marks the boundary between process-private PTEs and system-shared PTEs. The value returned is the same for
every process on the system. Because this number is a quadword, the buffer length field in the item descriptor should specify 8 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_SID | Returns the contents of the system identification register of the node.
On Alpha and Integrity server 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 | Returns the number of free pages in the currently installed swapping files.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_SWAPFILE_PAGE | Returns the number of pages in the currently installed swapping files.
Because this number is a longword, the buffer length field in the item descriptor should specify 4 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_SYSTEM_RIGHTS | Returns the system rights list as an array of quadword identifiers. Each entry consists of a longword identifier value and the following longword identifier attributes:
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$_SYSTEM_UUID | On Integrity server systems, returns the Universal Unique Identifier (UUID) for the system. If the UUID is not supported or is not available, a null UUID (all zeroes) is returned.
Because SYI$_SYSTEM_UUID is 128 bits long, the buffer length field in the item descriptor must specify 16 bytes. | ||||||||||||||||||||||||||||||||||
| SYI$_SYSTYP | On Alpha and Integrity server systems, returns the name of the family or system hardware platform.
For example, the integer 2 represents a DEC 4000 processor, the integer 3 represents a DEC 7000 or DEC 10000 processor, and the integer 4 represents a DEC 3000 processor. | ||||||||||||||||||||||||||||||||||
| SYI$_VERSION | Returns, as a character string, the software version number of the OpenVMS operating system running on the node.
Because the version number is 8-byte blank-filled, the buffer length field in the item descriptor should specify 8 (bytes). | ||||||||||||||||||||||||||||||||||
| SYI$_VECTOR_EMULATOR | Returns a byte, the low-order bit of which, when set, indicates the presence of the Vector Instruction Emulator facility (VVIEF) in the system. | ||||||||||||||||||||||||||||||||||
| SYI$_VP_MASK | Returns a longword mask, the bits of which, when set, indicate which processors in the system have vector coprocessors. | ||||||||||||||||||||||||||||||||||
| SYI$_VP_NUMBER | Returns an unsigned longword containing the number of vector processors in the system. | ||||||||||||||||||||||||||||||||||
| SYI$_XCPU | Returns the extended CPU processor type of the node.
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). | ||||||||||||||||||||||||||||||||||
| SYI$_XSID | Returns processor-specific information. For the MicroVAX II system, this information is the contents of the system type register of the node. The system type register contains the full extended information used in determining the extended system type codes. For other processors, the data returned by SYI$_XSID is currently undefined.
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 | Returns the current value of the system parameter named xxxx for the node.
The buffer must specify a longword into which $GETSYI writes the value of the specified system parameter. | ||||||||||||||||||||||||||||||||||
Condition Values Returned
| Value | Description |
|---|---|
| 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. |
Privileges Required
None
