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, see
the Synchronize ($SYNCH) service.
On Alpha and Integrity server 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);
1 – 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
OpenVMS Cluster system 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. 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
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.
To view the item code diagrams and descriptor fields tables, see
the VSI OpenVMS System Services Reference Manual.
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 or 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:
o 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.
o If you are using the $SYNCH service to synchronize completion
of the service, the I/O status block is a required argument
for $SYNCH.
o 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.