 |
HP OpenVMS System Services Reference Manual
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.
$GETUTC
Returns the current time in 128-bit UTC format.
On Alpha and I64 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 and I64); 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 and I64 systems, the frequency at which system time is updated
varies, depending on the clock frequency of the Alpha or I64 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.
|
$GET_ALIGN_FAULT_DATA (Alpha and I64)
On Alpha and I64 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.
|
$GET_ARITH_EXCEPTION (Alpha and I64)
On Alpha and I64 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.
|
$GET_DEFAULT_TRANS
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-45:
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.
|
$GET_GALAXY_LOCK_INFO (Alpha Only)
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.
|
$GET_GALAXY_LOCK_SIZE (Alpha Only)
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.
|
$GET_REGION_INFO (Alpha and I64)
On Alpha and I64 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-46 shows the format of the Region Summary Buffer:
Table SYS-46 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
|
|
