VMS Help
System Services
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
|
This help category provides an overview and the format for each of
the system services. The C function prototypes are available only on
OpenVMS Alpha systems.
System services provide basic operating system functions,
interprocess communication, and various control resources.
Ends a transaction by aborting it.
Format
SYS$ABORT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[reason]]
C Prototype
int sys$abort_trans (unsigned int efn, unsigned int flags,
struct _iosb *iosb,...);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag that is set when the service completes.
If this argument is omitted, event flag 0 is set.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the service. The flags argument is
a longword bit mask in which each bit corresponds to an option
flag. The $DDTMDEF macro defines symbolic names for these option
flags. All undefined bits must be 0. If this argument is omitted,
no flags are set.
DDTM$M_SYNC, the only flag currently defined, is described in the
following table:
Flag Description
DDTM$M_SYNC Set this flag to specify that successful
synchronous completion is to be indicated by
returning SS$_SYNCH. When SS$_SYNCH is returned,
the AST routine is not called, the event flag is
not set, and the I/O status block is not filled
in.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block in which the following information is returned:
o The completion status of the service, returned as a condition
value.
o An abort reason code that gives one reason why the transaction
aborted, if the completion status of the service is SS$_
NORMAL.
Note that, if there are multiple reasons why the transaction
aborted, the abort reason code returned in the I/O status
block might not be the same as the abort reason code passed
in the reason argument. The DECdtm transaction manager returns
one of the reasons in the I/O status block.
For example, if the call to $ABORT_TRANS gives DDTM$_ABORTED
as the reason and the transaction timeout expires at about the
same time as the call to $ABORT_TRANS, then either the DDTM$_
TIMEOUT or DDTM$_ABORTED reason code can be returned in the
I/O status block.
The $DDTMMSGDEF macro defines symbolic names for abort reason
codes. Those currently defined are shown in Abort Reason Codes.
Table SYS-1 Abort Reason Codes
Symbolic Name Description
DDTM$_ABORTED The application aborted the transaction.
DDTM$_COMM_FAIL A communications link failed.
DDTM$_INTEGRITY A resource manager integrity constraint
check failed.
DDTM$_LOG_FAIL A write operation to the transaction log
failed.
DDTM$_PART_SERIAL A resource manager serialization check
failed.
DDTM$_PART_TIMEOUT The timeout specified by a resource manager
expired.
DDTM$_SEG_FAIL A process or image terminated.
DDTM$_ A DECdtm transaction manager serialization
SERIALIZATION check failed.
DDTM$_SYNC_FAIL The transaction was not globally
synchronized.
DDTM$_TIMEOUT The timeout specified on $START_TRANS
expired.
DDTM$_UNKNOWN The reason is unknown.
DDTM$_VETOED A resource manager was unable to commit the
transaction.
Refer to the OpenVMS System Services Reference Manual to view the
I/O status block structure diagram.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST routine that is executed when the service completes, if SS$_
NORMAL is returned in R0. The astadr argument is the address of
this routine. The routine is executed in the access mode of the
caller.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter that is passed to the AST routine specified by the
astadr argument.
tid
OpenVMS usage:transaction_id
type: octaword (unsigned)
access: read only
mechanism: by reference
Identifier of the transaction to be aborted.
If this argument is omitted, $ABORT_TRANS aborts the default
transaction of the calling process.
reason
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Code that gives the reason why the application is aborting the
transaction. The $DDTMMSGDEF macro defines symbolic names for
abort reason codes. The default value for this argument is DDTM$_
ABORTED.
Ends a transaction by aborting it.
$ABORT_TRANSW always waits for the request to complete before
returning to the caller. Other than this, it is identical to
$ABORT_TRANS.
Format
SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[reason]]
C Prototype
int sys$abort_transw (unsigned int efn, struct _iosb
*iosb,...);
|
3 - $ACQUIRE GALAXY LOCK (Alpha Only)
|
Acquires ownership 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 OpenVMS Alpha Partitioning and Galaxy
Guide.
Format
SYS$ACQUIRE_GALAXY_LOCK handle ,timeout ,flags
C Prototype
int sys$acquire_galaxy_lock (unsigned __int64 lock_handle,
unsigned int timeout, unsigned int
flags);
3.1 - Arguments
handle
OpenVMS usage:galaxy lock handle
type: quadword (unsigned)
access: read
mechanism: input by value
The 64-bit lock handle that identifies the lock to be acquired.
This value is returned by SYS$CREATE_GALAXY_LOCK.
timeout
OpenVMS usage:wait timeout
type: longword (unsigned)
access: read
mechanism: input by value
The 32-bit wait or spin timeout specified in 10 microsecond
units. If not specified, defaults to 10 microseconds.
flags
OpenVMS usage:bit mask
type: longword (unsigned)
access: read
mechanism: input by value
Control flags defined by the GLOCKDEF macro: GLOCK$C_NOBREAK,
GLOCK$C_NOSPIN, and GLOCK$C_NOWAIT.
Adds a specified holder record to a target identifier.
Format
SYS$ADD_HOLDER id ,holder ,[attrib]
C Prototype
int sys$add_holder (unsigned int id, struct _generic_64
*holder, unsigned int attrib);
4.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Target identifier granted to the specified holder when $ADD_
HOLDER completes execution. The id argument is a longword
containing the binary value of the target identifier.
holder
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Holder identifier that is granted access to the target identifier
when $ADD_HOLDER completes execution. The holder argument is the
address of a quadword data structure that consists of a longword
containing the holder's UIC identifier followed by a longword
containing a value of 0.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Attributes to be placed in the holder record when $ADD_HOLDER
completes execution. The attrib argument is a longword containing
a bit mask specifying the attributes. A holder is granted a
specified attribute only if the target identifier has the
attribute.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The symbols are defined
in the system macro library ($KGBDEF). The symbolic name for each
bit position is listed in the following table:
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
database by using the DCL command SET
RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of
users who hold an identifier, unless they
own the identifier themselves.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it
translated-either from binary to ASCII or
vice versa-but prevents unauthorized users
from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
Adds the specified identifier to the rights database.
Format
SYS$ADD_IDENT name ,[id] ,[attrib] ,[resid]
C Prototype
int sys$add_ident (void *name, unsigned int id, unsigned int
attrib, unsigned int *resid);
5.1 - Arguments
name
OpenVMS usage:char-string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Identifier name to be added to the rights database when $ADD_
IDENT completes execution. The name argument is the address of
a character-string descriptor pointing to the identifier name
string.
An identifier name consists of 1 to 31 alphanumeric characters,
including dollar signs ($) and underscores (_), and must contain
at least one nonnumeric character. Any lowercase characters
specified are automatically converted to uppercase.
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Identifier to be created when $ADD_IDENT completes execution.
The id argument is a longword containing the binary value of the
identifier to be created.
If the id argument is omitted, $ADD_IDENT selects a unique
available value from the general identifier space and returns
it in resid, if it is specified.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Attributes placed in the identifier's record when $ADD_IDENT
completes execution. The attrib argument is a longword containing
a bit mask that specifies the attributes.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The symbols are defined
in the system macro library ($KGBDEF). The symbolic name for each
bit position is listed in the following table:
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
database by using the DCL command SET
RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of
users who hold an identifier, unless they
own the identifier themselves.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it
translated-either from binary to ASCII or
vice versa-but prevents unauthorized users
from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
resid
OpenVMS usage:rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value assigned by the system when $ADD_IDENT completes
execution. The resid argument is the address of a longword in
which the system-assigned identifier value is written.
Adds a new proxy to, or modifies an existing proxy in, the proxy
database.
Format
SYS$ADD_PROXY rem_node ,rem_user ,local_user ,[flags]
C Prototype
int sys$add_proxy (void *rem_node, void *rem_user, void
*local_user, unsigned int flags);
6.1 - Arguments
rem_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote node name of the proxy to be added to or modified in
the proxy database. The rem_node argument is the address of a
character-string descriptor pointing to the remote node name
string.
A remote node name consists of 1 to 1024 characters. No specific
characters, format, or case are required for a remote node name
string. Node names are converted to their DECnet for OpenVMS full
name unless the PRX$M_BYPASS_EXPAND flag is set with the flags
argument.
If you specify a single asterisk (*) for the rem_node argument,
the user name specified by the rem_user argument on all nodes is
served by the proxy.
rem_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote user name of the proxy to be added to or modified in
the proxy database. The rem_user argument is the address of a
character-string descriptor pointing to the user name string.
A remote user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($), underscores (_), and brackets
([ ]). Any lowercase characters specified are automatically
converted to uppercase.
The rem_user argument can be specified in user identification
code (UIC) format ([group, member]). Brackets are allowed only
if the remote user name string specifies a UIC. Group and member
are character-string representations of octal numbers with no
leading zeros.
If you specify a single asterisk (*) for the rem_user argument,
all users from the node specified by the rem_node argument
are served by the same user names specified by the local_user
argument.
local_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Local user name to add to the proxy record specified by the rem_
node and rem_user arguments in the proxy database as either
the default user or local user. The local_user argument is the
address of a character-string descriptor pointing to the local
user name.
A local user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($) and underscores (_). Any lowercase
characters specified are automatically converted to uppercase.
The user name specified by the local_user argument must be a user
name known to the local system.
If the PRX$M_DEFAULT flag is specified in the flags argument, the
user name specified by the local_user argument will be added to
the proxy record in the proxy database as the default user. If a
default user already exists for the specified proxy record, the
default user is placed into the proxy's local user list and is
replaced by the user name specified by the local_user argument.
Proxy records can contain no more than 16 local users and 1
default user. To add multiple users to a single proxy, you must
call this service once for each local user.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Functional specification for the service and type of user the
local_user argument represents. The flags argument is a longword
bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $PRXDEF macro defines
the following symbolic names:
Symbolic Name Description
PRX$M_BYPASS_ The service should not convert the node name
EXPAND specified in the rem_node argument to its
corresponding DECnet for OpenVMS full name.
If this flag is set, it is the caller's
responsibility to ensure that the fully
expanded node name is passed into the service.
PRX$M_DEFAULT The user name specified by the local_user
argument is the default user for the proxy.
If this flag is not specified, the user name
specified by the local_user argument is added
to the proxy record's local user list.
PRX$M_IGNORE_ The service should not wait for a return
RETURN status from the security server. No return
status from the server's function will be
returned to the caller.
Modifies the stack pointer for a less privileged access mode.
The operating system uses this service to modify a stack pointer
for a less privileged access mode after placing arguments on the
stack.
Format
SYS$ADJSTK [acmode] ,[adjust] ,newadr
C Prototype
int sys$adjstk (unsigned int acmode, short int adjust, void
*(*(newadr)));
7.1 - Arguments
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the stack pointer is to be adjusted. The
acmode argument is this longword value. If not specified, the
default value 0 (kernel access mode) is used.
adjust
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Signed adjustment value used to modify the value specified by the
newadr argument. The adjust argument is a signed longword, which
is the adjustment value.
Only the low-order word of this argument is used. The value
specified by the low-order word is added to or subtracted
from (depending on the sign) the value specified by the newadr
argument. The result is loaded into the stack pointer for the
specified access mode.
If the adjust argument is not specified or is specified as 0, the
stack pointer is loaded with the value specified by the newadr
argument.
newadr
OpenVMS usage:address
type: longword (unsigned)
access: modify
mechanism: by reference
Value that adjust is to adjust. The newadr argument is the
address of this longword value.
The value specified by this argument is both read and written
by $ADJSTK. The $ADJSTK service reads the value specified and
adjusts it by the value of the adjust argument (if specified).
After this adjustment is made, $ADJSTK writes the adjusted value
back into the longword specified by newadr and then loads the
stack pointer with the adjusted value.
If the value specified by newadr is 0, the current value of the
stack pointer is adjusted by the value specified by adjust. This
new value is then written back into newadr, and the stack pointer
is modified.
Adjusts a process's current working set limit by the specified
number of pages (on VAX systems) or pagelets (on Alpha systems)
and returns the new value to the caller. The working set limit
specifies the maximum number of process pages or pagelets that
can be resident in physical memory.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ADJWSL [pagcnt] ,[wsetlm]
C Prototype
int sys$adjwsl (int pagcnt, unsigned int *wsetlm);
8.1 - Arguments
pagcnt
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Signed adjustment value specifying the number of pages (on VAX
systems) or pagelets (on Alpha systems) to add to (if positive)
or subtract from (if negative) the current working set limit. The
pagcnt argument is this signed longword value.
Note that, on Alpha systems, the specified value is rounded up to
an even multiple of the CPU-specific page size.
If pagcnt is not specified or is specified as 0, no adjustment
is made and the current working set limit is returned in the
longword specified by the wsetlm argument (if this argument is
specified).
wsetlm
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Value of the working set limit, in pages (on VAX systems) or
pagelets (on Alpha systems), returned by $ADJWSL. The wsetlm
argument is the 32-bit address (on VAX systems) or the 32- or
64-bit address (on Alpha systems) of this longword value. The
wsetlm argument receives the newly adjusted value if pagcnt is
specified, and it receives the prior, unadjusted value if pagcnt
is not specified.
Allocates a device for exclusive use by a process and its
subprocesses. No other process can allocate the device or assign
channels to it until the image that called $ALLOC exits or
explicitly deallocates the device with the Deallocate Device
($DALLOC) service.
Format
SYS$ALLOC devnam ,[phylen] ,[phybuf] ,[acmode] ,[flags]
C Prototype
int sys$alloc (void *devnam, unsigned short int *phylen, void
*phybuf, unsigned int acmode, unsigned int
flags);
9.1 - Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Device name of the device to be allocated. The devnam argument
is the address of a character string descriptor pointing to the
device name string.
The string can be either a physical device name or a logical
name. If it is a logical name, it must translate to a physical
device name.
phylen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Word into which $ALLOC writes the length of the device name
string for the device it has allocated. The phylen argument is
the address of this word.
phybuf
OpenVMS usage:device_name
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Buffer into which $ALLOC writes the device name string for the
device it has allocated. The phybuf argument is the address of a
character string descriptor pointing to this buffer.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the allocated device. The
acmode argument is a longword containing the access mode.
The most privileged access mode used is the access mode of the
caller. Only equal or more privileged access modes can deallocate
the device.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of status flags indicating whether to interpret the
devnam argument as the type of device to be allocated. Only one
flag exists, bit 0. When it is set, the $ALLOC service allocates
the first available device that has the type specified in the
devnam argument.
This feature is available for the following mass storage devices:
RA60 RA80 RA81 RC25
RCF25 RK06 RK07 RL01
RL02 RM03 RM05 RM80
RP04 RP05 RP06 RP07
RX01 RX02 TA78 TA81
TS11 TU16 TU58 TU77
TU78 TU80 TU81
Associates a named common event flag cluster with a process
to execute the current image and to be assigned a process-
local cluster number for use with other event flag services.
If the named cluster does not exist but the process has suitable
privilege, the service creates the cluster.
Format
SYS$ASCEFC efn ,name ,[prot] ,[perm]
C Prototype
int sys$ascefc (unsigned int efn, void *name, char prot, char
perm);
10.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag contained within the desired common
event flag cluster. The efn argument is a longword value
specifying this number; however, $ASCEFC uses only the low-order
byte.
There are two common event flag clusters: cluster 2 and cluster
3. Cluster 2 contains event flag numbers 64 to 95, and cluster
3 contains event flag numbers 96 to 127. (Clusters 0 and 1 are
process-local event flag clusters.)
To associate with common event flag cluster 2, specify any flag
number in the cluster (64 to 95); to associate with common event
flag cluster 3, specify any event flag number in the cluster (96
to 127).
name
OpenVMS usage:ef_cluster_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the common event flag cluster with which to associate.
The name argument is the address of a character string descriptor
pointing to this name string.
The character string descriptor can be 1 to 15 bytes in length,
and each byte can be any 8-bit value.
Common event flag clusters are accessible only to processes
having the same UIC group number, and each such process must
associate with the cluster using the same name (specified in the
name argument). The operating system implicitly associates the
group UIC number with the name, making the name unique to a UIC
group.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
prot
OpenVMS usage:Boolean
type: byte (unsigned)
access: read only
mechanism: by value
Protection specifier that allows or disallows access to the
common event flag cluster for processes with the same UIC group
number as the creating process. The prot argument is a longword
value, which is interpreted as Boolean.
The default value 0 specifies that any process with the same UIC
group number as the creating process can access the event flag
cluster. The value 1 specifies that only processes having the UIC
of the creating process can access the event flag cluster.
When the prot argument is 1, all access to the Group category is
denied.
The process must have associate access to access an existing
common event flag cluster.
perm
OpenVMS usage:Boolean
type: byte (unsigned)
access: read only
mechanism: by value
Permanent specifier that marks a common event flag cluster as
either permanent or temporary. The perm argument is a longword
value, which is interpreted as Boolean.
The default value 0 specifies that the cluster is temporary. The
value 1 specifies that the cluster is permanent.
Converts an absolute or delta time from 64-bit system time format
to an ASCII string.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASCTIM [timlen] ,timbuf ,[timadr] ,[cvtflg]
C Prototype
int sys$asctim (unsigned short int *timlen, void *timbuf,
struct _generic_64 *timadr, char cvtflg);
11.1 - Arguments
timlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Length (in bytes) of the ASCII string returned by $ASCTIM. The
timlen argument is the 32-bit address (on VAX systems) or the 32-
or 64-bit address (on Alpha systems) of a word containing this
length.
timbuf
OpenVMS usage:time_name
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
Buffer into which $ASCTIM writes the ASCII string. The timbuf
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 the buffer.
The buffer length specified in the timbuf argument, together with
the cvtflg argument, controls what information is returned.
timadr
OpenVMS usage:date_time
type: quadword
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Time value that $ASCTIM is to convert. The timadr argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on
Alpha systems) of this 64-bit time value. A positive time value
represents an absolute time. A negative time value represents
a delta time. If you specify a delta time, it must be less than
10,000 days.
If timadr is not specified or is specified as 0 (the default),
$ASCTIM returns the current date and time.
cvtflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Conversion indicator specifying which date and time fields
$ASCTIM should return. The cvtflg argument is a longword
value, which is interpreted as Boolean. The value 1 specifies
that $ASCTIM should return only the hour, minute, second, and
hundredths-of-second fields. The default value 0 specifies that
$ASCTIM should return the full date and time.
Translates the specified identifier name into its binary
identifier value.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASCTOID name ,[id] ,[attrib]
C Prototype
int sys$asctoid (void *name, unsigned int *id, unsigned int
*attrib);
12.1 - Arguments
name
OpenVMS usage:char_string
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)
Identifier name translated when $ASCTOID completes execution.
The name argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character-string
descriptor pointing to the identifier name.
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Identifier value resulting when $ASCTOID completes execution. The
id argument is the 32- or 64-bit address (on Alpha systems) or
the 32-bit address (on VAX systems) of a longword in which the
identifier value is written.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Attributes associated with the identifier returned in id when
$ASCTOID completes execution. The attrib argument is the 32-
or 64-bit address (on Alpha systems) or the 32-bit address (on
VAX systems) of a longword containing a bit mask specifying the
attributes.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The symbols are defined
in the system macro $KGBDEF library. The symbolic names for each
bit position are listed in the following table:
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
database by using the DCL command SET
RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of
users who hold an identifier, unless they
own the identifier themselves. Special
privilege is required to translate hidden
names.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it
translated-either from binary to ASCII or
vice versa-but prevents unauthorized users
from translating the identifier. Special
privilege is required to translate hidden
names.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows the holder to charge resources,
such as disk blocks, to the identifier.
KGB$V_SUBSYSTEM Allows holders of the identifier to create
and maintain protected subsystems by
assigning the Subsystem access control
entry (ACE) to the application images in
the subsystem.
Converts an absolute time from 128-bit UTC format to an ASCII
string.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASCUTC [timlen] ,timbuf ,[utcadr] ,[cvtflg]
C Prototype
int sys$ascutc (unsigned short int *timlen, void *timbuf,
unsigned int *utcadr [4], char cvtflg);
13.1 - Arguments
timlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Length (in bytes) of the ASCII string returned by $ASCUTC. The
timlen argument is the 32-bit address (on VAX systems) or the 32-
or 64-bit address (on Alpha systems) of a word containing this
length.
timbuf
OpenVMS usage:time_name
type: character-coded string text
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor-fixed-length string descriptor
(VAX)
Buffer into which $ASCUTC writes the ASCII string. The timbuf
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 the buffer. The buffer length specified in the
timbuf argument, together with the cvtflg argument, controls
what information is returned.
utcadr
OpenVMS usage:coordinated universal time
type: utc_date_time
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Time value that $ASCUTC is to convert. The timadr argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on
Alpha systems) of this 128-bit time value. Relative times are not
permitted. If the timadr argument is not specified, it defaults
to 0 and $ASCUTC returns the current date and time.
cvtflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Conversion indicator specifying which date and time fields
$ASCUTC should return. The cvtflg argument is a longword value
that is interpreted as Boolean. The value 1 specifies that
$ASCUTC should return only the time, including hour, minute,
second, and hundredths-of-second fields. The default value 0
specifies that $ASCUTC should return the full date and time.
Provides a process with an I/O channel so input/output operations
can be performed on a device, or establishes a logical link with
a remote node on a network.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASSIGN devnam ,chan ,[acmode] ,[mbxnam] ,[flags]
C Prototype
int sys$assign (void *devnam, unsigned short int *chan,
unsigned int acmode, void *mbxnam,...);
14.1 - Arguments
devnam
OpenVMS usage:device_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 device to which $ASSIGN is to assign a channel. The
devnam argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character string
descriptor pointing to the device name string.
If the device name contains a double colon (::), the system
assigns a channel to the first available network device (NET:)
and performs an access function on the network.
chan
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Number of the channel that is assigned. The chan argument is the
32- or 64-bit address (on Alpha systems) or the 32-bit address
(on VAX systems) of a word into which $ASSIGN writes the channel
number.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel. The acmode
argument specifies the access mode. The $PSLDEF macro defines
the following symbols for the four access modes:
Symbol Access Mode Numeric Value
PSL$C_KERNEL Kernel 0
PSL$C_EXEC Executive 1
PSL$C_SUPER Supervisor 2
PSL$C_USER User 3
The specified access mode and the access mode of the caller are
compared. The less privileged (but the higher numeric valued)
of the two access modes becomes the access mode associated
with the assigned channel. I/O operations on the channel can
be performed only from equal and more privileged access modes.
For more information, refer to the section on access modes in the
OpenVMS Programming Concepts Manual.
mbxnam
OpenVMS usage:device_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)
Logical name of the mailbox to be associated with the device. The
mbxnam argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character string
descriptor pointing to the logical name string.
If you specify mbxnam as 0, no mailbox is associated with the
device. This is the default.
You must specify the mbxnam argument when performing a
nontransparent, task-to-task, network operation.
Only the owner of a device can associate a mailbox with the
device; the owner of a device is the process that has allocated
the device, whether implicitly or explicitly. Only one mailbox
can be associated with a device at any one time.
For unshareable, nonspooled devices, an implicit $ALLOCATE is
done. This requires read, write, or control access to the device.
A mailbox cannot be associated with a device if the device has
foreign (DEV$M_FOR) or shareable (DEV$M_SHR) characteristics.
A mailbox is disassociated from a device when the channel that
associated it is deassigned.
If a mailbox is associated with a device, the device driver can
send status information to the mailbox. For example, if the
device is a terminal, this information might indicate dialup,
hangup, or the reception of unsolicited input; if the device is a
network device, it might indicate that the network is connected
or perhaps that the line is down.
For details on the nature and format of the information returned
to the mailbox, refer to the OpenVMS I/O User's Reference Manual.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
An optional device-specific argument. The flags argument is a
longword bit mask.
For more information on the applicability of the flags argument
for a particular device, refer to the OpenVMS I/O User's
Reference Manual.
Appends an event message to the system security audit log file or
sends an alarm to a security operator terminal.
Format
SYS$AUDIT_EVENT [efn] ,[flags] ,itmlst ,[audsts] ,[astadr]
,[astprm]
C Prototype
int sys$audit_event (unsigned int efn, unsigned int flags,
void *itmlst, unsigned int *audsts, void
(*astadr)(__unknown_params), int 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 audit completes. The
efn argument is a longword containing the number of the event
flag; however, $AUDIT_EVENT uses only the low-order byte. If efn
is not specified, event flag 0 is used.
Upon request initiation, $AUDIT_EVENT clears the specified event
flag.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $AUDIT_EVENT system operation.
The flags argument is a longword bit mask, where each bit
corresponds to an option.
Each flag option has a symbolic name. The $NSADEF macro defines
the following symbolic names:
Symbolic Name Description
NSA$M_ACL Specifies an event generated by an Alarm ACE
or Audit ACE. This flag is reserved to Compaq.
NSA$M_FLUSH Specifies that all messages in the audit
server buffer be written to the audit log
file.
NSA$M_INTERNAL Specifies that the $AUDIT_EVENT call
originates in the context of a trusted
computing base (TCB) component. The auditing
components use this flag to indicate that
internal auditing failures should result in a
SECAUDTCB bugcheck. This flag is reserved to
Compaq.
NSA$M_MANDATORY Specifies that an audit is to be performed,
regardless of system alarm and audit settings.
NSA$M_NOEVTCHECK Specifies that an audit is to be performed,
regardless of the system alarm or audit
settings. This flag is similar to the NSA$M_
MANDATORY bit but, unlike the NSA$M_MANDATORY
bit, this flag is not reflected in the NSA$W_
FLAGS field in the resulting audit record on
disk.
NSA$M_SERVER Indicates that the call originates in a TCB
server process and that the event should be
audited regardless of the state of a process-
specific, no-audit bit.
Trusted servers use this flag to override
the no-audit bit when they want to perform
explicit auditing on behalf of a client
process. This flag is reserved to Compaq.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying information to include in the audit record.
The itmlst argument is the address of a list of item descriptors.
The list of item descriptors is terminated by a longword of 0.
The item list for all calls to $AUDIT_EVENT must include the
following item codes:
o NSA$_EVENT_TYPE
o NSA$_EVENT_SUBTYPE
o At least one of the NSA$_ALARM_NAME item code or the NSA$_
AUDIT_NAME item code.
o If the event being reported is an object access (NSA$C_MSG_
OBJ_ACCESS) or an object delete (NSA$C_MSG_OBJ_DELETE), the
NSA$_FINAL_STATUS, NSA$_ACCESS_DESIRED, and NSA$_OBJECT_CLASS
item codes must be specified.
o If the event being reported is an object create (NSA$C_MSG_
OBJ_CREATE), the NSA$_FINAL_STATUS and NSA$_OBJECT_CLASS item
codes must be specified.
o If the event being reported is a privilege audit (NSA$C_MSG_
PRVAUD), the NSA$_PRIVS_USED or the NSA$_PRIVS_MISSING item
code must be specified.
o If the audit event being reported is a deaccess event (NSA$C_
MSG_OBJ_DEACCESS), the NSA$_OBJECT_CLASS item code must be
specified.
The item list is a standard format item list.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
audsts
OpenVMS usage:cond_value_type
type: longword (unsigned)
access: write only
mechanism: by reference
Longword condition value that receives the final completion
status from the operation. If a security audit is required,
the final completion status represents either the successful
completion of the resulting security audit or any failing status
that occurred while the security audit was performed within the
audit server process.
The audsts argument is valid only when the service returns
success and the status is not SS$_EVTNOTENAB. In addition, the
caller must either make use of the astadr argument or use the
$AUDIT_EVENTW service before attempting to access audsts.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Asynchronous system trap (AST) routine to be executed after the
audsts is updated. The astadr argument, which is the address of a
longword value, is the procedure value of the AST routine.
The AST routine executes in the access mode of the caller of
$AUDIT_EVENT.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Asynchronous system trap (AST) parameter passed to the AST
service routine. The astprm argument is a longword value
containing the AST parameter.
Determines whether a security-related event should be reported.
If the event should be reported, the service sends the event
report to the audit server.
The $AUDIT_EVENTW service completes synchronously; that is, it
returns only after receiving an explicit confirmation from the
audit server that the associated audit, if enabled, has been
performed.
For asynchronous completion, use the Audit Event ($AUDIT_EVENT)
service. In all other respects, $AUDIT_EVENTW is identical to
$AUDIT_EVENT. For additional information about $AUDIT_EVENTW,
refer to the $AUDIT_EVENT service.
Format
SYS$AUDIT_EVENTW efn ,[flags] ,itmlst ,audsts ,[astadr]
,[astprm]
C Prototype
int sys$audit_eventw (unsigned int efn, unsigned int flags,
void *itmlst, unsigned int *audsts, void
(*astadr)(__unknown_params), int astprm);
Requests that the EXEC avoid preempting the calling process or
thread.
Format
SYS$AVOID_PREEMPT enable
C Prototype
int sys$avoid_preempt (int enable);
17.1 - Arguments
enable
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Enables or disables preemption avoidance. If the enable argument
is set to 1, preemption avoidance is enabled; if 0, preemption
avoidance is disabled.
Converts an ASCII string to an absolute or delta time value in
the system 64-bit time format suitable for input to the Set Timer
($SETIMR) or Schedule Wakeup ($SCHDWK) service.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$BINTIM timbuf ,timadr
C Prototype
int sys$bintim (void *timbuf, struct _generic_64 *timadr);
18.1 - Arguments
timbuf
OpenVMS usage:time_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)
Buffer that holds the ASCII time to be converted. The timbuf
argument specifies the 32-bit address (on VAX systems) or the
32- or 64-bit address (on Alpha systems) of a character string
descriptor pointing to the time string. The time string specifies
the absolute or delta time to be converted by $BINTIM.
timadr
OpenVMS usage:date_time
type: quadword
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Time value that $BINTIM has converted. The timadr argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on
Alpha systems) of the quadword system time, which receives the
converted time.
Converts an ASCII string to an absolute time value in the 128-bit
UTC format.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$BINUTC timbuf ,utcadr
C Prototype
int sys$binutc (void *timbuf, unsigned int *utcadr [4]);
19.1 - Arguments
timbuf
OpenVMS usage:time_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)
Buffer that holds the ASCII time to be converted. The timbuf
argument specifies the 32-bit address (on VAX systems) or the
32- or 64-bit address (on Alpha systems) of a character string
descriptor pointing to a local time string. The time string
specifies the absolute time to be converted by $BINUTC.
utcadr
OpenVMS usage:coordinated universal time
type: utc_date_time
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Time value that $BINUTC has converted. The utcadr argument is
the 32-bit address (on VAX systems) or the 32- or 64-bit address
(on Alpha systems) of a 16-byte location to receive the converted
time.
Sends a message to one or more terminals. The $BRKTHRU service
completes asynchronously; that is, it returns to the caller after
queuing the message request, without waiting for the message to
be written to the specified terminals.
For synchronous completion, use the Breakthrough and Wait
($BRKTHRUW) service. The $BRKTHRUW service is identical to the
$BRKTHRU service in every way except that $BRKTHRUW returns
to the caller after the message is written to the specified
terminals.
The $BRKTHRU service supersedes the Broadcast ($BRDCST) service.
When writing new programs, you should use $BRKTHRU instead of
$BRDCST. When updating old programs, you should change all uses
of $BRDCST to $BRKTHRU.
Format
SYS$BRKTHRU [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]
[,carcon] [,flags] [,reqid] [,timout] [,astadr]
[,astprm]
C Prototype
int sys$brkthru (unsigned int efn, void *msgbuf, void *sendto,
unsigned int sndtyp, struct _iosb *iosb,
unsigned int carcon, unsigned int flags,
unsigned int reqid, unsigned int timout, void
(*astadr)(__unknown_params), int 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 message has been
written to the specified terminals. The efn argument is a
longword containing this number; however, $BRKTHRU uses only
the low-order byte.
When the message request is queued, $BRKTHRU clears the specified
event flag (or event flag 0 if efn is not specified). Then, after
the message is sent, $BRKTHRU sets the specified event flag (or
event flag 0).
msgbuf
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Message text to be sent to the specified terminals. The msgbuf
argument is the address of a descriptor pointing to this message
text.
The $BRKTHRU service allows the message text to be as long as
16,350 bytes; however, both the system parameter MAXBUF and the
caller's available process space can affect the maximum length of
the message text.
sendto
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of a single device (terminal) or single user name to which
the message is to be sent. The sendto argument is the address of
a descriptor pointing to this name.
The sendto argument is used in conjunction with the sndtyp
argument. When sndtyp specifies BRK$C_DEVICE or BRK$C_USERNAME,
the sendto argument is required.
If you do not specify sndtyp or if sndtyp does not specify BRK$C_
DEVICE or BRK$C_USERNAME, you should not specify sendto; if
sendto is specified, $BRKTHRU ignores it.
sndtyp
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Terminal type to which $BRKTHRU is to send the message. The
sndtyp argument is a longword value specifying the terminal type.
Each terminal type has a symbolic name, which is defined by the
$BRKDEF macro. The following table describes each terminal type:
Terminal Type Description
BRK$C_ When specified, $BRKTHRU sends the message to all
ALLTERMS terminals at which users are logged in and to all
other terminals that are connected to the system
except those with the AUTOBAUD characteristic
set.
BRK$C_ When specified, $BRKTHRU sends the message to all
ALLUSERS users who are currently logged in to the system.
BRK$C_DEVICE When specified, $BRKTHRU sends the message to a
single terminal; you must specify the name of the
terminal by using the sendto argument.
BRK$C_ When specified, $BRKTHRU sends the message to a
USERNAME user with a specified user name; you must specify
the user name by using the sendto argument.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb argument is the address of this quadword block.
When the iosb argument is specified, $BRKTHRU sets the quadword
to 0 when it queues the message request. Then, after the message
is sent to the specified terminals, $BRKTHRU returns four
informational items, one item per word, in the quadword I/O
status block.
These informational items indicate the status of the messages
sent only to terminals and mailboxes on the local node; these
items do not include the status of messages sent to terminals and
mailboxes on other nodes in an OpenVMS Cluster system.
The following table shows each word of the quadword block and the
informational item it contains:
Word Informational Item
1 A condition value describing the final completion status.
2 A decimal number indicating the number of terminals and
mailboxes to which $BRKTHRU successfully sent the message.
3 A decimal number indicating the number of terminals to which
$BRKTHRU failed to send the message because the write to the
terminals timed out.
4 A decimal number indicating the number of terminals to which
$BRKTHRU failed to send the message because the terminals
were set to the NOBROADCAST characteristic (by using the DCL
command SET TERMINAL/NOBROADCAST).
carcon
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Carriage control specifier indicating the carriage control
sequence to follow the message that $BRKTHRU sends to the
terminals. The carcon argument is a longword containing the
carriage control specifier.
For a list of the carriage control specifiers that you can use
in the carcon argument, refer to the OpenVMS I/O User's Reference
Manual.
If you do not specify the carcon argument, $BRKTHRU uses a
default value of 32, which represents a space in the ASCII
character set. The message format resulting from this default
value is a line feed, the message text, and a carriage return.
The carcon argument has no effect on message formatting
specified by the BRK$M_SCREEN flag in the flags argument. See
the description of the flags argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag bit mask specifying options for the $BRKTHRU operation. The
flags argument is a longword value that is the logical OR of each
desired flag option.
Each flag option has a symbolic name. The $BRKDEF macro defines
the following symbolic names:
Symbolic Name Description
BRK$V_ERASE_ When specified with the BRK$M_SCREEN flag,
LINES BRK$V_ERASE_LINES causes a specified number of
lines to be cleared from the screen before the
message is displayed. When BRK$M_SCREEN is not
also specified, BRK$V_ERASE_LINES is ignored.
Unlike the other Boolean flags, BRK$V_ERASE_
LINES specifies a 1-byte integer in the range
0 to 24. It occupies the first byte in the
longword flag mask. In coding the call to
$BRKTHRU, specify the desired integer value in
the OR operation with any other desired flags.
BRK$M_SCREEN When specified, $BRKTHRU sends screen-formatted
messages as well as messages formatted through
the use of the carcon argument. $BRKTHRU sends
screen-formatted messages to terminals with
the DEC_CRT characteristic, and it sends
messages formatted by carcon to those without
the DEC_CRT characteristic. You set the DEC_CRT
characteristic for the terminal by using the DCL
command SET TERMINAL/DEC_CRT.
A screen-formatted message is displayed at the
top of the terminal screen, and the cursor is
repositioned at the point it was prior to the
broadcast message. However, the BRK$V_ERASE_
LINES and BRK$M_BOTTOM flags also affect the
display.
BRK$M_BOTTOM When BRK$M_BOTTOM is specified and BRK$M_SCREEN
is also specified, $BRKTHRU writes the message
to the bottom of the terminal screen instead of
the top. BRK$M_BOTTOM is ignored if the BRK$M_
SCREEN flag is not set.
BRK$M_ When BRK$M_NOREFRESH is specified, $BRKTHRU,
NOREFRESH after writing the message to the screen, does
not redisplay the last line of a read operation
that was interrupted by the broadcast message.
This flag is useful only when the BRK$M_SCREEN
flag is not specified, because BRK$M_NOREFRESH
is the default for screen-formatted messages.
BRK$M_CLUSTER Specifying BRK$M_CLUSTER enables $BRKTHRU to
send the message to terminals or mailboxes on
other nodes in an OpenVMS Cluster system. If
BRK$M_CLUSTER is not specified, $BRKTHRU sends
messages only to terminals or mailboxes on the
local node.
reqid
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Class requester identification, which identifies to $BRKTHRU
the application (or image) that is calling $BRKTHRU. The reqid
argument is this longword identification value.
The reqid argument is used by several images that send messages
to terminals and can be used by as many as 16 different user
images as well.
When such an image calls $BRKTHRU, specifying reqid, $BRKTHRU
notifies the terminal that this image wants to write to the
terminal. This makes it possible for you to allow the image to
write or prevent it from writing to the terminal.
To prevent a particular image from writing to your
terminal, you use the image's name in the DCL command SET
TERMINAL/NOBROADCAST=image-name. Note that image-name in this
DCL command is the same as the value of the reqid argument that
the image passed to $BRKTHRU.
For example, you can prevent the Mail utility (which is an image)
from writing to the terminal by entering the DCL command SET
BROADCAST=NOMAIL.
The $BRKDEF macro defines class names that are used by several
OpenVMS components. These components specify their class names by
using the reqid argument in calls to $BRKTHRU. The $BRKDEF macro
also defines 16 class names (BRK$C_USER1 through BRK$C_USER16)
for the use of user images that call $BRKTHRU. The class names
and the components to which they correspond are as follows:
Class Name Component
BRK$C_GENERAL This class name is used by the image invoked
by the DCL command REPLY and the callers of the
$BRKTHRU service. This is the default if the
reqid argument is not specified.
BRK$C_PHONE This class name is used by the OpenVMS Phone
utility.
BRK$C_MAIL This class name is used by the OpenVMS Mail
utility.
BRK$C_DCL This class name is used by the DIGITAL Command
Language (DCL) interpreter for the Ctrl/T
command, which displays the process status.
BRK$C_QUEUE This class name is used by the queue manager,
which manages print and batch jobs.
BRK$C_SHUTDOWN This class name is used by the system shutdown
image, which is invoked by the DCL command
REPLY/ID=SHUTDOWN.
BRK$C_URGENT This class name is used by the image invoked by
the DCL command REPLY/ID=URGENT.
BRK$C_USER1 These class names can be used by user-written
through BRK$C_ images.
USER16
timout
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Timeout value, which is the number of seconds that must elapse
before an attempted write by $BRKTHRU to a terminal is considered
to have failed. The timout argument is this longword value (in
seconds).
Because $BRKTHRU calls the $QIO service to perform write
operations to the terminal, the timeout value specifies the
number of seconds allotted to $QIO to perform a single write
operation to the terminal.
If you do not specify the timout argument, $BRKTHRU uses a
default value of 0 seconds, which specifies infinite time (no
timeout occurs).
The value specified by timout can be 0 or any number greater than
4; the numbers 1, 2, 3, and 4 are illegal.
When you press Ctrl/S or the No Scroll key, $BRKTHRU cannot send
a message to the terminal. In such a case, the value of timout is
usually exceeded and the attempted write to the terminal fails.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed after $BRKTHRU has sent the
message to the specified terminals. The astadr argument is the
address of this routine.
If you specify astadr, the AST routine executes at the same
access mode as the caller of $BRKTHRU.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST routine specified by the
astadr argument. The astprm argument specifies this longword
parameter.
Sends a message to one or more terminals. The $BRKTHRUW service
operates synchronously; that is, it returns to the caller after
the message has been sent to the specified terminals.
For asynchronous operations, use the Breakthrough ($BRKTHRU)
service; $BRKTHRU returns to the caller after queuing the message
request, without waiting for the message to be delivered.
Aside from the preceding, $BRKTHRUW is identical to $BRKTHRU. For
all other information about the $BRKTHRUW service, refer to the
description of $BRKTHRU.
The $BRKTHRU and $BRKTHRUW services supersede the Broadcast
($BRDCST) service. When writing new programs, you should use
$BRKTHRU or $BRKTHRUW instead of $BRDCST. When updating old
programs, you should change all uses of $BRDCST to $BRKTHRU or
$BRKTHRUW. $BRDCST is now an obsolete system service and is no
longer being enhanced.
Format
SYS$BRKTHRUW [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]
[,carcon] [,flags] [,reqid] [,timout] [,astadr]
[,astprm]
C Prototype
int sys$brkthruw (unsigned int efn, void *msgbuf, void
*sendto, unsigned int sndtyp, struct _iosb
*iosb, unsigned int carcon, unsigned int
flags, unsigned int reqid, unsigned int
timout, void (*astadr)(__unknown_params),int
astprm);
Cancels all pending I/O requests on a specified channel. In
general, this includes all I/O requests that are queued, as well
as the request currently in progress.
Format
SYS$CANCEL chan
C Prototype
int sys$cancel (unsigned short int chan);
22.1 - Argument
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel on which I/O is to be canceled. The chan argument is
a word containing the channel number.
Deletes an exit control block from the list of control blocks for
the calling access mode. Exit control blocks are declared by the
Declare Exit Handler ($DCLEXH) service and are queued according
to access mode in a last-in first-out order.
Format
SYS$CANEXH [desblk]
C Prototype
int sys$canexh (void *desblk);
23.1 - Argument
desblk
OpenVMS usage:exit_handler_block
type: longword (unsigned)
access: read only
mechanism: by reference
Control block describing the exit handler to be canceled. If you
do not specify the desblk argument or specify it as 0, all exit
control blocks are canceled for the current access mode. The
desblk argument is the address of this control block.
Cancels all or a selected subset of the Set Timer requests
previously issued by the current image executing in a process.
Cancellation is based on the request identification specified
in the Set Timer ($SETIMR) service. If you give the same request
identification to more than one timer request, all requests with
that request identification are canceled.
Format
SYS$CANTIM [reqidt] ,[acmode]
C Prototype
int sys$cantim (unsigned __int64 reqidt, unsigned int acmode);
24.1 - Arguments
reqidt
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Request identification of the timer requests to be canceled.
If you specify it as 0 (the default), all timer requests are
canceled. The reqidt argument is a longword containing this
identification.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the requests to be canceled. The acmode argument
is a longword containing the access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
Removes all scheduled wakeup requests for a process from the
timer queue, including those made by the caller or by other
processes. The Schedule Wakeup ($SCHDWK) service makes scheduled
wakeup requests.
Format
SYS$CANWAK [pidadr] ,[prcnam]
C Prototype
int sys$canwak (unsigned int *pidadr, void *prcnam);
25.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process for which wakeups are
to be canceled. The pidadr argument is the address of a longword
specifying the PID. The pidadr argument can refer to a process
running on the local node or a process running on another node in
the OpenVMS Cluster system.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the process for which wakeups are to be canceled. The
prcnam argument is the address of a character string descriptor
pointing to the process name string.
A process running on the local node can be identified with a 1-
to 15-character string. To identify a process on a specific node
in a cluster, specify the full process name, which includes the
node name as well as the process name. The full process name can
contain up to 23 characters.
The operating system interprets the UIC group number of the
calling process as part of the process name; the names of
processes are unique to UIC groups. Because of this, you can
use the prcnam argument only on behalf of processes in the same
group as the calling process.
Determines on behalf of a third-party user whether a named user
can access the object specified.
Format
SYS$CHECK_ACCESS [objtyp], [objnam], [usrnam], itmlst,
[contxt], [clsnam], [objpro], [usrpro]
C Prototype
int sys$check_access (unsigned int *objtyp, void *objnam,
void *usrnam, void *itmlst, unsigned int
*contxt, void *clsnam, void *objpro, void
*usrpro);
26.1 - Arguments
objtyp
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Type of object being accessed. The objtyp argument is the address
of a longword containing a value specifying the type of object.
The appropriate symbols are listed in the following table and are
defined in the system macro $ACLDEF library:
Symbol Meaning
ACL$C_CAPABILITY Object is a restricted resource; use the
reserved name VECTOR.
ACL$C_DEVICE Object is a device.
ACL$C_FILE Object is a Files-11 On-Disk Structure
Level 2 file.
ACL$C_GROUP_GLOBAL_ Object is a group global section.
SECTION
ACL$C_JOBCTL_QUEUE Object is a batch, print, or server
queue.
ACL$C_LOGICAL_NAME_ Object is a logical name table.
TABLE
ACL$C_SYSTEM_GLOBAL_ Object is a system global section.
SECTION
For further information about these symbols, see the description
of the clsnam argument.
objnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the object being accessed. The objnam argument is the
address of a character-string descriptor pointing to the object
name.
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the user attempting access. The usrnam argument is the
address of a descriptor that points to a character string that
contains the name of the user attempting to gain access to the
specified object. The user name string can contain a maximum of
12 alphanumeric characters.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes describing how the object is to be accessed and
information returned after $CHECK_ACCESS performs the protection
check (for instance, security alarm information).
For each item code, you must include a set of four elements and
end the list with a longword containing the value 0 (CHP$_END).
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:longword
type: longword (unsigned)
access: read-write
mechanism: by reference
Longword used to maintain the user authorization file (UAF)
context. The contxt argument is the address of a longword
to receive a UAI context longword. On the initial call, this
longword should contain the value -1. On subsequent calls, the
value of the contxt argument from the previous call should be
passed back in.
Using the contxt argument keeps the UAF open across all calls,
thereby improving the performance of the system on subsequent
calls. To close the UAF, you must run down the image.
The resulting contxt value from a $CHECK_ACCESS call can also be
used as the input contxt argument to the $GETUAI system service,
and vice versa.
clsnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Object class name associated with the protected object. The
clsnam argument is the address of a descriptor pointing to the
name of the object class associated with the object specified by
either the objnam or the objpro argument. The clsnam and objtyp
arguments are mutually exclusive. The clsnam argument is the
preferred argument to $CHECK_ACCESS. The following object class
names are valid:
CAPABILITY QUEUE
COMMON_EVENT_CLUSTER RESOURCE_DOMAIN
DEVICE SECURITY_CLASS
FILE SYSTEM_GLOBAL_SECTION
GROUP_GLOBAL_SECTION VOLUME
LOGICAL_NAME_TABLE
objpro
OpenVMS usage:char_string
type: opaque byte stream or object handle
access: read only
mechanism: by descriptor
Buffer containing an object security profile or object handle.
The objpro argument is the address of a descriptor pointing to
a buffer that contains an encoded object security profile or the
address of a descriptor pointing to an object handle.
Object handles vary according to the associated security object
class. Currently, the only supported object handles are for the
file and device class objects where the object handle is a word
or longword channel.
The objpro and objnam arguments are mutually exclusive unless the
objpro argument is a simple object handle. The objpro and usrpro
arguments are also mutually exclusive unless the objpro argument
is an object handle.
usrpro
OpenVMS usage:char_string
type: opaque byte stream
access: read only
mechanism: by descriptor
Buffer containing a user security profile. The usrpro argument is
the address of a descriptor pointing to a buffer that contains an
encoded user security profile.
The $CREATE_USER_PROFILE service can be used to construct a user
security profile. The usrpro and usrnam arguments are mutually
exclusive. The objpro and usrpro arguments are also mutually
exclusive unless the objpro argument is an object handle.
|
27 - $CHECK FEN (Alpha Only)
|
On Alpha systems, indicates whether floating point is enabled for
the current image.
Format
SYS$CHECK_FEN
C Prototype
int sys$check_fen (void);
27.1 - Arguments
None.
Determines whether the caller has the specified privileges
or identifier. In addition to checking for a privilege or an
identifier, $CHECK_PRIVILEGE determines if the caller's use of
privilege needs to be audited.
Format
SYS$CHECK_PRIVILEGE [efn] ,prvadr ,[altprv] ,[flags] ,[itmlst]
,[audsts] ,[astadr] ,[astprm]
C Prototype
int sys$check_privilege (unsigned int efn, struct _generic_64
*prvadr, struct _generic_64
*altprv, unsigned int flags, void
*itmlst, unsigned int *audsts, void
(*astadr)(__unknown_params), int
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 audit completes. The
efn argument is a longword containing the number of the event
flag; however, $CHECK_PRIVILEGE uses only the low-order byte. If
efn is not specified, event flag 0 is used.
Upon request initiation, $CHECK_PRIVILEGE clears the specified
event flag.
prvadr
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
The privilege, privileges, or identifier that the calling process
must possess.
The prvadr argument is either the address of a quadword bit
array, where each bit corresponds to a privilege, or the address
of a quadword identifier.
When the array lists privileges, each bit has a symbolic name.
The $PRVDEF macro defines these names. You form the bit array
by specifying the symbolic name of each desired privilege in a
logical OR operation. See the $SETPRV system service for the
symbolic name and description of each privilege.
If the caller passes an identifier, the caller must set the
NSA$M_IDENTIFIER bit in the flags longword. The identifier
structure is defined by the $KGBDEF macro. The identifier
attributes (KGB$) are reserved for future use and should be set
to 0.
altprv
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Alternate privilege mask to check against. The altprv argument
is the address of a quadword privilege mask, where each bit
corresponds to a privilege. This argument and the flags NSA$M_
AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
exclusive.
With this argument, $CHECK_PRIVILEGE uses the supplied set of
privileges instead of the current, active privileges. Each bit
in the mask has a symbolic name, defined by the $PRVDEF macro.
You form the bit array by specifying the symbolic name of each
desired privilege in a logical OR operation. See the $SETPRV
system service for the symbolic name and description of each
privilege.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags that specify options for the $CHECK_PRIVILEGE operation.
The flags argument is a longword bit mask, where each bit
corresponds to an option.
Each flag option has a symbolic name. The $NSADEF macro defines
the following symbolic names. Be aware that the flags NSA$M_
AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
exclusive; therefore, you can specify only one of these flag
options.
Symbolic Name Description
NSA$M_AUTHPRIV Checks the authorized privileges of the
process instead of the current (active)
privileges.
NSA$M_FLUSH Specifies that all messages in the audit
server buffer be written to the audit log
file.
NSA$M_IDENTIFIER Interprets the prvadr argument as the address
of an identifier instead of a privilege mask.
NSA$M_INTERNAL Specifies that the $CHECK_PRIVILEGE call
originates in the context of a trusted
computing base (TCB) component. The auditing
components use this flag to indicate that
internal auditing failures should result in a
SECAUDTCB bugcheck. This flag is reserved to
Compaq.
NSA$M_MANDATORY Specifies that an audit is to be performed,
regardless of system alarm and audit settings.
NSA$M_PROCPRIV Checks the permanent privileges of the
process, instead of the privileges in the
current (active) mask.
NSA$M_SERVER Indicates that the call originates in a TCB
server process and that the event should be
audited regardless of the state of a process-
specific no-audit bit.
Trusted servers use this flag to override
the no-audit bit when they want to perform
explicit auditing on behalf of a client
process. This flag is reserved to Compaq.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying additional security auditing information
to be included in any security audit that is generated by the
service. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
audsts
OpenVMS usage:cond_value_type
type: longword (unsigned)
access: write only
mechanism: by reference
Longword condition value that receives a final completion status
from the operation. If a security audit is required, the final
completion status represents either the successful completion of
the resulting security audit or any failing status that occurred
while the security audit was performed within the AUDIT_SERVER
process.
The audsts argument is valid only when the service returns
success and the status is not SS$_EVTNOTENAB. In addition, the
caller must either make use of the astadr argument or use the
$CHECK_PRIVILEGEW service before attempting to access audsts.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Asynchronous system trap (AST) routine to be executed after the
audsts argument is written. The astadr argument, which is the
address of a longword value, is the procedure value of the AST
routine.
The AST routine executes in the access mode of the caller of
$CHECK_PRIVILEGE.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Asynchronous system trap (AST) parameter passed to the AST
service routine. The astprm argument is a longword value
containing the AST parameter.
Determines whether the caller has the specified privileges
or identifier. In addition to checking for a privilege or an
identifier, the Check Privilege and Wait service determines if
the caller's use of privilege needs to be audited.
$CHECK_PRIVILEGEW completes synchronously; that is, it returns
the final status to the caller only after receiving an explicit
confirmation from the audit server that the associated audit, if
enabled, has been performed.
Format
SYS$CHECK_PRIVILEGEW efn ,prvadr ,[altprv] ,[flags] ,[itmlst]
,audsts ,[astadr] ,[astprm]
C Prototype
int sys$check_privilegew (unsigned int efn, struct _generic_64
*prvadr, struct _generic_64
*altprv, unsigned int flags, void
*itmlst, unsigned int *audsts, void
(*astadr)(__unknown_params), int
astprm);
Determines whether an accessor with the specified rights and
privileges can access an object with the specified attributes.
Format
SYS$CHKPRO itmlst ,[objpro] ,[usrpro]
C Prototype
int sys$chkpro (void *itmlst, void *objpro, void *usrpro);
30.1 - Argument
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Protection attributes of the object and the rights and privileges
of the accessor. The itmlst argument is the address of an item
list of descriptors used to specify the protection attributes of
the object and the rights and privileges of the accessor.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
Specifying any specific protection attribute causes that
protection check to be made; any protection attribute not
specified is not checked. Rights and privileges specified are
used as needed. If a protection check requires any right or
privilege not specified in the item list, the right or privilege
of the caller's process is used.
objpro
OpenVMS usage:char_string
type: opaque byte stream
access: read only
mechanism: by descriptor
Buffer containing an object security profile. The objpro
argument is the address of a descriptor pointing to a buffer
that contains an encoded object security profile. The objpro
argument eliminates the need to supply all of the component
object protection attributes with the $CHKPRO item list. The
objpro argument is currently reserved to Compaq.
usrpro
OpenVMS usage:char_string
type: opaque byte stream
access: read only
mechanism: by descriptor
Buffer containing a user security profile. The usrpro argument is
the address of a descriptor pointing to a buffer that contains an
encoded user security profile. The usrpro argument eliminates the
need to supply all of the component user security attributes with
the $CHKPRO item list.
The $CREATE_USER_PROFILE service can be used to construct a user
security profile. When the usrpro argument is specified, any
component user profile attributes specified in the $CHKPRO item
list replace those contained in the user security profile.
|
31 - $CLEAR SYSTEM EVENT (Alpha Only)
|
Removes one or more notification requiests previously established
by a call to $SET_SYSTEM_EVENT.
This service does not allow you to specify a handle and an
event. You must pass a zero as one of these parameters. You can
either clear by handle or request that all events for the user be
cleared.
Format
SYS$CLEAR_SYSTEM_EVENT [handle] ,[acmode] ,event
C Prototype
int sys$clear_system_event (struct _generic_64 * handle,
unsigned int acmode, unsigned int
event);
31.1 - Arguments
handle
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification of the AST request to be cleared. The handle
argument uniquely identifies the request and is returned when
the $SET_SYSTEM_EVENT service is called. The handle argument may
be omitted by specifying a zero address.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the system event to be cleared. The acmode
argument is a longword containing the access mode. The value of
the access mode is maximized with the access mode of the caller.
event
OpenVMS usage:event_code
type: longword (unsigned)
access: read only
mechanism: by value
The event argument is a value indicating the type of system event
to be cleared. SYSEVT$C_ALL_EVENTS may be specified to clear all
event types.
Clears the "AST active" status.
This enables delivery of asynchronous system traps (ASTs) for the
access mode from which the service call was issued, while an AST
routine is active.
NOTE
The explicit use of $CLRAST is strongly discouraged, as
it complicates synchronization issues and may lead to the
unbounded consumption of stack space.
Normally, AST delivery for a particular access mode is deferred
while an AST routine is executing in that access mode. When the
AST routine returns, an implicit call is made to $CLRAST to re-
enable AST delivery.
Explicitly calling $CLRAST within an AST routine allows the
delivery of ASTs for the access mode from which the service call
was issued, prior to completion of the active AST routine.
Format
SYS$CLRAST
32.1 - Arguments
None.
Removes one or more notification requests previously established
by a call to SYS$SETCLUEVT.
Format
SYS$CLRCLUEVT [handle] ,[acmode] ,[event]
C Prototype
int sys$clrcluevt (struct _cluevthndl *handle, unsigned int
acmode, unsigned int event);
33.1 - Arguments
handle
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification of the AST request to be canceled. The handle
argument uniquely identifies the request and is returned when the
$SETCLUEVT service is called.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the cluster configuration event to be canceled.
The acmode argument is a longword containing the access mode.
Each access mode has a symbolic name. The $PSLDEF macro defines
the following symbols for the four access types:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
event
OpenVMS usage:event_code
type: longword (unsigned)
access: read only
mechanism: by value
Event code indicating the type of cluster configuration event for
which an AST is no longer to be delivered. The event argument is
a value indicating which type of event is no longer of interest.
Each event type has a symbolic name. The $CLUEVTDEF macro defines
the following symbolic names:
Symbolic Name Description
CLUEVT$C_ADD One or more OpenVMS nodes have been added to
the OpenVMS Cluster system.
CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed
from the OpenVMS Cluster system.
Clears (sets to 0) an event flag in a local or common event flag
cluster.
Format
SYS$CLREF efn
C Prototype
int sys$clref (unsigned int efn);
34.1 - Argument
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be cleared. The efn argument is a
longword containing this number; however, $CLREF uses only the
low-order byte.
Changes the access mode of the calling process to executive mode.
Format
SYS$CMEXEC routin ,[arglst]
C Prototype
int sys$cmexec (int (*routin)(__unknown_params), unsigned int
*arglst);
Arguments
routin
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Routine to be executed while the process is in executive mode.
The routin argument is the address of this routine.
arglst
OpenVMS usage:arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Argument list to be passed to the routine specified by the routin
argument. The arglst argument is the address of this argument
list.
If the arglst value is nonzero and is not accessible as an
address or if the routine is inaccessible, the service returns
SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a
value of 0 in the arglst argument. This means that the arglst
argument must contain an accessible virtual address for an
argument list, the first longword of which must be a valid list
size.
|
36 - $CMEXEC 64 (Alpha Only)
|
On Alpha systems, changes the access mode of the calling process
to executive mode.
This service accepts 64-bit addresses.
Format
SYS$CMEXEC_64 routin_64 ,arglst_64
C Prototype
int sys$cmexec_64 (int (*routin_64)(__unknown_params),
unsigned __int64 *arglst_64);
36.1 - Arguments
routin_64
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference
Routine to be executed while the process is in executive mode.
The routin_64 argument is the 32- or 64-bit address of this
routine.
arglst_64
OpenVMS usage:arg_list
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Argument list to be passed to the routine specified by the
routin_64 argument. The arglst_64 argument is the 32- or 64-bit
address of this argument list.
If the arglst value is nonzero and is not accessible as an
address or if the routine is inaccessible, the service returns
SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a
value of 0 in the arglst_64 argument. This means that the arglst_
64 argument, if nonzero, must contain an accessible virtual
address for an argument list, the first quadword of which must
be a number between 0 and 255 specifying the number of quadwords
that follow it on the list.
Changes the access mode of the calling process to kernel mode.
This service allows a process to change its access mode to
kernel, execute a specified routine, and then return to the
access mode in effect before the call was issued.
Format
SYS$CMKRNL routin ,[arglst]
C Prototype
int sys$cmkrnl (int (*routin)(__unknown_params), unsigned int
*arglst);
Arguments
routin
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Routine to be executed while the process is in kernel mode. The
routin argument is the address of this routine.
arglst
OpenVMS usage:arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Argument list to be passed to the routine specified by the routin
argument. The arglst argument is the address of this argument
list.
If the arglst value is nonzero and is not accessible as an
address or if the routine is inaccessible, the service returns
SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a
value of 0 in the arglst argument. This means that the arglst
argument must contain an accessible virtual address for an
argument list, the first longword of which must be a valid list
size.
|
38 - $CMKRNL 64 (Alpha Only)
|
On Alpha systems, changes the access mode of the calling process
to kernel mode. This service allows a process to change its
access mode to kernel, execute a specified routine, and then
return to the access mode in effect before the call was issued.
This service accepts 64-bit addresses.
Format
SYS$CMKRNL_64 routin_64 ,arglst_64
C Prototype
int sys$cmkrnl_64 (int (*routin_64)(__unknown_params),
unsigned __int64 *arglst_64);
38.1 - Arguments
routin_64
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference
Routine to be executed while the process is in kernel mode. The
routin_64 argument is the 32- or 64-bit address of this routine.
arglst_64
OpenVMS usage:arg_list
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Quadword argument list to be passed to the routine specified
by the routin_64 argument. The routin_64 argument is the 32- or
64-bit address of this routine.
If the arglst value is nonzero and is not accessible as an
address or if the routine is inaccessible, the service returns
SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a
value of 0 in the arglst_64 argument. This means that the arglst_
64 argument, if nonzero, must contain an accessible virtual
address for an argument list, the first quadword of which must
be a number between 0 and 255 specifying the number of quadwords
that follow it on the list.
|
39 - $CPU CAPABILITIES (Alpha Only)
|
On Alpha systems, allows modification of the user capability
set for a specified CPU, or for the global user capability CPU
default.
This service accepts 64-bit addresses.
Format
SYS$CPU_CAPABILITIES cpu_id [,select_mask] [,modify_mask]
[,prev_mask] [,flags]
C Prototype
int sys$cpu_capabilities (int cpu_id, struct _generic_64
*select_mask, struct _generic_64
*modify_mask, struct _generic_64
*prev_mask, struct _generic_64
*flags);
39.1 - Arguments
cpu_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Identifier of the CPU whose user capability mask is to be
modified or returned. The cpu_id argument is a longword
containing this number, which is in the supported range of
individual CPUs from 0 to SYI$_MAX_CPUS -1.
Specifying the constant CAP$K_ALL_ACTIVE_CPUS applies the current
modification operation to all CPUs currently in the active set,
and to the default CPU initialization context in SCH$GL_DEFAULT_
CPU_CAP. If the prev_mask argument is also supplied, the previous
default CPU initialization context in SCH$GL_DEFAULT_CPU_CAP will
be returned rather than any specific CPU state.
To modify only the user capabilities in SCH$GL_DEFAULT_CPU_CAP,
the flags argument has a bit constant CAP$M_FLAG_DEFAULT_ONLY.
When this bit is set, all service operations are performed on
the global cell rather than on an individual CPU specified in
the cpu_id argument. This bit does not supersede the CAP$K_
ALL_ACTIVE_CPUS constant, however. If both constants are
specified, CAP$K_ALL_ACTIVE_CPUS take precedence; nevertheless,
the operations to SCH$GL_DEFAULT_CPU are identical because that
function is a direct subset of the other.
select_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying which bits of the specified CPU's user capability
mask are to be modified. The select_mask argument is the 32-
or 64-bit address of a quadword bit vector wherein a bit, when
set, specifies that the corresponding user capability is to be
modified.
The individual user capability bits in select_mask can be
referenced by their symbolic constant names, CAP$M_USER1 through
CAP$M_USER16. These constants (not zero-relative) specify the
position in the mask quadword that corresponds to the bit
name. Multiple capabilities can be selected by connecting the
appropriate bits with a logical OR operation.
The constant CAP$K_ALL_USER, when specified in the select_mask
argument, selects all user capability bits.
modify_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying the settings for those capabilities selected in
the select_mask argument. The modify_mask argument is the 32-
or 64-bit address of a quadword bit vector wherein a bit, when
set, specifies that the corresponding user capability is to be
added to the specified CPU; when clear, the corresponding user
capability is to be removed from the specified CPU.
The bit constants CAP$M_USER1 through CAP$M_USER16 can be used
to modify the appropriate bit position in modify_mask. Multiple
capabilities can be modified by connecting the appropriate bits
with OR.
To add a specific user capability to the specified CPU, that
bit position must be set in both select_mask and modify_mask. To
remove a specific user capability from the specified CPU, that
bit position must be set in select_mask and cleared in modify_
mask.
The symbolic constant CAP$K_ALL_USER_ADD, when specified in
modify_mask, indicates that all capabilities specified in select_
mask are to be added to the current user capability set. The
constant CAP$K_ALL_USER_REMOVE indicates that all capabilities
specified are to be cleared from the set.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Previous user capability mask for the specified CPU before
execution of this call to $CPU_CAPABILITIES. The prev_mask
argument is the 32- or 64-bit address of a quadword into which
$CPU_CAPABILITIES writes a quadword bit mask specifying the
previous user capabilities.
If this argument is specified in conjunction with CAP$K_ALL_
ACTIVE_CPUS as the cpu_id selection constant or with CAP$M_
FLAG_DEFAULT_ONLY, the user capability portion of the default
boot initialization state context SCH$GL_DEFAULT_CPU_CAP will be
returned.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for the user capability modification. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option. Only the bits specified in the following table are used;
the remainder of the quadword bits are reserved and must be 0.
Each option (bit) has a symbolic name, defined by the $CAPDEF
macro. The flags argument is constructed by performing a logical
OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:
Symbolic Name Description
CAP$M_FLAG_DEFAULT_ Indicates that the specified operations
ONLY are to be performed on the global context
cell instead of on a specific CPU.
This bit supersedes any individual CPU
specified in cpu_id but does not override
the all active set behavior (CAP$K_ALL_
ACTIVE_CPUS). Specifying this bit constant
applies this operation to the default
startup capabilities for all CPUs booted
for the first time.
CAP$M_FLAG_CHECK_CPU Determines whether the kernel thread can
be left in a nonrunnable state under
some circumstances. No operation of
this service allows a transition from a
runnable to blocked state; however, if
the kernel thread is already at a blocked
state, this bit determines whether the
result of the operation must leave it
runnable. If CAP$M_FLAG_CHECK_CPU is set
or flags is not specified, the kernel
thread is checked to ensure that it can
safely run on one of the CPUs in the
active set. If CAP$M_FLAG_CHECK_CPU is
not set, any state operations on kernel
threads already in a blocked state are
allowed.
|
40 - $CPU TRANSITION (Alpha Only)
|
On Alpha systems, changes the current processing state of a CPU
in the configure set of the current system or an unassigned
CPU in an OpenVMS Galaxy configuration. This service completes
asynchronously. For synchronous completion, use the $CPU_
TRANSITIONW service.
This service accepts 64-bit addresses. Parameter and bit
definitions are resolved in $CSTDEF in the appropriate STARLET
library.
Refer to the OpenVMS Alpha Partitioning and Galaxy Guide for more
information.
Format
SYS$CPU_TRANSITION tran_code ,cpu_id ,nodename ,node_id ,flags
,efn ,iosb ,astadr_64 ,astprm_64
C Prototype
int sys$cpu_transition (int tran_code, int cpu_id,
dsc64$descriptor_s_pq nodename, int
node_id, uint32 flags, int efn, IOSB
*iosb, VOID_PQ astadr, uint64 astprm,
uint32 timout);
Arguments
tran_code
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Identifier specifying the type of state change to be initiated on
the target CPU. The tran_code argument is a longword containing
one of the following values:
Symbolic Name Description
CST$K_CPU_STOP The target CPU is to be removed from the
active set and halted into console mode. It
remains in the configure set of the current
partition.
CST$K_CPU_MIGRATE The target CPU is removed from the configure
set of the local partition and the console
is requested to add it to the configure set
of the partition specified in node_id. If
the CPU is currently in the active set, it is
automatically brought to console mode through
the CST$K_CPU_STOP function first.
CST$K_CPU_START The target CPU is requested to exit console
mode and join the active set of the current
partition. The CPU must already be part of the
configure set.
CST$K_CPU_ The CPU is assigned a default target partition
FAILOVER where it will automatically migrate on system
failure. This assignment persists until it
is superseded. To remove an assignment or
partition name, the current partition ID
should be specified.
cpu_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Identifier of the CPU whose state is to be modified. The cpu_
id argument is a longword number in the supported range of
individual CPUs from 0 to SYI$_MAX_CPUS - 1. In a Galaxy, this
CPU must be in the configure set of the local partition or not
assigned to any other partitions. The symbolic values, CST$K_ANY_
LOCAL_CPU can be used in certain types of transitions to allow
the next available processor of the appropriate type be used
instead of a specific one.
node_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Identifier of the target Galaxy partition in CST$K_CPU_ASSIGN,
CST$K_CPU_FAILOVER, or CST$K_CPU_MIGRATE transition. The node_id
argument is a longword containing a number in the supported range
of IDs provided by the console for the current hardware platform.
If the nodename parameter is specified, node_id is ignored.
flags
OpenVMS usage:longword_mask
type: longword (unsigned)
access: read only
mechanism: by value
Options selected for the CPU state transition. The flags argument
is a longword bit vector wherein a bit corresponds to an option.
Only the bits specified below are used; the remainder of the
longword bits are reserved and must be 0.
Each option (bit) has a symbolic name. The flags argument is
constructed by performing a logical OR operation using the
symbolic names of the following options:
Symbolic Name Description
CST$V_CPU_ At the completion of the transition, the CPU's
DEFAULT_ user capabilities are set back to the default
CAPABILITIES system value. If this option is not specified,
modified user capabilities are maintained
across STOP and START transitions as long
as the CPU remains in the local partition
configure set.
CST$V_CPU_ALLOW_ The transition is to be allowed even though it
ORPHANS will leave at least one thread in the system
unable to execute on any CPU in the active
set.
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
The event flag to be set when the state transition attempt has
completed. The efn argument is a longword specifying the number
of the event flag; however, this service only uses the low-order
byte.
When you invoke $CPU_TRANSITION, the specified event flag is
cleared; when the operation is complete, the event flag is set.
iosb
OpenVMS usage:io_status_area
type: IOSB structure
access: write only
mechanism: by 32-bit or 64-bit reference
The I/O status area to receive the final completion status of
the transition operation. The iosb argument is the 32-bit or 64-
bit virtual address of the I/O status area. The I/O status area
structure is 32 bytes in length; its definition can be found in
$IOSBDEF in STARLET.MLB for macro and in the file IOSBDEF.H in
SYS$STARLET_C.TLB for C.
When you call $CPU_TRANSITION, the I/O status area is cleared.
After the transition operation is complete, the block is modified
as follows:
Symbolic Name Description
iosb$w_status The first word contains the condition value
return, indicating the final completion status
of the operation.
The first bit in the second word of the IOSB
is set only if an error occurred during the
operation; the remaining bits are zeroes.
astadr_64
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32-bit or 64-bit reference
The AST routine to be executed when the requested transition
attempt has completed. The astadr_64 argument is the 32-bit
or 64-bit virtual address of this routine. If you specify the
astadr_64 argument, the AST routine executes at the access mode
from which the state transition was requested.
astprm_64
OpenVMS usage:user_arg
type: quadword
access: read only
mechanism: by value
The quadword AST parameter to be passed to the AST routine.
|
41 - $CPU TRANSITIONW (Alpha Only)
|
On Alpha systems, changes the current processing state of a
CPU in the configure set or an unassigned CPU in a Galaxy
configuration. This service completes synchronously; that is,
it returns to the caller only after the final completion status
of the operation is known.
In all other respects, $CPU_TRANSITIONW is identical to $CPU_
TRANSITION. For all other information about the $CPU_TRANSITIONW
service, refer to the description of $CPU_TRANSITION in this
manual.
This service accepts 64-bit addresses.
Refer to the OpenVMS Alpha Partitioning and Galaxy Guide for more
information.
Format
SYS$CPU_TRANSITIONW tran_id ,cpu_id ,nodename ,node_id ,flags
,efn ,iosb ,astadr_64 ,astprm_64
C Prototype
int sys$cpu_transitionw (int tran_code, int cpu_id,
dsc64$descriptor_s_pq nodename,
int node_id, uint32 flags, int efn,
IOSB *iosb, UINT64_PQ astadr, uint64
astprm, uint32 timout);
|
42 - $CREATE GALAXY LOCK (Alpha Only)
|
Allocates an OpenVMS Galaxy lock block from a lock table created
with the $CREATE_GALAXY_LOCK_TABLE service.
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 OpenVMS Alpha Partitioning and Galaxy
Guide.
Format
SYS$CREATE_GALAXY_LOCK lcktbl_handle ,name ,size ,timeout ,ipl
,rank ,handle
C Prototype
int sys$create_galaxy_lock (unsigned int lcktbl_handle, void
*name, unsigned int size, unsigned
int timeout, unsigned int ipl,
unsigned int rank, unsigned __int64
*lock_handle);
Arguments
lcktbl_handle
OpenVMS usage:lock table handle
type: longword (unsigned)
access: read
mechanism: input by value
The 32-bit lock table handle that identifies the lock table in
which to create the lock. This value is returned by SYS$CREATE_
GALAXY_LOCK_TABLE.
name
OpenVMS usage:address
type: ASCID string
access: read
mechanism: input by reference
The name parameter is a pointer to an ASCID string (passed by
descriptor). The name can be a maximum of 15 characters. Lock
names are not checked for uniqueness; therefore, multiple locks
can be created with the same name.
timeout
OpenVMS usage:wait timeout
type: longword (unsigned)
access: read
mechanism: input by value
The 32-bit wait or spin timeout specified in 10 microsecond
units. If not specified, the timeout defaults to 10 microseconds.
size
OpenVMS usage:byte count
type: longword (unsigned)
access: read
mechanism: input by value
The size of the galaxy lock in bytes. Galaxy locks have two legal
sizes. These values are returned by SYS$GET_GALAXY_LOCK_SIZE. The
value passed to SYS$CREATE_GALAXY_LOCK must be equal to the value
passed to the call to SYS$CREATE_GALAXY_LOCK_TABLE.
ipl
OpenVMS usage:IPL of lock
type: longword (unsigned)
access: read
mechanism: input by value
For galaxy locks acquired in kernel mode, the IPL to raise to
while the lock is held. This parameter is ignored for all other
access mode.
rank
OpenVMS usage:rank of lock
type: longword (unsigned)
access: read
mechanism: input by value
Rank applied to a galaxy lock. Ranking is used to detect
potential deadlocks. This parameter is currently ignored.
handle
OpenVMS usage:address
type: quadword (unsigned)
access: write
mechanism: output by reference
The handle parameter is a pointer to a quadword. The value
returned is a 64-bit handle that uniquely identifies the lock
galaxy-wide.
|
43 - $CREATE GALAXY LOCK TABLE (Alpha Only)
|
Allocates an OpenVMS Galaxy lock table.
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 OpenVMS Alpha Partitioning and Galaxy
Guide.
Format
SYS$CREATE_GALAXY_LOCK_TABLE name ,accmode ,section_size
,section_type ,prot ,lock_size
,lcktbl_handle
C Prototype
int sys$create_galaxy_lock_table (void *name, unsigned int
accmode, unsigned __int64
section_size, unsigned int
section_type, unsigned int
prot, unsigned int lock_size,
unsigned int *lcktbl_handle);
43.1 - Arguments
name
OpenVMS usage:address
type: ASCID string
access: read
mechanism: input by reference
The name parameter is a pointer to an ASCID string (passed by
descriptor). The name is given to the global section that is
created to contain the galaxy locks.
accmode
OpenVMS usage:access mode
type: longword (unsigned)
access: read
mechanism: input by value
Access mode that is to be the owner of the pages created during
the mapping. The accmode argument is a longword containing the
access mode.
section_size
OpenVMS usage:byte count
type: quadword (unsigned)
access: read
mechanism: input by value
Length of the global section to be created, in bytes. The size
must be specified as a multiple of the CPU-specific page size. A
size of zero is illegal.
section_type
OpenVMS usage:bit mask
type: longword (unsigned)
access: read
mechanism: input by value
Used to control where in virtual memory the global section
is created. If GLCKTBL$C_PROCESS is specified, the section is
created in P2 (process) space. If GLCKTBL$C_SYSTEM is specified,
the section is created in S0/S1 (system) space. These constants
are defined in the GLOCKDEF macro.
prot
OpenVMS usage:protection
type: longword (unsigned)
access: read
mechanism: input by value
Protection to be applied to the global section.
lock_size
OpenVMS usage:byte count
type: longword (unsigned)
access: read
mechanism: input by value
The size of the galaxy lock in bytes. Galaxy locks have two
sizes. The legal values are returned by SYS$GET_GALAXY_LOCK_SIZE.
lcktbl_handle
OpenVMS usage:address
type: longword
access: write
mechanism: output by reference
Pointer to a longword. The value returned is a 32-bit handle that
uniquely identifies the lock table galaxy-wide.
|
44 - $CREATE BUFOBJ 64 (Alpha Only)
|
On Alpha systems, creates a buffer object out of a range of
pages.
This service accepts 64-bit addresses.
Format
SYS$CREATE_BUFOBJ_64 start_va_64 ,length_64 ,acmode ,flags
,return_va_64 ,return_length_64
,buffer_handle_64
C Prototype
int sys$create_bufobj_64 (void *start_va_64, unsigned
__int64 length_64, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64, struct _generic_64
*buffer_handle_64);
44.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
Starting virtual address of the pages to be included in the
buffer object. The specified virtual address will be rounded
down to a CPU-specific page boundary.
The virtual address space must already exist.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be included in the buffer
object. The specified length will be rounded up to a CPU-specific
page boundary such that it includes all CPU-specific pages in the
requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of
the caller. For the $CREATE_BUFOBJ_64 service to complete
successfully, the resultant access mode must be equal to or more
privileged than the access mode already associated with the pages
in the specified input range.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the request options. The flags argument is a
longword bit vector in which each bit corresponds to a flag. The
$CBODEF macro in STARLET.MLB and CBODEF.H file in SYS$STARLET_
C.TLB define a symbolic name for each flag.
The following table describes each flag that is valid for the
$CREATE_BUFOBJ_64 service:
Flag Value Description
CBO$M_RETSVA 1 If set, returns the system virtual address
in the return_va_64 argument instead of the
process virtual address range. (Valid for
inner mode callers only.)
CBO$M_SVA_32 4 If set, creates the buffer object window
in 32-bit S0/S1 space. (By default, this
service creates the window in 64-bit S2
space.)
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the pages in the buffer
object. The return_va_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service
returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range in the buffer object. The
return_length_64 argument is the 32- or 64-bit virtual address of
a naturally aligned quadword into which the service returns the
length of the virtual address range in bytes.
buffer_handle_64
OpenVMS usage:handle
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned
quadword into which a buffer handle is returned to be used when
referencing the created buffer object.
|
45 - $CREATE GDZRO (Alpha Only)
|
On Alpha systems, creates a permanent, memory-resident, global
demand-zero section to which processes can map. Shared page table
sections can also be created.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GDZRO gs_name_64 ,ident_64 ,prot ,length_64 ,acmode
,flags [,reserved_length_64] [,rad_mask]
C Prototype
int sys$create_gdzro (void *gs_name_64, struct _secid
*ident_64, unsigned int prot, unsigned
__int64 length_64, unsigned int acmode,
unsigned int flags,...);
45.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of the global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. Their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global demand-zero section. The
mask contains four 4-bit fields. Bits are read from right to left
in each field.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful for
section protection. Delete access bits are ignored. Read access
also grants execute access for those situations where execute
access applies. If 0 is specified, read access and write access
are granted to all users.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global demand-zero section to be
created. The length_64 argument must be specified as a multiple
of the CPU-specific page size. A length of 0 cannot be specified.
NOTE
Creating a memory-resident global section with shared page
tables does not imply that the global section must have
a length that is an even multiple of CPU-specific page
table pages. The global section might not fully use the
last shared page table page.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
If the memory-resident global section is created with shared
page tables, this is the access mode that is stored in the owner,
read, and write fields of the corresponding shared page table
entries (PTEs).
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of global section to be created as
well as its characteristics. The flags argument is a longword bit
vector in which each bit corresponds to a flag. The $SECDEF macro
and the SECDEF.H file define a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes the flags that are valid for the
$CREATE_GDZRO service:
Flag Description
SEC$M_DZRO Pages are demand-zero pages. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_MRES Pages form a memory-resident section. By default,
this flag is always present in this service and
cannot be disabled.
SEC$M_PERM Global section is permanent. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_RAD_ When set, the argument rad_mask is used as a mask
HINT of RADs from which to allocate memory. See the rad_
mask argument description for more information.
SEC$M_READ_ Create shared table pages for the section that
ONLY_SHPT allow read access only.
SEC$M_SHMGS Create a shared-memory global section.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_WRT Pages form a read/write section. By default, this
flag is always present in this service and cannot
be disabled.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set.
reserved_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: 32- or 64-bit reference
Length, in bytes, of the global section as currently registered
in the Reserved Memory Registry. The reserved_length_64 argument
is the 32- or 64-bit virtual address of a naturally aligned
quadword into which the service returns the reserved length.
If reserved_length_64 is not specified or is specified as 0, no
reserved length is returned to the caller.
If the memory-resident global section is not registered,
reserved_length_64 is written with the value 0.
rad_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by value
Use the rad_mask argument to specify from which RADs to allocate
memory. Currently only one bit may be set. The specified RAD
must contain memory. This argument is only a hint. Memory may be
obtained from other RADs if no free memory is available at the
time of allocation.
The rad_mask argument is considered only if the SEC$M_RAD_HINT
flag is specified. Otherwise, this argument is ignored.
On a system that does not support resource affinity domains
(RADs), specifying 1 for the rad_mask argument is allowed.
Note: OpenVMS support for RADs is available only on the new
AlphaServer GS series systems. For more information about using
RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
|
46 - $CREATE GFILE (Alpha Only)
|
On Alpha systems, creates a permanent global disk file section to
which processes can map.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GFILE gs_name_64 ,ident_64 ,file_offset_64
,length_64 ,chan ,acmode ,flags
,return_length_64 [,fault_cluster]
C Prototype
int sys$create_gfile (void *gs_nam_64, struct _secid
*ident_64, unsigned __int64
file_offset_64, unsigned __int64
length_64, unsigned short int chan,
unsigned int acmode, unsigned int flags,
unsigned __int64 *return_length_64,...);
46.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 64-
bit virtual address of a naturally aligned 32- or 64-bit string
descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order two bits. The valid values, symbolic names by which they
can be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword and contains
two fields: a minor identification in the low-order 24 bits
and a major identification in the high-order 8 bits. You can
assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
file_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Byte offset into the file that marks the beginning of the
section. The file_offset_64 argument is a quadword containing
this number. If you do not specify the file_offset_64 argument or
specify it as 0, the section is created beginning with the first
byte in the file.
The file_offset_64 argument must be a multiple of virtual disk
blocks.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global disk file section to be created.
The length specified must be 0 or a multiple of virtual disk
blocks. If the length specified is 0 or extends beyond end-of-
file (EOF), the global disk file section is created up to and
including the virtual block number that contains EOF.
chan
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The
chan argument is a longword containing this number. The access
mode at which the channel was opened must be equal to or less
privileged than the access mode of the caller.
You can use the OpenVMS Record Management Services (RMS) macro
$OPEN to access a file; the file options parameter in the file
access block must indicate a user file open (UFO keyword).
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of global section to be created as
well as its characteristics. The flags argument is a longword bit
vector in which each bit corresponds to a flag. The $SECDEF macro
and the SECDEF.H file define a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes each flag that is valid for the
$CREATE_GFILE service:
Flag Description
SEC$M_CRF Pages are copy-on-reference. By default, pages are
shared.
SEC$M_DZRO Pages are demand-zero pages. By default, they are
not zeroed when copied.
Note that SEC$M_DZRO and SEC$M_CRF cannot both be
set and that SEC$M_DZRO set and SEC$M_WRT clear is
an invalid combination.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PERM Global section is permanent. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the global section created. The return_length_64
argument is the 32- or 64-bit virtual address of a naturally
aligned quadword into which the service returns the length of the
global section in bytes.
fault_cluster
OpenVMS usage:byte count
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster in byte units indicating how many pages are
to be brought into memory when a page fault occurs for a single
page. The fault cluster specified is rounded up to a multiple of
CPU-specific pages.
If this argument is specified as 0, the system default page fault
cluster is used. If this argument is specified as more than
the maximum allowed for the system, no error is returned. The
systemwide maximum is used.
|
47 - $CREATE GPFILE (Alpha Only)
|
On Alpha systems, creates a permanent global page file section to
which processes can map.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GPFILE gs_name_64 ,ident_64 ,prot ,length_64
,acmode ,flags
C Prototype
int sys$create_gpfile (void *gs_name_64, struct _secid
*ident_64, unsigned int prot, unsigned
__int64 length_64, unsigned int acmode,
unsigned int flags);
47.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. Their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page file section. The
mask contains four 4-bit fields. Bits are read from right to left
in each field.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful for
section protection. Delete access bits are ignored. Read access
also grants execute access for those situations where execute
access applies. If 0 is specified, read access and write access
are granted to all users.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global page file section to be created.
The length_64 argument must be specified as a multiple of the
CPU-specific page size. A length of 0 cannot be specified.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of global section to be created as
well as its characteristics. The flags argument is a longword bit
vector in which each bit corresponds to a flag. The $SECDEF macro
and the SECDEF.H file define a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes the flags that are valid for the
$CREATE_GPFILE service:
Flag Description
SEC$M_DZRO Pages are demand-zero pages.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PAGFIL Pages form a global page-file section. SEC$M_PAGFIL
also implies SEC$M_WRT and SEC$M_DZRO. By default,
this flag is always present in this service and
cannot be disabled.
SEC$M_PERM Global section is permanent. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_WRT Pages form a read/write section. By default, this
flag is always present in this service and cannot
be disabled.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set.
|
48 - $CREATE GPFN (Alpha Only)
|
On Alpha systems, creates a permanent page frame section to which
processes can map.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GPFN gs_name_64 ,ident_64 ,prot ,start_pfn
,page_count ,acmode ,flags
C Prototype
int sys$create_gpfn (void *gs_name_64, struct _secid
*ident_64, unsigned int prot, unsigned
int start_pfn, unsigned int page_count,
unsigned int acmode, unsigned int flags);
48.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order two bits.
The valid values, symbolic names by which they can be specified,
and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page frame section. The
mask contains four 4-bit fields. Bits are read from right to left
in each field.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful
for section protection. Delete access bits are ignored. Read
access also grants execute access for those situations where
execute access applies. If zero is specified, read access and
write access are granted to all users.
start_pfn
OpenVMS usage:page frame number
type: longword (unsigned)
access: read only
mechanism: by value
The CPU-specific page frame number where the section begins in
memory.
page_count
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Length of the page frame section in CPU-specific pages.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the page frame
section to be created. The flags argument is a longword bit
vector in which each bit corresponds to a flag. The $SECDEF macro
and the SECDEF.H file define a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes the flags that are valid for the
$CREATE_GPFN service:
Flag Description
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PERM Global section is permanent. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PFNMAP Pages form a page frame section. By default, this
flag is always present in this service and cannot
be disabled.
SEC$M_SYSGBL Pages form a system global page frame section.
By default, pages form a group global page frame
section.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
Initializes a rights database.
Format
SYS$CREATE_RDB [sysid]
C Prototype
int sys$create_rdb (struct _generic_64 *sysid);
49.1 - Argument
sysid
OpenVMS usage:system_access_id
type: quadword (unsigned)
access: read only
mechanism: by reference
System identification value associated with the rights database
when $CREATE_RDB completes execution. The sysid argument is the
address of a quadword containing the system identification value.
If you omit sysid, the current system time in 64-bit format is
used.
|
50 - $CREATE REGION 64 (Alpha Only)
|
On Alpha systems, creates a virtual region within the process's
private address space.
This service accepts 64-bit addresses.
Format
SYS$CREATE_REGION_64 length_64 ,region_prot ,flags
,return_region_id_64 ,return_va_64
,return_length_64 [,start_va_64]
C Prototype
int sys$create_region_64 ( unsigned __int64 length_64,
unsigned int region_prot,
unsigned int flags, struct
_generic_64 *return_region_id, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
50.1 - Arguments
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual region to be created. The length specified
must be a multiple of CPU-specific pages. This length is fixed at
the time the region is created.
If the flag VA$M_SHARED_PTS is set, this length is rounded up to
include an even multiple of CPU-specific pages mapped by a page
table page.
region_prot
OpenVMS usage:region_protection
type: longword (unsigned)
access: read only
mechanism: by value
Region protection to be associated with the region to be created.
The region_prot argument is a longword containing the create and
owner mode.
The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
STARLET.MLB define the following symbols for valid combinations
of create and owner modes:
Symbol Create and Owner Modes
VA$C_REGION_UCREATE_ User create mode and user owner mode
UOWN
VA$C_REGION_UCREATE_ User create mode and supervisor owner mode
SOWN
VA$C_REGION_UCREATE_ User create mode and executive owner mode
EOWN
VA$C_REGION_UCREATE_ User create mode and kernel owner mode
KOWN
VA$C_REGION_SCREATE_ Supervisor create mode and supervisor
SOWN owner mode
VA$C_REGION_SCREATE_ Supervisor create mode and executive owner
EOWN mode
VA$C_REGION_SCREATE_ Supervisor create mode and kernel owner
KOWN mode
VA$C_REGION_ECREATE_ Executive create mode and executive owner
EOWN mode
VA$C_REGION_ECREATE_ Executive create mode and kernel owner
KOWN mode
VA$C_REGION_KCREATE_ Kernel create mode and kernel owner mode
KOWN
For both create and owner mode, the $CREATE_REGION_64 service
uses whichever of the following two access modes is least
privileged:
o Access mode specified by the acmode argument
o Access mode of the caller
A subsequent call to any system service that created address
space within a region must be made from an access mode that is
the same or more privileged than the create mode associated with
the region.
A subsequent call to $DELETE_REGION_64 to delete the region must
be made from an access mode that is the same or more privileged
than the owner mode associated with the region.
All regions created by $CREATE_REGION_64 are automatically
deleted when the image is run down on image exit.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the region to
be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The file VADEF.H in
SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a
symbolic name for each flag. You construct the flags argument
by performing a logical OR operation on the symbol names for all
desired flags.
The following table describes the flags that are valid for the
$CREATE_REGION_64 service:
Flag Description
VA$M_DESCEND Created region is a descending region; that
is, allocation occurs toward decreasing virtual
addresses. If VA$M_DESCEND is not specified,
the region allocation occurs toward increasing
virtual addresses.
VA$M_SHARED_PTS Created region requires the virtual address
space created within it to be capable of
using shared page tables. If this flag is not
specified, the virtual address space created
within the region is mapped by process-private
page tables only. By default, the region does
not allow the use of shared page tables.
VA$M_P0_SPACE Create region in P0 space. This flag cannot be
set if VA$M_P1_SPACE is set.
VA$M_P1_SPACE Create region in P1 space. This flag cannot be
set if VA$M_P0_SPACE is set.
All other bits in the flags argument are reserved for future use
by Compaq. The condition value SS$_IVREGFLG is returned if any
undefined bits are set.
return_region_id_64
OpenVMS usage:region identifier
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The region ID associated with the created region. The
return_region_id_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the region ID.
return_va_64
OpenVMS usage:return address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the region. The
return_va_64 argument is the 32- or 64-bit virtual address of
a naturally aligned quadword into which the service returns the
lowest virtual address of the region.
If the flag VA$M_SHARED_PTS is set, the returned virtual address
is aligned to a CPU-specific page table page boundary. If the
global section mapped by this shared page table region is large
enough that multiple page table pages are required to map the
global section, the page tables themselves can be mapped with
granularity hints; therefore, the alignment of the returned
virtual address can be even greater than that of a single CPU-
specific page table page boundary.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the region actually created. The return_length_64
argument is the 32- or 64-bit virtual address of a naturally
aligned quadword into which the service returns the length of the
region in bytes.
If the flag VA$M_SHARED_PTS is set, the returned length is the
input length rounded up to an even multiple of bytes mapped by a
single CPU-specific page table page.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting address for the created virtual region. The
specified virtual address must be a CPU-specific page aligned
address.
If the start_va_64 argument is not specified or is specified
as 0, the region can be created anywhere within the following
address spaces:
o P2 space (if the flags VA$M_P0_SPACE and VA$M_P1_SPACE are
clear)
o P0 space (if the flag VA$M_P0_SPACE is set and VA$M_P1_SPACE
is clear)
o P1 space (if the flag VA$M_P1_SPACE is set and VA$M_P0_SPACE
is clear)
If the flag VA$M_SHARED_PTS is set and this argument is
specified, the specified starting address must be aligned to a
natural page table page boundary or an error is returned.
|
51 - $CREATE USER PROFILE
|
Returns an encoded security profile for the specified user.
Format
SYS$CREATE_USER_PROFILE usrnam ,[itmlst] ,[flags] ,usrpro
,usrprolen ,[contxt]
C Prototype
int sys$create_user_profile (void *usrnam, void *itmlst,
unsigned int flags, void *usrpro,
unsigned int *usrprolen, unsigned
int *contxt);
51.1 - Arguments
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the user whose security profile is to be returned. The
usrnam argument is the address of a descriptor pointing to a text
string containing the user name. The user name string can contain
a maximum of 12 alphanumeric characters.
For more information about user names, refer to the OpenVMS Guide
to System Security.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying the portions of the user's security profile
to be replaced or augmented.
Refer to the OpenVMS System Services Reference Manual to view the
general format of an item descriptor and the fields description.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The flags argument is used to control the behavior of the
$CREATE_USER_PROFILE service. This argument does not accept ISS$
mask values; therefore, continue to use the CHP$ mask values for
this argument.
The following table describes each flag:
Symbol Description
CHP$M_ By default, $CREATE_USER_PROFILE initializes
DEFCLASS the security profile with the user's maximum
authorized classification. When this flag is set,
the service initializes the security profile from
the user's default classification instead. This
flag is reserved to Compaq.
CHP$M_DEFPRIV By default, $CREATE_USER_PROFILE initializes
the security profile with the user's authorized
privilege mask. When this flag is set, the
service initializes the security profile from
the user's default privilege mask instead.
CHP$M_ Instructs the service not to access the user
NOACCESS authorization file (SYSUAF.DAT) or rights
database (RIGHTSLIST.DAT) to build the security
profile. This flag can be used as an optimization
when all the information necessary to build the
security profile is known to the caller.
usrpro
OpenVMS usage:char_string
type: opaque byte stream
access: write only
mechanism: by reference
Buffer to receive the security profile. The usrpro argument is
the address of a buffer to receive the encoded security profile.
If an address of 0 is specified, $CREATE_USER_PROFILE returns the
size of the buffer needed in the usrprolen argument.
usrprolen
OpenVMS usage:word
type: word (unsigned)
access: read/write
mechanism: by reference
Word to receive the full size of the security profile. On input,
the usrprolen argument specifies the length of the buffer pointed
to by the usrpro argument. The usrprolen argument is the address
of a word to which $CREATE_USER_PROFILE writes the actual length
of the security profile. If the caller specifies a usrpro address
of 0, $CREATE_USER_PROFILE returns the anticipated size, in
bytes, of the buffer needed to hold the user's security profile
in the usrprolen argument.
contxt
OpenVMS usage:longword
type: longword (unsigned)
access: modify
mechanism: by reference
Longword used to maintain authorization file context. The contxt
argument is the address of a longword to receive a $GETUAI
context value. On the initial call, this longword should contain
the value -1. On subsequent calls, the value of the contxt
argument from the previous call should be passed back in.
Using the contxt argument keeps the UAF open across all calls,
thereby improving the performance of the system on subsequent
calls. To close the UAF, you must run down the image.
The resulting context value from a $CREATE_USER_PROFILE call can
also be used as the input contxt argument to the $GETUAI system
service, and vice versa.
Creates a logical name and specifies its equivalence names.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$CRELNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
C Prototype
int sys$crelnm (unsigned int *attr, void *tabnam, void
*lognam, unsigned char *acmode, void *itmlst);
52.1 - Arguments
attr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Attributes to be associated with the logical name. The attr
argument is the 32-bit address (on VAX systems) or the 32- or 64-
bit address (on Alpha systems) of a longword bit mask specifying
these attributes.
Each bit in the longword corresponds to an attribute and has a
symbolic name. These symbolic names are defined by the $LNMDEF
macro. To specify an attribute, specify its symbolic name or set
its corresponding bit. The longword bit mask is the logical OR of
all desired attributes. All undefined bits in the longword must
be 0.
If you do not specify this argument or specify it as 0 (no bits
set), no attributes are associated with the logical name.
The attributes are as follows:
Attribute Description
LNM$M_ If set, the logical name is not copied from the
CONFINE process to its spawned subprocesses. You create
a subprocess with the DCL command SPAWN or the
LIB$SPAWN Run-Time Library routine. If the logical
name is placed into a process-private table that
has the CONFINE attribute, the CONFINE attribute
is automatically associated with the logical
name. This applies only to process-private logical
names.
LNM$M_NO_ If set, the logical name cannot be duplicated in
ALIAS this table at an outer access mode. If another
logical name with the same name already exists in
the table at an outer access mode, it is deleted.
tabnam
OpenVMS usage:logical_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 table in which to create the logical name. The tabnam
argument is the 32-bit address (on VAX systems) or the 32- or
64-bit address (on Alpha systems) of a descriptor that points
to the name of this table. This argument is required and must be
specified in uppercase.
The name must be entered in uppercase letters. (This requirement
differs from the $CRELNT system service, which automatically
changes tabnam to uppercase.)
If tabnam is not the name of a logical name table, it is assumed
to be a logical name and is translated iteratively until either
the name of a logical name table is found or the number of
translations allowed by the system has been performed. If tabnam
translates to a list of logical name tables, the logical name is
entered into the first table in the list.
lognam
OpenVMS usage:logical_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 logical name to be created. The lognam argument
is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha systems) of a descriptor that points to the
logical name string. Logical name strings of logical names
created within either the system or process directory table
must consist of uppercase alphanumeric characters, dollar signs
($), and underscores (_); the maximum length is 31 characters.
The maximum length of logical name strings created within other
tables is 255 characters with no restrictions on the types of
characters that can be used. This argument is required.
acmode
OpenVMS usage:access_mode
type: byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Access mode to be associated with the logical name. The acmode
argument is the 32-bit address (on VAX systems) or the 32- or
64-bit address (on Alpha systems) of a byte that specifies the
access mode.
The access mode associated with the logical name is determined
by maximizing the access mode of the caller with the access
mode specified by the acmode argument, which means that the less
privileged of the two is used. Symbols for the four access modes
are defined by the $PSLDEF macro.
You cannot specify an access mode more privileged than that
of the containing table. However, if the caller has SYSNAM
privilege, then the specified access mode is associated with
the logical name regardless of the access mode of the caller.
If you omit this argument or specify it as 0, the access mode of
the caller is associated with the logical name.
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 describing the equivalence names to be defined for
the logical name and information to be returned to the caller.
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 specifies information about an
equivalence name. 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.
Note that it is possible to create a logical that has no
equivalence names. This is done by either omitting the itmlst
argument to $CRELNM, or by not including the LNM$_STRING item
code to the itmlst data structure that is passed into $CRELNM. It
is not possible to create this kind of logical using DCL.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
Creates a process-private or shareable logical name table.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$CRELNT [attr] ,[resnam] ,[reslen] ,[quota]
,[promsk] ,[tabnam] ,partab ,[acmode]
C Prototype
int sys$crelnt (unsigned int *attr, void *resnam, unsigned
short int *reslen, unsigned int *quota,
unsigned short int *promsk, void *tabnam, void
*partab, unsigned char *acmode);
53.1 - Arguments
attr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Attributes to affect the creation of the logical name table and
to be associated with the newly created logical name table. The
attr argument is the 32-bit address (on VAX systems) or the 32-
or 64-bit address (on Alpha systems) of a longword bit mask
specifying these attributes.
Each bit in the longword corresponds to an attribute and has a
symbolic name. These symbolic names are defined by the $LNMDEF
macro. To specify an attribute, specify its symbolic name or set
its corresponding bit. The longword bit mask is the logical OR of
all desired attributes. All unused bits in the longword must be
0.
If you do not specify this argument or specify it as 0 (no bits
set), no attributes are associated with the logical name table or
affect the creation of the new table.
The following table describes each attribute:
Attribute Description
LNM$M_CONFINE If set, the logical name table is not copied
from the process to its spawned subprocesses. You
create a subprocess with the DCL command SPAWN or
the Run-Time Library LIB$SPAWN routine. You can
specify this attribute only for process-private
logical name tables; it is ignored for shareable
tables.
The state of this bit is also propagated from
the parent table to the newly created table
and can be overridden only if the parent table
does not have the bit set. Thus, if the parent
table has the LNM$M_CONFINE attribute, the newly
created table will also have it, no matter what
is specified in the attr argument. On the other
hand, if the parent table does not have the
LNM$M_CONFINE attribute, the newly created table
can be given this attribute through the attr
argument.
The process-private directory table LNM$PROCESS_
DIRECTORY does not have the LNM$M_CONFINE
attribute.
LNM$M_CREATE_ This attribute applies to all types of logical
IF name tables except clusterwide logical name
tables. If set, a new logical name table is
created only if the specified table name is not
already entered at the specified access mode in
the appropriate directory table. If the table
name exists, a new table is not created and no
modification is made to the existing table name.
This holds true even if the existing name has
differing attributes or quota values, or even if
it is not the name of a logical name table.
If LNM$M_CREATE_IF is not set, the new logical
name table will supersede any existing table name
with the same access mode within the appropriate
directory table. Setting this attribute is useful
when two or more users want to create and use
the same table but do not want to synchronize its
creation.
Regardless of the setting of LNM$M_CREATE_IF:
o You cannot create a new clusterwide logical
name table with the same name and the same
mode as an existing clusterwide logical name
table until you delete the existing one.
o If you specify a new clusterwide logical name
table with the same name and access mode as
an existing local logical name table, the new
clusterwide logical name table is created,
and the local table and its logical names are
deleted.
LNM$M_NO_ If set, the name of the logical name table cannot
ALIAS be duplicated at an outer access mode within the
appropriate directory table. If this name already
exists at an outer access mode, it is deleted.
resnam
OpenVMS usage:logical_name
type: character-coded text string
access: write 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 newly created logical name table, returned by
$CRELNT. The resnam argument is the 32-bit address (on VAX
systems) or the 32- or 64-bit address (on Alpha systems) of a
descriptor pointing to this name. The name is a character string
whose maximum length is 31 characters.
reslen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Length in bytes of the name of the newly created logical name
table, returned by $CRELNT. The reslen argument is the 32-bit
address (on VAX systems) or the 32- or 64-bit address (on Alpha
systems) of a word to receive this length.
quota
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Maximum number of bytes of memory to be allocated for logical
names contained in this logical name table. The quota argument is
the 32-bit address (on VAX systems) or the 32- or 64-bit address
(on Alpha systems) of a longword specifying this value.
If you specify no quota value, the logical name table has an
infinite quota. Note that a shareable table created with infinite
quota permits users with write access to that table to consume
system dynamic memory without limit.
promsk
OpenVMS usage:file_protection
type: word (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Protection mask to be associated with the newly created shareable
logical name table. The promsk argument is the 32-bit address (on
VAX systems) or the 32- or 64-bit address (on Alpha systems) of
a word that contains a value that represents four 4-bit fields.
Each field grants or denies the type of access, either delete,
create, write, or read, allowed for system, owner, group, and
world users.
The following diagram depicts these protection bits:
|------------|------------|------------|------------|
| World | Group | Owner | System |
|------------|------------|------------|------------|
| D C W R | D C W R | D C W R | D C W R |
|------------|------------|------------|------------|
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Create access is required to create a shareable table within
another shareable table.
Each field consists of 4 bits specifying protection for the
logical name table. The remaining bits in the protection mask
are as follows:
o Read privileges allow access to names in the logical name
table.
o Write privileges allow creation and deletion of names within
the logical name table.
o Delete privileges allow deletion of the logical name table.
If a bit is clear, access is granted.
The initial security profile for any shared logical name table is
taken from the logical name table template. The owner is then set
to the process UIC and, if the promsk argument is nonzero, that
value replaces the protection mask.
tabnam
OpenVMS usage:logical_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)
The name of the new logical name table. The tabnam 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. Table names are contained in either the process
or system directory table (LNM$PROCESS_DIRECTORY or LNM$SYSTEM_
DIRECTORY); therefore, table names must consist of alphanumeric
characters, dollar signs ($), and underscores (_); the maximum
length is 31 characters. Names of logical name tables must be in
uppercase latters. If you specify a lowercase name, the $CRELNT
service automatically changes it to uppercase.
This argument is required for clusterwide logical name tables.
For all other logical name tables, if you do not specify this
argument, a default name in the format LNM$xxxx is used, where
xxxx is a unique hexadecimal number.
You need SYSPRV privilege or write access to LNM$SYSTEM_DIRECTORY
to specify the name of a shareable logical name table.
partab
OpenVMS usage:char_string
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 string for the parent table name. The partab 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.
If the parent table is shareable, then the newly created table
is shareable and is entered into the system directory LNM$SYSTEM_
DIRECTORY. If the parent table is process-private, then the newly
created table is process-private and is entered in the process
directory LNM$PROCESS_DIRECTORY.
You need SYSPRV privilege or write access to the system directory
table to create a named shareable table. This argument is
required.
acmode
OpenVMS usage:access_mode
type: byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Access mode to be associated with the newly created logical
name table. The acmode argument is the 32-bit address (on VAX
systems) or the 32- or 64-bit address (on Alpha systems) of
a byte containing this access mode. The $PSLDEF macro defines
symbolic names for the four access modes.
If you do not specify the acmode argument or specify it as 0, the
access mode of the caller is associated with the newly created
logical name table.
The access mode associated with the logical name table is
determined by maximizing the access mode of the caller with the
access mode specified by the acmode. The less privileged of the
two access modes is used.
However, if the caller has SYSNAM privilege, then the specified
access mode is associated with the logical name table, regardless
of the access mode of the caller.
Access modes associated with logical name tables govern logical
name table processing and provide a protection mechanism that
prevents the deletion of inner access mode logical name tables
by nonprivileged users. You cannot specify an access mode more
privileged than that of the parent table.
A logical name table with supervisor mode access can contain
supervisor mode and user mode logical names and can be a parent
to supervisor mode and user mode logical name tables, but cannot
contain executive or kernel mode logical names or be a parent to
executive or kernel mode logical name tables.
You need SYSNAM privilege to specify executive or kernel mode
access for a logical name table.
Creates a virtual mailbox device named MBAn and assigns an I/O
channel to it. The system provides the unit number n when it
creates the mailbox. If a logical name is specified and a mailbox
with the specified name already exists, the $CREMBX service
assigns a channel to the existing mailbox.
Format
SYS$CREMBX [prmflg] ,chan ,[maxmsg] ,[bufquo] ,[promsk]
,[acmode] ,[lognam] ,[flags] ,[nullarg]
C Prototype
int sys$crembx (char prmflg, unsigned short int *chan,
unsigned int maxmsg, unsigned int bufquo,
unsigned int promsk, unsigned int acmode, void
*lognam,...);
54.1 - Arguments
prmflg
OpenVMS usage:boolean
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the created mailbox is to be
permanent or temporary. The prmflg argument is a longword value.
The value 1 specifies a permanent mailbox; the value 0, which
is the default, specifies a temporary mailbox. Any other values
result in an error.
chan
OpenVMS usage:channel
type: word
access: write only
mechanism: by reference
Channel number assigned by $CREMBX to the mailbox. The chan
argument is the address of a word into which $CREMBX writes the
channel number.
maxmsg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Maximum size (in bytes) of a message that can be sent to the
mailbox. The maxmsg argument is a longword value containing this
size.
The maximum value you can specify for the maxmsg argument is
65535. If you do not specify a value or specify the value as 0,
the operating system provides a default value.
bufquo
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of bytes of system dynamic memory that can be used to
buffer messages sent to the mailbox. The bufquo argument is a
word value containing this number. If you do not specify the
bufquo argument or specify it as 0, the operating system provides
a default value.
The maximum value that you can specify with the bufquo argument
is 60000. For a temporary mailbox, this value must be less than
or equal to the process buffer quota.
promsk
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection mask to be associated with the created mailbox. The
promsk argument is a longword value that is the combined value
of the bits set in the protection mask. Cleared bits grant access
and set bits deny access to each of the four classes of user:
world, group, owner, and system. The following diagram depicts
these protection bits:
|------------|------------|------------|------------|
| World | Group | Owner | System |
|------------|------------|------------|------------|
| L P W R | L P W R | L P W R | L P W R |
|------------|------------|------------|------------|
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
If you do not specify the promsk argument or specify it as 0, the
mailbox template is used.
The logical access bit must be clear for the class of user
requiring access to the mailbox. The access bit must be clear
for all categories of user because logical access is required to
read or write to a mailbox; thus, setting or clearing the read
and write access bits is meaningless unless the logical access
bit is also cleared.
The physical access bit is ignored for all categories of user.
Logical access also allows you to queue read or write attention
ASTs.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel to which the
mailbox is assigned. The acmode argument is a longword containing
the access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode Numeric Value
PSL$C_KERNEL Kernel 0
PSL$C_EXEC Executive 1
PSL$C_SUPER Supervisor 2
PSL$C_USER User 3
The most privileged access mode used is the access mode of
the caller. The specified access mode and the access mode of
the caller are compared. The less privileged (but the higher
numeric valued) of the two access modes becomes the access
mode associated with the assigned channel. I/O operations on
the channel can be performed only from equal or more privileged
access modes.
lognam
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Logical name to be assigned to the mailbox. The lognam argument
is the address of a character string descriptor pointing to the
logical name string.
The equivalence name for the mailbox is MBAn. The equivalence
name is marked with the terminal attribute. Processes can use the
logical name to assign other I/O channels to the mailbox.
For permanent mailboxes, the $CREMBX service enters the specified
logical name, if any, in the LNM$PERMANENT_MAILBOX logical name
table and, for temporary mailboxes, into the LNM$TEMPORARY_
MAILBOX logical name table.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The flags argument is used for specifying options for the
assign operation that occurs in $CREMBX. The flags argument
is a longword bit mask that enables the user to specify that
the channel assigned to the mailbox is a READ ONLY or WRITE
ONLY channel. If the flags argument is not specified, then the
default channel behavior is READ/WRITE. The $CMBDEF macro defines
a symbolic name for each flag bit.
The following table describes each flag:
Flag Description
CMB$M_ When this flag is specified, $CREMBX assigns
READONLY a read-only channel to the mailbox device.
An attempt to issue a QIO WRITE operation on
the mailbox channel results in an illegal I/O
operation error.
CMB$M_ When this flag is specified, $CREMBX assigns
WRITEONLY a write-only channel to the mailbox device.
An attempt to issue a QIO READ operation on
the mailbox channel results in an illegal I/O
operation error.
For more information about the flags argument, refer to the
OpenVMS I/O User's Reference Manual.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Compaq.
Creates, on behalf of the calling process, a subprocess or
detached process on the current node, or a detached process on
another OpenVMS Cluster node.
Format
SYS$CREPRC [pidadr] ,[image] ,[input] ,[output] ,[error]
,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic]
,[mbxunt] ,[stsflg] ,[itmlst] ,[node] ,[home_rad]
C Prototype
int sys$creprc (unsigned int *pidadr, void *image, void
*input, void *output, void *error, struct
_generic_64 *prvadr, unsigned int *quota, void
*prcnam, unsigned int baspri, unsigned int
uic, unsigned short int mbxunt, unsigned int
stsflg,...);
55.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: write only
mechanism: by reference
Process identification (PID) of the newly created process. The
pidadr argument is the address of a longword into which $CREPRC
writes the PID.
image
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the image to be activated in the newly created process.
The image argument is the address of a character string
descriptor pointing to the file specification of the image.
The image name can have a maximum of 63 characters. If the image
name contains a logical name, the logical name is translated in
the created process and must therefore be in a logical name table
that it can access.
To create a process that will run under the control of a command
language interpreter (CLI), specify SYS$SYSTEM:LOGINOUT.EXE as
the image name.
input
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name SYS$INPUT
in the logical name table of the created process. The input
argument is the address of a character string descriptor pointing
to the equivalence name string.
output
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name
SYS$OUTPUT in the logical name table of the created process. The
output argument is the address of a character string descriptor
pointing to the equivalence name string.
error
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name SYS$ERROR
in the logical name table of the created process. The error
argument is the address of a character string descriptor pointing
to the equivalence name string.
Note that the error argument is ignored if the image argument
specifies SYS$SYSTEM:LOGINOUT.EXE; in this case, SYS$ERROR has
the same equivalence name as SYS$OUTPUT.
prvadr
OpenVMS usage:mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference
Privileges to be given to the created process. The prvadr
argument is the address of a quadword bit mask wherein each bit
corresponds to a privilege; setting a bit gives the privilege. If
the prvadr argument is not specified, the current privileges are
used.
Each bit has a symbolic name; the $PRVDEF macro defines these
names. You form the bit mask by specifying the symbolic name of
each desired privilege in a logical OR operation.
Refer to the OpenVMS System Services Reference Manual to view
the table containing the symbolic name and description of each
privilege.
You need the user privilege SETPRV to grant a process any
privileges other than your own. If the caller does not have this
privilege, the mask is minimized with the current privileges of
the creating process; any privileges the creating process does
not have are not granted, but no error status code is returned.
quota
OpenVMS usage:item_quota_list
type: longword (unsigned)
access: read only
mechanism: by reference
Process quotas to be established for the created process. These
quotas limit the created process's use of system resources. The
quota argument is the address of a list of quota descriptors,
where each quota descriptor consists of a 1-byte quota name
followed by a longword that specifies the desired value for
that quota. The list of quota descriptors is terminated by the
symbolic name PQL$_LISTEND.
If you do not specify the quota argument or specify it as 0, the
operating system supplies a default value for each quota.
Refer to the OpenVMS System Services Reference Manual to
view MACRO and C examples, individual quota descriptions, and
instructions for use of the quota list.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name to be assigned to the created process. The prcnam
argument is the address of a character string descriptor pointing
to a process name string.
If a subprocess is being created, the process name is implicitly
qualified by the UIC group number of the creating process. If a
detached process is being created, the process name is qualified
by the group number specified in the uic argument.
baspri
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base priority to be assigned to the created process. The baspri
argument is a longword value.
The OpenVMS VAX range is 0 to 31, where 31 is the highest
priority and 0 is the lowest. Usual priorities are in the range 0
to 15, and real-time priorities are in the range 16 to 31.
The OpenVMS Alpha range is 0 to 63, with real-time priorities in
the range 32 to 63.
If you want a created process to have a higher priority than its
creating process, you must have ALTPRI privilege to raise the
priority level. If the caller does not have this privilege, the
specified base priority is compared with the caller's priority
and the lower of the two values is used.
A process with ALTPRI privilege running on a VAX node can create
a process with a priority greater than 31 on an Alpha node.
If the baspri argument is not specified, the priority defaults
to 2 for VAX MACRO and VAX BLISS-32 and to 0 for all other
languages.
uic
OpenVMS usage:uic
type: longword (unsigned)
access: read only
mechanism: by value
User identification code (UIC) to be assigned to the created
process. The uic argument is a longword value containing the UIC.
If you do not specify the uic argument or specify it as 0 (the
default), $CREPRC creates a process and assigns it the UIC of the
creating process.
If you specify a nonzero value for the uic argument, $CREPRC
creates a detached process. This value is interpreted as a 32-bit
octal number, with two 16-bit fields:
bits 0-15-member number
bits 16-31-group number
You need IMPERSONATE or CMKRNL privilege to create a detached
process with a UIC that is different from the UIC of the creating
process.
If the image argument specifies the SYS$SYSTEM:LOGINOUT.EXE,
the UIC of the created process will be the UIC of the caller of
$CREPRC, and the UIC parameter is ignored.
mbxunt
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Unit number of a mailbox to receive a termination message when
the created process is deleted. The mbxunt argument is a word
containing this number.
If you do not specify the mbxunt argument or specify it as 0 (the
default), the operating system sends no termination message when
it deletes the process.
The Get Device/Volume Information ($GETDVI) service can be used
to obtain the unit number of the mailbox.
If you specify the mbxunt argument, the mailbox is used when
the created process actually terminates. At that time, the
$ASSIGN service is issued for the mailbox in the context of the
terminating process and an accounting message is sent to the
mailbox. If the mailbox no longer exists, cannot be assigned,
or is full, the error is treated as if no mailbox had been
specified.
If you specify this argument when you create a process on another
node, an accounting message will be written to the mailbox when
the process terminates. If the node is removed from the cluster
before the created process terminates, an accounting message
will be simulated. The simulated message will contain the created
process's PID and name and a final status of SS$_NODELEAVE, but
will lack execution statistics.
Note that two processes on different nodes cannot use the
termination mailbox for general interprocess communication.
The accounting message is sent before process rundown is
initiated but after the process name has been set to null. Thus,
a significant interval of time can occur between the sending of
the accounting message and the final deletion of the process.
To receive the accounting message, the caller must issue a read
to the mailbox. When the I/O completes, the second longword of
the I/O status block, if one is specified, contains the process
identification of the deleted process.
The $ACCDEF macro defines symbolic names for offsets of fields
within the accounting message.
Refer to the OpenVMS System Services Reference Manual to view
the table describing the offsets, their symbolic names, and the
contents of each field.
stsflg
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Options selected for the created process. The stsflg argument
is a longword bit vector wherein a bit corresponds to an option.
Only bits 0 to 22 are used; the others are reserved and must be
0.
Each option (bit) has a symbolic name, which the $PRCDEF macro
defines. You construct the stsflg argument by performing a
logical OR operation using the symbolic names of each desired
option.
Refer to the OpenVMS System Services Reference Manual to view the
table describing the symbolic name of each option.
itmlst
OpenVMS usage:reserved
type: longword (unsigned)
access:
mechanism: 0
The itmlst argument is reserved by Compaq.
node
OpenVMS usage:SCS_nodename
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the OpenVMS Cluster node on which the process is to be
created. The node argument is the address of a character string
descriptor pointing to a 1- to 6-character SCS node name string.
If the argument is present but zero or if the string is zero
length, the process is created on the current node.
home_rad
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Sets the home resource affinity domain (RAD) of a process.
The home RAD is determined by the operating system, unless you
explicitly request one. If bit PRC$M_HOME_RAD in the stsflg is
set, home_rad is the RAD on which the process is to start. Note
that you may set this bit to 0 on non-RAD systems.
Note: OpenVMS support for RADs is available only on the new
AlphaServer GS series systems. For more information about using
RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
Adds a range of demand-zero allocation pages (on VAX systems) or
pagelets (on Alpha systems) to a process's virtual address space
for the execution of the current image.
Format
SYS$CRETVA inadr ,[retadr] ,[acmode]
C Prototype
int sys$cretva (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a 2-longword array containing the starting and ending
virtual addresses of the pages to be created. If the starting and
ending virtual addresses are the same, a single page is created.
The addresses are adjusted up or down to fall on CPU-specific
page boundaries. Only the virtual page number portion of the
virtual address is used; the low order byte-within-page bits are
ignored.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference or descriptor
Address of a 2-longword array to receive the starting and ending
virtual addresses of the pages created.
On Alpha systems, the retadr argument should be checked by
programs for actual allocation. Because the Alpha architecture
defines more than one page size, more space might be created than
was specified in the retadr argument.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode and protection for the new pages. The acmode argument
is a longword containing the access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The most privileged access mode used is the access mode of
the caller. The protection of the pages is read/write for the
resultant access mode and those more privileged.
|
57 - $CRETVA 64 (Alpha Only)
|
On Alpha systems, adds a range of demand-zero allocation pages
to a process's virtual address space for the execution of the
current image. The new pages are added at the virtual address
specified by the caller.
This service accepts 64-bit addresses.
Format
SYS$CRETVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode
,flags ,return_va_64 ,return_length_64
C Prototype
int sys$cretva_64 (struct _generic_64 *region_id_64, void
*start_va_64, unsigned __int64 length_64,
unsigned int acmode, unsigned int flags,
void *(*(return_va_64)), unsigned __int64
*return_length_64);
57.1 - Arguments
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 to create the virtual
address range. 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. Also, given a particular virtual address, the
region ID for the region it is in can be obtained by calling the
$GET_REGION_INFO system service specifying the VA$_REGSUM_BY_VA
function.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting address for the created virtual address range. The
specified virtual address must be a CPU-specific page aligned
address.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be created. The length
specified must be a multiple of CPU-specific pages.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $CRETVA_64. The access
mode determines the owner mode of the pages as well as the read
and write protection on the pages. The acmode argument is a
longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The $CRETVA_64 service uses whichever of the following access
modes is least privileged:
o Access mode specified by the acmode argument
o Access mode of the caller
The protection of the pages is read/write for the resultant
access mode and those more privileged.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask controlling the characteristics of the demand-zero
pages created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $VADEF macro and the
VADEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes the flag that is valid for the
$CRETVA_64 service:
Flag Description
VA$M_NO_OVERMAP Pages cannot overmap existing address space.
By default, pages can overmap existing address
space.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVVAFLG is returned if any undefined bits are set.
return_va_64
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the created virtual address
range. The return_va_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service
returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range created. The
return_length_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
Allows a process to associate (map) a section of its address
space with either a specified section of a file (a disk file
section) or specified physical addresses represented by page
frame numbers (a page frame section). This service also allows
the process to create either type of section and to specify that
the section be available only to the creating process (private
section) or to all processes that map to it (global section).
Format
SYS$CRMPSC [inadr] ,[retadr] ,[acmode] ,[flags] ,[gsdnam]
,[ident] ,[relpag] ,[chan] ,[pagcnt] ,[vbn] ,[prot]
,[pfc]
C Prototype
int sys$crmpsc (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, unsigned int
flags, void *gsdnam, unsigned int relpag,
unsigned short int chan, unsigned int pagcnt,
unsigned int vbn, unsigned int prot,unsigned
int pfc);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses into which the section is
to be mapped. The inadr argument is the address of a 2-longword
array containing, in order, the starting and ending process
virtual addresses. Only the virtual page number portion of each
virtual address is used to specify which pages are to be mapped;
the low-order byte-within-page bits are ignored for this purpose.
The interpretation of the inadr argument depends on the setting
of SEC$M_EXPREG in the inadr argument and whether you are using
an Alpha or a VAX system. Refer to the OpenVMS System Services
Reference Manual for a complete description of these differences.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference
Starting and ending process virtual addresses into which the
section was actually mapped by $CRMPSC. The retadr argument
is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
On Alpha systems, the retadr argument returns starting and ending
addresses of the usable range of addresses. This might differ
from the total amount mapped. The retadr argument is required
when the relpag argument is specified. If the section being
mapped does not completely fill the last page used to map the
section, the retadr argument indicates the highest address that
actually maps the section. If the relpag argument is used to
specify an offset into the section, the retadr argument reflects
the offset.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of section to be created or mapped
to, as well as its characteristics. The flags argument is a
longword bit vector wherein each bit corresponds to a flag.
The $SECDEF macro defines a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes each flag and the default value
that it supersedes:
Flag Description
SEC$M_GBL Pages form a global section. The default is
private section.
SEC$M_CRF Pages are copy-on-reference. By default, pages
are shared.
SEC$M_DZRO Pages are demand-zero pages. By default, they
are not zeroed when copied. For page file
sections, the default is demand zero.
SEC$M_EXPREG Pages are mapped into the first available space.
By default, pages are mapped into the range
specified by the inadr argument.
See the inadr argument description for a
complete explanation of how to set the SEC$M_
EXPREG flag.
SEC$M_WRT Pages form a read/write section. By default,
pages form a read-only section. For page file
sections, the default is writeable.
SEC$M_PERM Global section is permanent. By default, global
sections are temporary.
SEC$M_PFNMAP Pages form a page frame section. By default,
pages form a disk file section. Pages mapped
by SEC$M_PFNMAP are not included in or charged
against the process's working set; they are
always valid. Do not lock these pages in the
working set by using $LKWSET; this can result in
a machine check if they are in I/O space.
On Alpha systems, when the SEC$M_PFNMAP flag
is set, the pagcnt and relpag arguments are
interpreted in CPU-specific pages, not as
pagelets.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_PAGFIL Pages form a global page file section. By
default, pages form a disk file section. SEC$M_
PAGFIL also implies SEC$M_WRT and SEC$M_DZRO.
SEC$M_EXECUTE Pages are mapped if the caller has execute
access. This flag takes effect only (1) when
specified from executive or kernel mode, (2)
when the SEC$M_GBL flag is also specified, and
(3) when SEC$M_WRT is not specified. By default
$CRMPSC performs a read access check against the
section.
SEC$M_NO_ Pages cannot overmap existing address space.
OVERMAP Note that, by default, pages can overmap
existing address space.
gsdnam
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the global section. The gsdnam argument is the address of
a character string descriptor pointing to this name string.
For group global sections, the operating system interprets the
UIC group as part of the global section name; thus, the names of
global sections are unique to UIC groups.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
ident
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument
is the address of a quadword structure containing three fields.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
The first longword specifies, in its low-order two bits, the
matching criteria. The valid values, symbolic names by which they
can be specified, and their meanings are as follows:
Value/Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor identifications
match.
2 SEC$K_MATLEQ Match if the major identifications are equal and
the minor identification of the mapper is less
than or equal to the minor identification of the
global section.
When a section is mapped at creation time, the match control
field is ignored.
If you do not specify the ident argument or specify it as 0 (the
default), the version number and match control fields default to
0.
relpag
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the global section of the first page
in the section to be mapped. The relpag argument is a longword
containing this page number.
On Alpha systems, the relpag argument is interpreted as an index
into the section file, measured in pagelets for a file-backed
section or in CPU-specific pages for a PFN-mapped section.
On Alpha and VAX systems, you use this argument only for global
sections. If you do not specify the relpag argument or specify it
as 0 (the default), the global section is mapped beginning with
the first virtual block in the file.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The
chan argument is a word containing this number.
The file must have been accessed with the OpenVMS RMS macro
$OPEN; the file options parameter (FOP) in the FAB must indicate
a user file open (UFO keyword). The access mode at which the
channel was opened must be equal to or less privileged than the
access mode of the caller.
pagcnt
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pages (on VAX systems) or pagelets (on Alpha systems)
in the section. The pagcnt argument is a longword containing this
number.
On Alpha systems, the smallest allocation is an Alpha page, which
is 8192 bytes. When requesting pagelets, the size requested is
a multiple of 512 bytes, but the actual allocation is rounded to
8192. For example, when requesting 17 pagelets, the allocation is
for two Alpha pages, 16384 bytes.
On Alpha systems, if the SEC$M_PFNMAP flag bit is set, the pagcnt
argument is interpreted as CPU-specific pages, not as pagelets.
On Alpha and VAX systems, the specified page count is compared
with the number of blocks in the section file; if they are
different, the lower value is used. If you do not specify the
page count or specify it as 0 (the default), the size of the
section file is used. However, for physical page frame sections,
this argument must not be 0.
vbn
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Virtual block number in the file that marks the beginning of the
section. The vbn argument is a longword containing this number.
If you do not specify the vbn argument or specify it as 0 (the
default), the section is created beginning with the first virtual
block in the file.
If you specified page frame number mapping (by setting the SEC$M_
PFNMAP flag), the vbn argument specifies the CPU-specific page
frame number where the section begins in memory.
Refer to the OpenVMS System Services Reference Manual to view
which arguments are required and which are optional for three
different uses of the $CRMPSC service.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page file and PFN
sections. For file-backed sections, the protection is taken from
the backing file and the prot argument is ignored.
The mask contains four 4-bit fields. Bits are read from right to
left in each field.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user.
Only read, write, and execute access are meaningful for section
protection. Delete access bits are ignored. Read access also
grants execute access for those situations where execute access
applies.
Protection is taken from the system or group global section
template for page file or PFN global sections if the prot
argument is not specified.
pfc
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster size indicating how many pages (on VAX
systems) or pagelets (on Alpha systems) are to be brought into
memory when a page fault occurs for a single page.
On Alpha systems, this argument is not used for page file
sections or physical page frame sections. The pfc argument is
rounded up to CPU-specific pages. That is, at least 16 pagelets
(on an Alpha system with an 8KB page size) will be mapped for
each physical page. The system cannot map less than one physical
page.
On VAX systems, this argument is not used for page file sections
or physical page frame sections.
|
59 - $CRMPSC FILE 64 (Alpha Only)
|
On Alpha systems, allows a process to map a section of its
address space to a specified portion of a file. This service
creates and maps a private disk file section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_FILE_64 region_id_64 ,file_offset_64 ,length_64
,chan ,acmode ,flags ,return_va_64
,return_length_64 [,fault_cluster
[,start_va_64]]
C Prototype
int sys$crmpsc_file_64 (struct _generic_64 *region_id_64,
unsigned __int64 file_offset_64,
unsigned __int64 length_64, unsigned
short int chan, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
59.1 - Arguments
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 to map the private disk
file section. 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.
file_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Byte offset into the file that marks the beginning of the
section. The file_offset_64 argument is a quadword containing
this number. If you specify the file_offset_64 argument as 0, the
section is created beginning with the first byte in the file.
The file_offset_64 argument must be a multiple of virtual disk
blocks.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: value
Length, in bytes, of the private disk file section to be created
and mapped to. The length specified must be 0 or a multiple of
virtual disk blocks. If the length specified is 0 or extends
beyond end-of-file (EOF), the disk file is mapped up to and
including the virtual block number that contains EOF.
chan
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The
chan argument is a longword containing this number. The access
mode at which the channel was opened must be equal to or less
privileged than the access mode of the caller.
Use the OpenVMS Record Management Services (RMS) macro $OPEN
to access a file; the file options parameter in the file access
block must indicate a user file open (UFO) keyword.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the private section
to be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes each flag that is valid for the
$CRMPSC_FILE_64 service:
Flag Description
SEC$M_CRF Pages are copy-on-reference.
SEC$M_DZRO Pages are demand-zero pages. By default, they are
not zeroed when copied.
Note that SEC$M_DZRO and SEC$M_CRF cannot both be
set and that SEC$M_DZRO set and SEC$M_WRT clear is
an invalid combination.
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
SEC$M_NO_ Pages cannot overmap existing address space. By
OVERMAP default, pages can overmap existing address space.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the private disk
file section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the usable virtual
address range mapped in bytes. This length might differ from
the total amount mapped. If the section being mapped does not
completely fill the last page used to map the section, the
return_va_64 and return_length_64 arguments indicate the highest
address that actually maps the section.
fault_cluster
OpenVMS usage:byte count
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster in byte units indicating how many pages
are to be brought into memory when a page fault occurs for a
single page. The fault cluster specified will be rounded up to a
multiple of CPU-specific pages.
If this argument is specified as 0, the process default page
fault cluster will be used. If this argument is specified as more
than the maximum allowed for the system, no condition value will
be returned. The systemwide maximum will be used.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the private disk file
section. The specified virtual address must be a CPU-specific
page aligned address. If the flag SEC$M_EXPREG is specified, the
start_va_64 argument must not be specified or must be specified
as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
nonzero, the condition value SS$_IVSECFLG is returned.
|
60 - $CRMPSC GDZRO 64 (Alpha Only)
|
On Alpha systems, allows a process to create a memory-resident
global demand-zero section and to map a section of its address
space to the global section. Shared page table sections can also
be created.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_GDZRO_64 gs_name_64 ,ident_64 ,prot ,length_64
,region_id_64 ,section_offset_64 ,acmode
,flags ,return_va_64 ,return_length_64
[[[[,start_va_64] ,map_length_64]
,reserved_length_64] ,rad_mask]
C Prototype
int sys$crmpsc_gdzro_64 (void *gs_nam_64, struct _secid
*ident_64, unsigned int prot, unsigned
__int64 length_64, struct _generic_64
*region_id_64, unsigned __int64
section_offset_64, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
60.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. The valid values, symbolic names by which they can
be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
When a section is mapped at creation time, the match control
field is ignored. If you specify the ident_64 argument as 0, the
version number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global demand-zero section. The
mask contains four 4-bit fields. Bits are read from right to left
in each field.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful
for section protection. Delete access bits are ignored. Read
access also grants execute access for those situations where
execute access applies. If zero is specified, read access and
write access are granted to all users.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global demand-zero section to be
created. The length_64 must be specified as a multiple of the
CPU-specific page size. A length of 0 cannot be specified.
NOTE
Creating a memory-resident global section with shared page
table does not imply that the global section must have an
even multiple of CPU-specific page table pages. The global
section might not fully use the last page table page.
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 to map the global page
file section.
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.
section_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Offset into the global section to start mapping into the
process's virtual address space. The offset specified must be
a multiple of a CPU-specific page size.
If a shared page table region is specified by the region_id_
64 argument, section_offset_64 must be an even multiple of the
number of bytes that can be mapped by a CPU-specific page table
page.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. This access mode is also the read access mode
and the write access mode. The acmode argument is a longword
containing the access mode.
If the memory-resident global section is created with shared
page tables, this is the access mode that is stored in the owner,
read, and write fields of the corresponding shared page table
entries (PTEs).
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of the global section to be created
as well as its characteristics. The flags argument is a longword
bit vector in which each bit corresponds to a flag. The $SECDEF
macro and the SECDEF.H file define a symbolic name for each
flag. You construct the flags argument by performing a logical
OR operation on the symbol names for all desired flags.
The following table describes each flag that is valid for the
$CRMPSC_GDZRO_64 service:
Flag Description
SEC$M_DZRO Pages are demand-zero pages. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
If the /ALLOCATE qualifier was specified when the
global section was registered in the Reserved
Memory Registry, virtually aligned addresses
after the first available space are chosen for
the mapping.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_NO_ Pages cannot overmap existing address space.
OVERMAP
SEC$M_PERM Global section is permanent.
SEC$M_RAD_ When set, the argument rad_mask is used as a mask
HINT of RADs from which to allocate memory. See the rad_
mask argument description for more information.
SEC$M_READ_ Create shared table pages for the section that
ONLY_SHPT allow read access only.
SEC$M_SHMGS Create a shared-memory global section.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_MRES Pages form a memory-resident section. By default,
this page is always present in this service and
cannot be disabled.
SEC$M_WRT Pages form a read/write section. By default, this
flag is always present in this service and cannot
be disabled.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
invalid combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the global demand-
zero section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
If a shared page table region is specified by the region_id_64
argument and the SEC$M_EXPREG flag is set, the returned virtual
address is aligned to a CPU-specific page table page boundary.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range mapped in bytes.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the memory-resident global
section. The specified virtual address must be a CPU-specific
page aligned address. If the flag SEC$M_EXPREG is specified, the
start_va_64 argument must not be specified or must be specified
as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
nonzero, the condition value SS$_IVSECFLG is returned.
If SEC$M_EXPREG is clear, start_va_64 is nonzero, and a shared
page table region is specified, the specified starting address
must be aligned to a natural page table page boundary; otherwise,
the condition value SS$_VA_NOTPAGALGN is returned.
If the /ALLOCATE qualifier was specified when the memory-resident
global section was registered in the Reserved Memory Registry
and start_va_64 is aligned to a multiple of CPU-specific pages
appropriate for taking advantage of granularity hints (8, 64, or
512 pages), then granularity hints are used to map to the global
section.
map_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the memory-resident global section to be mapped. The
length specified must be a multiple of CPU-specific pages. If
this argument is not specified or is specified as zero, the
global file section is mapped up to and including the last page
in that section.
If a shared page table region is specified by the region_id_64
argument, map_length_64 must be an even multiple of the number
of bytes that can be mapped by a CPU-specific page table page or
must include the last page within the global section.
reserved_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: 32- or 64-bit reference
Length, in bytes, of the global section as currently registered
in the Reserved Memory Registry. The reserved_length_64 argument
is the 32- or 64-bit virtual address of a naturally aligned
quadword into which the service returns the reserved length.
If reserved_length_64 is not specified or is specified as 0, no
reserved length is returned to the caller.
If the memory-resident global section is not registered,
reserved_length_64 is written with the value 0.
rad_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by value
Use the rad_mask argument to specify from which RADs to allocate
memory. Currently only one bit may be set. The specified RAD
must contain memory. This argument is only a hint. Memory may be
obtained from other RADs if no free memory is available at the
time of allocation.
The rad_mask argument is considered only if the SEC$M_RAD_HINT
flag is specified. Otherwise, this argument is ignored.
On a system that does not support resource affinity domains
(RADs), specifying 1 for the rad_mask argument is allowed.
Note: OpenVMS support for RADs is available only on the new
AlphaServer GS series systems. For more information about using
RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
|
61 - $CRMPSC GFILE 64 (Alpha Only)
|
On Alpha systems, allows a process to create a global disk file
section and to map a section of its address space to the global
section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_GFILE_64 gs_name_64 ,ident_64 ,file_offset_64
,length_64 ,chan ,region_id_64
,section_offset_64 ,acmode ,flags
,return_va_64 ,return_length_64
[,fault_cluster
[,start_va_64 [,map_length_64]]]
C Prototype
int sys$crmpsc_gfile_64 (void *gs_nam_64, struct _secid
*ident_64, unsigned __int64
file_offset_64, unsigned __int64
length_64, unsigned short
int chan, struct _generic_64
*region_id_64, unsigned __int64
section_offset_64, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
61.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. The valid values, symbolic names by which they can
be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
When a section is mapped at creation time, the match control
field is ignored. If you specify the ident_64 argument as 0, the
version number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
file_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Byte offset into the file that marks the beginning of the
section. The file_offset_64 argument is a quadword containing
this number. If you specify the file_offset_64 argument as 0, the
section is created beginning with the first byte in the file.
The file offset specified must be a multiple of virtual disk
blocks.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global disk file section to be created.
The length specified must be 0 or a multiple of virtual disk
blocks. If the length specified is 0 or extends beyond the end-
of-file (EOF), the global disk file section is created up to and
including the virtual block number that contains EOF.
chan
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The
chan argument is a longword containing this number. The access
mode at which the channel was opened must be equal to or less
privileged than the access mode of the caller.
You can use the OpenVMS Record Management Services (RMS) macro
$OPEN to access a file; the file options parameter in the file
access block must indicate a user file open (UFO) keyword.
region_id_64
OpenVMS usage:region identifier
type: quadword (unsigned)
access: read only
mechanism: by 64 bit reference
The region ID associated with the region in which to map the
global disk file section. 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.
section_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Offset into the global section to start mapping into the
process's virtual address space. The offset specified must be
a multiple of virtual disk blocks.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the global section
to be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes each flag that is valid for the
$CRMPSC_GFILE_64 service:
Flag Description
SEC$M_CRF Pages are copy-on-reference.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
SEC$M_DZRO Pages are demand-zero pages. By default, they are
not zeroed when copied.
Note that SEC$M_DZRO and SEC$M_CRF cannot both be
set and that SEC$M_DZRO set and SEC$M_WRT clear is
an invalid combination.
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
SEC$M_NO_ Pages cannot overmap existing address space. By
OVERMAP default, pages can overmap existing address space.
SEC$M_PERM Global section is permanent. By default, global
sections are temporary.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the global disk
file section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
Upon successful completion of this service, if the
section_offset_64 argument was specified, the virtual address
returned in return_va_64 reflects the offset into the global
section mapped such that the virtual address returned cannot
be aligned on a CPU-specific page boundary. The virtual address
returned will always be on an even virtual disk block boundary.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range mapped in bytes.
Upon successful completion of this service, the value in the
return_length_64 argument indicates the amount of created address
space backed by the section file.
If the number of disk blocks mapped does not represent an exact
multiple of CPU-specific pages, the last page in the mapped
address space will not be completely mapped by the section file.
In this case, modifying memory beyond the amount indicated by
return_length_64 can result in the loss of this data.
Unlike the return_length_64 argument for the $CREATE_GFILE
service, upon successful completion of this service, the
return_length_64 argument does not represent the total length
of the global section created if the section_offset_64 argument
was specified as nonzero. The value in the section_offset_64
argument plus the value in the return_length_64 argument is the
total length of the global disk file section created.
fault_cluster
OpenVMS usage:byte count
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster in byte units indicating how many pages
are to be brought into memory when a page fault occurs for a
single page. The fault cluster specified will be rounded up to a
multiple of CPU-specific pages.
If this argument is specified as 0, the system default page fault
cluster will be used. If this argument is specified as more than
the maximum allowed for the system, no error will be returned.
The systemwide maximum will be used.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the global disk file section.
The specified virtual address must be a CPU-specific page aligned
address. If the flag SEC$M_EXPREG is specified, this argument
will not be used. If SEC$M_EXPREG is clear and the start_va_64
argument is not specified or is specified as 0, the condition
value SS$_IVSECFLG will be returned.
Always refer to the return_va_64 and return_length_64 arguments
to determine the usable range of virtual addresses mapped.
map_length_64
OpenVMS usage:byte count
type: quadword unsigned
access: read only
mechanism: by value
Length of the global disk file section to be mapped. The length
specified must be a multiple of virtual disk blocks. If this
argument is not specified as zero, the global disk section is
mapped up to and including the last disk block in the section.
|
62 - $CRMPSC GPFILE 64 (Alpha Only)
|
On Alpha systems, allows a process to create a global page file
section and to map a section of its address space to the global
section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_GPFILE_64 gs_name_64 ,ident_64 ,prot ,length_64
,region_id_64 ,section_offset_64 ,acmode
,flags ,return_va_64 ,return_length_64
[,start_va_64 [,map_length_64]]
C Prototype
int sys$crmpsc_gpfile_64 (void *gs_nam_64, struct _secid
*ident_64, unsigned int prot,
unsigned __int64 length_64, struct
_generic_64 *region_id_64, unsigned
__int64 section_offset_64, unsigned
int acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
62.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. The valid values, symbolic names by which they can
be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
When a section is mapped at creation time, the match control
field is ignored. If you specify the ident_64 argument as 0, the
version number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page file section. The
mask contains four 4-bit fields. Bits are read from right to left
in each field.
Refer to the OpenVMS System Services Reference Manual to view the
mask diagram.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful
for section protection. Delete access bits are ignored. Read
access also grants execute access for those situations where
execute access applies. If zero is specified, read access and
write access are granted to all users.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the global page file section to be created.
The length specified must be a multiple of CPU-specific pages. A
length of 0 cannot be specified.
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 to map the global page
file section.
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.
section_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Offset into the global section to start mapping into the
process's virtual address space. The offset specified must be
a multiple of virtual disk blocks.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the global section
to be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes each flag that is valid for the
$CRMPSC_GPFILE_64 service:
Flag Description
SEC$M_DZRO Pages are demand-zero pages. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_EXPREG Pages are mapped into the first available space
at the current end of the specified region.
SEC$M_EXPREG cannot be specified with the
SEC$M_NO_OVERMAP flag.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_NO_ Pages cannot overmap existing address space. By
OVERMAP default, pages can overmap existing address space.
SEC$M_NO_OVERMAP cannot be specified with the
SEC$M_EXPREG flag.
SEC$M_PAGFIL Pages form a global page file section. By default,
this flag is always present in this service and
cannot be disabled.
SEC$M_PERM Global section is permanent. By default, global
sections are temporary.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_WRT Pages form a read/write section. By default, this
flag is always present in this service and cannot
be disabled.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
invalid combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the global page
file section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range mapped in bytes.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the global page file section.
The specified virtual address must be a CPU-specific page aligned
address. If the flag SEC$M_EXPREG is specified, the start_va_64
argument must not be specified or must be specified as 0. If
SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
condition value SS$_IVSECFLG is returned.
Always refer to the return_va_64 and return_length_64 arguments
to determine the range of virtual addresses mapped.
map_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the global page file section to be mapped. The length
specified must be a multiple of CPU-specific pages. If this
argument is not specified or is specified as zero, the global
file section is mapped up to and including the last page in that
section.
|
63 - $CRMPSC GPFN 64 (Alpha Only)
|
On Alpha systems, allows a process to create a permanent global
page frame section and to map a section of its address space to
the global page frame section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_GPFN_64 gs_name_64 ,ident_64 ,prot ,start_pfn
,page_count ,region_id_64 ,relative_page
,acmode ,flags ,return_va_64
,return_length_64 [,start_va_64
[,map_page_count]]
C Prototype
int sys$crmpsc_gpfn_64 (void *gs_nam_64, struct _secid
*ident_64, unsigned int prot, unsigned
int start_pfn, unsigned int page_count,
struct _generic_64 *region_id_64,
unsigned int relative_page, unsigned
int acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
63.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order 2 bits. The valid values, symbolic names by which they can
be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
When a section is mapped at creation time, the match control
field is ignored. If you specify the ident_64 argument as 0, the
version number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page file section.
The mask contains four 4-bit fields. Bits are read from right to
left in each field.
Refer to the OpenVMS System Services Reference Manual to view the
mask diagram.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user. Only read, write, and execute access are meaningful
for section protection. Delete access bits are ignored. Read
access also grants execute access for those situations where
execute access applies. If zero is specified, read access and
write access are granted to all users.
start_pfn
OpenVMS usage:page frame number
type: longword (unsigned)
access: read only
mechanism: by value
The CPU-specific page frame number where the section begins.
page_count
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Length of the page frame section in CPU-specific pages.
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 to map the global page
frame section. 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.
relative_page
OpenVMS usage:CPU-specific page number
type: longword (unsigned)
access: read only
mechanism: by value
Relative CPU-specific page number within the global section to
start mapping.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the global section
to be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes each flag that is valid for
$CRMPSC_GPFN_64:
Flag Description
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PERM Global section is permanent. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_PFNMAP Pages form a page frame section. By default, this
flag is always present in this service and cannot
be disabled.
SEC$M_NO_ Pages cannot overmap existing address space. By
OVERMAP default, pages can overmap existing address space.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the global page
frame section was mapped. The return_va_64 argument is the 32-
or 64-bit address of a naturally aligned quadword into which the
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range mapped in bytes.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the global page frame
section. The specified virtual address must be a CPU-specific
page-aligned address. If the flag SEC$M_EXPREG is specified, the
start_va_64 argument must not be specified or must be specified
as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
nonzero, the condition value SS$_IVSECFLG is returned.
Always refer to the return_va_64 and return_length_64 arguments
to determine the range of virtual addresses mapped.
map_page_count
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Length of the global page frame section to be mapped in CPU-
specific pages.
|
64 - $CRMPSC PFN 64 (Alpha Only)
|
On Alpha systems, allows a process to map a section of its
address space to a specified physical address range represented
by page frame numbers. This service creates and maps a private
page frame section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_PFN_64 region_id_64 ,start_pfn ,page_count ,acmode
,flags ,return_va_64 ,return_length_64
[,start_va_64]
C Prototype
int sys$crmpsc_pfn_64 (struct _generic_64 *region_id_64,
unsigned int start_pfn, unsigned
int page_count, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
64.1 - Arguments
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 to map the private page
frame section. 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_pfn
OpenVMS usage:page frame number
type: longword (unsigned)
access: read only
mechanism: by value
The CPU-specific page frame number where the section begins in
memory.
page_count
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Length of the page frame section in CPU-specific pages.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the characteristics of the private section
to be created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
The following table describes each flag that is valid for the
$CRMPSC_PFN_64 service:
Flag Description
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
SEC$M_NO_ Pages cannot overmap existing address space. By
OVERMAP default, pages can overmap existing address space.
SEC$M_PFNMAP Pages form a page frame section. By default, this
flag is always present in this service and cannot
be disabled.
SEC$M_WRT Pages form a read/write section. By default, pages
form a read-only section.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
invalid combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the private page
frame section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range mapped. The
return_length_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the private page frame
section. The specified virtual address must be a CPU-specific
page aligned address. If the flag SEC$M_EXPREG is specified, the
start_va_64 argument must not be specified or must be specified
as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
nonzero, the condition value SS$_IVESCFLG is returned.
|
65 - $CVT FILENAME (Alpha Only)
|
Converts a string from RMS format to file-system (ACP-QIO) format
or from file-system (ACP-QIO) format to RMS format.
Format
SYS$CVT_FILENAME cvttyp ,srcstr ,inflags ,outbuf ,outlen
,outflags
C Prototype:
int sys$cvt_filename (unsigned int cvttyp, void *srcstr,
unsigned int inflags, void *outbuf,
unsigned short int *outlen, unsigned int
*outflags);
65.1 - Arguments
cvttyp
OpenVMS usage:unsigned_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword value that indicates whether the conversion is from RMS
format to ACP-QIO format or vice versa.
There are two legal values for this parameter, represented by the
symbols CVTFNM$C_ACPQIO_TO_RMS and CVTFNM$C_RMS_TO_ACPQIO, that
are defined by the $CVTFNMDEF macro.
srcstr
OpenVMS usage:string of bytes or words
type: string of bytes or words
access: read only
mechanism: by 32-bit descriptor-fixed-length string descriptor
String to be converted by the service.
If the conversion is from RMS format to ACP-QIO format, srcstr
is an ISO-Latin-1 or VTF-7-encoded character string. If the
conversion is from ACP-QIO format to RMS format, srcstr is a
string of byte-width or word-width characters.
The descriptor length field indicates the length of the input
string in bytes, whether the characters are byte-width or word-
width.
The srcstr argument is the 32-bit address of a descriptor that
points to this string.
inflags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword flag mask indicating the characteristics of the input
string.
For conversion from RMS format to ACP-QIO format, only the
CVTFNM$V_NO_DELIMITERS flag is valid.
For conversion from ACP-QIO format to RMS format, legal flags are
CVTFNM$V_WORD_CHARS and CVTFNM$V_NO_DELIMITERS (defined by the
$CVTFNMDEF macro).
Flag Description
CVTFNM$V_WORD_ Input source string contains word-width
CHARS UCS-2 characters (ACPQIO_TO_RMS conversion
only).
CVTFNM$V_NO_ Input source string should be treated as an
DELIMITERS arbitrary string (such as a subdirectory
name) rather than as a file name that
contains (or should contain) dots or
semicolons as type and version delimiters.
CVTFNM$V_FORCE_ Causes this system service to convert each
UPCASE character to uppercase. (ACPQIO_TO_RMS
conversion only).
outbuf
OpenVMS usage:string of bytes or words
type: string of bytes or words
access: write only
mechanism: by 32-bit descriptor-fixed-length string descriptor
The buffer into which the converted string is to be written.
If the conversion is from RMS format to ACP-QIO format, the
string may consist of byte-width ISO Latin-1 characters or
word-width UCS-2 characters, depending on the characters in the
source string. (If any character in the source string must be
converted to UCS-2, then all characters in the output buffer will
be converted to UCS-2.)
If the conversion is from ACP-QIO format to RMS format, then the
output string will consist of ISO Latin-1 and VTF-7 characters
in RMS canonical form. (Refer to the Guide to OpenVMS File
Applications.)
For ACPQIO_TO_RMS conversion, if the output string contains word-
width characters, the CVTFNM$V_WORD_CHARS flag in the outflags
flag mask will be set.
The outbuf argument is the 32-bit address of a descriptor
pointing to a buffer writable in the access mode of the caller.
outlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32-bit reference
The outlen argument is the 32-bit address of a (16-bit) word
writable in the access mode of the caller.
outflags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by 32-bit reference
Longword flag mask in which the service sets or clears flags to
indicate characteristics of the output string.
For an RMS_TO_ACPQIO conversion, SYS$CVT_FILENAME sets the bit
corresponding to CVTFNM$V_WORD_CHARS (defined by the $CVTFNMDEF
macro) if the characters of the converted string are one-
word wide rather than one-byte wide. If the characters of the
converted string are one-byte wide, the service clears the
CVTFNM$V_WORD_CHARS bit. All other bits are cleared by an RMS_
TO_ACPQIO conversion.
The outflags argument is the 32-bit address of a 32-bit flag mask
writable in the access mode of the caller.
Releases the calling process's association with a common event
flag cluster.
Format
SYS$DACEFC efn
C Prototype
int sys$dacefc (unsigned int efn);
66.1 - Argument
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag in the common cluster to be
disassociated. The efn argument is a longword containing this
number; however, $DACEFC uses only the low-order byte. The number
must be in the range of 64 through 95 for cluster 2, and 96
through 127 for cluster 3.
Deallocates a previously allocated device.
Format
SYS$DALLOC [devnam] ,[acmode]
C Prototype
int sys$dalloc (void *devnam, unsigned int acmode);
67.1 - Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the device to be deallocated. The devnam argument is the
address of a character string descriptor pointing to the device
name string. The string might be either a physical device name or
a logical name. If it is a logical name, it must translate to a
physical device name.
If you do not specify a device name, all devices allocated by the
process from access modes equal to or less privileged than that
specified are deallocated.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode from which the deallocation is to be performed. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
Deassigns (releases) an I/O channel previously acquired using the
Assign I/O Channel ($ASSIGN) service.
Format
SYS$DASSGN chan
C Prototype
int sys$dassgn (unsigned short int chan);
68.1 - Argument
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is
a word containing this number.
Queues an asynchronous system trap (AST) for the calling access
mode or for a less privileged access mode.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$DCLAST astadr ,[astprm] ,[acmode]
C Prototype
int sys$dclast (void (*astadr)(__unknown_params), unsigned
__int64 astprm, unsigned int acmode);
69.1 - Arguments
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. On Alpha systems, the astadr
argument is the 32- or 64-bit address of this routine. On VAX
systems, the astadr argument is the 32-bit address of this
routine.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
AST parameter to be passed to the AST routine specified by the
astadr argument. On Alpha sytems, the astprm argument is a
quadword value containing this parameter. On VAX systems, the
astprm argument is a longword value containing this parameter.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the AST is to be declared. The most
privileged access mode used is the access mode of the caller. The
resultant mode is the access mode for which the AST is declared.
On Alpha systems, specifies the address of a routine to receive
control when a Change Mode to User or Change Mode to Supervisor
instruction trap occurs.
On VAX systems, specifies the address of a routine to receive
control when a Change Mode to User or Change Mode to Supervisor
instruction trap occurs, or when a compatibility mode fault
occurs.
Format
SYS$DCLCMH addres ,[prvhnd] ,[type]
C Prototype
int sys$dclcmh (int (*addres)(__unknown_params), void
*(*(prvhnd)), char type);
70.1 - Arguments
addres
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Routine to receive control when a change mode trap or a
compatibility mode fault occurs. The addres argument is the
exception handling code in the address space of the calling
process.
If you specify the addres argument as 0, $DCLCMH clears the
previously declared handler.
prvhnd
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a previously declared handler. The prvhnd argument
is the address of a longword containing the address of the
previously declared handler.
type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Handler type indicator. The type argument is a longword value.
The value 0 (the default) indicates that a change mode handler
is to be declared for the access mode at which the request is
issued; the value 1 specifies that a compatibility mode handler
is to be declared.
Declares an exit handling routine that receives control when an
image exits.
Format
SYS$DCLEXH desblk
C Prototype
int sys$dclexh (void *desblk);
71.1 - Argument
desblk
OpenVMS usage:exit_handler_block
type: longword (unsigned)
access: write
mechanism: by reference
Exit handler control block. The desblk argument is the address of
this control block.
Refer to the OpenVMS System Services Reference Manual to view the
control block diagram.
|
72 - $DELETE BUFOBJ (Alpha Only)
|
On Alpha systems, deletes a buffer object previously created by
the $CREATE_BUFOBJ_64 system service.
This service accepts 64-bit addresses.
Format
SYS$DELETE_BUFOBJ buffer_handle_64
C Prototype
int sys$delete_bufobj (struct _generic_64 *buffer_handle_64);
72.1 - Arguments
buffer_handle_64
OpenVMS usage:handle
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
The buffer object to be deleted. The buffer_handle_64 argument
is the 32- or 64-bit address of a 2-longword array previously
returned by a $CREATE_BUFOBJ_64 call.
|
73 - $DELETE GALAXY LOCK (Alpha Only)
|
Invalidates an OpenVMS Galaxy lock and deletes it.
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 OpenVMS Alpha Partitioning and Galaxy
Guide.
Format
SYS$DELETE_GALAXY_LOCK handle
C Prototype
int sys$delete_galaxy_lock (unsigned __int64 lock_handle);
Arguments
handle
OpenVMS usage:galaxy lock handle
type: quadword (unsigned)
access: read
mechanism: input by value
The 64-bit lock handle that identifies the lock to be deleted.
This value is returned by SYS$CREATE_GALAXY_LOCK.
|
74 - $DELETE GALAXY LOCK TABLE (Alpha Only)
|
Deletes an OpenVMS Galaxy locktable.
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 OpenVMS Alpha
Partitioning and Galaxy Guide.
Format
SYS$DELETE_GALAXY_LOCK_TABLE handle
C Prototype
int sys$delete_galaxy_lock_table (unsigned int
*lcktbl_handle);
74.1 - Arguments
lcktbl_handle
OpenVMS usage:lock table handle
type: longword (unsigned)
access: read
mechanism: input by value
The 32-bit lock table handle that identifies the table to be
deleted. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.
Searches for and deletes all records in the intrusion database
matching the caller's specifications.
Format
SYS$DELETE_INTRUSION user_criteria ,[flags]
C Prototype
int sys$delete_intrusion (void *user_criteria, unsigned int
flags);
75.1 - Arguments
user_criteria
OpenVMS usage:char_string or item_list_3
type: character-coded text string or longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length string descriptor or by
reference
If the CIA$M_ITEMLIST flag is FALSE:
The user_criteria argument is the description of intruder or
suspect. This argument is the address of a character-string
descriptor pointing to a buffer containing the user criteria to
match an intrusion record's user specification in the intrusion
database.
The user_criteria argument is a character string of 1 to 1058
bytes containing characters to match the user specification on
records in the intrusion database.
A user specification is any combination of the suspect's or
intruder's source node name, source user name, source DECnet-
Plus address, local failed user name, or local terminal. The user
specification for an intrusion record is based on the input to
the $SCAN_INTRUSION service and the settings of the LGI system
parameter. For more information, refer to the OpenVMS Guide to
System Security.
Wildcards are allowed for the user_criteria argument. For
example, if you specify an asterisk (*) for the user_criteria
argument, the service deletes all records in the intrusion
database.
If the CIA$M_ITEMLIST flag is TRUE:
The user_criteria argument is now the address of a 32-bit item
list. If the item list is used, one item, the CIA$_USER_CRITERIAL
item, must be present in the item list. The ITM$L_BUFADR should
point to a buffer containing the specified user criteria.
The following table lists the valid item descriptions for the
user_criteria argument:
Item Description
CIA$_SCSNODE_LIST Address of a list of 8-character null-padded
SCS nodenames for which intrusions are to be
deleted.
CIA$_USER_ Address of a buffer, 1-1058 bytes long,
CRITERIAL containing the intruder or suspect.
If the CIA$_SCSNODE_LIST item is present, it is the address
of a list of 8-character null-padded SCS nodenames for which
intrusions are to be deleted. If this item is absent, the service
deletes the specified intrusion records for all nodes in the
cluster. Multiple CIA$_SCSNODE_LIST items are permitted.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Functional specification for the service. The flags argument is a
longword bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $CIADEF macro defines
the following valid names for the $DELETE_INTRUSION service:
Symbolic Name Description
CIA$M_IGNORE_ The service should not wait for the return
RETURN status from the security server. No return
status from the server's function will be
returned to the caller.
CIA$M_ITEMLIST If FALSE, the user_criteria argument is a
character string. If TRUE, this argument is a
32-bit item list.
Deletes an existing proxy or removes the default user or a local
user from an existing proxy in the proxy database.
Format
SYS$DELETE_PROXY rem_node ,rem_user ,[local_user] ,[flags]
D Prototype
int sys$delete_proxy (void *rem_node, void *rem_user, void
*local_user, unsigned int flags);
76.1 - Arguments
rem_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote node name of the proxy to be deleted from or modified
in the proxy database. The rem_node argument is the address of
a character-string descriptor pointing to the remote node name
string.
A remote node name consists of 1 to 1024 characters. No specific
characters, format, or case are required for a remote node name
string. All node names are converted to their DECnet for OpenVMS
full name unless the PRX$M_BYPASS_EXPAND flag is set with the
flags argument.
Asterisk (*) and percent sign (%) wildcards are allowed for the
remote node specification. If you specify wildcards for the rem_
node argument, the security server searches for an exact match
to the specified remote node first. If it does not find an exact
match, the server performs the requested operations on all of the
matching proxies in the proxy database.
rem_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote user name of the proxy to be deleted from or modified in
the proxy database. The rem_user argument is the address of a
character-string descriptor pointing to the user name string.
A remote user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($), underscores (_), and brackets
([ ]). Any lowercase characters specified are automatically
converted to uppercase.
The rem_user argument can be specified in user identification
code (UIC) format ([group, member]). Brackets are allowed only
if the remote user name string specifies a UIC. Group and member
are character-string representations of octal numbers with no
leading zeros.
Asterisk (*) and percent sign (%) wildcards are allowed for
the remote user specification. If you specify wildcards for the
rem_user argument, the server searches for an exact match to
the specified remote user first. If it does not find an exact
match, the server performs the requested operations on all of the
matching proxies in the proxy database.
local_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Local user name to delete from the proxy record specified by the
rem_node and rem_user arguments in the proxy database. The local_
user argument is the address of a character-string descriptor
pointing to the local user name.
A local user name consists of 0 to 32 alphanumeric characters,
including dollar signs ($) and underscores (_). If the local_
user argument is not specified or has a length of 0, the server
will delete the entire record or records specified by the rem_
node and rem_user arguments from the proxy database.
If the local_user argument is specified, the server will delete
only the user name specified by the local_user argument from
the record specified by the rem_node and rem_user arguments. The
local_user argument can specify either the proxy's default user
or a user name in the proxy's local users list.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Functional specification for the service and type of user the
local_user argument represents. The flags argument is a longword
bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $PRXDEF macro defines
the following symbolic names:
Symbolic Name Description
PRX$M_BYPASS_ The service should not convert the node name
EXPAND specified in the rem_node argument to its
corresponding DECnet full name. If this flag
is set, it is the caller's responsibility to
ensure that the fully expanded node name is
passed into the service.
PRX$M_IGNORE_ The service should not wait for a return
RETURN status from the security server. No return
status from the server's function will be
returned to the caller.
PRX$M_EXACT The service should match exactly the remote
node and remote user and ignore wildcards.
|
77 - $DELETE REGION 64 (Alpha Only)
|
On Alpha systems, deletes a virtual region within the process's
address space, including all created virtual addresses within the
region.
This service accepts 64-bit addresses.
Format
SYS$DELETE_REGION_64 region_id_64 ,acmode ,return_va_64
,return_length_64
C Prototype
nt sys$delete_region_64 (struct _generic_64 *region_id_64,
unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
77.1 - Arguments
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 to be deleted. The
region ID specified must be one returned by the $CREATE_REGION_64
service. You cannot specify VA$C_P0, VA$C_P1, or VA$C_P2.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $DELETE_REGION_64. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The caller can delete pages only if those pages are owned
by an access mode equal to or less privileged than the access
mode of the caller.
Once all pages are deleted within the region, the region can be
deleted only if the region is owned by an access mode equal to or
less privileged than the access mode of the caller.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the pages that
$DELETE_REGION_64 has successfully deleted. The return_va_64
argument is the 32- or 64-bit virtual address of a naturally
aligned quadword into which the service returns the virtual
address of the first page deleted. Virtual addresses are deleted
from low address to high address, regardless of the direction in
which virtual addresses expand for that region.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range that $DELETE_REGION_64
has successfully deleted. The return_length_64 argument is the
32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the deleted virtual
address range in bytes.
Deletes all logical names with the specified name at the
specified access mode or outer access mode, or it deletes all
the logical names with the specified access mode or outer access
mode in a specified table.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$DELLNM tabnam ,[lognam] ,[acmode]
C Prototype
int sys$dellnm (void *tabnam, void *lognam, unsigned char
*acmode);
78.1 - Arguments
tabnam
OpenVMS usage:logical_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 a logical name table or a list of tables to be searched
for the logical name to be deleted. The tabnam argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on
Alpha systems) of a descriptor that points to the table name.
This argument is required.
If tabnam is not the name of a logical name table, it is assumed
to be a logical name and is translated iteratively until either
the name of a logical name table is found or the number of
translations allowed by the system has been performed.
If tabnam translates to the name of a list of tables, $DELLNM
does the following:
o If you specify the lognam argument, $DELLNM searches (in
order) each table in the list until it finds the first table
that contains the specified logical name. If the logical
name is at the specified access mode, $DELLNM then deletes
occurrences of the logical name at the specified access mode
and at outer access modes within the table.
o If you do not specify the lognam argument, $DELLNM deletes all
of the logical names at the specified access mode or at outer
access modes from the first table in the list whose access
mode is equal to or less privileged than the caller's access
mode.
lognam
OpenVMS usage:logical_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)
Logical name to be deleted. The lognam argument is the 32-bit
address (on VAX systems) or the 32- or 64-bit address (on Alpha
systems) of a descriptor that points to the logical name string.
acmode
OpenVMS usage:access_mode
type: byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Access mode to be used in the delete operation. The acmode
argument is the 32-bit address (on VAX systems) or the 32- or
64-bit address (on Alpha systems) of a byte containing this
access mode. The $PSLDEF macro defines symbolic names for the
four access modes.
You determine the access mode actually used in the delete
operation by maximizing the access mode of the caller with the
access mode specified by the acmode argument; that is, the less
privileged of the two is used.
However, if you have SYSNAM privilege, the delete operation is
executed at the specified access mode regardless of the caller's
access mode.
If you omit this argument or specify it as 0, the access mode
of the caller is used in the delete operation. The access mode
used in the delete operation determines which tables are used and
which names are deleted.
Marks a permanent mailbox for deletion.
Format
SYS$DELMBX chan
C Prototype
int sys$delmbx (unsigned short int chan);
79.1 - Argument
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the channel assigned to the mailbox that is to be
deleted. The chan argument is a word containing this number.
Allows a process to delete itself or another process.
Format
SYS$DELPRC [pidadr] ,[prcnam]
C Prototype
int sys$delprc (unsigned int *pidadr, void *prcnam);
80.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be deleted. The
pidadr argument is the address of a longword that contains the
PID. The pidadr argument can refer to a process running on the
local node or a process running on another node in the OpenVMS
Cluster system.
You must specify the pidadr argument to delete processes in other
UIC groups.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name of the process to be deleted. The prcnam is the
address of a character string descriptor pointing to the
process name string. A process running on the local node can
be identified with a 1- to 15-character string. To identify
a process on a particular node on a cluster, specify the full
process name, which includes the node name as well as the process
name. The full process name can contain up to 23 characters.
You use the prcnam argument to delete only processes in the
same UIC group as the calling process, because process names
are unique to UIC groups, and the operating system uses the UIC
group number of the calling process to interpret the process name
specified by the prcnam argument.
You must use the pidadr argument to delete processes in other
groups.
Deletes a range of addresses from a process's virtual address
space. Upon successful completion of the service, the deleted
pages are inaccessible, and references to them cause access
violations.
Format
SYS$DELTVA inadr ,[retadr] ,[acmode]
C Prototype
int sys$deltva (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the pages to be
deleted. The inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses. If the starting and ending virtual addresses are the
same, a single page is deleted. The addresses are adjusted up or
down to fall on CPU-specific page boundaries. Only the virtual
page number portion of each virtual address is used; the low-
order byte-within-page bits are ignored.
The $DELTVA service deletes pages starting at the address
contained in the second longword of the inadr argument and ending
at the address in the first longword. Thus, if you use the same
address array for both the Create Virtual Address Space ($CRETVA)
and the $DELTVA services, the pages are deleted in the reverse
order from which they were created.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the pages that
$DELTVA has deleted. The retadr argument is the address of a
2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the service is to be performed.
The acmode argument is a longword containing the access mode.
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
|
82 - $DELTVA 64 (Alpha Only)
|
On Alpha systems, deletes a range of virtual addresses from a
process's virtual address space. Upon successful completion of
the service, the deleted pages are inaccessible, and references
to them cause access violations.
This service accepts 64-bit addresses.
Format
SYS$DELTVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode
,return_va_64 ,return_length_64
C Prototype
int sys$deltva_64 (struct _generic_64 *region_id_64,
void *start_va_64, unsigned __int64
length_64, unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
82.1 - Arguments
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 from which to address
the VA space.
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. Also, the region ID that a virtual address
is in can be obtained by calling the $GET_REGION_INFO service,
specifying the VA$_REGSUM_BY_VA function.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be deleted. The
specified address must be a CPU-specific page aligned address.
If the region_id_64 argument specifies a shared page table region
or if the start_va_64 argument lies within a shared page table
region, the specified address must be a CPU-specific page table
page aligned address.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be deleted. The length
specified must be a multiple of CPU-specific pages. If the
virtual address space is being deleted from a shared page table
region, the specified length must be page table page aligned or
include the last page in a memory-resident section.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $DELTVA_64. The acmode
argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. The calling process can delete pages only if those pages
are owned by an access mode equal to or less privileged than the
access mode of the calling process.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the deleted virtual address
range. The return_va_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the $DELTVA_64
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the $DELTVA_64 service returns the length in bytes of
the virtual address range deleted.
Dequeues (unlocks) granted locks; dequeues the sublocks of a
lock; or cancels an ungranted lock request. The calling process
must have previously acquired the lock or queued the lock request
by calling the Enqueue Lock Request ($ENQ) service.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]
C Prototype
int sys$deq (unsigned int lkid, void *valblk, unsigned int
acmode, unsigned int flags);
83.1 - Arguments
lkid
OpenVMS usage:lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the lock to be dequeued. The lkid argument
specifies this lock identification.
Note that if you do not specify the lkid argument, you must
specify the LCK$M_DEQALL flag in the flags argument.
When you specify the LCK$M_DEQALL flag in the flags argument,
different values (or no value) for the lkid argument produce
varying behavior:
o When you do not specify the lkid argument (or specify it as
0) and you do specify the LCK$M_DEQALL flag, $DEQ dequeues all
locks held by the process, at access modes equal to or less
privileged than the effective access mode, on all resources.
The effective access mode is the least privileged of the
caller's access mode and the access mode specified in the
acmode argument.
o When you specify the lkid argument as a nonzero value together
with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks of
the lock identified by lkid; it does not dequeue the lock
identified by lkid. For this operation, $DEQ ignores the
LCK$M_CANCEL flag if it is set. A sublock of a lock is a lock
that was created when the parid argument in the call to $ENQ
was specified, where parid is the lock ID of the parent lock.
If you omit the lkid argument (or specify it as 0) and the LCK$M_
DEQALL flag is not set, the $DEQ service returns the invalid lock
ID condition value (SS$_IVLOCKID).
valblk
OpenVMS usage:lock_value_block
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Lock value block for the resource associated with the lock to be
dequeued. The valblk argument is the 32- or 64-bit address (on
Alpha systems) or the 32-bit (on VAX systems) of the 16-byte lock
value block. When you specify the LCK$M_DEQALL flag, you cannot
use this argument.
When a protected write (PW) or exclusive (EX) mode lock is
being dequeued and you specify a lock value block in the valblk
argument, the contents of that lock value block are written to
the lock value block in the lock database. Further, if the lock
value block in the lock database was marked as invalid, that
condition is cleared; the block becomes valid.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the lock to be dequeued. The acmode argument is a
longword containing the access mode.
The acmode argument is valid only if the LCK$M_DEQALL flag of the
flags argument is set. The $PSLDEF macro defines the following
symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
When dequeuing locks, $DEQ maximizes the access mode of the
caller and the specified acmode argument. The maximized access
mode is the less privileged of the caller's access mode and the
acmode argument. If you do not specify the acmode argument, $DEQ
uses the caller's access mode. Only those locks with an access
mode that is equal to or less than the maximized access mode are
dequeued.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $DEQ operation. The flags
argument is a longword bit mask that is the logical OR of each
bit set, where each bit corresponds to an option.
Note that if you do not specify the lkid argument, you must
specify the LCK$M_DEQALL flag in the flags argument.
A symbolic name for each flag bit is defined by the $LCKDEF
macro. The following table describes each flag:
Flag Description
LCK$M_DEQALL When you specify this flag, $DEQ dequeues
multiple locks, depending on the value of the
lkid argument. Refer to the description of the
lkid argument for details. The acmode argument is
ignored if the LCK$M_DQALL flag is not set. If you
specify LCK$M_DEQALL, the LCK$M_CANCEL flag, if
set, is ignored.
LCK$M_CANCEL When you specify this flag, $DEQ attempts to
cancel a lock request that was queued by $ENQ.
You can cancel only a waiting request. When the
request is canceled, $DEQ returns the condition
value SS$_NORMAL.
If you attempt to cancel a granted lock, the
request fails and $DEQ returns the condition value
SS$_CANCELGRANT. There are two types of waiting
requests that can be canceled:
o A request for a new lock
o A request to convert an existing lock
When canceling a new lock request, the following
action is taken:
o If a completion asynchronous system trap (AST)
was requested, the AST is queued for delivery
and SS$_ABORT is stored in the lock status
block.
When canceling a request to convert an existing
lock, the conversion request is canceled. The
existing granted lock remains unchanged. The
following specific actions are taken:
o The blocking AST address specified for the
existing granted lock is queued for delivery
if the granted mode of the existing lock is
blocking other waiting requests.
o If a completion AST was specified by the
conversion request, the completion AST is
queued for delivery with SS$_CANCEL status
stored in the lock status block that was
specified by the conversion request.
If you specify the LCK$M_DEQALL flag, the LCK$M_
CANCEL flag is ignored.
LCK$M_ When you specify this flag, $DEQ marks the lock
INVVALBLK value block, which is maintained for the resource
in the lock database, as invalid. The lock value
block remains marked as invalid until it is again
written to. The Description section of the $ENQ
service provides additional information about lock
value block invalidation.
This flag is ignored if (1) the lock mode of the
lock being dequeued is not protected write or
exclusive, or (2) you specify the LCK$M_CANCEL
flag.
Returns the displayable pathname for a given I/O channel or
device name. Can be used to return all displayable paths to an
I/O device.
Format
SYS$DEVICE_PATH_SCAN [chan] [,devnam] ,itmlst [,contxt]
[,nullarg]
C Prototype
int sys$device_path_scan (unsigned short int chan, void
*devnam, void *itmlst, unsigned int
*contxt, struct_generic_64 *nullarg);
84.1 - Arguments
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word containing
this number.
To identify a device to $DEVICE_PATH_SCAN, you can specify either
the chan or devnam parameters, but you should not specify both.
If you specify both arguments, the chan argument is used.
If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a
default value of 0 for chan.
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
The name of the device about which $DEVICE_PATH_SCAN is to
return path information. The devnam argument is the address of
a character string descriptor pointing to this name string.
The device name string can be either a physical device name
or a logical name. If the first character in the string is an
underscore (_), the string is considered a physical device name;
otherwise, the string is considered a logical name and logical
name translation is performed until either a physical device name
is found or the system default number of translations has been
performed.
If the device name string contains a colon (:), the colon and
the characters that follow it are ignored.
To identify a device to $DEVICE_PATH_SCAN, you can specify either
the chan or devnam argument, but you should not specify both. If
both arguments are specified, the chan argument is used.
If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a
default value of 0 for chan.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
Value used to indicate the current position of a $DEVICE_PATH_
SCAN search. The contxt argument is the address of the longword
that receives this information. On the initial call, the longword
should contain 0.
nullarg
OpenVMS usage:null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
Placeholding argument reserved to Compaq.
Returns the names of all devices that match a specified set of
search criteria.
Format
SYS$DEVICE_SCAN return_devnam ,retlen ,[search_devnam]
,[itmlst] ,[contxt]
C Prototype
int sys$device_scan (void *return_devnam, unsigned short
int *retlen, void *search_devnam, void
*itmlst, struct _generic_64 *contxt);
85.1 - Arguments
return_devnam
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Buffer to receive the device name. The return_devnam argument is
the address of a character string descriptor pointing to a buffer
into which $DEVICE_SCAN writes the name of the first or next
device that matches the specified search criteria. The maximum
size of any device name is 64 bytes.
retlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the device name string returned by $DEVICE_SCAN. The
retlen argument is the address of a word into which $DEVICE_SCAN
writes the length of the device name string.
search_devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the device for which $DEVICE_SCAN is to search. The
search_devnam argument accepts the standard wildcard characters,
the asterisk (*), which matches any sequence of characters, and
the percent sign (%), which matches any one character. If the
search_devnam argument does not include a wildcard character,
an exact match is used for comparison. For example, to match all
unit 0 DU devices on any controller, specify *DU%0. This string
is compared to the most complete device name (DVI$_ALLDEVNAM).
Only uppercase characters are accepted.
itmlst
OpenVMS usage:item_list_3
type: longword_unsigned
access: read only
mechanism: by reference
Item list specifying search criteria used to identify the device
names for return by $DEVICE_SCAN. The itmlst argument is the
address of a list of item descriptors, each of which describes
one search criterion. The list of item descriptors is terminated
by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Value used to indicate the current position of a $DEVICE_SCAN
search. The contxt argument is the address of the quadword that
receives this information. On the initial call, the quadword
should contain 0.
Marks an existing permanent global section for deletion. The
actual deletion of the global section takes place when all
processes that have mapped the global section have deleted the
mapped pages.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$DGBLSC [flags] ,gsdnam ,[ident]
C Prototype
int sys$dgblsc (unsigned int flags, void *gsdnam, struct
_secid *ident);
86.1 - Arguments
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Mask indicating global section characteristics. The flags
argument is a longword value. A value of 0 (the default)
specifies a group global section; a value of SEC$M_SYSGBL
specifies a system global section; a value of SEC$M_SHMGS on
an OpenVMS Galaxy system creates a shared-memory global section.
gsdnam
OpenVMS usage:section_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 global section to be deleted. The gsdnam argument
is the address of a character string descriptor pointing to this
name string.
For group global sections, the operating system interprets the
group UIC as part of the global section name; thus, the names of
global sections are unique to UIC groups.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
ident
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Identification value specifying the version number of the global
section to be deleted and the matching criteria to be applied.
The ident argument is the 32- or 64-bit address (on Alpha
systems) or the 32-bit address (on VAX systems) of a quadword
structure containing three fields.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. Values
for these fields can be assigned by installation convention to
differentiate versions of global sections. If you specify no
version number when creating a section, processes that specify a
version number when mapping cannot access the global section.
The first longword specifies, in its low-order 3 bits, the
matching criteria. The valid values, the symbolic names by
which they can be specified, and their meanings are listed in
the following table:
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor identifications
match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify no address or specify it as 0 (the default), the
version number and match control fields default to 0.
Dismounts a mounted volume or volume sets.
Format
SYS$DISMOU devnam ,[flags]
C Prototype
int sys$dismou (void *devnam, unsigned int flags);
87.1 - Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Device name of the device to be dismounted. The devnam argument
is the address of a character string descriptor pointing to
the device name string. The string can be either a physical
device name or a logical name. If it is a logical name, it must
translate to a physical device name.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
A longword bit vector specifying options for the dismount
operation. The flags argument is a longword bit vector wherein
a bit, when set, selects the corresponding option. Each bit has a
symbolic name; these names are defined by the $DMTDEF macro.
The flags and their meanings are listed in the following table:
Flag Meaning
DMT$M_ABORT The volume is to be dismounted even if
the caller did not mount the volume. If
the volume was mounted with MNT$M_SHARE
specified, $DISMOU dismounts the volume for
all of the users who mounted it.
To specify DMT$M_ABORT, the caller must: (1)
have GRPNAM privilege for a group volume,
(2) have SYSNAM privilege for a system
volume, or (3) either own the volume or have
VOLPRO privilege.
DMT$M_CLUSTER The volume is to be dismounted clusterwide,
that is, from all nodes in the OpenVMS
Cluster system. $DISMOU dismounts the volume
from the caller's node first and then from
every other node in the existing cluster.
DMT$M_CLUSTER dismounts only system or
group volumes. To dismount a group volume
clusterwide, the caller must have GRPNAM
privilege. To dismount a system volume
clusterwide, the caller must have SYSNAM
privilege.
DMT$M_CLUSTER has no effect if the system
is not a member of a cluster. DMT$M_CLUSTER
applies only to disks.
DMT$M_FORCE If connectivity to a device has been lost and
the shadow set is in mount verification, this
flag causes a named shadow set member to be
immediately expelled from the shadow set.
DMT$M_MINICOPY_ $DISMOU takes place, regardless of whether
OPTIONAL minicopy is enabled on the disk.
DMT$M_MINICOPY_ $DISMOU fails if minicopy has not been
REQUIRED enabled on the disk.
DMT$M_NOUNLOAD Specifies that the volume is not to be
physically unloaded after the dismount. If
both the DMT$M_UNLOAD and DMT$M_NOUNLOAD
flags are specified, the DMT$M_NOUNLOAD flag
is ignored. If neither flag is specified,
the volume is physically unloaded, unless
the DMT$M_NOUNLOAD flag was specified on
the $MOUNT system service or the /NOUNLOAD
qualifier was specified on the MOUNT command
when the volume was mounted.
DMT$M_OVR_CHECKS Specifies that the volume should be
dismounted without checking for open files,
spooled devices, installed images, or
installed swap and page files.
DMT$M_UNIT The specified device, rather than the entire
volume set, is dismounted.
DMT$M_UNLOAD Specifies that the volume is to be physically
unloaded after the dismount. If both the
DMT$M_UNLOAD and DMT$M_NOUNLOAD flags
are specified, the DMT$M_NOUNLOAD flag
is ignored. If neither flag is specified,
the volume is physically unloaded, unless
the DMT$M_NOUNLOAD flag was specified on
the $MOUNT system service or the /NOUNLOAD
qualifier was specified on the MOUNT command
when the volume was mounted.
Returns information about one or more existing proxies.
Format
SYS$DISPLAY_PROXY rem_node ,rem_user ,buffer_sizes ,proxy_node
,proxy_user ,default_user ,local_users
,flags ,[context]
C Prototype
int sys$display_proxy (void *rem_node, void *rem_user,
unsigned short int buffer_sizes [4],
void *proxy_node, void *proxy_user,
void *default_user, unsigned int
*local_users, unsigned int flags,
unsigned int *context);
88.1 - Arguments
rem_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote node name of the proxy about which information is being
requested. The rem_node argument is the address of a character-
string descriptor pointing to the remote node name string.
A remote node name consists of 1 to 1024 characters. No specific
characters, format, or case are required for a remote node
name string. All node names are converted to their DECnet full
name unless the PRX$M_BYPASS_EXPAND flag is set with the flags
argument.
Asterisk (*) and percent sign (%) wildcards are allowed for the
remote node specification. If you specify wildcards for the rem_
node argument, the server searches the entire proxy database for
matches to the remote node and remote user you specified. If a
match is found, information about the matched proxy is returned.
Refer to the OpenVMS System Services Reference Manual for
additional details on retrieving information about multiple
proxies.
rem_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote user name of the proxy about which information is being
requested. The rem_user argument is the address of a character-
string descriptor pointing to the user name string.
A remote user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($), underscores (_), and brackets
([ ]). Any lowercase characters specified are automatically
converted to uppercase.
The rem_user argument can be specified in user identification
code (UIC) format ([group, member]). Brackets are allowed only
if the remote user name string specifies a UIC. Group and member
are character-string representations of octal numbers with no
leading zeros.
Asterisk (*) and percent sign (%) wildcards are allowed for the
remote user specification. If you specify wildcards for the rem_
user argument, the server searches the entire proxy database for
matches to the remote node and remote user you specified. If a
match is found, information about the matched proxy is returned.
See the Description section for information about retrieving
information about multiple proxies.
buffer_sizes
OpenVMS usage:return length block
type: array of 4 words (unsigned)
access: write only
mechanism: by reference
Array of return lengths for various input buffers.
Refer to the OpenVMS System Services Reference Manual to view the
array diagram and buffer_sizes fields table.
proxy_node
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Node name of a proxy matching the remote node name specified by
the rem_node argument and the remote user name specified by the
rem_user argument. The proxy_node argument is the address of a
character-string descriptor pointing to a buffer to receive the
proxy node name.
The descriptor's buffer must be 1024 bytes long to receive a node
name. The length of the returned node name is specified by the
proxy node length field returned in the buffer specified by the
buffer_sizes argument.
proxy_user
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
User name of a proxy matching the remote node name specified by
the rem_node argument and the remote user name specified by the
rem_user argument. The proxy_user argument is a character-string
descriptor pointing to a buffer to receive the remote user name
of a proxy.
The descriptor's buffer must be 32 bytes long to receive a user
name. The length of the returned user name is specified by the
proxy user length field returned in the buffer specified by the
buffer_sizes argument.
default_user
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Default user of a proxy matching the node name specified by the
rem_node argument and the remote user name specified by the rem_
user argument. The default_user argument is the address of a
character-string descriptor pointing to a buffer to receive the
default user name.
The descriptor's buffer must be 32 bytes long to receive a user
name. The length of the returned user name is specified in the
default user length field in the buffer specified by the buffer_
sizes argument.
local_users
OpenVMS usage:buffer
type: array of 0 to 16 user name buffers
access: write only
mechanism: by reference
Array of local user names associated with a proxy matching the
remote node name specified by the rem_node argument and the
remote user name specified by the rem_user argument. The local_
users argument is the address of a buffer to receive an array of
local user names.
Refer to the OpenVMS System Services Reference Manual to view the
array diagram and local_users fields table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Functional specification for the service and type of user the
local_user argument represents. The flags argument is a longword
bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $PRXDEF macro defines
the following symbolic names:
Symbolic Name Description
PRX$M_BYPASS_ The service should not convert the node name
EXPAND specified in the rem_node argument to its
corresponding DECnet full name. If this flag
is set, it is the caller's responsibility to
ensure that the fully expanded node name is
passed into the service.
PRX$M_EXACT The service should match exactly the remote
node and remote user and ignore wildcards.
context
OpenVMS usage:context
type: longword (unsigned)
access: write only
mechanism: by reference
Context information to keep between related calls to the
$DISPLAY_PROXY service. The context argument is the address of
a longword to receive a context from the $DISPLAY_PROXY service.
The initial value contained in the longword pointed to by the
context argument must be 0. The contents of the unsigned longword
must not be changed after the service has set its value. If the
contents of the buffer pointed to by the context argument are
changed between calls to the $DISPLAY_PROXY service, the service
will return SS$_BADCONTEXT. If the contents of the context
argument are changed between calls to the $DISPLAY_PROXY service,
you can change the value of the context argument back to 0 to
start the search over again.
Contexts become invalid after one-half hour of non-use. This
means that if you call the $DISPLAY_PROXY service with a wildcard
rem_node or rem_user, and do not call the service to get the
next matching record within one-half hour, the context becomes
invalid. If the context has become invalid, you must start your
search of the proxy database over from its beginning by resetting
the context to 0.
Marks a permanent common event flag cluster for deletion.
Format
SYS$DLCEFC name
C Prototype
int sys$dlcefc (void *name);
89.1 - Argument
name
OpenVMS usage:ef_cluster_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the common event flag cluster to be deleted. The name
argument is the address of a character string descriptor pointing
to the name of the cluster.
The names of event flag clusters are unique to UIC groups, and
the UIC group number of the calling process is part of the name.
On VAX systems, the DIGITAL Distributed Name Service (DECdns)
clerk allows client applications to store resource names and
addresses.
The $DNS system service completes asynchronously; that is, it
returns to the client immediately after making a name service
call. The status returned to the client call indicates whether a
request was successfully queued to the name service.
The DIGITAL Distributed Name Service Clerk Wait ($DNSW) system
service is the synchronous equivalent of $DNS. $DNSW is identical
to $DNS in every way except that $DNSW returns to the caller
after the operation completes.
Format
SYS$DNS [efn] ,func ,itmlst ,[dnsb] ,[astadr] ,[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 $DNS completes. The efn
argument is a longword containing this number. The efn argument
is optional; if not specified, event flag 0 is set.
When $DNS begins execution, it clears the event flag. Even if the
service encounters an error and completes without queuing a name
service request, the specified event flag is set.
func
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function code specifying the action that $DNS is to perform. The
func argument is a longword containing this function code.
A single call to $DNS can specify one function code. Most
function codes require or allow for additional information to
be passed in the call with the itmlst argument.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list supplying information to be used in performing the
function specified by the func argument. The itmlst argument is
the address of the item list. The item list consists of one or
more item descriptors, each of which is three longwords.
The descriptors can be in any order in the item list. Each item
descriptor specifies an item code. Item codes are specified
as either input or output parameters. Input parameters modify
functions, set context, or describe the information to be
returned. Output parameters return the requested information.
The item list is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
dnsb
OpenVMS usage:dns_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
Status block to receive the final completion status of the $DNS
operation. The dnsb argument is the address of the quadword $DNS
status block.
Refer to the OpenVMS System Services Reference Manual to view
the $DNS status block structure diagram and status block fields
table.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Asynchronous system trap (AST) routine to be executed when I/O
completes. The astadr argument is the address of the AST routine.
The AST routine executes in the access mode of the caller of
$DNS.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Asynchronous system trap parameter passed to the AST service
routine. The astprm argument is a longword value containing the
AST parameter.
On VAX systems, is the client interface to the DIGITAL
Distributed Name Service.
The $DNSW service completes synchronously; that is, it returns to
the caller after the operation completes.
For asynchronous completion, use the $DNS service, which returns
to the caller immediately after making a name service call. The
return status to the client call indicates whether a request was
successfully queued to the name service.
In all other respects, $DNSW is identical to $DNS. Refer to
the $DNS description for complete information about the $DNSW
service.
Format
SYS$DNSW [efn] ,func ,itmlst [,dnsb] [,astadr] [,astprm]
Ends a transaction by attempting to commit it, and returns the
outcome of the transaction.
Format
SYS$END_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid]]
C Prototype
int sys$end_trans (unsigned int efn, unsigned int flags,
struct _iosb *iosb,...);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag that is set when the service completes.
If this argument is omitted, event flag 0 is set.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the service. The flags argument is
a longword bit mask in which each bit corresponds to an option
flag. The $DDTMDEF macro defines symbolic names for these option
flags.
All undefined bits must be 0. If this argument is omitted, no
flag is set.
The flag currently defined is shown in the following table:
Flag Description
DDTM$M_SYNC Set this flag to specify that successful
synchronous completion is to be indicated by
returning SS$_SYNCH. When SS$_SYNCH is returned,
the asynchronous system trap (AST) routine is not
called, the event flag is not set, and the I/O
status block is not filled in.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block in which the following information is returned:
o The completion status of the service. This is returned as a
condition value.
o The outcome of the transaction.
If the service returns SS$_NORMAL, the outcome of the
transaction is commit. If the service returns SS$_ABORT, the
outcome of the transaction is abort.
o An abort reason code that gives one reason why the transaction
aborted, if the completion status of the service is SS$_ABORT.
The $DDTMMSGDEF macro defines symbolic names for these abort
reason codes; those currently defined are shown in the following
table:
Symbolic Name Description
DDTM$_ABORTED The application aborted the transaction.
DDTM$_COMM_FAIL A communications link failed.
DDTM$_INTEGRITY A resource manager integrity constraint
check failed.
DDTM$_LOG_FAIL A write operation to the transaction log
failed.
DDTM$_PART_SERIAL A resource manager serialization check
failed.
DDTM$_PART_TIMEOUT The timeout specified by a resource manager
expired.
DDTM$_SEG_FAIL A process or image terminated.
DDTM$_ A DECdtm transaction manager serialization
SERIALIZATION check failed.
DDTM$_SYNC_FAIL The transaction was not globally
synchronized.
DDTM$_TIMEOUT The timeout specified on $START_TRANS
expired.
DDTM$_UNKNOWN The reason is unknown.
DDTM$_VETOED A resource manager was unable to commit the
transaction.
Refer to the OpenVMS System Services Reference Manual to view the
structure of the I/O status block.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST routine that is executed when the service completes. The
astadr argument is the address of this routine. The routine is
executed in the access mode of the caller.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter that is passed to the AST routine specified by the
astadr argument.
tid
OpenVMS usage:transaction_id
type: octaword (unsigned)
access: read only
mechanism: by reference
Identifier of the transaction to be ended.
If this argument is omitted, $END_TRANS ends the default
transaction of the calling process.
Ends a transaction by attempting to commit it, and returns the
outcome of the transaction.
$END_TRANSW always waits for the request to complete before
returning to the caller. Other than this, it is identical to
$END_TRANS.
Format
SYS$END_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid]]
C Prototype
int sys$end_transw (unsigned int efn, unsigned int flags,
struct _iosb *iosb,...);
Queues a new lock or lock conversion on a resource.
The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get
Lock Information) services together provide the user interface to
the Lock Management facility.
On Alpha systems, this service accepts 64-bit addresses.
For additional information about system service completion, see
the Synchronize ($SYNCH) service.
Format
SYS$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid]
,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]
,[nullarg]
C Prototype
int sys$enq (unsigned int efn, unsigned int lkmode,
struct _lksb *lksb, unsigned int flags,
void *resnam, unsigned int parid, void
(*astadr)(__unknown_params), unsigned int acmode,
unsigned int rsdm_id,...);
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 request has been
granted or canceled. Cancellation occurs if you use $DEQ with the
cancel modifier or if the waiting request is chosen to break a
deadlock. The efn argument is a longword containing this number;
however, $ENQ uses only the low-order byte.
Upon request initiation, $ENQ clears the specified event flag
(or event flag 0 if efn was not specified). Then, when the lock
request is granted, the specified event flag (or event flag 0)
is set unless you specified the LCK$M_SYNCSTS flag in the flags
argument.
lkmode
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Lock mode requested. The lkmode argument is a longword specifying
this lock mode.
Each lock mode has a symbolic name. The $LCKDEF macro defines
these symbolic names. The following table gives the symbolic name
and description for each lock mode:
Lock Mode Description
LCK$K_NLMODE Null mode. This mode grants no access to the
resource but serves as a placeholder and indicator
of future interest in the resource. The null mode
does not inhibit locking at other lock modes;
further, it prevents the deletion of the resource
and lock value block, which would otherwise occur
if the locks held at the other lock modes were
dequeued.
LCK$K_CRMODE Concurrent read. This mode grants the caller read
access to the resource while permitting write
access to the resource by other users. This mode is
used to read data from a resource in an unprotected
manner, because other users can modify that data as
it is being read. This mode is typically used when
additional locking is being performed at a finer
granularity with sublocks.
LCK$K_CWMODE Concurrent write. This mode grants the caller
write access to the resource while permitting write
access to the resource by other users. This mode is
used to write data to a resource in an unprotected
fashion, because other users can simultaneously
write data to the resource. This mode is typically
used when additional locking is being performed at
a finer granularity with sublocks.
LCK$K_PRMODE Protected read. This mode grants the caller read
access to the resource while permitting only read
access to the resource by other users. Write access
is not allowed. This is the traditional share lock.
LCK$K_PWMODE Protected write. This mode grants the caller write
access to the resource while permitting only read
access to the resource by other users; the other
users must have specified concurrent read mode
access. No other writers are allowed access to the
resource. This is the traditional update lock.
LCK$K_EXMODE Exclusive. The exclusive mode grants the caller
write access to the resource and allows no access
to the resource by other users. This is the
traditional exclusive lock.
Table SYS-2 Compatibility of Lock Modes
Mode of Mode of Currently Granted Locks
Requested
Lock NL CR CW PR PW EX
NL Yes Yes Yes Yes Yes Yes
CR Yes Yes Yes Yes Yes No
CW Yes Yes Yes No No No
PR Yes Yes No Yes No No
PW Yes Yes No No No No
EX Yes No No No No No
__________________________________________________________________
Key to Lock Modes:
NL-Null
CR-Concurrent read
CW-Concurrent write
PR-Protected read
PW-Protected write
EX-Exclusive
lksb
OpenVMS usage:lock_status_block
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Lock status block in which $ENQ writes the final completion
status of the operation. The lksb argument is the 32- or 64-bit
address (on Alpha systems) or the 32-bit address (on VAX systems)
of the 8-byte lock status block.
The lock status block can optionally contain a 16-byte lock value
block. The initial value of the lock value block is zero (0).
When you specify the LCK$M_VALBLK flag in the flags argument, the
lock status block contains a lock value block. In this case, the
16-byte lock value block appears at the beginning of the first
byte following the eighth byte of the lock status block, bringing
the total length of the lock status block to 24 bytes.
Refer to the OpenVMS System Services Reference Manual to view the
lock status block format diagram and status block fields table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $ENQ operation. The flags
argument is a longword bit mask that is the logical OR of each
bit set, where each bit corresponds to an option.
The $LCKDEF macro defines a symbolic name for each flag bit.
Refer to the OpenVMS System Services Reference Manual to view the
table describing each flag.
resnam
OpenVMS usage:char_string
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 resource to be locked by this lock. The resnam
argument is the 32- or 64-bit address (on Alpha systems) or the
32-bit address (on VAX systems) of a character string descriptor
pointing to this name. The name string can be from 1 to 31 bytes
in length.
If you are creating a new lock, the resnam argument should be
specified because the default value for the resnam argument
produces an error when it is used to create a lock. The resnam
argument is ignored for lock conversions.
parid
OpenVMS usage:lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the parent lock. The parid argument is a
longword containing this identification value.
If you do not specify this argument or specify it as 0, $ENQ
assumes that the lock does not have a parent lock. This argument
is optional for new locks and is ignored for lock conversions.
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 the lock is either
granted or converted. The astadr argument is the 32- or 64-
bit address (on Alpha systems) or the 32-bit address (on VAX
systems) of this routine. The AST is also delivered when the lock
or conversion request is canceled. Cancellation occurs if you use
$DEQ with the cancel modifier or if the waiting request is chosen
to break a deadlock.
If you specify the astadr argument, the AST routine executes at
the same access mode as the caller of $ENQ.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST routine specified by the
astadr argument. The astprm argument specifies this quadword
parameter.
blkast
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)
Blocking AST routine to be called whenever this lock is granted
and is blocking any other lock requests. The blkast argument
is the 32- or 64-bit address (on Alpha systems) or the 32-
bit address (on VAX systems) of this routine. Locks that are
converting to a new mode, but that are not yet granted in the new
mode, do not receive blocking ASTs.
You can pass a parameter to this routine by using the astprm
argument.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the resource name. The acmode
argument indicates the least privileged access mode from which
locks can be queued on the resource.
This argument does not affect the access mode associated with the
lock or its blocking and completion ASTs. The acmode argument is
a longword containing the access mode. The $PSLDEF macro defines
the following symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The $ENQ service associates an access mode with the lock in the
following way:
o If you specified a parent lock (with the parid argument),
$ENQ uses the access mode associated with the parent lock and
ignores both the acmode argument and the caller's access mode.
o If the lock has no parent lock (you did not specify the parid
argument or specified it as 0), $ENQ uses the least privileged
of the caller's access mode and the access mode specified
by the acmode argument. If you do not specify the acmode
argument, $ENQ uses the caller's access mode.
rsdm_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Resource domain identification. The rsdm_id argument is a
longword specifying the resource domain association through
which a new lock is to be taken. This argument is ignored for
lock conversions and sublocks (parid is nonzero). Valid resource
domain identifiers are returned from the $SET_RESOURCE_DOMAIN
service, or by the constants RSDM$K_SYSTEM_RSDM_ID or RSDM$K_
PROCESS_RSDM_ID, which are defined by the $RSDMDEF macro in
STARLET.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Compaq.
Queues a lock on a resource. The $ENQW service completes
synchronously; that is, it returns to the caller when the
lock has been either granted or converted. For asynchronous
completion, use the Enqueue Lock Request ($ENQ) service; $ENQ
returns to the caller after queuing the lock request, without
waiting for the lock to be either granted or converted. In
all other respects, $ENQW is identical to $ENQ. See the $ENQ
description for all other information about the $ENQW service.
The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the
user interface to the Lock Management facility.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ENQW [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid]
,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]
C Prototype
int sys$enqw (unsigned int efn, unsigned int lkmode,
struct _lksb *lksb, unsigned int flags,
void *resnam, unsigned int parid, void
(*astadr)(__unknown_params), unsigned __int64
astprm, void (*blkast)(__unknown_params),
unsigned int acmode, unsigned int rsdm_id,...);
Generates a security erase pattern.
Format
SYS$ERAPAT [type] ,[count] ,[patadr]
C Prototype
int sys$erapat (int type, unsigned int count, unsigned int
*patadr);
96.1 - Arguments
type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Type of storage to be written over with the erase pattern. The
type argument is a longword containing the type of storage.
The three storage types, together with their symbolic names,
are defined by the $ERADEF macro and are listed in the following
table:
Storage Type Symbolic Name
Main memory ERA$K_MEMORY
Disk ERA$K_DISK
Tape ERA$K_TAPE
count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of times that $ERAPAT has been called in a single security
erase operation. The count argument is a longword containing the
iteration count.
You should call the $ERAPAT service initially with the count
argument set to 1, the second time with the count argument set to
2, and so on, until the status code SS$_NOTRAN is returned.
patadr
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Security erase pattern to be written. The patadr argument is the
address of a longword into which the security erase pattern is to
be written.
Initiates image rundown when the current image in a process
completes execution. Control normally returns to the command
interpreter.
Format
SYS$EXIT [code]
C Prototype
int sys$exit (unsigned int code);
97.1 - Argument
code
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Longword value to be saved in the process header as the
completion status of the current image. If you do not specify
this argument in a macro call, a value of 1 is passed as the
completion code for VAX MACRO and VAX BLISS-32, and a value of
0 is passed for other languages. You can test this value at the
command level to provide conditional command execution.
Adds a specified number of new virtual pages to a process's
program region or control region for the execution of the current
image. Expansion occurs at the current end of that region's
virtual address space.
Format
SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]
C Prototype
int sys$expreg (unsigned int pagcnt, struct _va_range *retadr,
unsigned int acmode, char region);
Arguments
pagcnt
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pages (on VAX systems) or pagelets (on Alpha systems)
to add to the current end of the program or control region. The
pagcnt argument is a longword value containing this number.
On Alpha systems, the specified value is rounded up to an even
multiple of the CPU-specific page size.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the pages that
$EXPREG has actually added. The retadr argument is the address of
a 2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the newly added pages. The
acmode argument is a longword containing the access mode.
The most privileged access mode used is the access mode of the
caller.
The newly added pages are given the following protection:
(1) read and write access for access modes equal to or more
privileged than the access mode used in the call, and (2) no
access for access modes less privileged than that used in the
call.
region
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number specifying which program region is to be expanded. The
region argument is a longword value. A value of 0 (the default)
specifies that the program region (P0 region) is to be expanded.
A value of 1 specifies that the control region (P1 region) is to
be expanded.
|
99 - $EXPREG 64 (Alpha Only)
|
On Alpha systems, adds a specified number of demand-zero
allocation pages to a process's virtual address space for the
execution of the current image. Expansion occurs at the next free
available address within the specified region.
This service accepts 64-bit addresses.
Format
SYS$EXPREG_64 region_id_64 ,length_64 ,acmode ,flags
,return_va_64 ,return_length_64
C Prototype
int sys$expreg_64 (struct _generic_64 *region_id_64, unsigned
__int64 length_64, unsigned int acmode,
unsigned int flags, void *(*(return_va_64)),
unsigned __int64 *return_length_64);
99.1 - Arguments
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 virtual address range to be
expanded. 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.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be created. The length
specified must be a multiple of CPU-specific pages.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $EXPREG_64. The access
mode determines the owner mode of the pages as well as the read
and write protection on the pages. The acmode argument is a
longword containing the access mode. The $PSLDEF macro defines
symbols for the four access modes.
The $EXPREG_64 service uses whichever of the following two access
modes is least privileged:
o The access mode specified by the acmode argument.
o The access mode of the caller. The protection of the pages
is read/write for the resultant access mode and those more
privileged.
Address space cannot be created within a region that has a create
mode associated with it that is more privileged than the caller's
mode. The condition value SS$_IVACMODE is returned if the caller
is less privileged than the create mode for the region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask controlling the characteristics of the demand-zero
pages created. The flags argument is a longword bit vector in
which each bit corresponds to a flag. The $VADEF macro and the
VADEF.H file define a symbolic name for each flag. You construct
the flags argument by performing a logical OR operation on the
symbol names for all desired flags.
All bits in the flags argument are reserved for future use
by Compaq and should be specified as 0. The condition value
SS$_IVVAFLG is returned if any bits are set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of a created virtual address
range. The return_va_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service
returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length in bytes of the virtual
address range created.
Converts a binary value into an ASCII character string in
decimal, hexadecimal, or octal notation; returns the character
string in an output string; and inserts variable character-string
data into an output string.
The Formatted ASCII Output with List Parameter ($FAOL) service
provides an alternate method for specifying input parameters when
calling the $FAO system service.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$FAO ctrstr ,[outlen] ,outbuf ,[p1]...[pn]
SYS$FAOL ctrstr ,[outlen] ,outbuf ,[prmlst]
C Prototype
int sys$fao (void *ctrstr, unsigned short int *outlen, void
*outbuf,...);
int sys$faol (void *ctrstr, unsigned short int *outlen, void
*outbuf, void *prmlst);
Arguments
ctrstr
OpenVMS usage:char_string
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)
Control string passed to $FAO that contains the text to be output
together with one or more $FAO directives. $FAO directives are
used to specify repeat counts or the output field length, or
both, and they are preceded by an exclamation point (!). The
ctrstr argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character string
descriptor pointing to the control string.
There is no restriction on the length of the control string or
on the number of $FAO directives it can contain; however, if an
exclamation point must appear in the output string, it must be
represented in the control string by a double exclamation point
(!!). A single exclamation point in the control string indicates
to $FAO that the next characters are to be interpreted as FAO
directives.
When $FAO processes the control string, it writes to the output
buffer each character that is not part of an $FAO directive.
If the $FAO directive is valid, $FAO processes it. If the
directive requires a parameter, $FAO processes the next
consecutive parameter in the specified parameter list. If the
$FAO directive is not valid, $FAO terminates and returns a
condition value in R0.
The $FAO service reads parameters from the argument list
specified in the call; these arguments have the names p1, p2,
p3, and so on, up to p17. Each argument specifies one parameter.
Because $FAO accepts a maximum of 17 parameters in a single call,
you must use $FAOL if the number of parameters exceeds 17. The
$FAOL service accepts any number of parameters used with the
prmlst argument.
outlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Length in bytes of the fully formatted output string returned
by $FAO. The outlen argument is the 32- or 64-bit address (on
Alpha systems) or the 32-bit address (on VAX systems) of a word
containing this value.
outbuf
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor-fixed-length string descriptor
(VAX)
Output buffer into which $FAO writes the fully formatted output
string. The outbuf argument is the 32- or 64-bit address (on
Alpha systems) or the 32-bit address (on VAX systems) of a
character string descriptor pointing to the output buffer. The
maximum number of bytes written is limited to 64K.
p1 to pn
OpenVMS usage:varying_arg
type: quadword (signed)
access: read only
mechanism: by value
$FAO directive parameters. The p1 argument is a quadword
containing the parameter needed by the first $FAO directive
encountered in the control string, the p2 argument is a quadword
containing the parameter needed for the second $FAO directive,
and so on for the remaining arguments up to p17. If an $FAO
directive does not require a parameter, that $FAO directive is
processed without reading a parameter from the argument list.
Depending on the directive, a parameter can be a value to be
converted, a 32- or 64-bit address of a string to be inserted
into the output string, or a length or argument count. Each
directive in the control string might require a corresponding
parameter or parameters.
prmlst
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
List of $FAO directive parameters to be passed to $FAOL. The
prmlst argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a list of longwords
wherein each longword is a parameter. The $FAOL service processes
these parameters sequentially as it encounters, in the control
string, $FAO directives that require parameters.
The parameter list can be a data structure that already exists in
a program and from which certain values are to be extracted.
|
101 - $FAOL 64 (Alpha Only)
|
On Alpha systems, converts a binary value into an ASCII character
string in decimal, hexadecimal, or octal notation; returns
the character string in an output string; and inserts variable
character-string data into an output string.
$FAOL_64 interprets the parameter list as a list of quadwords
rather than a list of longwords. In all other respects, $FAOL_64
is identical to $FAOL. For all other information about the $FAOL_
64 service, refer to the help for $FAO/$FAOL.
This service accepts 64-bit addresses.
Format
SYS$FAOL_64 ctrstr_64 [,outlen_64 [,outbuf_64
[,quad_prmlst_64]]]
C Prototype
int sys$faol_64 (void *ctrstr_64, unsigned short int
*outlen_64, void *outbuf_64, void
*quad_prmlst_64);
101.1 - Arguments
ctrstr_64
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
The 32- or 64-bit address of the control string (64-bit or 32-bit
string descriptor).
outlen_64
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit address of the quadword that contains the
output length, in bytes, of the fully formatted output string.
outbuf_64
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
The 32- or 64-bit address of a character string descriptor that
points to the output buffer into which $FAOL_64 writes the fully
formatted output string.
quad_prmlst_64
OpenVMS usage:vector_quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit address of a quadword-aligned array of quadword
FAO arguments.
Searches a string for a file specification and parses the
components of that file specification.
Format
SYS$FILESCAN srcstr ,valuelst ,[fldflags] ,[auxout] ,[retlen]
C Prototype
int sys$filescan (void *srcstr, void *valuelst, unsigned int
*fldflags, void *auxout, unsigned short int
*retlen);
102.1 - Arguments
srcstr
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
String to be searched for the file specification. The srcstr
argument is the address of a descriptor pointing to this string.
valuelst
OpenVMS usage:item_list_2
type: longword (unsigned)
access: modify
mechanism: by reference
Item list specifying which components of the file specification
are to be returned by $FILESCAN. The components are the full node
specification, primary node name, primary node's access control,
secondary node information, device, directory, file name, file
type, and version number. The itmlst argument is the address of a
list of item descriptors wherein each item descriptor specifies
one component. The list of item descriptors is terminated by a
longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
fldflags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Longword flag mask in which $FILESCAN sets a bit for each file
specification component found in the input string. The fldflags
argument is the address of this longword flag mask.
The $FSCNDEF macro defines a symbolic name for each significant
flag bit. The following table shows the file specification
component that corresponds to the symbolic name of each flag
bit:
Symbolic Name Corresponding Component
FSCN$V_DEVICE Device name
FSCN$V_ Directory name
DIRECTORY
FSCN$V_NAME File name
FSCN$V_NODE Node name
FSCN$V_NODE_ACS Access control string of primary node
FSCN$V_NODE_ Primary (first) node name
PRIMARY
FSCN$V_NODE_ Secondary (additional) node information
SECONDARY
FSCN$V_ROOT Root directory name string
FSCN$V_TYPE File type
FSCN$V_VERSION Version number
The fldflags argument is optional. When you want to know which
components of a file specification are present in a string but
do not need to know the contents or length of these components,
specify fldflags instead of valuelst.
auxout
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Auxiliary output buffer. The auxout argument is the address of a
character-string descriptor pointing to the auxiliary buffer.
When you specify an auxiliary output buffer, $FILESCAN copies
the entire source string, with quotation information reduced and
simplified for only the primary node, into the auxiliary output
buffer.
When the auxiliary output buffer is provided, all addresses
returned in the item list point to locations in the auxiliary
output buffer.
retlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the auxiliary buffer. The retlen argument is the
address of a word into which $FILESCAN writes the length of the
auxiliary buffer name string.
Returns the identifiers held by a specified holder.
Format
SYS$FIND_HELD holder ,[id] ,[attrib] ,[contxt]
C Prototype
int sys$find_held (struct _generic_64 *holder, unsigned int
*id, unsigned int *attrib, unsigned int
*contxt);
103.1 - Arguments
holder
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Holder whose identifiers are to be found when $FIND_HELD
completes execution. The holder argument is the address of a
quadword data structure containing the holder identifier. This
quadword data structure consists of a longword containing the
holder UIC, followed by a longword containing the value 0.
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value found when $FIND_HELD completes execution.
The id argument is the address of a longword containing the
identifier value with which the holder is associated.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes associated with the holder returned in id when $FIND_
HELD completes execution. The attrib argument is the address of a
longword containing a bit mask specifying the attributes.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The symbols are defined
in the system macro library ($KGBDEF). The following are the
symbols for each bit position:
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it
from or add it to the process rights list by
using the DCL command SET RIGHTS_LIST.
KGB$V_ Makes any access rights of the identifier
NOACCESS null and void. This attribute is intended as
a modifier for a resource identifier or the
Subsystem attribute.
KGB$V_ Allows the holder to charge resources, such as
RESOURCE disk blocks, to the identifier.
KGB$V_ Allows holders of the identifier to create and
SUBSYSTEM maintain protected subsystems by assigning the
Subsystem ACE to the application images in the
subsystem.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used when repeatedly calling $FIND_HELD. The contxt
argument is the address of a longword used while searching for
all identifiers. The context value must be initialized to 0,
and the resulting context of each call to $FIND_HELD must be
presented to each subsequent call. After contxt is passed to
$FIND_HELD, you must not modify its value.
Returns the holder of a specified identifier.
Format
SYS$FIND_HOLDER id ,[holder] ,[attrib] ,[contxt]
C Prototype
int sys$find_holder (unsigned int id, struct _generic_64
*holder, unsigned int *attrib, unsigned
int *contxt);
104.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary identifier value whose holders are found by $FIND_HOLDER.
The id argument is a longword containing the binary identifier
value.
holder
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: write only
mechanism: by reference
Holder identifier returned when $FIND_HOLDER completes execution.
The holder argument is the address of a quadword containing
the holder identifier. The first longword contains the UIC of
the holder with the high-order word containing the group number
and the low-order word containing the member number. The second
longword contains the value 0.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Mask of attributes associated with the holder record specified
by holder. The attrib argument is the address of a longword
containing the attribute mask.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The symbols are defined
in the system macro library ($KGBDEF). The following are the
symbols for each bit position:
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it
from or add it to the process rights list by
using the DCL command SET RIGHTS_LIST. For more
information on SET RIGHTS_LIST, refer to the
OpenVMS DCL Dictionary.
KGB$V_ Makes any rights of the identifier null and void.
NOACCESS This attribute is intended as a modifier for a
resource identifier or the Subsystem attribute.
KGB$V_ Allows the holder of an identifier to charge disk
RESOURCE space to the identifier. It is used only for file
objects.
KGB$V_ Allows holders of an identifier to create and
SUBSYSTEM maintain protected subsystems by assigning the
Subsystem ACE to the application images in the
subsystem.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used while searching for all the holders of the
specified identifier when executing $FIND_HOLDER. The contxt
argument is the address of a longword containing the context
value. When calling $FIND_HOLDER repeatedly, contxt must be
set initially to 0 and the resulting context of each call to
$FIND_HOLDER must be presented to each subsequent call. After
the argument is passed to $FIND_HOLDER, you must not modify its
value.
Deallocates the record stream and clears the context value used
with $FIND_HELD, $FIND_HOLDER, or $IDTOASC.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$FINISH_RDB contxt
C Prototype
int sys$finish_rdb (unsigned int *contxt);
105.1 - Argument
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Context value to be cleared when $FINISH_RDB completes execution.
The contxt argument is a longword containing the address of the
context value.
Causes an Exit ($EXIT) service call to be issued on behalf of a
specified process.
Format
SYS$FORCEX [pidadr] ,[prcnam] ,[code]
C Prototype
int sys$forcex (unsigned int *pidadr, void *prcnam, unsigned
int code);
106.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be forced to exit.
The pidadr argument is the address of a longword containing the
PID.
The pidadr argument can refer to a process running on the local
node or a process running on another node in the OpenVMS Cluster
system.
The pidadr argument is optional but must be specified if the
process that is to be forced to exit is not in the same UIC group
as the calling process.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name of the process that is to be forced to exit. The
prcnam argument is the address of a character string descriptor
pointing to the process name string. A process running on the
local node can be identified with a 1- to 15-character string.
To identify a process on a particular node in a cluster, specify
the full process name, which includes the node name as well as
the process name. The full process name can contain up to 23
characters.
The prcnam argument can be used only on behalf of processes in
the same UIC group as the calling process. To force processes in
other groups to exit, you must specify the pidadr argument. This
restriction exists because the operating system interprets the
UIC group number of the calling process as part of the specified
process name; the names of processes are unique to UIC groups.
code
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Completion code value to be used as the exit parameter. The
code argument is a longword containing this value. If you do
not specify the code argument, the value 0 is passed as the
completion code.
Formats the specified access control entry (ACE) into a text
string.
Format
SYS$FORMAT_ACL aclent ,[acllen] ,aclstr ,[width] ,[trmdsc]
,[indent] ,[accnam] ,[nullarg]
C Prototype
int sys$format_acl (void *aclent, unsigned short int
*acllen, void *aclstr, unsigned short
int *width, void *trmdsc, unsigned short
int *indent, unsigned int *accnam, int
(*routin)(__unknown_params));
107.1 - Arguments
aclent
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Description of the ACE formatted when $FORMAT_ACL completes
execution. The aclent argument is the address of a descriptor
pointing to a buffer containing the description of the input ACE.
The first byte of the buffer contains the length of the ACE; the
second byte contains a value that identifies the type of ACE,
which in turn determines the ACE format.
See the $FORMAT_ACL Description section in the OpenVMS System
Services Reference Manual for more information about the ACE
format.
acllen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string resulting when $FORMAT_ACL completes
execution. The acllen argument is the address of a word
containing the number of characters written to aclstr.
aclstr
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Formatted ACE resulting when $FORMAT_ACL completes its execution.
The aclstr argument is the address of a string descriptor
pointing to a buffer containing the output string.
width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum width of the formatted ACE resulting when $FORMAT_ACL
completes its execution. The width argument is the address of
a word containing the maximum width of the formatted ACE. If
this argument is omitted or contains the value 0, an infinite
length display line is assumed. When the width is exceeded, the
character specified by trmdsc is inserted.
trmdsc
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Line termination characters used in the formatted ACE. The trmdsc
argument is the address of a descriptor pointing to a character
string containing the termination characters that are inserted
for each formatted ACE when the width has been exceeded.
indent
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of blank characters beginning each line of the formatted
ACE. The indent argument is the address of a word containing
the number of blank characters that you want inserted at the
beginning of each formatted ACE.
accnam
OpenVMS usage:access_bit_names
type: longword (unsigned)
access: read only
mechanism: by reference
Names of the bits in the access mask when executing the $FORMAT_
ACL. The accnam argument is the address of an array of 32
quadword descriptors that define the names of the bits in the
access mask. Each element points to the name of a bit. The first
element names bit 0, the second element names bit 1, and so on.
You can call LIB$GET_ACCNAM to retrieve the access name table for
the class of object whose ACL is to be formatted.
If you omit accnam, the following names are used:
Bit Name
Bit 0 READ
Bit 1 WRITE
Bit 2 EXECUTE
Bit 3 DELETE
Bit 4 CONTROL
Bit 5 BIT_5
Bit 6 BIT_6
.
.
.
Bit BIT_31
31
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
Converts a security auditing event message from binary format to
ASCII text.
Format
SYS$FORMAT_AUDIT fmttyp ,audmsg ,[outlen] ,outbuf ,[width]
,[trmdsc] ,[routin] ,[fmtflg]
C Prototype
int sys$format_audit (unsigned int fmttyp, void *audmsg,
unsigned short int *outlen, void *outbuf,
unsigned short int *width, void *trmdsc,
int (*routin)(__unknown_params), unsigned
int fmtflg);
108.1 - Arguments
fmttyp
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Format for the message. The fmttyp argument is a value indicating
whether the security audit message should be in brief format,
which is one line of information, or full format. The default
is full format. Refer to the OpenVMS System Manager's Manual for
examples of formatted output.
The following table defines the brief and full formats:
Value Meaning
NSA$C_FORMAT_STYLE_ Use a brief format for the message.
BRIEF
NSA$C_FORMAT_STYLE_ Use a full format for the message.
FULL
audmsg
OpenVMS usage:char_string
type: byte stream (unsigned)
access: read only
mechanism: by reference
Security auditing message to format. The audmsg argument is
the address of a buffer containing the message that requires
formatting.
outlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the formatted security audit message. The outlen
argument is the address of the word receiving the final length
of the ASCII message.
outbuf
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Buffer holding the formatted message. The outbuf argument is
the address of a descriptor pointing to the buffer receiving the
message.
width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum width of the formatted message. The width argument is the
address of a word containing the line width value. The default is
80 columns.
The width argument does not work consistently. In most cases, if
you specify both the width argument and the full format style
(NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores the width
argument. The minimum width is 80 columns; lower values do not
limit the width to less than 80. If you specify a width greater
than 80 columns, most lines are not joined to use the full width.
In most cases, you should avoid using the width argument.
trmdsc
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Line termination characters used in a full format message. The
trmdsc argument is the address of a descriptor pointing to the
line termination characters to insert within a line segment
whenever the width is reached.
routin
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Routine that writes a formatted line to the output buffer. The
routin argument is the address of a routine called each time a
line segment is formatted. The argument passed to the routine
is the address of a character string descriptor for the line
segment.
When an application wants event messages in the brief format,
$FORMAT_AUDIT calls the routine twice to format the first event
message. The first time it is called, the routine passes a string
containing the column titles for the message. The second and
subsequent calls to the routine pass the formatted event message.
By using this routine argument, a caller can gain control at
various points in the processing of an audit event message.
fmtflg
OpenVMS usage:longword (unsigned)
type: mask_longword
access: read only
mechanism: by value
Determines the formatting of certain kinds of audit messages.
The fmtflg argument is a mask specifying whether sensitive
information should be displayed or column titles built for
messages in brief format. For example, the operating system
uses bit 0 to suppress plain-text passwords from security alarm
messages.
The following table describes the significant bits:
Bit Value Description
0 1 Do not format sensitive information.
0 Format sensitive information.
1 1 Build a column title for messages in brief format.
(You must specify a fmttyp of brief and a routin
argument.)
0 Do not build column titles.
|
109 - $FREE USER CAPABILITY (Alpha Only)
|
On Alpha systems, releases a user capability, indicating to other
processes that the resource is now available.
This service accepts 64-bit addresses.
Format
SYS$FREE_USER_CAPABILITY cap_num [,prev_num] [,flags]
C Prototype
int sys$free_user_capability (int *cap_num, struct _generic_64
*prev_mask, struct _generic_64
*flags);
109.1 - Arguments
cap_num
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Capability number to be released by the calling Kernel thread.
This number can range from 1 to 16. The cap_num argument is
the 32- or 64-bit address of the longword containing the user
capability number.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The previous user capability reservation mask before execution
of this service call. The prev_mask argument is the 32- or 64-bit
address of a quadword into which the service writes a quadword
bit mask specifying the previously reserved user capabilities.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for the user capability reservation. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option.
Each option (bit) has a symbolic name, which the $CAPDEF macro
defines. The flags argument is constructed by performing a
logical OR operation using the symbolic names of each desired
option.
At this time, all bits are reserved to Compaq and must be 0.
Returns information related to the primary and secondary device
characteristics of an I/O device.
For synchronous completion, use the Get Device/Volume Information
and Wait ($GETDVIW) service. The $GETDVIW service is identical to
the $GETDVI service in every way except that $GETDVIW returns to
the caller with the requested information.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service.
Format
SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
C Prototype
int sys$getdvi (unsigned int efn, unsigned short int chan,
void *devnam, void *itmlst, struct _iosb *iosb,
void (*astadr)(__unknown_params), int astprm,
struct _generic_64 *nullarg);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETDVI returns the
requested information. The efn argument is a longword containing
this number; however, $GETDVI uses only the low-order byte.
Upon request initiation, $GETDVI clears the specified event flag
(or event flag 0 if efn was not specified). Then, when $GETDVI
returns the requested information, it sets the specified event
flag (or event flag 0).
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word containing
this number.
To identify a device to $GETDVI, you can specify either the
chan or devnam argument, but you should not specify both. If
you specify both arguments, the chan argument is used.
If you specify neither chan nor devnam, $GETDVI uses a default
value of 0 for chan.
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
The name of the device about which $GETDVI is to return
information. The devnam argument is the address of a character
string descriptor pointing to this name string.
The device name string can be either a physical device name
or a logical name. If the first character in the string is an
underscore (_), the string is considered a physical device name;
otherwise, the string is considered a logical name and logical
name translation is performed until either a physical device name
is found or the system default number of translations has been
performed.
If the device name string contains a colon (:), the colon and
the characters that follow it are ignored.
To identify a device to $GETDVI, you can specify either the chan
or devnam argument, but you should not specify both. If both
arguments are specified, the chan argument is used.
If you specify neither chan nor devnam, $GETDVI uses a default
value of 0 for chan.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb argument is the address of the quadword I/O status
block.
When you specify the iosb argument, $GETDVI 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 to Compaq.
Though this argument is optional, Compaq 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 $GETDVI 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 $GETDVI, 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 reference
AST service routine to be executed when $GETDVI completes. The
astadr argument is the address of this routine.
If you specify astadr, the AST routine executes at the same
access mode as the caller of the $GETDVI 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.
nullarg
OpenVMS usage:null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
Placeholding argument reserved to Compaq.
Returns information about an I/O device; this information
consists of primary and secondary device characteristics.
The $GETDVIW service completes synchronously; that is, it returns
to the caller with the requested information. Compaq recommends
that you use an IOSB with this service. An IOSB prevents the
service from completing prematurely. In addition, the IOSB
contains additional status information.
For asynchronous completion, use the Get Device/Volume
Information ($GETDVI) service; $GETDVI returns to the caller
after queuing the information request, without waiting for the
information to be returned. In all other respects, $GETDVIW
is identical to $GETDVI. For all other information about the
$GETDVIW service, refer to the description of $GETDVI.
Format
SYS$GETDVIW [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
C Prototype
int sys$getdviw (unsigned int efn, unsigned short int chan,
void *devnam, void *itmlst, struct _iosb
*iosb, void (*astadr)(__unknown_params), int
astprm, unsigned __int64 *nullarg);
|
112 - $GETENV (Alpha Only)
|
Returns the value(s) of the specified console environment
variable(s).
Format
SYS$GETENV itmlst
C Prototype
int sys$getenv (void *itmlst);
112.1 - Arguments
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
The itmlst argument is the address of a list of item descriptors,
each of which describes an item of information. The list of item
descriptors is terminated by a longword of 0.
The service takes one argument as input, an item list. This item
list has the following format for a single item descriptor:
63 31 0
+-------------------------------------+
| Buffer length | Item code | STENVDEF$L_ITEM_CODE/STENVDEF$L_BUF_LEN
+-------------------------------------+
| Buffer address | STENVDEF$Q_BUF_ADDR
+-------------------------------------+
| Return length address | STENVDEF$Q_RET_ADDR
+-------------------------------------+
The following table defines the item descriptor fields:
Descriptor
Field Definition
Item code A longword indicating which environment variable
you want to retrieve. These codes are defined in
$STENVDEF.
Buffer A longword specifying the length of the buffer
length in which GETENV is to write the environment
variable's value.
Buffer A quadword indicating the address of the buffer
address in which GETENV is to write the environment
variable's value.
Return A quadword indicating the return address in
length which to put the length of the value that GETENV
address retrieved.
Returns information about one or more processes on the system or
across the OpenVMS Cluster system.
The $GETJPI service completes asynchronously. For synchronous
completion, use the Get Job/Process Information and Wait
($GETJPIW) service.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$GETJPI [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr]
,[astprm]
C Prototype
int sys$getjpi (unsigned int efn, unsigned int *pidadr, void
*prcnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), unsigned __int64
astprm);
Arguments
efn
OpenVMS usage:ef_number
type: quadword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETJPI returns the
requested information. The efn argument is a quadword containing
this number; however, $GETJPI uses only the low-order byte.
Upon request initiation, $GETJPI clears the specified event flag
(or event flag 0 if efn was not specified). Then, when $GETJPI
returns the requested information, it sets the specified event
flag (or event flag 0).
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Process identification (PID) of the process about which $GETJPI
is to return information. The pidadr argument is the 32-bit
address (on VAX systems) or the 32- or 64-bit address (on Alpha
systems) of a longword containing the PID. The pidadr argument
can refer to a process running on the local node or a process
running on another node in the cluster.
If you give pidadr the value -1, $GETJPI assumes a wildcard
operation and returns the requested information for each process
on the system that it has the privilege to access, one process
per call. To perform a wildcard operation, you must call $GETJPI
in a loop, testing for the condition value SS$_NOMOREPROC after
each call and exiting from the loop when SS$_NOMOREPROC is
returned.
If you use $GETJPI with $PROCESS_SCAN, you can perform wildcard
searches across the cluster. In addition, with $PROCESS_SCAN
you can search for specific processes based on many different
selection criteria.
You cannot abbreviate a PID. All significant digits of a PID must
be specified; only leading zeros can be omitted.
prcnam
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 process about which $GETJPI is to return information.
The prcnam 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.
A process running on the local node can be identified with a 1-
to 15-character string. To identify a process on a cluster, you
must specify the full process name, which includes the node name
as well as the process name. The full process name can contain up
to 23 characters.
A local process name can look like a remote process name;
therefore, if you specify ATHENS::SMITH, the system checks for
a process named ATHENS::SMITH on the local node before checking
node ATHENS for a process named SMITH.
You can use the prcnam argument only if the process identified
by prcnam has the same UIC group number as the calling process.
If the process has a different group number, $GETJPI returns
no information. To obtain information about processes in other
groups, you must use the pidadr 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 (Alpha)
mechanism: by 32-bit reference (VAX)
Item list specifying which information about the process or
processes is to be returned. 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.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
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 that is 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, $GETJPI 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:
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 $GETJPI 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 $GETJPI, 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 $GETJPI 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 $GETJPI 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.
Returns information about one or more processes on the system.
The $GETJPIW service completes synchronously; that is, it returns
to the caller with the requested information. Compaq recommends
that you use an IOSB with this service. An IOSB prevents the
service from completing prematurely. In addition, the IOSB
contains status information.
For asynchronous completion, use the Get Job/Process Information
($GETJPI) service; $GETJPI returns to the caller after queuing
the information request, without waiting for the information to
be returned.
In all other respects, $GETJPIW is identical to $GETJPI. For
all other information about the $GETJPIW service, refer to the
description of $GETJPI in this manual.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$GETJPIW [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb]
,[astadr] ,[astprm]
C Prototype
int sys$getjpiw (unsigned int efn, unsigned int *pidadr, void
*prcnam, void *itmlst, struct _iosb *iosb,
void (*astadr)(__unknown_params), int astprm);
Returns information about the lock database on a system.
The $GETLKI service completes asynchronously; for synchronous
completion, use the Get Lock Information and Wait ($GETLKIW)
service.
The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together
provide the user interface to the Lock Management facility.
Format
SYS$GETLKI [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]
[,nullarg]
C Prototype
int sys$getlki (unsigned int efn, unsigned int *lkidadr,
void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm,
unsigned int reserved);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETLKI completes. The
efn argument is a longword containing this number; however,
$GETLKI uses only the low-order byte. If you do not specify efn,
$GETLKI sets event flag 0.
lkidadr
OpenVMS usage:lock_id
type: longword (unsigned)
access: modify
mechanism: by reference
Lock identification (lock ID) for the lock about which
information is to be returned. The lock ID is the second longword
in the lock status block, which was created when the lock was
granted. The lkidadr argument is the address of this longword.
If the value specified by lkidadr is 0 or -1, $GETLKI assumes
a wildcard operation and returns information about each lock to
which the calling process has access, one lock per call.
To use the $GETLKI service, you must have read/write access to
the lock ID.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying the lock information that $GETLKI is to
return. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb argument is the address of a quadword.
When $GETLKI is called, it sets the I/O status block to 0. When
$GETLKI completes, it writes a condition value to the first
longword in the quadword. The remaining two words in the quadword
are unused.
Although this argument is optional, Compaq 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 $GETLKI 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 $GETLKI, 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 reference
AST service routine to be executed when the service completes.
The astadr argument is the address of this routine.
If you specify this argument, the AST routine executes at the
same access mode as the caller of the $GETLKI 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.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Compaq.
Returns information about the lock database on a system.
The $GETLKIW service completes synchronously; that is, it returns
to the caller with the requested information.
For asynchronous completion, use the Get Lock Information
($GETLKI) service; $GETLKI returns to the caller after queuing
the information request, without waiting for the information to
be returned.
In all other respects, $GETLKIW is identical to $GETLKI. For
all other information about the $GETLKIW service, refer to the
description of $GETLKI in this manual.
The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together
provide the user interface to the Lock Management facility.
Format
SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]
[,nullarg]
C Prototype
int sys$getlkiw (unsigned int efn, unsigned int *lkidadr,
void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm,
unsigned int reserved);
Returns message text associated with a given message
identification code into the caller's buffer. The message can
be from the system message file or a user-defined message.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]
C Prototype
int sys$getmsg (unsigned int msgid, unsigned short int
*msglen, void *bufadr, unsigned int flags,
unsigned char outadr [4]);
117.1 - Arguments
msgid
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Identification of the message to be retrieved. The msgid argument
is a longword value containing the message identification. Each
message has a unique identification, contained in bits 3 through
27 of system longword condition values.
msglen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Length of the message string returned by $GETMSG. The msglen
argument is the 32- or 64-bit address (on Alpha systems) or the
32-bit address (on VAX systems) of a word into which $GETMSG
writes this length.
bufadr
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor-fixed-length string descriptor
(VAX)
Buffer to receive the message string. The bufadr argument is the
32- or 64-bit address (on Alpha systems) or the 32-bit address
(on VAX systems) of a character string descriptor pointing to the
buffer into which $GETMSG writes the message string. The maximum
size of any message string is 256 bytes.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Message components to be returned. The flags argument is a
longword bit vector wherein a bit, when set, specifies that the
message component is to be returned.
The following table describes the significant bits:
Bit Value Description
0 1 Include text of message
0 Do not include text of message
1 1 Include message identifier
0 Do not include message identifier
2 1 Include severity indicator
0 Do not include severity indicator
3 1 Include facility name
0 Do not include facility name
If you omit this argument in a VAX MACRO or BLISS-32 service
call, it defaults to a value of 15; that is, all flags are set
and all components of the message are returned. If you omit this
argument in a Fortran service call, it defaults to a value of 0;
the value 0 causes $GETMSG to use the process default flags.
outadr
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Optional information to be returned by $GETMSG. The outadr
argument is the 32- or 64-bit address (on Alpha systems) or the
32-bit address (on VAX systems) of a 4-byte array into which
$GETMSG writes the following information:
Byte Contents
0 Reserved
1 Count of FAO arguments associated with message
2 User-specified value in message, if any
3 Reserved
Returns information about queues and the jobs initiated from
those queues.
The $GETQUI service completes asynchronously; for synchronous
completion, use the Get Queue Information and Wait ($GETQUIW)
service.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service.
Format
SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr]
[,astprm]
C Prototype
int sys$getqui (unsigned int efn, unsigned short int func,
unsigned int *context, void *itmlst, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETQUI completes. The
efn argument is a longword containing this number; however,
$GETQUI uses only the low-order byte. The efn argument is
optional.
When the request is queued, $GETQUI clears the specified event
flag (or event flag 0 if efn was not specified). Then, when the
operation completes, $GETQUI sets the specified event flag (or
event flag 0).
func
OpenVMS usage:function_code
type: word (unsigned)
access: read only
mechanism: by value
Function code specifying the function that $GETQUI is to perform.
The func argument is a word containing this function code. The
$QUIDEF macro defines the names of each function code.
You can specify only one function code in a single call to
$GETQUI. Most function codes require or allow for additional
information to be passed in the call. You pass this information
by using the itmlst argument, which specifies a list of one or
more item descriptors. Each item descriptor in turn specifies an
item code, which either describes the specific information to be
returned by $GETQUI, or otherwise affects the action designated
by the function code.
You can use wildcard mode to make a sequence of calls to $GETQUI
to get information about all characteristics, form definitions,
queues, or jobs contained in the system job queue file.
Refer to the OpenVMS System Services Reference Manual for
information on using wildcard mode.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Address of a longword containing the number of a context stream
for this call to the $GETQUI system service. If the argument is
unspecified or 0, the service uses the default context stream
(#0).
To generate a new context stream, the specified longword must
contain -1. $GETQUI then modifies the longword to hold the
context number for that stream of operation. The context is
marked with the caller's mode (user, supervisor, executive, or
kernel). Any attempt to use that context in successive calls
is checked and no call from a mode outside the recorded mode is
allowed access.
To clean up a context, make a $GETQUI call using the QUI$_CANCEL_
OPERATION function code and specify the address of the context
number as the context argument.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list supplying information to be used in performing the
function specified by the func argument. The itmlst argument is
the address of the item list. The item list consists of one or
more item descriptors, each of which contains an item code. The
item list is terminated by an item code of 0 or by a longword of
0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block into which $GETQUI writes the completion status
after the requested operation has completed. The iosb argument is
the address of the I/O status block.
At request initiation, $GETQUI sets the value of the quadword I/O
status block to 0. When the requested operation has completed,
$GETQUI writes a condition value in the first longword of the
I/O status block. It writes the value 0 into the second longword;
this longword is unused and reserved for future use.
The condition values returned by $GETQUI in the I/O status block
are condition values from the JBC facility, which are defined by
the $JBCMSGDEF macro. The condition values returned from the JBC
facility are listed in the section Condition Values Returned in
the I/O Status Block section.
Though this argument is optional, Compaq 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 $GETQUI 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 $GETQUI, 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 reference
AST service routine to be executed when $GETQUI completes. The
astadr argument is the address of this routine.
If specified, the AST routine executes at the same access mode as
the caller of $GETQUI.
astprm
OpenVMS usage:user_parm
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 this longword
parameter.
Returns information about queues and jobs initiated from those
queues. The $SNDJBC service is the major interface to the Job
Controller, which is the queue and accounting manager.
The $GETQUIW service completes synchronously; that is, it returns
to the caller with the requested information. For asynchronous
completion, use the Get Queue Information ($GETQUI) service;
$GETQUI returns to the caller after queuing the information
request, without waiting for the information to be returned.
In all other respects, $GETQUIW is identical to $GETQUI.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service.
Format
SYS$GETQUIW [efn] ,func [,context] [,itmlst] [,iosb] [,astadr]
[,astprm]
C Prototype
int sys$getquiw (unsigned int efn, unsigned short int func,
unsigned int *context, void *itmlst, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm);
Returns system performance information about the local system.
Format
SYS$GETRMI [efn] [,nullarg] [,nullarg] ,itmlst [,iosb]
[,astadr] [,astprm]
C Prototype
int sys$getrmi (unsigned int efn, unsigned int nullarg,
unsigned int nullarg, void *itmlst, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm);
120.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of event flag to be set when the $GETRMI request
completes. The efn argument is a longword containing this number;
however, $GETRMI uses only the low order byte.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information is to be returned about
the local node. The itmlst argument is the address of a list of
item descriptors, each of which describes an item of information.
The list of descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block to receive the final completion status. The iosb
argument is the address of the quadword I/O status block.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $GETRMI completes. The
astadr argument is the address of this routine.
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.
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.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
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:
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 (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.
Returns information about the local system or about other systems
in a cluster.
The $GETSYIW service completes synchronously; that is, it returns
to the caller with the requested information. For asynchronous
completion, use the Get Systemwide Information ($GETSYI) service;
$GETSYI returns to the caller after queuing the information
request, without waiting for the information to be returned.
In all other respects, these services are identical; refer to the
documentation about $GETSYI for information about the $GETSYIW
service.
Format
SYS$GETSYIW [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb]
[,astadr] [,astprm]
C Prototype
int sys$getsyiw (unsigned int efn, unsigned int *csidadr, void
*nodename, void *itmlst, struct _iosb *iosb,
void (*astadr)(__unknown_params), int astprm);
You must specify either the csidadr or the nodename argument,
but not both. For wildcard operations, however, you must use the
csidadr argument.
Returns the current system time in a 64-bit format.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$GETTIM timadr
C Prototype
int sys$gettim (struct _generic_64 *timadr);
123.1 - Argument
timadr
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of a quadword to receive the current
time in 64-bit format.
Returns authorization information about a specified user.
Format
SYS$GETUAI [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg]
,[nullarg] ,[nullarg]
C Prototype
int sys$getuai (unsigned int efn, unsigned int *contxt, void
*usrnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm);
124.1 - Arguments
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the user about whom $GETUAI returns authorization
information. The usrnam argument is the address of a descriptor
pointing to a character text string containing the user name.
The user name string can contain a maximum of 12 alphanumeric
characters.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information from the specified user's
user authorization file (UAF) record is to be returned. The
itmlst argument is the address of a list of one or more item
descriptors, each of which specifies an item code. The item list
is terminated by an item code value of 0 or by a longword value
of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:longword
type: longword (unsigned)
access: modify
mechanism: by reference
On VAX systems, an optional longword used to maintain an open
channel to the authorization file. The contxt argument is the
address of a longword to receive a $GETUAI context value. If the
contxt argument is specified on the initial call, this longword
should contain the value -1, and on subsequent calls, the value
of the contxt argument from the previous call should be passed
back in.
Returns the current time in 128-bit UTC format.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$GETUTC utcadr
C Prototype
int sys$getutc (unsigned int *utcadr [4]);
125.1 - Arguments
utcadr
OpenVMS usage:coordinated universal time
type: utc_date_time
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 128-bit time value to be returned.
|
126 - $GET ALIGN FAULT DATA (Alpha Only)
|
On Alpha systems, obtains data from the user image alignment
fault buffer if buffered user alignment fault data reporting has
been enabled.
This service accepts 64-bit addresses.
Format
SYS$GET_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size
C Prototype
int sys$get_align_fault_data (void *buffer, int buffer_size,
int *return_size);
126.1 - 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.
|
127 - $GET ARITH EXCEPTION (Alpha Only)
|
On Alpha systems, returns information about the exception context
for a given arithmetic exception.
Format
SYS$GET_ARITH_EXCEPTION sigarg ,mcharg ,buffer
C Prototype
int sys$get_arith_exception (void *sigarg, void *mcharg, void
*buffer);
127.1 - 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.
|
128 - $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 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.
|
129 - $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 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);
129.1 - 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.
|
130 - $GET REGION INFO (Alpha Only)
|
On Alpha systems, gets information about a specified virtual
region.
This service accepts 64-bit addresses.
Format
SYS$GET_REGION_INFO function_code ,region_id_64 ,start_va_64
,nullarg ,buffer_length ,buffer_address_64
,return_length_64
C Prototype
int sys$get_region_info (unsigned int function_code, struct
_generic_64 *region_id_64, void
*start_va_64, void *reserved,
unsigned int buffer_length, void
*buffer_address_64, unsigned int
*return_length_64);
130.1 - 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_ Return the region summary information for
BY_VA 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 Compaq.
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.
The following table shows the format of the Region Summary
Buffer:
Table SYS-3 Region Summary Buffer Format
Field
Size Field Offset
Field name Meaning (Bytes) (Decimal)
VA$L_FLAGS Flags used when 4 8
region was created
VA$L_REGION_ Create and owner 4 12
PROTECT mode of region
VA$Q_REGION_ID Region identifier 8 0
VA$PQ_START_VA Starting (lowest) 8 16
virtual address of
region
VA$Q_REGION_SIZE Total length of 8 24
region
VA$PQ_FIRST_FREE_ First free virtual 8 32
VA address in region
VA$C_REGSUM_LENGTH Length of Region constant 40
Summary Buffer
The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF MACRO in
STARLET.MLB define the REGSUM structure.
return_length_64
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned longword
into which the service returns the length of the information in
bytes.
Retrieves the security characteristics of an object.
Format
SYS$GET_SECURITY [clsnam] ,[objnam] ,[objhan] ,[flags]
,[itmlst] ,[contxt] ,[acmode]
C Prototype
int sys$get_security ( void *clsnam, void *objnam, unsigned
int *objhan, unsigned int flags, void
*itmlst, unsigned int *contxt, unsigned
int *acmode);
131.1 - Arguments
clsnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the object class. The clsnam argument is the address of a
descriptor pointing to a string containing the name of the object
class.
The following is a list of protected object class names:
CAPABILITY
COMMON_EVENT_CLUSTER
DEVICE
FILE
GLXSYS_GLOBAL_SECTION
GLXGRP_GLOBAL_SECTION
GROUP_GLOBAL_SECTION
ICC_ASSOCIATION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME
objnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the protected object whose associated security profile
is going to be retrieved. The objnam argument is the address
of a descriptor pointing to a string containing the name of the
protected object.
The format of an object name is class specific. The following
table lists object names and describes their formats:
Object Class Object Name Format
CAPABILITY A character string. Currently, the only
capability object is VECTOR.
COMMON_EVENT_ Name of the event flag cluster, as defined
CLUSTER in the Associate Common Event Flag Cluster
($ASCEFC) system service.
DEVICE Standard device specification, described in
the OpenVMS User's Manual.
FILE Standard file specification, described in the
OpenVMS User's Manual.
GROUP_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
ICC_ASSOCIATION ICC security object name node::association_
name. The special node name, ICC$::, refers
to entries in the clusterwide registry. For
registry entries, the Access Access Type does
not apply.
LOGICAL_NAME_TABLE Table name, as defined in the Create Logical
Name Table ($CRELNT) system service.
QUEUE Standard queue name, as described in the Send
to Job Controller ($SNDJBC) system service.
RESOURCE_DOMAIN An identifier or octal string enclosed in
brackets.
SECURITY_CLASS Any class name shown in column 1, or a
class name followed by a period (.) and
the template name. Use the DCL command SHOW
SECURITY to display possible template names.
SYSTEM_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
VOLUME Volume name or name of the device on which
the volume is mounted.
objhan
OpenVMS usage:object_handle
type: longword (unsigned)
access: read only
mechanism: by reference
Data structure identifying the object whose associated
characteristics are going to be retrieved. The objhan argument
is an address of a longword containing the object handle. You can
use the objhan argument as an alternative to the objnam argument;
for example, channel number clearly specifies the file open on
the channel and can serve as an object handle.
The following table shows the format of the object classes:
Object Class Object Handle Format
COMMON_EVENT_CLUSTER Event flag number
DEVICE Channel number
FILE Channel number
RESOURCE_DOMAIN Resource domain identifier
VOLUME Channel number
flags
OpenVMS usage:flags
type: mask_longword
access: read only
mechanism: by value
Mask specifying processing options. The flags argument is a
longword bit vector wherein a bit, when set, specifies the
processing option. The flags argument requires the contxt
argument.
The following table describes each flag:
Symbolic Name Description
OSS$M_RELCTX Release the context structure at the completion
of this request.
OSS$M_WLOCK Maintain a write lock on the security profile
at the completion of this request. $GET_SECURITY
ignores the flag if the context has already been
established.
These symbolic names are defined in the $OSSDEF macro. You
construct the flags argument by specifying the symbolic names
of each flag.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the process or
processes is to be returned. The itmlst argument is the address
of a list of item descriptors, each of which describes an item
of information. The list of item descriptors is terminated by a
longword of 0.
With the item list, the user retrieves the protected object's
characteristics. The user defines which security characteristics
to retrieve. If this argument is not present, only the flags
argument is processed. Without the itmlst argument, you can only
manipulate the security profile lock or release contxt resources.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Value used to maintain the processing context when dealing with
a single protected object across multiple $GET_SECURITY/$SET_
SECURITY calls. Whenever the context value is nonzero, the class
name, object name, or object handle arguments are disregarded.
An input value of 0 indicates that a new context should be
established.
Because an active context block consumes process memory, be sure
to release the context block by setting the RELCTX flag when the
profile processing is complete. $GET_SECURITY sets the context
argument to 0 once the context is released.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the object protection check. The acmode
argument is the address of a longword containing the access mode.
The acmode argument defaults to kernel mode; however, the system
compares acmode with the caller's access mode and uses the least
privileged mode. The access modes are defined in the system macro
$PSLDEF library. Compaq recommends that this argument be omitted
(passed as zero).
|
132 - $GET SYS ALIGN FAULT DATA (Alpha Only)
|
On Alpha systems, obtains data from the system alignment fault
buffer if buffered system alignment fault data reporting has been
enabled.
This service accepts 64-bit addresses.
Format
SYS$GET_SYS_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size
C Prototype
int sys$get_sys_align_fault_data (void *buffer, int
buffer_size, int
*return_size);
132.1 - Arguments
buffer
OpenVMS usage:address
type: longword (unsigned)
access: read/write
mechanism: by 32- or 64-bit reference
The user buffer in which the alignment fault data is to be
stored. The buffer argument is the 32- or 64-bit virtual address
of this buffer.
buffer_size
OpenVMS usage:byte count
type: longword (signed)
access: read
mechanism: by value
The size, in bytes, of the buffer specified by the buffer
argument.
return_size
OpenVMS usage:longword_signed
type: longword (signed)
access: write
mechanism: by 32- or 64-bit reference
The amount of data, in bytes, stored in the buffer. The return_
size argument is the 32- or 64-bit virtual address of a naturally
aligned longword into which the service returns the amount of
data, in bytes, stored in the buffer. The return_size argument is
set to 0 if there is no data in the buffer.
|
133 - $GET USER CAPABILITY (Alpha Only)
|
On Alpha systems, reserves a user capability, indicating to other
processes that the resource is in use.
This service accepts 64-bit addresses.
Format
SYS$GET_USER_CAPABILITY cap_num [,select_num] [,select_mask]
[,prev_mask] [,flags]
C Prototype
int sys$get_user_capability (*cap_num, int *select_num, struct
_generic_64 *select_mask, struct
_generic_64 *prev_mask, struct
_generic_64 *flags);
133.1 - Arguments
cap_num
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Capability number to be reserved by the calling kernel thread.
This number can range from 1 to 16 for an explicit request, or
the symbolic constant CAP$K_GET_FREE_CAP can be specified to
get the next available user capability. The cap_num argument is
the 32- or 64-bit address of the longword containing the user
capability number or symbolic constant.
select_num
OpenVMS usage:longword
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The number of the user capability selected by the service
call. The select_num argument is the 32- or 64-bit address of
a longword into which the system writes the user capability
number. For an explicit numeric request, the value returned in
this longword will match that specified in cap_num; otherwise,
this cell contains the next available user capability.
select_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
A quadword bit mask with a single bit position set, reflecting
the user capability selected by the service. The select_
mask argument is the 32- or 64-bit address of a quadword into
which the system writes the selected user capability bit mask.
This bit mask is the most efficient method for indicating the
reserved user capability with the $CPU_CAPABILITIES and $PROCESS_
CAPABILITIES services.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The previous user capability reservation mask before execution
of this service call. The prev_mask argument is the 32- or 64-bit
address of a quadword into which the service writes a quadword
bit mask specifying the previously reserved user capabilities
taken from the global cell SCH$GQ_RESERVED_USER_CAPS.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for the user capability reservation. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option.
Each option (bit) has a symbolic name, which the $CAPDEF macro
defines. The flags argument is constructed by performing a
logical OR operation using the symbolic names of each desired
option.
At this time, all bits are reserved to Compaq and must be 0.
|
134 - $GOTO UNWIND (Alpha Only)
|
On Alpha systems, unwinds the call stack.
Format
SYS$GOTO_UNWIND target_invo ,target_pc ,[new_r0] ,[new_r1]
C Prototype
int sys$goto_unwind (void *target_invo, void *(*(target_pc)),
unsigned __int64 *new_r0, unsigned
__int64 *new_r1);
134.1 - Arguments
target_invo
OpenVMS usage:invo_handle
type: longword (unsigned)
access: read only
mechanism: by reference
The address of a location that contains a handle for the target
invocation.
If you do not specify the target_invo argument, or if the handle
value is 0, an exit unwind is initiated.
target_pc
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
The address of a location that contains the address at which
execution should continue in the target invocation.
If the target_pc argument is omitted or the value is 0, a system-
defined target PC is assumed and execution resumes at the
location specified at the return address for the call frame of
the target procedure invocation.
new_r0
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
The address of a location that contains the value to place in the
saved R0 location of the mechanism argument vector. The contents
of this location are then loaded into the processor R0 register
at the time that execution continues in the target invocation.
If the new_r0 argument is omitted, the contents of the processor
R0 register at the time of the call to $GOTO_UNWIND are used.
new_r1
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a location that contains the value to place in the
saved R1 location of the mechanism argument vector. The contents
of the location are then loaded into the processor R1 register at
the time that execution continues in the target invocation.
If the new_r1 argument is omitted, the contents of the processor
R1 register at the time of the call to $GOTO_UNWIND are used.
Adds the specified identifier record to the rights list of the
process or the system.
Format
SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]
C Prototype
int sys$grantid (unsigned int *pidadr, void *prcnam, struct
_generic_64 *id, void *name, unsigned int
*prvatr, unsigned int segment);
135.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) number of the process affected when
$GRANTID completes execution. The pidadr argument is the address
of a longword containing the PID of the process to be affected.
You use -1 to indicate the system rights list. When pidadr is
passed, it is also returned; therefore, you must pass it as a
variable rather than a constant. If you specify neither pidadr
nor prcnam, your own process is used.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name on which $GRANTID operates. The prcnam argument
is the address of a character string descriptor containing the
process name. The maximum length of the name is 15 characters.
Because the UIC group number is interpreted as part of the
process name, you must use pidadr to specify the rights list
of a process in a different group. If you specify neither pidadr
nor prcnam, your own process is used.
id
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: modify
mechanism: by reference
Identifier and attributes to be granted when $GRANTID completes
execution. The id argument is the address of a quadword
containing the binary identifier code to be granted in the first
longword and the attributes in the second longword.
Use the id argument to modify the attributes of the identifier.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the macro library ($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
database using the DCL command SET RIGHTS_
LIST.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
You must specify either id or name. Because the id argument is
returned as well as passed if you specify name, you must pass it
as a variable rather than a constant in this case.
name
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the identifier granted when $GRANTID completes execution.
The name argument is the address of a descriptor pointing to
the name of the identifier. The identifier is granted as it is
created. You must specify either id or name.
prvatr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous attributes of the identifier. The prvatr argument is
the address of a longword used to store the attributes of the
identifier if it was previously present in the rights list. If
you added rather than modified the identifier, prvatr is ignored.
Applies the hash algorithm you select to an ASCII password string
and returns a quadword hash value that represents the encrypted
password.
Format
SYS$HASH_PASSWORD pwd ,alg ,[salt] ,usrnam ,hash
C Prototype
int sys$hash_password (void *pwd, unsigned char alg, unsigned
short int salt, void *usrnam, struct
_generic_64 *hash);
136.1 - Arguments
pwd
OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
ASCII password string to be encrypted. The pwd argument is the
address of a character string descriptor pointing to the ASCII
password. The password string can contain between 1 and 32
characters and use the uppercase characters A through Z, the
numbers 0 through 9, the dollar sign ($), and the underscore
(_).
The caller must validate the password string before calling
$HASH_PASSWORD to ensure that only permitted characters are
included.
alg
OpenVMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value
Algorithm used to hash the ASCII password string. The alg
argument is an unsigned byte specifying the hash algorithm.
Refer to the OpenVMS System Services Reference Manual to view the
table of recognized algorithms.
Values ranging from 128 to 255 are reserved for customer use; the
constant UAI$K_CUST_ALGORITHM defines the start of this range.
You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with
the $GETUAI system service to retrieve the primary and secondary
password hash algorithms for a user.
salt
OpenVMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Value used to increase the effectiveness of the hash. The salt
argument is an unsigned word containing 16 bits of data that is
used by the hash algorithms when encrypting a password for the
associated user name. The $GETUAI item code UAI$_SALT is used to
retrieve the SALT value for a given user. If you do not specify a
SALT value, $HASH_PASSWORD uses the value of 0.
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the user associated with the password. The usrnam
argument is the address of a descriptor pointing to a character
text string containing the user name. The current password
encryption algorithm (UAI$C_PURDY_S) folds the user name into
the ASCII password string to ensure that different users with the
same password produce different hash values. This argument must
be supplied for all calls to $HASH_PASSWORD but is ignored when
using the CRC algorithm (UAI$C_AD_II).
hash
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Output hash value representing the encrypted password. The hash
argument is the address of an unsigned quadword to which $HASH_
PASSWORD writes the output of the hash. If you use the UAI$C_AD_
II algorithm, the second longword of the hash is always set to 0.
Allows a process to make itself inactive but to remain known to
the system so that it can be interrupted; for example, to receive
ASTs.
Format
SYS$HIBER
C Prototype
int sys$hiber (void);
137.1 - Arguments
None.
Responds to an incoming connection request. This call is used to
complete an ICC connection from the server side.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_ACCEPT conn_handle ,[accept_buf] ,[accept_len]
,[user_context] ,[flags]
C Prototype:
int sys$icc_accept (unsigned int conn_handle, char *
accept_buf, unsigned int accept_len,
unsigned int user_context, unsigned int
flags);
138.1 - Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the requested connection.
accept_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
A buffer of up to 1000 bytes of accept data that is sent to the
source of the connection at the completion of the connection
process.
accept_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The actual number of bytes in accept_buf to be sent.
user_context
OpenVMS usage:user_arg
type: longword (unsigned) (VAX), quadword (Alpha)
access: read only
mechanism: by value
A user-specified value that is subsequently returned on any
disconnect or data events on this connection.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
ICC$M_SYNCH_MODE can be specified to indicate that the data
transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE,
and $ICC_REPLY are allowed to return the status SS$_SYNCH in
the case of synchronous completion, and that the AST will not be
called.
Closes the application's association with ICC.
Format
SYS$ICC_CLOSE_ASSOC assoc_handle
C Prototype:
int sys$icc_close_assoc (unsigned int assoc_handle);
139.1 - Arguments
assoc_handle
OpenVMS usage:association_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the association to be closed.
Establishes a connection to a remote application over an open
association.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_CONNECT ios_icc ,[astadr] ,[astprm] ,assoc_handle
,conn_handle ,remote_assoc ,[remote_node]
,[user_context] ,[conn_buf] ,[conn_buf_len]
,[return_buf] ,[return_buf_len] ,[retlen_addr]
,[flags]
C Prototype:
int sys$icc_connect (struct _ios_icc *ios_icc, void
(*astadr)(__unknown_params), __int64
astprm, unsigned int assoc_handle,
unsigned int *conn_handle, void
*remote_assoc, void *remote_node, unsigned
int user_context, char *conn_buf, unsigned
int conn_buf_len, char *return_buf,
unsigned int return_buf_len, unsigned int
*retlen_addr, unsigned int flags);
Arguments
ios_icc
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
-------------------------------------------------
| Undefined | Completion status |
-------------------------------------------------
| ios_icc$l_remstat |
-------------------------------------------------
+6 +4
Completion status values:
SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM,
SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM,
SS$_NOSUCHID, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT,
SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE
The second longword is undefined unless the completion code
is SS$_REJECT. In this case, the application-defined rejection
reason code is supplied by the server when $ICC_REJECT is called.
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha), longword (unsigned)
(VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
The parameter to be passed to the AST routine.
assoc_handle
OpenVMS usage:association_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the association on which the connection is to be
opened. The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates
that the default association is to be used (and opened if
necessary).
conn_handle
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of a longword into which $ICC_CONNECT
writes the connection handle of the created connection on a
successful call.
remote_assoc
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
An ASCII character string (31 characters maximum) specifying the
name of the target application to connect to. Association names
are case sensitive.
remote_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
The name of the node where the target association resides. A
null or blank string can be used to indicate the local node.
If omitted (by passing zero by value), the simple clusterwide
association registry is to be used. Each node name is a one-to-
six character SCS node name. A comma-delimited list of nodes may
be specified, indicating that one is to be chosen at random.
user_context
OpenVMS usage:user_arg
type: longword (unsigned) (VAX), quadword (Alpha)
access: read only
mechanism: by value
A user-specified value to be subsequently returned on any
disconnect or data events on this connection.
conn_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
A buffer of up to 1000 bytes of connection data to be sent to the
target of the connection during the connection process.
conn_buf_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes in conn_buf to be sent.
return_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
A buffer of up to 1000 bytes in length to receive any incoming
connection accept or reject data returned.
return_buf_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the supplied return_buf.
retlen_addr
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of a longword into which $ICC_CONNECT
writes the actual length (in bytes) of any user accept or reject
data returned in the buffer return_buf.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
ICC$M_SYNCH_MODE can be specified to indicate that the data
transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE,
and $ICC_REPLY are allowed to return the status SS$_SYNCH in the
case of synchronous completion, indicating that the AST will not
be called.
Establishes a link between two ICC associations.
The $ICC_CONNECTW service completes synchronously; that is, it
returns to the caller after the server has either accepted or
rejected the connection request.
For asynchronous completion, use the $ICC_CONNECT service; $ICC_
CONNECT returns to the caller as soon as the connection request
has been sent to the server, without waiting for a response from
the server.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_CONNECTW ios_icc, [astadr], [astprm], assoc_handle,
conn_handle, remote_assoc, [remote_node],
[user_context], [conn_buf], [conn_buf_len],
[return_buf], [return_buf_len],
[retlen_addr], [flags]
C Prototype:
int sys$icc_connectw (struct _ios_icc *ios_icc, void
(*astadr)(__unknown_params), __int64
astprm, unsigned int assoc_handle,
unsigned int *conn_handle, void
*remote_assoc, void *remote_node,
unsigned int user_context, char
*conn_buf, unsigned int conn_buf_len,
char *return_buf, unsigned int
return_buf_len, unsigned int
*retlen_addr, unsigned int flags);
Terminates the specified connection.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_DISCONNECT conn_handle ,iosb ,[astadr] ,[astprm]
,[disc_buf] ,[disc_buf_len]
C Prototype:
int sys$icc_disconnect (unsigned int conn_handle,
struct _iosb, *iosb, void
(*astadr)(__unknown_params),
__int64 astprm, char * disc_buf,
unsigned int disc_buf_len);
Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The ID of the connection to be disconnected.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
-------------------------------------------------
| Undefined | Completion status |
-------------------------------------------------
| Unused | Unused |
-------------------------------------------------
+6 +4
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha), longword (unsigned)
(VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
The parameter to be passed to the AST routine.
disc_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
A buffer of up to 1000 bytes of disconnect data to be sent to the
partner in the connection when notifying it that disconnection is
being initiated. Delivery of this data is not guaranteed.
disc_buf_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes in disc_buf to be sent.
Terminates a link between two ICC associations.
The $ICC_DISCONNECTW service completes synchronously; that is,
it returns to the caller after the connection has completely
finished the disconnection request.
For asynchronous completion, use the $ICC_DISCONNECT service;
$ICC_DISCONNECT returns to the caller as soon as the
disconnection request has been sent to the transport layer,
without waiting for notification that the disconnection has
completed.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_DISCONNECTW conn_handle ,iosb ,[astadr] ,[astprm]
,[disc_buf] ,[disc_buf_len]
C Prototype:
int sys$icc_disconnectw (unsigned int conn_handle,
struct _iosb, *iosb, void
(*astadr)(__unknown_params), __int64
astprm, char * disc_buf, unsigned int
disc_buf_len);
Declares an application association with ICC.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_OPEN_ASSOC assoc_handle ,[assoc_name] ,[logical_name]
,[logical_table] ,[conn_event_rtn]
,[disc_event_rtn] ,[recv_rtn]
,[maxflowbufcnt] ,[prot]
C Prototype:
int sys$icc_open_assoc (unsigned int *assoc_handle, void
*assoc_name, void *logical_name,
void *logical_table, void
(*conn_event_rtn)(__unknown_params),
void
(*disc_event_rtn)(__unknown_params),
void (*recv_rtn)(__unknown_params),
unsigned int maxflowbufcnt, unsigned
int prot);
144.1 - Arguments
assoc_handle
OpenVMS usage:association_id
type: longword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of a longword into which $ICC_OPEN_ASSOC
writes the handle assigned to the opened association.
assoc_name
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
An ASCII character string of up to 31 characters in length
specifying the name of the application opening the association.
Null (0 length), and empty or blank association names are not
allowed. If this argument is omitted (that is, a zero is passed
in by value), it signifies that the user wants to open the
default association. This argument is case sensitive.
logical_name
OpenVMS usage:logical name
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
A logical name in a clusterwide logical name table used to
maintain the simple association registry. The logical name
represents the name of the service provided by the application.
Logical names are case sensitive.
logical_table
OpenVMS usage:logical name table
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit descriptor (Alpha)
mechanism: by 32-bit descriptor (VAX)
The table containing the logical name logical_name. Logical
name tables are converted to uppercase. Unless your application
requires an application-specific logical name table,
this argument should be either the default ICC Registry
search list (ICC$REGISTRY), or the default registry table
(ICC$REGISTRY_TABLE).
conn_event_rtn
OpenVMS usage:user_routine
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The address of the AST routine to be called for incoming connect
events. This routine will be called in the mode of the caller.
(No mechanism is provided for the routine to be called at a
different mode).
You must have a conn_event_rtn to operate as a server.
disc_event_rtn
OpenVMS usage:user_routine
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The address of the AST routine to be called for incoming
disconnect events. This routine will be called in the mode of the
caller. (No mechanism is provided for the routine to be called at
a different mode). The arguments, conn_event_rtn, and disc_event_
rtn, may reference the same routine.
recv_rtn
OpenVMS usage:user_routine
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The address of the AST routine to be called for incoming new data
events.
If the user provides this routine, it indicates that the
user will supply a buffer of the size required (specified in
an argument to the recv_rtn at each call) each time one is
requested. If the user supplies this routine, receive calls
should only be issued after receive events arrive and sufficient
buffer space has been allocated to handle the incoming data.
This routine will be called in the mode of the caller. (No
mechanism is provided for the routine to be called at a different
mode).
maxflowbufcnt
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The maximum number of pending inbound messages (per connection)
that ICC will allow the user before initiating flow control. A
message is pending if it is being held within ICC but no receive
call(s) are outstanding from the user.
Default = 5 (Pass 0 to get the default)
prot
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
This argument is ignored for non-server applications.
The default protection scheme for this association is as follows:
0 - access for everyone (default)
1 - stops WORLD access
2 - stops both WORLD and GROUP access
Advanced access control is provided by ICC Security objects.
Refer to the OpenVMS System Manager's Manual for information on
ICC system management and security.
Receives a single message over a connection.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_RECEIVE conn_handle ,ios_icc ,[astadr] ,[astprm]
,recv_buf ,recv_buf_len
C Prototype:
sys$icc_receive (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *recv_buf, unsigned int
recv_buf_len);
Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the fully established connection.
ios_icc
OpenVMS usage:io_status_block
type: four longwords (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
-------------------------------------------------
| Undefined | Completion status |
-------------------------------------------------
| ios_icc$l_rcv_len: recvlen | +4
-------------------------------------------------
| ios_icc$l_req_handle: request_handle | +8
-------------------------------------------------
| ios_icc$l_reply_len: reply_len | +12
-------------------------------------------------
Completion codes:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL,
SS$_ACCVIO
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha)
access: longword (unsigned) (VAX)
mechanism: read only
mechanism: by 64-bit value (Alpha)
The parameter to be passed to the AST routine.
recv_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer to receive the incoming
data. The length of this buffer is specified by the argument
recv_buf_len.
recv_buf_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The length (in bytes) of the buffer available to hold the
incoming data. This value specifies the length of the buffer
recv_buf.
IOS_ICC Arguments:
recvlen (output)
OpenVMS usage:longword unsigned
type: longword (unsigned)
access: write only
mechanism: by value
This parameter is returned in the ios_icc. $ICC_RECEIVE writes
the actual length of the incoming data message received from the
target application (in bytes) into offset ios_icc$l_rcv_len of
the ios_icc.
request_handle (output)
OpenVMS usage:request_id
type: longword (unsigned)
access: write only
mechanism: by value
This parameter is returned in the ios_icc. $ICC_RECEIVE writes
the Request/Response handle into offset ios_icc$l_req_handle
of the ios_icc. The request_handle argument is nonzero if the
application is expected to reply to this message.
reply_len (output)
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
This parameter is returned in the ios_icc. The $ICC_RECEIVE
service writes the maximum length (in bytes) of the expected
Reply message into offset ios_icc$l_reply_len of the ios_icc, if
request_handle is nonzero.
The Intra-Cluster Communications Receive and Wait service queues
a receive request to the specified connection.
The $ICC_RECEIVEW service completes synchronously; that is, it
returns to the caller with data.
For asynchronous completion, use the $ICC_RECEIVE service; $ICC_
RECEIVE returns to the caller as soon as the receive request is
queued, without waiting for data on the connection.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_RECEIVEW conn_handle ,ios_icc ,[astadr] ,[astprm]
,recv_buf ,recv_buf_len
C Prototype:
sys$icc_receivew (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *recv_buf, unsigned int
recv_buf_len);
Refuses a connection request.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_REJECT conn_handle, [reject_buf], [reject_buf_len],
[reason]
C Prototype:
int sys$icc_reject (unsigned int conn_handle, char *
reject_buf, unsigned int reject_buf_len,
unsigned int reason);
147.1 - Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the requested connection.
reject_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
A buffer of up to 1000 bytes of reject data to be sent to the
source of the connection at the completion of the rejection
process.
reject_buf_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes in reject_buf to be sent.
reason
OpenVMS usage:cond_code
type: longword (unsigned)
access: read only
mechanism: by value
User-specified reject reason code to be supplied to the remote
application.
Default = SS$_REJECT
Sends a single message over a connection. This service is used
in response to the reception of a Request Handle in a previous
$ICC_RECEIVE system service.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_REPLY conn_handle ,ios_icc ,[astadr] ,[astprm]
,reply_buf ,reply_len
C Prototype:
sys$icc_reply (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *reply_buf, unsigned int
reply_len);
Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the fully established connection.
ios_icc
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: modify
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
-------------------------------------------------
| Undefined | Completion status |
-------------------------------------------------
| ios_icc$l_replyto_handle: request_handle | +4
-------------------------------------------------
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT,
SS$_LINKDISCON
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha), longword (unsigned)
(VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
The parameter to be passed to the AST routine.
reply_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer containing the reply
data to be sent. The length of this buffer is specified by the
argument reply_len.
reply_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The length (in bytes) of the reply data to be sent over the
connection. This value specifies the length of the buffer reply_
buf. ICC segments larger buffers internally.
The maximum Reply length is the smaller of the Reply buffer size
supplied in the $ICC_RECEIVE call, or 1MB.
IOS_ICC Argument:
request_handle (input)
OpenVMS usage:request_id
type: longword (unsigned)
access: read only
mechanism: by value
This parameter is passed through the ios_icc. The
Request/Response handle from the received Transceive request
is placed at offset ios_icc$l_replyto_handle of the ios_icc.
The Intra-Cluster Communications Reply and Wait service transmits
a single message over a connection in response to a $ICC_
TRANSCEIVE[W] request.
The $ICC_REPLYW service completes synchronously; that is, it
returns to the caller when the underlying transport layer has
released use of the reply buffer.
For asynchronous completion, use the $ICC_REPLY service; $ICC_
REPLY returns to the caller as soon as the transmission request
has been queued to the transport layer, without waiting for
notification that the transport layer has released control of
the data buffer.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_REPLYW conn_handle, ios_icc, [astadr], [astprm],
reply_buf, reply_len
C Prototype:
sys$icc_replyw (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *reply_buf, unsigned int
reply_len);
Sends a single message over a connection and then waits for a
reply.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_TRANSCEIVE conn_handle ,ios_icc ,[astadr] ,[astprm]
,send_buf ,send_len
C Prototype:
sys$icc_transceive (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *send_buf, unsigned
int send_len);
Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the fully established (open) connection.
ios_icc
OpenVMS usage:io_status_block
type: five longwords (unsigned)
access: modify
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
--------------------------------------------------
| Undefined | Completion status |
--------------------------------------------------
| ios_icc$l_txrcv_len: returned_data_len | +4
--------------------------------------------------
| ios_icc$a_reply_buffer: reply_buf | +8
| | +12
--------------------------------------------------
| ios_icc$l_txreply_len: reply_buf_len | +16
--------------------------------------------------
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_BUFOVFL, SS$_LINKABORT,
SS$_LINKDISCON
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha), longword (unsigned)
(VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
The parameter to be passed to the AST routine.
send_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer containing the data to
be sent. The length of this buffer is specified by the argument
send_len.
send_len
OpenVMS usage:buffer size
type: longword (unsigned)
access: read only
mechanism: by value
The length (in bytes) of the data to be sent over the connection.
This value specifies the length of the buffer send_buf.
IOS_ICC Arguments:
returned_data_len (output)
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
This parameter is passed through the ios_icc. The $ICC_TRANSCEIVE
service writes the actual length (in bytes) of the reply data
received into offset ios_icc$l_txrcv_len of the ios_icc. This
value represents how much data in reply_buf was returned by the
target application.
reply_buf (input)
OpenVMS usage:byte_stream
type: character-coded text string
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
This parameter is passed through the ios_icc. The 32-bit or 64-
bit address (on Alpha systems) or the 32-bit address (on VAX
systems) of the buffer available to receive the incoming reply
message is placed in offset ios_icc$a_reply_buffer of the ios_
icc.
reply_buf_len (input)
OpenVMS usage:buffer_size
type: longword (unsigned)
access: read only
mechanism: by value
This parameter is passed through the ios_icc. The length (in
bytes) of the buffer to receive the reply message. This value
specifies the length of the buffer reply_buf. This value is
placed in offset ios_icc$l_txreply_len of the ios_icc.
Sends a single message over a connection and waits for a reply.
The $ICC_TRANSCEIVEW service completes synchronously; that is, it
returns to the caller when the data from the reply is available.
For asynchronous completion, use the $ICC_TRANSCEIVE service;
$ICC_TRANSCEIVE returns to the caller when the transmit portion
of the tranceive request has been queued to the transport layer,
but without waiting for notification that the transport layer has
released control of the data buffer or for the reply data from
the receiving end of the connection.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_TRANSCEIVEW conn_handle ,ios_icc ,[astadr] ,[astprm]
,send_buf ,send_len
C Prototype:
sys$icc_transceivew (unsigned int conn_handle,
struct _ios_icc *ios_icc, void
(*astadr)(__unknown_params), __int64
astprm, char *send_buf, unsigned int
send_len);
Sends a single message over a connection.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_TRANSMIT conn_handle ,ios_icc ,[astadr] ,[astprm]
,send_buf ,send_len
C Prototype:
sys$icc_transmit (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *send_buf, unsigned int
send_len);
Arguments
conn_handle
OpenVMS usage:connection_id
type: longword (unsigned)
access: read only
mechanism: by value
The handle of the fully established (open) connection to send the
data over.
ios_icc
OpenVMS usage:ios_status_block
type: structure IOS_ICC
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block:
+2 0
-------------------------------------------------
| Undefined | Completion status |
-------------------------------------------------
| Unused |
-------------------------------------------------
+6 +4
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT,
SS$_LINKDISCON
astadr
OpenVMS usage:ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha)
mechanism: by 32-bit reference (VAX)
The AST routine to be executed when the operation completes.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned) (Alpha), longword (unsigned)
(VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
The parameter to be passed to the AST routine.
send_buf
OpenVMS usage:byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer containing the data to
be sent. The length of this buffer is specified by the argument
send_len.
send_len
OpenVMS usage:buffer_length
type: longword (unsigned)
access: read only
mechanism: by value
The length (in bytes) of the data to be sent over the connection.
This value specifies the length of the buffer send_buf. The
maximum transmission size is 1MB.
Sends a single message over a connection.
The $ICC_TRANSMITW service completes synchronously; that is, it
returns to the caller when the underlying transport layer has
released use of the Transmit buffer. This does not mean that the
data has been received by the partner application.
For asynchronous completion, use the $ICC_TRANSMIT service.
The $ICC_TRANSMIT service returns to the caller as soon as the
transmission request has been queued to the transport layer,
without waiting for notification that the transport layer has
released control of the data buffer.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_TRANSMITW conn_handle ,ios_icc ,[astadr] ,[astprm]
,send_buf ,send_len
C Prototype:
sys$icc_transmitw (unsigned int conn_handle, struct _ios_icc
*ios_icc, void (*astadr)(__unknown_params),
__int64 astprm, char *send_buf, unsigned int
send_len);
Translates the specified identifier value to its identifier name.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$IDTOASC id ,[namlen] ,[nambuf] ,[resid] ,[attrib]
,[contxt]
C Prototype
int sys$idtoasc (unsigned int id, unsigned short int *namlen,
void *nambuf, unsigned int *resid, unsigned
int *attrib, unsigned int *contxt);
154.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary identifier value translated by $IDTOASC. The id argument
is a longword containing the binary value of the identifier. To
determine the identifier names of all identifiers in the rights
database, you specify id as -1 and call $IDTOASC repeatedly until
it returns the status code SS$_NOSUCHID. The identifiers are
returned in alphabetical order.
namlen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Number of characters in the identifier name translated by
$IDTOASC. The namlen argument is the 32- or 64-bit address (on
Alpha systems) or the 32-bit address (on VAX systems) of a word
containing the length of the identifier name written to nambuf.
nambuf
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor-fixed-length string descriptor
(VAX)
Identifier name text string returned when $IDTOASC completes the
translation. The nambuf argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of a
descriptor pointing to the buffer in which the identifier name is
written.
resid
OpenVMS usage:rights_id
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Identifier value of the identifier name returned in nambuf. The
resid argument is the 32- or 64-bit address (on Alpha systems) or
the 32-bit address (on VAX systems) of a longword containing the
32-bit code of the identifier.
attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Mask of attributes associated with the identifier returned in
resid. The attrib argument is the 32- or 64-bit address (on Alpha
systems) or the 32-bit address (on VAX systems) of a longword
containing the attribute mask.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
list using the DCL command SET RIGHTS_
LIST.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have
it translated, either from binary to ASCII
or vice versa, but prevents unauthorized
users from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Context value used when repeatedly calling $IDTOASC. The contxt
argument is the 32- or 64-bit address (on Alpha systems) or
the 32-bit address (on VAX systems) of a longword used while
$IDTOASC searches for all identifiers. The context value must
be initialized to the value 0, and the resulting context of each
call to $IDTOASC must be presented to each subsequent call. After
contxt is passed to $IDTOASC, you must not modify its value.
|
155 - $IEEE SET FP CONTROL (Alpha Only)
|
On Alpha systems, modifies the software IEEE floating-point
control register and, optionally, returns the previous register
value.
The service provides the mechanism to set the specified bits in
the IEEE floating-point control register, to clear the specified
bits in the register, and to swap the values of the register.
Format
SYS$IEEE_SET_FP_CONTROL [clrmsk] ,[setmsk] ,[prvmsk]
C Prototype
int sys$ieee_set_fp_control (struct _ieee *clrmsk, struct
_ieee *setmsk, struct _ieee
*prvmsk);
155.1 - Arguments
clrmsk
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a quadword bit mask to be cleared in the IEEE
floating-point control register.
The $IEEEDEF macro defines symbols for the floating-point
control register. The following table shows the symbols, their
corresponding masks, and their meaning:
Table SYS-4 Format of the IEEE Floating-Point Control Register
(Alpha Only)
Symbol Mask Meaning
IEEE$M_TRAP_ENABLE_ 2 Invalid operation
INV
IEEE$M_TRAP_ENABLE_ 4 Divide by 0
DZE
IEEE$M_TRAP_ENABLE_ 8 Overflow
OVF
IEEE$M_TRAP_ENABLE_ 10 Underflow
UNF
IEEE$M_TRAP_ENABLE_ 20 Inexact
INE
IEEE$M_MAP_UMZ 4000 Underflows are mapped to 0.0
IEEE$M_INHERIT 8000 Inherit FP state on thread create
IEEE$M_STATUS_INV 20000 Invalid operation
IEEE$M_STATUS_DZE 40000 Divide by 0
IEEE$M_STATUS_OVF 80000 Overflow
IEEE$M_STATUS_UNF 100000 Underflow
IEEE$M_STATUS_INE 200000 Inexact
setmsk
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a quadword bit mask to be set in the IEEE floating-
point control register.
See the clrmsk argument for the format of the IEEE floating-point
control register.
prvmsk
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by reference
Address of a quadword to receive the previous value of the IEEE
floating-point control register.
|
156 - $INIT SYS ALIGN FAULT REPORT (Alpha Only)
|
On Alpha systems, initializes system process alignment fault
reporting.
This service accepts 64-bit addresses.
Format
SYS$INIT_SYS_ALIGN_FAULT_REPORT match_table ,buffer_size
,flags
C Prototype
int sys$init_sys_align_fault_report (void *match_table, int
buffer_size, unsigned int
flags);
156.1 - Arguments
match_table
OpenVMS usage:address
type: longword (unsigned)
access: read
mechanism: by 32-bit or 64-bit reference
Describes the system fault match table. The match_table argument
is the 32-bit or 64-bit virtual address of an array of longwords
describing the system fault match table. The first longword is
the number of match entries; the remaining longwords are the
match entries.
The match table is used to restrict the number of alignment
faults reported. Each entry in the table is a bit mask divided
into three groups: mode bits, program counter (PC) space bits,
and virtual address (VA) space bits.
The following table lists the symbols that can be used to define
these bits:
Bit Type Symbols
Mode bits AME$M_KERNEL_MODE Kernel mode
AME$M_EXEC_MODE Executive mode
AME$M_SUPER_MODE Supervisor mode
AME$M_USER_MODE User mode
Program AME$M_USER_PC PC in User space
counter bits
AME$M_SYSTEM_PC PC in System space
Virtual AME$M_SYSTEM_VA VA in System space
address bits
AME$M_USER_VA_P0 VA in User P0 space
AME$M_USER_VA_P1 VA in User P1 space
AME$M_USER_VA_P2 VA in User P2 space
Refer to the OpenVMS System Services Reference Manual to view the
data structure of the match table.
When an alignment fault occurs, a fault bit mask is created with
one bit set in each group. The alignment fault handler then
compares this fault bit mask against each entry in the match
table. If the fault bit mask is a subset of an entry in the match
table, the fault is reported.
buffer_size
OpenVMS usage:byte count
type: longword (signed)
access: read
mechanism: by value
The number of bytes to allocate, from nonpaged pool, to save the
alignment fault data. The buffer you allocate must be sufficient
to accommodate one data item of the size specified in the flags
argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag bit mask specifying options for the $GET_SYS_ALIGN_FAULT_
DATA operation.
If the flags argument is 0, data items of size AFR$K_VMS_LENGTH
will be returned. If the flags argument is AFR$M_USER_INFO, the
user name and image name are added to each data item and they
are returned in a buffer of length AFR$K_EXTENDED_LENGTH. If the
user name and image name are not available, an empty string is
returned in the data item.
Formats a disk or magnetic tape volume and writes a label on the
volume. At the end of initialization, the disk is empty except
for the system files containing the structure information. All
former contents of the volume are lost.
Format
SYS$INIT_VOL devnam, volnam [,itmlst]
C Prototype
int sys$init_vol (void *devnam, void *volnam, void *itmlst);
157.1 - Arguments
devnam
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the device on which the volume is physically mounted. The
descriptor must point to the device name, a character string of 1
to 64 characters. The device name can be a physical device name
or a logical name; if it is a logical name, it must translate to
a physical name.
The device does not have to be currently allocated; however,
allocating the device before initializing it is recommended.
volnam
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Identification to be encoded on the volume. The descriptor
must point to the volume name, a character string of 1 to 12
characters. For a disk volume name, you can specify a maximum
of 12 ANSI characters; for a magnetic tape volume name, you can
specify a maximum of 6 ANSI "a" characters.
Any valid ANSI "a" characters can be used; these include numbers,
uppercase letters, and any one of the following nonalphanumeric
characters:
! " % ' ( ) * + , - . / : ; < = >
Compaq strongly recommends that a disk volume name consist of
only alphanumeric characters, dollar signs ($), underscores (_),
and hyphens (-).
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying options that can be used when initializing
the volume. The itmlst argument is the address of a list of item
descriptors, each of which describes one option. The list of item
descriptors is terminated by a longword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
|
158 - $IO CLEANUP (Alpha Only)
|
On Alpha systems, returns all resources allocated by $IO_SETUP.
This service accepts 64-bit addresses.
Format
SYS$IO_CLEANUP fandle
C Prototype
int sys$io_cleanup (unsigned __int64 fandl);
158.1 - Arguments
fandle
OpenVMS usage:fandle
type: 64-bit integer (unsigned)
access: read only
mechanism: by value
A fandle, passed by value, returned by a previous call to $IO_
SETUP.
|
159 - $IO FASTPATH (Alpha Only)
|
Provides the ability to control the set of Fast Path devices and
their assignment to CPUs enabled for Fast Path use.
Format
SYS$IO_FASTPATH efn ,cpu_mask ,function_code
C Prototype:
int sys$io_fastpath (unsigned int efn, UINT32_PQ cpu_mask,
unsigned int function_code);
Arguments
efn
OpenVMS usage:integer
type: longword bit mask (unsigned)
access: read
mechanism: by value
Number of the event flag to be set when the IO_FASTPATH(W)
operation completes. The efn argument is a longword containing
the number of the event flag.
cpu_mask
OpenVMS usage:integer
type: longword bit mask (unsigned)
access: read
mechanism: by 32- or 64-bit reference
The cpu_mask argument specifies a set of CPUs to be operated
upon.
function_code
OpenVMS usage:integer
type: longword (unsigned)
access: read
mechanism: by value
The function_code specifies the operation to be performed. Must
be one of the following:
FP$K_BALANCE_PORTS - Distribute Fast Path ports across CPUs.
Note that there is currently only one function code.
|
160 - $IO FASTPATHW (Alpha Only)
|
Performs operations on the set of Fast Path devices and CPUs
enabled for Fast Path use.
The $IO_FASTPATHW system service is functionally equivalent to
the $IO_FASTPATH service except that it completes synchronously.
That is, it returns after the operation is complete.
Format
SYS$IO_FASTPATHW efn ,cpu_mask ,function_code
C Prototype:
int sys$io_fastpathw (unsigned int efn, UINT32_PQ cpu_mask,
unsigned int function_code);
|
161 - $IO PERFORM (Alpha Only)
|
On Alpha systems, starts the Fast I/O operation. The $IO_PERFORM
service completes asynchronously. For synchronous completion, use
the Perform Fast I/O and Wait ($IO_PERFORMW) service.
This service accepts 64-bit addresses.
Format
SYS$IO_PERFORM fandle ,chan ,iosadr ,bufadr ,buflen ,devdata
C Prototype
int sys$io_perform (unsigned __int64 fandl, unsigned short int
chan, struct _iosa *iosadr, void *bufadr,
unsigned __int64 buflen, unsigned __int64
devdata);
Arguments
fandle
OpenVMS usage:fandle
type: 64-bit integer (unsigned)
access: read only
mechanism: by value
A fandle returned by a previous call to $IO_SETUP.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read
mechanism: by value
Software I/O channel number.
iosadr
OpenVMS usage:address
type: address
access: read only
mechanism: by value
Address of the I/O Status Area (IOSA). This value cannot be 0;
that is, an IOSA is required. The iosadr must be aligned to a
quadword boundary.
bufadr
OpenVMS usage:char_string
type: address
access: read only
mechanism: by value
The process buffer address. Must be aligned on a 512-byte
boundary.
buflen
OpenVMS usage:byte count
type: 64-bit integer
access: read only
mechanism: by value
The byte count for the I/O. The buflen argument must be a
multiple of 512 bytes. Drivers have further limitations on the
maximum size of an I/O request.
devdata
OpenVMS usage:address
type: pointer or integer
access: read only
mechanism: by value
A hardware integer passed unchanged to the driver. For disk
devices, this is the media address for the transfer; that is,
the virtual block number (VBN) for virtual I/O functions or
the logical block number (LBN) for logical I/O functions. This
argument is ignored for tape devices.
For drivers with complex parameters, devdata would be the address
of a descriptor or buffer specific to the device and function and
would be documented with the driver.
|
162 - $IO PERFORMW (Alpha Only)
|
On Alpha systems, starts a Fast I/O operation. The $IO_PERFORMW
service completes synchronously; that is, it returns to the
caller after performing the Fast I/O operation.
In all other respects, $IO_PERFORMW is identical to $IO_PERFORM.
For all other information about the IO_PERFORMW service, refer to
the help for $IO_PERFORM.
Format
SYS$IO_PERFORMW fandle ,chan ,iosadr ,bufadr ,buflen ,devdata
C Prototype
int sys$io_performw (unsigned __int64 fandl, unsigned short
int chan, struct _iosa *iosadr, void
*bufadr, unsigned __int64 buflen, unsigned
__int64 devdata);
|
163 - $IO SETUP (Alpha Only)
|
On Alpha systems, allocates resources for Fast I/O.
This service accepts 64-bit addresses.
Format
SYS$IO_SETUP func ,bufobj ,iosobj ,astadr ,flags
,return_fandle
C Prototype
int sys$io_setup (unsigned int func, struct _generic_64
*bufobj, struct _generic_64 *iosobj, void
(*astadr)(struct _iosa *), unsigned int
flags, unsigned __int64 *return_fandle);
163.1 - Arguments
func
OpenVMS usage:function_code
type: longword
access: read only
mechanism: by value
I/O function code. Must be one of the following:
o IO$_READVBLK
o IO$_WRITEVBLK
o IO$_READLBLK
o IO$_WRITELBLK
Various function modifiers are supported, depending on the
device and driver. Disk drivers support IO$M_NOVCACHE and
IO$M_DATACHECK. Some tape devices support IO$M_REVERSE. Illegal
modifiers are detected by the $IO_PERFORM(W) service.
bufobj
OpenVMS usage:buffer object
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Handle describing the buffer object that contains the user's
buffer. This identifier cannot be 0.
iosobj
OpenVMS usage:object handle
type: vector longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Buffer object handle describing the buffer object that contains
the I/O Status Area (IOSA). This might or might not be the same
identifier as the bufobj argument. This identifier cannot be 0.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: read only
mechanism: by 32- or 64-bit reference
Completion AST routine address (0, if none). There is no
AST parameter argument. When the AST routine is called, the AST
parameter will be the address of the IOSA for the operation.
Applications can store data in the IOSA at offset IOSA$IH_
CONTEXT.
flags
OpenVMS usage:mask_longword
type: 64-bit integer (unsigned)
access: read only
mechanism: by value
Flag mask. The flags argument is a bit vector in which each bit
corresponds to a flag. Flags are defined in the module IOSADEF.
The following table describes the flags that are valid for the
$IO_SETUP service:
Flag Description
FIO$M_ This is a high priority I/O; that is, it is
EXPEDITE to be given preferential treatment by the I/O
subsystem. Use of this bit requires ALTPRI or
PHY_IO privilege.
FIO$M_AST_ The AST procedure does not use, or call any
NOFLOAT procedure that uses, any floating-point
registers. This is a performance option. If
set, AST delivery will neither save nor restore
floating-point registers. Caution: Use of
floating-point registers when FIO$M_AST_NOFLOAT
has been specified can cause unpredictable,
difficult to detect, error conditions.
All other bits in the flags argument are reserved for future use
by Compaq and should be specified as 0.
return_fandle
OpenVMS usage:fandle
type: 64-bit integer (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Address of an aligned quadword to receive the fandle for this I/O
operation.
Locks a page or range of pages in memory. The specified virtual
pages are forced into the working set and then locked in memory.
A locked page is not swapped out of memory if the working set of
the process is swapped out. These pages are not candidates for
page replacement and in this sense are locked in the working set
as well.
Format
SYS$LCKPAG inadr ,[retadr] ,[acmode]
C Prototype
int sys$lckpag (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
locked. The inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses. Only the virtual page number portion of each virtual
address is used; the low-order byte-within-page bits are ignored.
On VAX systems, if the starting and ending virtual addresses are
the same, a single page is locked.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the pages that
$LCKPAG actually locked. The retadr argument is the address of
a 2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the four access modes.
The most privileged access mode used is the access mode of the
caller. For the $LCKPAG service to complete successfully, the
resultant access mode must be equal to or more privileged than
the access mode already associated with the pages to be locked.
|
165 - $LCKPAG 64 (Alpha Only)
|
On Alpha systems, locks a range of pages in memory. The specified
virtual pages are forced into the working set and then locked
in memory. A locked page is not swapped out of memory if the
working set of the process is swapped out. These pages are not
candidates for page replacement and, in this sense, are locked in
the working set as well.
This service accepts 64-bit addresses.
Format
SYS$LCKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$lckpag_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
165.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be locked. The
specified virtual address will be rounded down to a CPU-specific
page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be locked. The specified
length will be rounded up to a CPU-specific page boundary so that
it includes all CPU-specific pages in the requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the pages to be locked. The acmode
argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. For the $LCKPAG_64 service to complete successfully, the
resultant access mode must be equal to or more privileged than
the access mode already associated with the pages to be locked.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the pages locked in memory.
The return_va_64 argument is the 32- or 64-bit virtual address of
a naturally aligned quadword into which the service returns the
virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range locked in bytes.
Locks a range of pages in the working set; if the pages are not
already in the working set, it brings them in and locks them. A
page locked in the working set does not become a candidate for
replacement.
Format
SYS$LKWSET inadr ,[retadr] ,[acmode]
C Prototype
int sys$lkwset ( struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
locked in the working set. The inadr argument is the address of
a 2-longword array containing, in order, the starting and ending
process virtual addresses. Only the virtual page number portion
of each virtual address is used; the low-order byte-within-page
bits are ignored.
On VAX systems, if the starting and ending virtual addresses are
the same, a single page is locked.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the range of
pages actually locked by $LCKWSET. The retadr argument is the
address of a 2-longword array containing, in order, the starting
and ending process virtual addresses.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the four access modes.
The most privileged access mode used is the access mode of the
caller. For the $LKWSET service to complete successfully, the
resultant access mode must be equal to or more privileged than
the access mode already associated with the pages to be locked.
|
167 - $LKWSET 64 (Alpha Only)
|
On Alpha systems, locks a range of virtual addresses in the
working set; if the pages are not already in the working set,
the service brings them in and locks them. A page locked in the
working set does not become a candidate for replacement.
This service accepts 64-bit addresses.
Format
SYS$LKWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$lkwset_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
167.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be locked in the
working set. The specified virtual address will be rounded down
to a CPU-specific page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be locked in the working
set. The specified length will be rounded up to a CPU-specific
page boundary so that it includes all CPU-specific pages in the
requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the pages to be locked. The acmode
argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. For the $LKWSET_64 service to complete successfully, the
resultant access mode must be equal to or more privileged than
the access mode already associated with the pages to be locked.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the pages locked in the
working set. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range locked in the working
set. The return_length_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service
returns the length of the virtual address range in bytes.
Establishes a correspondence between pages (maps) in the virtual
address space of the process and physical pages occupied by a
global section.
Format
SYS$MGBLSC inadr ,[retadr] ,[acmode] ,[flags] ,gsdnam ,[ident]
,[relpag]
C Prototype
int sys$mgblsc (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, unsigned int
flags, void *gsdnam, struct _secid *ident,
unsigned int relpag);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses into which the section is
to be mapped. The inadr argument is the address of a 2-longword
array containing, in order, the starting and ending process
virtual addresses. Only the virtual page number portion of each
virtual address is used to specify which pages are to be mapped;
the low-order byte-within-page bits are ignored for this purpose.
The interpretation of the inadr argument depends on the setting
of SEC$M_EXPREG in the inadr argument and whether you are using
an Alpha or a VAX system. Refer to the OpenVMS System Services
Reference Manual for a complete description of these differences.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses into which the
section was actually mapped by $MGBLSC. The retadr argument
is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
On Alpha systems, the retadr argument returns the starting and
ending addresses of the usable range of addresses. This might
differ from the total amount mapped. The retadr argument is
required when the relpag argument is specified. If the section
being mapped does not completely fill the last page used to map
the section, the retadr argument indicates the highest address
that actually maps the section. If the relpag argument is used to
specify an offset into the section, the retadr argument reflects
the offset.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages mapped into the
process virtual address space. The acmode argument is a longword
containing the access mode. The $PSLDEF macro defines symbols for
the four access modes.
The most privileged access mode used is the access mode of the
caller.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying options for the operation. The flags
argument is a longword bit vector wherein a bit when set
specifies the corresponding option.
The $SECDEF macro defines symbolic names for the flag bits. You
construct the flags argument by specifying the symbolic names of
each desired option in a logical OR operation.
The following table describes each flag option:
Flag Option Description
SEC$M_WRT Map the section with read/write access. By default,
the section is mapped with read-only access. If
SEC$M_WRT is specified and the section is not copy-
on-reference, write access is required.
SEC$M_SYSGBL Map a system global section. By default, the
section is a group global section.
SEC$M_EXPREG Map the section into the first available virtual
address range. By default, the section is mapped
into the range specified by the inadr argument.
See the inadr argument description for a complete
explanation of how to set the SEC$M_EXPREG flag.
gsdnam
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the global section. The gsdnam argument is the address of
a character string descriptor pointing to this name string.
For group global sections, the operating system interprets the
group UIC as part of the global section name; thus, the names
of global sections are unique to UIC groups. Further, all global
section names are implicitly qualified by their identification
fields.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
ident
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument
is the address of a quadword structure containing three fields.
The first longword specifies, in the low-order two bits, the
matching criteria. Their valid values, the symbolic names by
which they can be specified, and their meanings are as follows:
Value/Name Match Criteria
0 SEC$K_ Match all versions of the section.
MATALL
1 SEC$K_ Match only if major and minor identifications
MATEQU match.
2 SEC$K_ Match if the major identifications are equal and
MATLEQ the minor identification of the mapper is less
than or equal to the minor identification of the
global section.
The version number is in the second longword and contains two
fields: a minor identification in the low-order 24 bits and a
major identification in the high-order 8 bits.
If you do not specify ident or specify it as the value 0 (the
default), the version number and match control fields default to
the value 0.
relpag
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the section of the first page to be
mapped. The relpag argument is a longword containing this number.
On Alpha systems, the relpag argument is interpreted as an index
into the section file, measured in pagelets for a file-backed
section or CPU-specific pages for a PFN-mapped section.
On Alpha and VAX systems, if you do not specify relpag or specify
it as the value 0 (the default), the global section is mapped
beginning with the first virtual block in a file-backed section
or the first CPU-specific page in a PFN-mapped section.
|
169 - $MGBLSC 64 (Alpha Only)
|
On Alpha systems, establishes a correspondence between pages in
the virtual address space of the process and the pages occupied
by a global disk file, page file, or demand-zero section and can
map to a demand-zero section with shared page tables.
This service accepts 64-bit addresses.
Format
SYS$MGBLSC_64 gs_name_64 ,ident_64 ,region_id_64
,section_offset_64 ,length_64 ,acmode
,flags ,return_va_64 ,return_length_64
[,start_va_64]
C Prototype
int sys$mgblsc_64 (void *gsdnam_64, struct _secid *ident_64,
struct _generic_64 *region_id_64, unsigned
__int64 section_offset_64, unsigned __int64
length_64, unsigned int acmode, unsigned int
flags, void *(*(return_va_64)), unsigned
__int64 *return_length_64,...);
169.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name_64 argument is the 32-
or 64-bit virtual address of a naturally aligned 32-bit or 64-bit
string descriptor pointing to this name string.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order two bits.
The valid values, symbolic names by which they can be specified,
and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
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 to map the global
section. 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.
section_offset_64
OpenVMS usage:byte offset
type: quadword (unsigned)
access: read only
mechanism: by value
Offset into the global section at which to start mapping into the
process's virtual address space.
If a map to a global disk file section is being requested, the
section_offset_64 argument specifies an even multiple of disk
blocks. If a map to a global page file or demand-zero section is
being requested, the section_offset_64 argument specifies an even
multiple of CPU-specific pages. If zero is specified, the global
section is mapped beginning with the first page of the section.
If the region_id_64 argument specifies a shared page table
region, section_offset_64 must be an even multiple of pages
mapped by a page table page.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length, in bytes, of the desired mapping of the global disk file
section.
If a map to a global section is being requested, the length_64
argument must specify an even multiple of disk blocks. If a map
to a global page file or demand-zero section is being requested,
the length_64 argument must specify an even multiple of CPU-
specific pages. If zero is specified, the size of the disk file
is used.
If a shared page-table region is specified by the region_id_64
argument, length_64 must be an even multiple of the number of
bytes that can be mapped by a CPU-specific page-table page or
must include the last page within the memory-resident global
section.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. This is also the read access mode and, if the SEC$M_
WRT flag is specified, the write access mode. The acmode argument
is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. Address space cannot be created within a region that has
a create mode associated with it that is more privileged than
the caller's mode. The condition value SS$_IVACMODE is returned
if the caller is less privileged than the create mode for the
region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying options for the operation. The flags
argument is a longword bit vector in which each bit corresponds
to a flag. The $SECDEF macro and the SECDEF.H file define a
symbolic name for each flag. You construct the flags argument
by performing a logical OR operation on the symbol names for all
desired flags.
The following table describes each flag that is valid for the
$MGBLSC_64 service:
Flag Description
SEC$M_EXPREG Pages are mapped into the first available space at
the current end of the specified region.
If /ALLOCATE was specified when the memory-resident
global section was registered in the Reserved
Memory Registry, virtually aligned addresses
after the first available space are chosen for
the mapping.
It the region_id_64 argument specifies a shared
page-table region, the first available space is
round up to the beginning of the next CPU-specific
page-table page.
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_NO_ Pages cannot overmap existing address space.
OVERMAP
SEC$M_SHMGS On OpenVMS Galaxy systems, create a shared-memory
global section.
SEC$M_SYSGBL The global section map is a system global section.
By default, the section is a group global section.
SEC$M_WRT Map the section with read/write access.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
attempt is made to use the SEC$M_PAGFIL flag, which applies only
to the creation of a page-file backed section.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The process virtual address into which the global disk or page
file section was mapped. The return_va_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the virtual address.
Upon successful completion of this service, if the
section_offset_64 argument was specified, the virtual address
returned in the return_va_64 argument reflects the offset into
the global section mapped such that the virtual address returned
cannot be aligned on a CPU-specific page boundary. The virtual
address returned will always be on an even virtual disk block
boundary.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the usable virtual address range mapped. The
return_length_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the length of the virtual address range mapped in bytes.
Upon successful completion of this service, the value in the
return_length_64 argument might differ from the total amount
of virtual address space mapped. The value in the return_va_64
argument plus the value in the return_length_64 argument
indicates the address of the first byte beyond the end of the
mapping of the global disk file section.
If the value in the section_offset_64 argument plus the value in
the length_64 argument did not specify to map the entire global
section, this byte can be located at an even virtual disk block
boundary within the last page of the mapping.
If the section being mapped does not completely fill the last
page used to represent the global disk file section, this byte
can be mapped into your address space; however, it is not backed
up by the disk file.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to which to map the global section.
The specified virtual address must be a CPU-specific page-aligned
address. If the flag SEC$M_EXPREG is specified, the start_va_64
argument must not be specified or must be specified as 0. If
SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
condition value SS$_IVSECFLG is returned.
If the region_id_64 argument specifies a shared page-table
region, start_va_64 must be aligned to a CPU-specific page-table
page boundary.
|
170 - $MGBLSC GPFN 64 (Alpha Only)
|
On Alpha systems, establishes a correspondence between pages in
the virtual address space of the process and the pages occupied
by a global page frame section.
This service accepts 64-bit addresses.
Format
SYS$MGBLSC_GPFN_64 gs_name_64 ,ident_64 ,region_id_64
,relative_page ,page_count ,acmode
,flags ,return_va_64 ,return_length_64
[,start_va_64]
C Prototype
int sys$mgblsc_gpfn_64 (void *gsdnam_64, struct _secid
*ident_64, struct _generic_64
*region_id_64, unsigned int
relative_page, unsigned int
page_count, unsigned int
acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64
*return_length_64,...);
170.1 - Arguments
gs_name_64
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the global section. The gs_name argument is the 32- or
64-bit virtual address of a naturally aligned 32-bit or 64-bit
descriptor pointing to this name string.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and on
section name processing is available in the OpenVMS Programming
Concepts Manual.
ident_64
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Identification value specifying the version number of a global
section. The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-
order two bits. The valid values, symbolic names by which they
can be specified, and their meanings are as follows:
Symbolic
Value Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor
identifications match.
2 SEC$K_MATLEQ Match if the major identifications are
equal and the minor identification of the
mapper is less than or equal to the minor
identification of the global section.
If you specify the ident_64 argument as 0, the version number and
match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
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 to map the private page
frame section. 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.
relative_page
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Relative CPU-specific page number within the global section to
start mapping.
page_count
OpenVMS usage:CPU-specific page count
type: longword (unsigned)
access: read only
mechanism: by value
Length of mapping in CPU-specific pages. If zero is specified,
the global page frame section is mapped to the end of the
section.
acmode
OpenVMS usage:access-mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages mapped into the
process virtual address space. The acmode argument is a longword
containing the access mode. The $PSLDEF macro defines symbols for
the four access modes.
The most privileged access mode used is the access mode of the
caller. Address space cannot be created within a region that has
a create mode associated with it that is more privileged than
the caller's mode. The condition value SS$_IVACMODE is returned
if the caller is less privileged than the create mode for the
region.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying options for the operation. The flags
argument is a longword bit vector in which each bit corresponds
to a flag. The $SECDEF macro and the SECDEF.H file define a
symbolic name for each flag. You construct the flags argument
by performing a logical OR operation on the symbol names for all
desired flags.
The following table describes each flag that is valid for the
$MGBLSC_GPFN_64 service:
Flag Description
SEC$M_GBL Pages form a global section. By default, this flag
is always present in this service and cannot be
disabled.
SEC$M_EXPREG Map the section into the first available space at
the current end of the specified region. If this
flag is specified, the start_va_64 argument is not
used.
SEC$M_PERM Pages are permanent. By default, this flag is
always present in this service and cannot be
disabled.
SEC$M_PFNMAP Pages form a page frame section. By default, this
flag is always present in this service and cannot
be disabled.
SEC$M_PAGFIL Pages form a global page-file section. SEC$M_PAGFIL
also implies SEC$M_WRT and SEC$M_DZRO.
SEC$M_SYSGBL Map a system global section. By default, the
section is a group global section.
SEC$M_WRT Map the section with read/write access. By default,
the section is mapped with read-only access. If
SEC$M_WRT is specified, write access is required.
All other bits in the flags argument are reserved for future
use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an
illegal combination of flags is set.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address into which the global page
frame section was mapped. The return_va_64 argument is the 32-
or 64-bit virtual address of a naturally aligned quadword that
contains the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned quadword
into which the $MGBLSC_GPFN_64 service returns the length of the
virtual address range in bytes.
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address to map the global section. The
specified virtual address must be a CPU-specified page-aligned
address. If the flag SEC$M_EXPREG is specified, the start_va_64
argument must not be specified or must be specified as 0. If
SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
condition value SS$_IVSECFLG is returned.
Always refer to the return_va_64 and return_length_64 arguments
to determine the range of virtual addresses mapped.
Modifies the specified holder record of the target identifier in
the rights database.
Format
SYS$MOD_HOLDER id ,holder ,[set_attrib] ,[clr_attrib]
C Prototype
int sys$mod_holder (unsigned int id, struct _generic_64
*holder, unsigned int set_attrib, unsigned
int clr_attrib);
171.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of target identifier whose holder record is modified
when $MOD_HOLDER completes execution. The id argument is a
longword containing the identifier value.
holder
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Identifier of holder being modified when $MOD_HOLDER completes
execution. The holder argument is the address of a quadword
containing the UIC identifier of the holder in the first longword
and the value of 0 in the second longword.
set_attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bit mask of attributes to be enabled for the identifier when
$MOD_HOLDER completes execution. The set_attrib argument is a
longword containing the attribute mask.
The attributes actually enabled are the intersection of those
specified and the attributes of the identifier. If you specify
the same attribute in set_attrib and clr_attrib, the attribute is
enabled.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it
from or add it to the process rights list by
using the DCL command SET RIGHTS_LIST.
KGB$V_ Makes any access rights of the identifier
NOACCESS null and void. This attribute is intended as
a modifier for a resource identifier or the
Subsystem attribute.
KGB$V_ Allows the holder to charge resources, such as
RESOURCE disk blocks, to the identifier.
KGB$V_ Allows holders of the identifier to create and
SUBSYSTEM maintain protected subsystems by assigning the
Subsystem ACE to the application images in the
subsystem.
clr_attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bit mask of attributes to be disabled for the identifier when
$MOD_HOLDER completes execution. The clr_attrib argument is a
longword containing the attribute mask.
If you specify the same attribute in set_attrib and clr_attrib,
the attribute is enabled.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it
from or add it to the process rights list by
using the DCL command SET RIGHTS_LIST.
KGB$V_ Makes any access rights of the identifier
NOACCESS null and void. This attribute is intended as
a modifier for a resource identifier or the
Subsystem attribute.
KGB$V_ Allows the holder to charge resources, such as
RESOURCE disk blocks, to the identifier.
KGB$V_ Allows holders of the identifier to create and
SUBSYSTEM maintain protected subsystems by assigning the
Subsystem ACE to the application images in the
subsystem.
Modifies the specified identifier record in the rights database.
Format
SYS$MOD_IDENT id ,[set_attrib] ,[clr_attrib] ,[new_name]
,[new_value]
C Prototype
int sys$mod_ident (unsigned int id, unsigned int set_attrib,
unsigned int clr_attrib, void *new_name,
unsigned int new_value);
172.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of identifier whose identifier record is modified
when $MOD_IDENT completes execution. The id argument is a
longword containing the identifier value.
set_attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bit mask of attributes to be enabled for the identifier when
$MOD_IDENT completes execution. The set_attrib argument is a
longword containing the attribute mask.
The attributes actually enabled are the intersection of those
specified and the attributes of the identifier. If you specify
the same attribute in set_attrib and clr_attrib, the attribute is
enabled.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
list by using the DCL command SET_RIGHTS_
LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of
users who hold an identifier, unless they
own the identifier themselves.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it
translated-either from binary to ASCII or
vice versa-but prevents unauthorized users
from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
clr_attrib
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bit mask of attributes to be disabled for the identifier when
$MOD_IDENT completes execution. The clr_attrib argument is a
longword containing the attribute mask.
If you specify the same attribute in set_attrib and clr_attrib,
the attribute is enabled.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove
it from or add it to the process rights
list by using the DCL command SET_RIGHTS_
LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of
users who hold an identifier, unless they
own the identifier themselves.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it
translated-either from binary to ASCII or
vice versa-but prevents unauthorized users
from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
new_name
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
New name to be given to the specified identifier. The new_
name argument is the address of the descriptor pointing to the
identifier name string.
An identifier name consists of 1 to 31 alphanumeric characters,
including dollar signs ($) and underscores (_), and must contain
at least one nonnumeric character. Any lowercase characters
specified are automatically converted to uppercase.
new_value
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
New value to be assigned to the specified identifier. The new_
value argument is a longword containing the binary value of the
specified identifier. When the identifier value is changed, $MOD_
IDENT also changes the value of the identifier in all of the
holder records in which the specified identifier appears.
Mounts a tape, disk volume, or volume set and specifies options
for the mount operation.
Format
SYS$MOUNT itmlst
C Prototype
int sys$mount (void *itmlst);
173.1 - Argument
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying options for the mount operation. The itmlst
argument is the address of a list of item descriptors, each of
which specifies an option and provides the information needed to
perform the operation.
The item list must include at least one device item descriptor
and is terminated by a longword value of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
Allows installations to provide their own routine to interpret
and output the accessibility field in the VOL1 and HDR1 labels of
an ANSI labeled magnetic tape.
Format
SYS$MTACCESS lblnam ,[uic] ,[std_version] ,[access_char]
,[access_spec] ,type
C Prototype
int sys$mtaccess ( unsigned int *lblnam, unsigned int uic,
unsigned int std_version, unsigned int
access_char, unsigned int access_spec,
unsigned int type);
174.1 - Arguments
lblnam
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
ANSI label to be processed. The lblnam argument is the address
of a longword containing the label. On input, the label passed
is either the VOL1 or HDR1 label read from the magnetic tape; on
output of labels, the value of this field is 0. The type of label
passed is determined by type.
uic
OpenVMS usage:uic
type: longword (unsigned)
access: read only
mechanism: by value
UIC of the user performing the operation. The uic argument is a
longword containing the UIC.
std_version
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Decimal equivalent of the ANSI standard version read from the
VOL1 label. The std_version argument is a longword containing the
standard version number.
access_char
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Accessibility character specified by the user. The access_char
argument is a byte containing the accessibility character used
for the output of labels.
access_spec
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Value specifying whether the accessibility character passed in
access_char was specified by the user.
The access_spec argument is a byte containing one of the
following values:
Value Meaning
MTA$K_ Yes
CHARVALID
MTA$K_NOCHAR No
This argument is used only for the output of labels.
type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Type of accessibility field to process.
The type argument is a byte containing one of the following
values:
Value Meaning
MTA$K_INVOL1 Input a VOL1 label
MTA$K_INHDR1 Input a HDR1 label
MTA$K_OUTVOL1 Output a VOL1 label
MTA$K_OUTHDR1 Output a HDR1 label
Converts an absolute or delta time from 64-bit system time format
to binary integer date and time values.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$NUMTIM timbuf ,[timadr]
C Prototype
int sys$numtim (unsigned short int timbuf [7], struct
_generic_64 *timadr);
175.1 - Arguments
timbuf
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Buffer into which $NUMTIM writes the converted date and time. The
timbuf argument is the 32-bit address (on VAX systems) or the 32-
or 64-bit address (on Alpha systems) of a 7-word structure.
Refer to the OpenVMS System Services Reference Manual to view the
diagram of the fields in this structure.
If the timadr argument specifies a delta time, $NUMTIM returns
the value 0 in the year since 0 and month of year fields. It
returns in the day of month field the number of days specified by
the delta time.
timadr
OpenVMS usage:date_time
type: quadword
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 64-bit time value to be converted. The timadr argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on
Alpha systems) of a quadword containing this time. A positive-
time value represents an absolute time, while a negative time
value indicates a delta time.
If you do not specify timadr, $NUMTIM returns the current system
time.
If timadr specifies the value 0, $NUMTIM returns the base date
(November 17, 1858).
Converts an absolute 128-bit binary time into its numeric
components. The numeric components are returned in local time.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$NUMUTC timbuf ,[utcadr]
C Prototype
int sys$numutc (unsigned short int timbuf [13], unsigned int
*utcadr [4]);
176.1 - Arguments
timbuf
OpenVMS usage:vector_word_unsigned
type: word
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Buffer into which $NUMUTC writes the converted date and time. The
timbuf argument is the 32-bit address (on VAX systems) or the 32-
or 64-bit address (on Alpha systems) of a 13-word structure
containing time, inaccuracy of time, and time differential
factor. The time differential factor encoded in the 128-bit
buffer is used to convert the UTC to its numerical components.
Negative values in the inaccuracy field indicate an infinite
inaccuracy.
Refer to the OpenVMS System Services Reference Manual to view the
diagram of the fields in this structure.
utcadr
OpenVMS usage:coordinated universal time
type: utc_date_time
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 128-bit UTC time value to be converted.
The utcadr argument is optional; if it is not used, $NUMUTC will
use the current time.
Parses the specified text string and converts it to the binary
representation for an access control entry (ACE).
Format
SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]
C Prototype
int sys$parse_acl (void *aclstr, void *aclent, unsigned
short int *errpos, void *accnam, int
(*routin)(void));
177.1 - Arguments
aclstr
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Formatted ACE that is parsed when $PARSE_ACL completes execution.
The aclstr argument is the address of a string descriptor
pointing to the text string to be parsed.
aclent
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Description of the ACE that is parsed when $PARSE_ACL completes
execution. The aclent argument is the address of a descriptor
pointing to the buffer in which the ACE is written. The first
byte of the buffer contains the length of the ACE; the second
byte contains a value that identifies the type of ACE, which in
turn defines the format of the ACE.
For information about the ACE types and their associated formats,
see $FORMAT_ACL system service documentation.
errpos
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters from aclstr processed by $PARSE_ACL. The
errpos argument is the address of a word that receives the number
of characters actually processed by the service. If the service
fails, this count points to the failing point in the string.
accnam
OpenVMS usage:access_bit_names
type: longword (unsigned)
access: read only
mechanism: by reference
Names of the bits in the access mask when $PARSE_ACL is
executing. The accnam argument is the address of an array of
32 quadword descriptors that define the names of the bits in the
access mask. Each element points to the name of a bit. The first
element names bit 0, the second element names bit 1, and so on.
You can call LIB$GET_ACCNAM to retrieve the access name table
for the class of object whose ACL is to be formatted. If you omit
accnam, the following names are used:
Bit Name
Bit 0 READ
Bit 1 WRITE
Bit 2 EXECUTE
Bit 3 DELETE
Bit 4 CONTROL
Bit 5 BIT_5
Bit 6 BIT_6
.
.
.
Bit BIT_31
31
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
|
178 - $PERM DIS ALIGN FAULT REPORT (Alpha Only)
|
On Alpha systems, disables user process alignment fault
reporting.
Format
SYS$PERM_DIS_ALIGN_FAULT_REPORT
C Prototype
int sys$perm_dis_align_fault_report (void);
178.1 - Arguments
None.
|
179 - $PERM REPORT ALIGN FAULT (Alpha Only)
|
On Alpha systems, initializes user process alignment fault
reporting.
Format
SYS$PERM_REPORT_ALIGN_FAULT
C Prototype
int sys$perm_report_align_fault (void);
179.1 - Arguments
None.
|
180 - $PERSONA ASSUME (VAX Only)
|
Modifies the context of the current process to match the context
of a given persona. The $PERSONA_ASSUME service allows an OpenVMS
process to assume the identity of another user or to discard a
persona to return the process to its original state.
Format
SYS$PERSONA_ASSUME persona ,[flags]
C Prototype
int sys$persona_assume (unsigned int *persona, unsigned int
flags);
Arguments
persona
OpenVMS usage:integer
type: longword (unsigned)
access: read
mechanism: by reference
Address of a longword in which the persona handle is expected.
If the value of the context passed is 1, then the current persona
is discarded, and the state of the calling process is returned
to the state that existed prior to the first call to $PERSONA_
CREATE.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying which Persona services options are to be
employed when the persona is assumed. This argument is ignored
when a persona is being discarded.
The following table describes each flag:
Flag Description
IMP$M_ASSUME_SECURITY Assume access rights, UIC, authorized
privileges, user name, and security audit
flag.
IMP$M_ASSUME_ACCOUNT Assume OpenVMS account.
IMP$M_ASSUME_JOB_WIDE Assume the new persona, even in a
multiprocess job.
|
181 - $PERSONA ASSUME (Alpha Only)
|
Allows an OpenVMS thread to assume the identity of another
persona.
Format
SYS$PERSONA_ASSUME persona ,[flags], [previous], [acmode]
C Prototype
int sys$persona_assume ( unsigned int *persona, unsigned int
flags, unsigned int *previous, unsigned
int acmode);
Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword in which the persona identification handle
is expected.
If the value passed is ISS$C_ID_NATURAL, then the state of the
calling thread is returned to the natural persona.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Ignored.
previous
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the persona identification
handle of the currently active persona being replaced is written.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be considered when assuming a persona. The acmode
argument is a longword containing the access mode.
The most privileged access mode used is the access mode of the
caller. Only equal or more privileged access modes can use this
persona.
|
182 - $PERSONA CLONE (Alpha Only)
|
Creates a copy of an existing persona within the context of
the current process. The service returns the assigned persona
identification for the new persona in the persona argument. This
persona can be assumed using the $PERSONA_ASSUME service.
Format
SYS$PERSONA_CLONE persona ,[input]
C Prototype
int sys$persona_clone (unsigned int *persona, unsigned int
*input);
182.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the persona identification
handle is written.
input
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword containing the persona identification of
the persona to be cloned. If this argument is 0, null, or absent,
the currently active persona is cloned.
|
183 - $PERSONA CREATE (VAX Only)
|
Creates a persona that can be assumed using the $PERSONA_ASSUME
service.
Format
SYS$PERSONA_CREATE persona ,usrnam ,flags
C Prototype
int sys$persona_create (unsigned int *persona, void *usrnam,
unsigned int flags);
Arguments
persona
OpenVMS usage:integer
type: longword (unsigned)
access: write
mechanism: by reference
Address of a longword into which the persona handle is written.
usrnam
OpenVMS usage:char_string
type: character coded text string
access: read only
mechanism: by descriptor - fixed-length descriptor
Name of the user to be impersonated. The usrnam argument is
the address of a descriptor pointing to a character string
containing the user name. The string can contain a maximum of
12 alphanumeric characters.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying which Persona services options are to be
employed when the persona is created.
The following table describes each flag:
Flag Description
IMP$M_ASSUME_DEFPRIV Create a persona with only default
privileges.
IMP$M_ASSUME_ Create a persona with default
DEFCLASS classification.
|
184 - $PERSONA CREATE (Alpha Only)
|
Creates a persona that can be assumed using the $PERSONA_ASSUME
service.
Format
SYS$PERSONA_CREATE persona ,[usrnam] ,[flags], [usrpro],
[itmlst]
C Prototype
int sys$persona_create (unsigned int *persona, void *usrnam,
unsigned int flags, unsigned int
*usrpro, unsigned int *itmlst);
Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the persona identification
handle is written.
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length descriptor
Name of the user to be impersonated. The usrnam argument is
the address of a descriptor pointing to a character string
containing the user name. The string can contain a maximum of
32 alphanumeric characters.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The $ISSDEF macro defines these codes:
o ISS$V_CREATE_AUTHPRIV - This bit is used to create a persona
with the privilege fields set to the authorized privileges of
the specified user.
o ISS$V_CREATE_DEFPRIV - This bit is used for backward
compatibility with the previous implementation of personae.
This bit is accepted but not processed, as it describes the
default behavior of the service.
o ISS$V_NOACCESS - Tells $PERSONA_CREATE not to access the
SYSUAF file. Only valid in exec or kernel mode.
usrpro
OpenVMS usage:char_string
type: opaque byte stream
access: read only
mechanism: by descriptor
Buffer containing an encoded security profile. The usrpro
argument is the address of a descriptor pointing to a buffer
that contains encoded security profile data. This profile can be
created by calling the SYS$CREATE_USER_PROFILE system service.
itmlst
OpenVMS usage:item_list_3
type: longword
access: read only
mechanism: by reference
Attributes describing modifications to the security profile. The
itmlst argument is the address of an item_list defining changes
to be made to the specified user profile.
|
185 - $PERSONA CREATE EXTENSION (Alpha Only)
|
Creates an extension on the current persona. A persona extension
is a mechanism to attach support for additional security
credentials.
Format
SYS$PERSONA_CREATE_EXTENSION persona ,extensionID ,buffer
,length ,flags
C Prototype
int sys$persona_create_extension (unsigned int *persona,
unsigned int *extensionID,
void *buffer, unsigned
int *length, unsigned int
*flags);
185.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the persona identification to
which $PERSONA_CREATE_EXTENSION attaches a new persona extension.
Two special values for persona are also permitted: 0, which means
the current persona, and -1, which means the process' natural
persona is used.
extensionID
OpenVMS usage:extension_ID
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the extension identification
(EID) for which the registered CREATE routine will be called to
create a new persona extension block.
buffer
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a buffer containing data to be used in creating the
persona extension data structure. The interpretation of the
data within this buffer is the responsibility of the extension
create routine. For example, this data could be a Type-Length-
Value (TLV) structure containing fields in the extension data
structure. Specifying this buffer is optional; a caller who does
not want to supply a buffer should specify an address of zero
(0).
length
OpenVMS usage:size
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the size, in bytes, of the
buffer argument. Specifying length is optional; a caller who
does not want to supply a length should specify an address of
zero (0). Specifying a buffer without a length is the same as not
specifying a buffer.
flags
OpenVMS usage:flags
type: longword (unsigned)
access: read only
mechanism: by reference
Flag mask specifying the options to be employed when the persona
extension is created. Specifying flags is optional; a caller who
does not want to supply flags should specify an address of zero
(0).
Flag Description
PXB$V_ This extension is recorded as the persona's primary
PRIMARY_ extension. If a persona already has a primary
EXTENSION extension, the error SS$_UNSUPPORTED is returned and
the extension is not created. The primary extension is
returned when the persona is queried for its "Primary
Extension." There is no other meaning for this value.
|
186 - $PERSONA DELEGATE (Alpha Only)
|
Delegates or assigns the currently active persona to another
process.
Format
SYS$PERSONA_DELEGATE serverPID ,persona ,input
C Prototype
int sys$persona_delegate (unsigned int *serverPID, unsigned
int *persona, unsigned int *input);
186.1 - Arguments
serverPID
OpenVMS usage:process_ID
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the extended process
identification (PID) of the server process to which $PERSONA_
DELEGATE grants the current persona.
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the persona identification that
this service reserved in the server's process for this client's
persona.
input
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the persona identification that
describes which persona is delegated to the server. If the input
argument is zero (0) or null, or if the input value is zero (0),
the current persona is delegated. If the input value is -1, then
the natural persona of the process is delegated.
Deletes a persona created using the $PERSONA_CREATE, the
$PERSONA_CLONE, or the $PERSONA_RESERVE service.
Format
SYS$PERSONA_DELETE persona
C Prototype
int sys$persona_delete (unsigned int *persona);
Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword in which the persona identification handle
is expected.
|
188 - $PERSONA DELETE EXTENSION (Alpha Only)
|
Deletes an extension attached to a persona.
Format
SYS$PERSONA_DELETE_EXTENSION persona ,extensionID
C Prototype
int sys$persona_delete_extension (unsigned int *persona,
unsigned int *extensionID);
188.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the persona identification for
which $PERSONA_DELETE_EXTENSION calls the registered Extension
Delete function.
extensionID
OpenVMS usage:extension_ID
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the extension identification
(EID) for which the registered DELETE routine is called in order
to delete a persona extension block from the specified persona.
|
189 - $PERSONA EXTENSION LOOKUP (Alpha Only)
|
Translates a text name of an extension (for example, VMS or NT)
into an extension identification (EID) that can be used in other
persona-related system services.
Format
SYS$PERSONA_EXTENSION_LOOKUP extensionName ,extensionID
C Prototype
int sys$persona_extension_lookup (void *extensionName,
unsigned int *extensionID);
189.1 - Arguments
extensionName
OpenVMS usage:extension_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length descriptor
Address of a character string descriptor pointing to the name of
the extension being looked up.
extensionID
OpenVMS usage:extension_ID
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the value of the extension
identification (EID) returned by the service is written.
|
190 - $PERSONA FIND (Alpha Only)
|
Enables the caller to find the personae within a process that
have certain attributes or settings.
Format
SYS$PERSONA_FIND persona ,itmlst ,contxt
C Prototype
int sys$persona_find (unsigned int *persona, void *itmlst,
unsigned int *contxt);
190.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the persona identification that
matches all of the items present in the item list is written.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes specifying which information about the persona is
to be compared. The itmlst argument is the address of a list of
item descriptors, each describing an item of information or an
item list processing directive. The list of item descriptors is
terminated by a longword value of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used when repeatedly calling $PERSONA_FIND. The
contxt argument is the address of a longword used while $PERSONA_
FIND searches for all personae that match the criteria. The
context value must be initialized to zero, and the resulting
context of each call to $PERSONA_FIND must be presented to each
subsequent call. After contxt is passed to $PERSONA_FIND, you
must not modify its value.
|
191 - $PERSONA MODIFY (Alpha Only)
|
Sets attribute values for a persona.
Format
SYS$PERSONA_MODIFY persona ,itmlst
C Prototype
int sys$persona_modify (unsigned int *persona, void *itmlst);
191.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the persona identification for
which this service is to set information.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes specifying which information in the persona is to
be modified. The itmlst argument is the address of a list of
item descriptors, each describing an item of information or an
item list processing directive. The list of item descriptors is
terminated by a longword value of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
|
192 - $PERSONA QUERY (Alpha Only)
|
Retrieves attribute values from a persona (and accompanying
extensions).
Format
SYS$PERSONA_QUERY persona ,itmlst
C Prototype
int sys$persona_query (unsigned int *persona, void *itmlst);
192.1 - Arguments
persona
OpenVMS usage:persona
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword into which the persona identification
handle is written.
Two special values for persona are also permitted: 0, which means
use the current persona, and -1, which means use the process'
natural persona.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes describing which information about the persona is to
be returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information or an
item list processing directive. The list of item descriptors is
terminated by a longword value of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
|
193 - $PERSONA RESERVE (Alpha Only)
|
Reserves a persona ID in the server's persona table to be filled
in by the $PERSONA_DELEGATE system service.
Format
SYS$PERSONA_RESERVE clientPID ,persona
C Prototype
int sys$persona_reserve (unsigned int *clientPID, unsigned int
*persona);
193.1 - Arguments
clientPID
OpenVMS usage:process_ID
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing the External Process
Identification (EPID) of the client process for which the server
is reserving the slot.
persona
OpenVMS usage:persona
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a longword into which the persona identification
is written. This service sets aside the identification for the
client's to-be-delegated persona.
|
194 - $PROCESS AFFINITY (Alpha Only)
|
On Alpha systems, allows modification of the CPU affinity set for
a specified kernel thread.
This service accepts 64-bit addresses.
Format
SYS$PROCESS_AFFINITY [pidadr] [,prcnam] [,select_mask]
[,modify_mask] [,prev_mask] [,flags]
C Prototype
int sys$process_affinity ( unsigned int *pidadr, void *prcnam,
struct _generic_64 *select_mask,
struct _generic_64 *modify_mask,
struct _generic_64 *prev_mask, struct
_generic_64 *flags);
194.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Process identification (PID) of a kernel thread whose affinity
mask is to be modified or returned. The pidadr argument is the
32- or 64-bit address of a longword that contains the PID.
Process selection is made through a combination of the pidadr
and prcnam arguments. If neither are specified or if both have a
zero value, the service operations are made to the user affinity
mask of the current kernel thread of the calling process. The
pidadr argument takes precedence over the prcnam argument in any
circumstances where both are supplied in the service call.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Process name of the process whose affinity mask is to be modified
or returned. The prcnam argument is the 32- or 64-bit address
of a character string descriptor pointing to the process name
string. A process can be identified with a 1- to 15-character
string. The service operations are made to the user affinity mask
of the initial thread of the specified process.
If pidadr and prcnam are both specified, then pidadr is modified
or returned and prcnam is ignored. If neither argument is
specified, then the context of the current kernel thread of the
calling process is modified or returned.
select_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying which bits of the specified process' affinity
mask are to be modified. The select_mask argument is the 32- or
64-bit address of a quadword bit vector wherein a bit, when set,
specifies that the corresponding CPU position in the mask is to
be modified.
The individual CPU bits in select_mask can be referenced by their
symbolic name constants, CAP$M_CPU0 through CAP$M_CPU31. These
constants (zero-relative to match system CPU IDs) specify the
position in the mask quadword that correspond to the bit name.
Multiple CPUs can be selected by ORing together the appropriate
bits.
modify_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying the settings for those explicit affinities
selected in the select_mask argument. The modify_mask argument is
the 32- or 64-bit address of a quadword bit vector wherein a bit,
when set, specifies that the corresponding CPU is to be added to
the specified process affinity set; when clear, the corresponding
CPU is to be removed from the specified process affinity set.
The bit constants CAP$M_CPU0 through CAP$M_CPU31 can be used to
modify the appropriate bit position in the quadword pointed to
by modify_mask. Multiple CPUs can be added to the affinity set by
ORing together the appropriate bits.
To add a specific CPU to the affinity mask set, that bit position
must be set in both select_mask and modify_mask. To remove a
specific CPU from the affinity mask set, that bit position must
be set in select_mask and clear in modify_mask.
The constant CAP$K_ALL_CPU_ADD, when specified in modify_mask,
indicates that all CPUs specified in select_mask are to be added
to the affinity mask set. The constant CAP$K_ALL_CPU_REMOVE
indicates that all CPUs in select_mask are to be removed from
the affinity mask set.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Previous CPU affinity mask for the specified kernel thread before
execution of this call to $PROCESS_AFFINITY. The prev_mask
argument is the 32- or 64-bit address of a quadword into which
$PROCESS_AFFINITY writes the previous explicit affinity bit mask.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for affinity modification. The flags argument
is a quadword bit vector wherein a bit corresponds to an option.
Only the bits specified below are used; the remainder of the
quadword bits are reserved and must be 0.
Each option (bit) has a symbolic name, which the $CAPDEF macro
defines. The flags argument is constructed by performing a
logical OR operation using the symbolic names of each desired
option.
The following table describes the symbolic name of each option:
Symbolic Name Description
CAP$M_FLAG_PERMANENT Indicates whether to modify the permanent
process affinities in addition to the
current image copy. If CAP$M_FLAG_
PERMANENT is set, then both the permanent
and current affinities are modified.
If the flag bit is clear or flags is
unspecified, then just the current image
process affinities are modified.
This bit also determines which of the
affinity masks are returned in prev_
mask. If set, the permanent mask, used
to reinitialize the current set at image
rundown, is returned. If the bit is clear
or the flags argument is not specified,
the current running mask is returned.
CAP$M_FLAG_CHECK_CPU Determines whether the kernel thread
can be left in a nonrunnable state under
some circumstances. No operation of this
service will allow a transition from a
runnable to blocked state; however, if
the kernel thread is already at a blocked
state, this bit determines whether the
result of the operation must leave it
runnable. If CAP$M_FLAG_CHECK_CPU is set
or flags is unspecified, the kernel thread
will be checked to ensure it can safely
run on one of the CPUs in the active set;
otherwise, any valid state operations on
kernel threads already in a blocked state
will be allowed.
CAP$M_FLAG_CHECK_CPU_ Indicates whether a check is made to
ACTIVE verify that all CPUs in the select mask
that are about to be selected for affinity
binding are in the active set. This does
not apply to CPUs that are about to be
cleared from the current affinity set.
Unlike CAP$M_FLAG_CHECK_CPU where only
a single CPU has to be valid for the
condition to pass, CAP$M_FLAG_CHECK_
CPU_ACTIVE requires that all CPUs in the
selected set must pass the criteria.
|
195 - $PROCESS CAPABILITIES (Alpha Only)
|
On Alpha systems, allows modification of the user capability set
for a specified kernel thread, or for the global user capability
process default.
This service accepts 64-bit addresses.
Format
SYS$PROCESS_CAPABILITIES [pidadr] [,prcnam] [,select_mask]
[,modify_mask] [,prev_mask] [,flags]
C Prototype
int sys$process_capabilities (unsigned int *pidadr, void
*prcnam, struct _generic_64
*select_mask, struct _generic_64
*modify_mask, struct _generic_64
*prev_mask, struct _generic_64
*flags);
195.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Process identification (PID) of a kernel thread whose user
capability mask is to be modified or returned. The pidadr
argument is the 32- or 64-bit address of a longword that contains
the PID.
Process selection is made through a combination of the pidadr and
prcnam arguments. If neither are specified or if both have a zero
value, the service operations are made to the user capability
mask of the current kernel thread of the calling process. The
pidadr argument takes precedence over the prcnam argument where
both are supplied in the service call.
If the constant CAP$M_FLAG_DEFAULT_ONLY is specified in flags,
then the user portion of the default process user capability
mask is modified or returned instead, regardless of the values
specified in pidadr.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Process name of the process whose user capability mask is to
be modified or returned. The prcnam argument is the 32- or 64-
bit address of a character string descriptor pointing to the
process name string. A process can be identified with a 1- to
15-character string. The service operations are made to the user
capability mask of the initial thread of the specified process.
You can use the prcnam argument only if the process identified
by the descriptor has the same UIC group number as the calling
process. To obtain information about processes in other groups,
the pidadr argument must be used.
If pidadr and prcnam are both specified, then prcnam is ignored.
If neither argument is specified, then the context of the current
kernel thread of the calling process is modified or returned.
select_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying which bits of the specified process' user
capability mask are to be modified. The select_mask argument
is the 32- or 64-bit address of a quadword bit vector wherein a
bit, when set, specifies that the corresponding user capability
is to be modified.
The individual user capability bits in select_mask can be
referenced by their symbolic bit constant names, CAP$M_USER1
through CAP$M_USER16. These constants (not zero-relative) specify
the position in the mask quadword that corresponds to the bit
name. Multiple capabilities can be selected by ORing together the
appropriate bits.
Alternatively, the constant CAP$K_ALL_USER, when specified as the
select_mask argument, selects all user capabilities.
modify_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying the settings for those capabilities selected in
the select_mask argument. The modify_mask argument is the 32- or
64-bit address of a quadword bit vector wherein a bit, when set,
specifies that the corresponding user capability is to be added
to the specified kernel thread; when clear, the corresponding
user capability is to be removed.
The symbolic bit constants CAP$M_USER1 through CAP$M_USER16 can
be used to modify the appropriate bit position in modify_mask.
Multiple capabilities can be modified by ORing together the
appropriate bits.
To add a specific user capability to a kernel thread, that bit
position must be set in both select_mask and modify_mask. To
remove a specific user capability from a kernel thread, that bit
position must be set in select_mask and clear in modify_mask.
The symbolic constant CAP$K_ALL_USER_ADD, when specified in
modify_mask, indicates that all capabilities specified in
select_mask are to be added to the appropriate capability set.
The symbolic constant CAP$K_ALL_USER_REMOVE indicates that all
specified capabilities are to be removed from the set.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Previous user capability mask for the specified process or thread
before execution of this call to $PROCESS_CAPABILITIES. The
prev_mask argument is the 32- or 64-bit address of a quadword
into which $PROCESS_CAPABILITIES writes the previous bit mask.
If CAP$M_FLAG_DEFAULT_ONLY is set in the flags argument, then
prev_mask will contain the user portion of the global default
capability mask.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for the user capability modification. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option. Only the bits specified below are used; the remainder of
the quadword bits are reserved and must be zero.
Each option (bit) has a symbolic name, defined by the $CAPDEF
macro. The flags argument is constructed by performing a logical
OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:
Symbolic Name Description
CAP$M_FLAG_DEFAULT_ Indicates that the specified operations
ONLY are to be performed on the global
context cell instead of on a specific
kernel thread. This bit supersedes any
individual kernel thread specified in
pidadr or prcnam. Specifying this bit
constant applies the service operations
to the capabilities for all newly created
processes.
CAP$M_FLAG_PERMANENT Indicates whether to modify the permanent
user process capabilities in addition to
the current image copy. If CAP$M_FLAG_
PERMANENT is set, then both the permanent
and current user process capabilities are
modified. If this bit is clear or flags is
unspecified, then just the current image
process capabilities are modified.
This bit also determines which of the
capability masks are returned in prev_
mask. If set, the permanent mask, used
to reinitialize the current set at image
rundown, is returned. If the bit is clear
or the flags argument is not specified,
the current running mask is returned.
CAP$M_FLAG_CHECK_CPU Determines whether the kernel thread can
be left in a nonrunnable state under some
circumstances. No operation of this
service will allow a transition from
runnable to blocked state; however, if
the kernel thread is already at a blocked
state, this bit determines whether the
result of the operation must leave it
runnable. If CAP$M_FLAG_CHECK_CPU is set
or flags is unspecified, the kernel thread
will be checked to ensure it can safely
run on one of the CPUs in the active set;
otherwise, any state operations on kernel
threads already in a blocked state will be
allowed.
Creates and initializes a process context that is used by $GETJPI
to scan processes on the local system or across the nodes in an
OpenVMS Cluster system.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$PROCESS_SCAN pidctx [,itmlst]
C Prototype
int sys$process_scan (unsigned int *pidctx, void *itmlst);
196.1 - Arguments
pidctx
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Context value supplied by $PROCESS_SCAN to be used as the pidadr
argument of $GETJPI. The pidctx argument is the 32-bit address
(on VAX systems) or the 32- or 64-bit address (on Alpha systems)
of a longword that is to receive the process context longword.
This longword normally contains 0 or a previous context. If it
contains a previous context, the old context is deleted. If it
contains a value other than 0 or a previous context, the old
value is ignored.
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 selection criteria to be used by the scan or
to control the scan.
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 one selection criterion or
control option. Within each selection criterion you can include
several item entries. 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 information in the item list is passed to the item descriptor
in one of two ways. If the item descriptor can always hold the
actual value of the selection criterion, the value is placed in
the second longword of the item descriptor and the buffer length
is specified as 0. If the item descriptor points to the actual
value of the selection criterion, the address of the value is
placed in the second longword of the item descriptor and you must
specify the buffer length for the selection criterion. Each item
code description specifies whether the information is passed by
value or by reference.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
Removes a specified range of pages from the current working set
of the calling process to make room for pages required by a new
program segment.
Format
SYS$PURGWS inadr
C Prototype
int sys$purgws (struct _va_range *inadr);
197.1 - Argument
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
purged. The inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses. The addresses are adjusted up or down to fall on CPU-
specific page boundaries. Only the virtual page number portion of
each virtual address is used; the low-order byte-within-page bits
are ignored.
|
198 - $PURGE WS (Alpha Only)
|
On Alpha systems, removes a specified range of pages from the
current working set of the calling process to make room for pages
required by a new program segment.
This service accepts 64-bit addresses.
Format
SYS$PURGE_WS start_va_64 ,length_64
C Prototype
int sys$purge_ws (void *start_va_64, unsigned __int64
length_64);
198.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be purged from the
working set. The specified virtual address will be rounded down
to a CPU-specific page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be purged from the working
set. The specified length will be rounded up to a CPU-specific
page boundary so that it includes all CPU-specific pages in the
requested range.
Writes informational and error messages to processes.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$PUTMSG msgvec ,[actrtn] ,[facnam] ,[actprm]
C Prototype
int sys$putmsg (void *msgvec, void
(*actrtn)(__unknown_params), void *facnam,
unsigned __int64 actprm);
199.1 - Arguments
msgvec
OpenVMS usage:cntrlblk
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Message argument vector specifying the message or messages to be
written and options that $PUTMSG is to use in writing the message
or messages. The msgvec argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of the
message vector.
The message vector consists of one longword followed by one or
more message descriptors, one descriptor per message.
Refer to the OpenVMS System Services Reference Manual to view
the diagram of the contents of the first longword and the message
vector fields table.
actrtn
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
User-supplied action routine to be executed during message
processing. The actrtn argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of this
routine.
Note that the first argument passed to the action routine is the
address of a character string descriptor pointing to the message
text; the parameter specified by actprm is the second.
The action routine receives control after a message is formatted
but before it is actually written to the user.
The completion code in general register R0 from the action
routine indicates whether the message should be written. If the
low-order bit of R0 is set (1), then the message will be written.
If the low-order bit is cleared (0), then the message will not be
written.
If you do not specify actrtn or specify it as 0 (the default), no
action routine executes.
Because $PUTMSG writes messages only to SYS$ERROR and SYS$OUTPUT,
an action routine is useful when output must be directed to, for
example, a file.
facnam
OpenVMS usage:char_string
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)
Facility prefix to be used in the first or only message written
by $PUTMSG. The facnam argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of a
character string descriptor pointing to this facility prefix.
If you do not specify facnam, $PUTMSG uses the default facility
prefix associated with the message.
actprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Parameter to be passed to the action routine. The actprm argument
is a longword value containing this parameter. If you do not
specify actprm, no parameter is passed.
Queues an I/O request to a channel associated with a device. This
service completes asynchronously; for synchronous completion, use
the Queue I/O Request and Wait ($QIOW) service.
Format
SYS$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1]
,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
C Prototype
int sys$qio (unsigned int efn, unsigned short int chan,
unsigned int func, struct _iosb *iosb, void
(*astadr)(__unknown_params), __int64 astprm, void
*p1, __int64 p2, __int64 p3, __int64 p4, __int64
p5, __int64 p6);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag that $QIO is to set when the I/O operation completes.
The efn argument is a longword value containing the number of the
event flag; however, $QIO uses only the low-order byte.
chan
OpenVMS usage:channel
type: longword (unsigned)
access: read only
mechanism: by value
I/O channel assigned to the device to which the request is
directed. The chan argument is a longword value containing the
number of the I/O channel; however, $QIO uses only the low-order
word.
Specifying an invalid value for the chan argument will result in
either SS$_IVCHAN or SS$_IVIDENT being returned.
func
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by value
Device-specific function codes and function modifiers specifying
the operation to be performed. The func argument is a longword
containing the function code.
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 of the
I/O operation. The iosb argument is the address of the quadword
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 the I/O completes. The
astadr argument is the address of the AST routine.
The AST routine executes at the access mode of the caller of
$QIO.
astprm
OpenVMS usage:user_arg
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
mechanism: by 32-bit value (VAX)
AST parameter to be passed to the AST service routine. On Alpha
systems, the astprm argument is a quadword value containing the
AST parameter. On VAX systems, the astprm argument is a longword
value containing the AST parameter.
p1 to p6
OpenVMS usage:varying_arg
type: quadword (unsigned) (Alpha); longword unsigned
(VAX)
access: read only
mechanism: by 32- or 64-bit reference or by 64-bit value
depending on the I/O function (Alpha)
mechanism: by 32-bit reference or by 32-bit value depending on
the I/O function (VAX)
Optional device-specific and function-specific I/O request
parameters.
The Queue I/O Request and Wait service queues an I/O request to a
channel associated with a device.
The $QIOW service completes synchronously; however, Digital
recommends that you use an IOSB with this service to avoid
premature completion.
For asynchronous completion, use the Queue I/O Request ($QIO)
service.
In all other respects, $QIOW is identical to $QIO. For more
information about $QIOW, refer to the description of $QIO.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$QIOW [efn] ,chan ,func ,[iosb] ,[astadr]
,[astprm] ,[p1] ,[p2] ,[p3]
,[p4] ,[p5] ,[p6]
C Prototype
int sys$qiow (unsigned int efn, unsigned short int chan,
unsigned int func, struct _iosb *iosb, void
(*astadr)(__unknown_params), __int64 astprm,
void *p1, __int64 p2, __int64 p3, __int64 p4,
__int64 p5, __int64 p6);
Returns the current status of all 32 event flags in a local or
common event flag cluster and indicates whether the specified
event flag is set or clear.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$READEF efn ,state
C Prototype
int sys$readef (unsigned int efn, unsigned int *state);
202.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag in the cluster whose status is to be
returned. The efn argument is a longword containing this number;
however, $READEF uses only the low-order byte. Specifying an
event flag within a cluster requests that $READEF return the
status of all event flags in that cluster.
There are two local event flag clusters, which are local to the
process: cluster 0 and cluster 1. Cluster 0 contains event flag
numbers 0 to 31, and cluster 1 contains event flag numbers 32 to
63.
There are two common event flag clusters: cluster 2 and cluster
3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
contains event flag numbers 96 to 127.
state
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
State of all event flags in the specified cluster. The state
argument is the 32- or 64-bit address (on Alpha systems) or the
32-bit address (on VAX systems) of a longword into which $READEF
writes the state (set or clear) of the 32 event flags in the
cluster.
|
203 - $REGISTRY (Alpha Only)
|
Interface to the OpenVMS Registry database server.
The $REGISTRY service allows you to query, update, and set keys,
subkeys, and values in the OpenVMS Registry database.
The $REGISTRY service supports both asynchronous and synchronous
operations. For asynchronous completion, use the Registry
($REGISTRY) system service.
For synchronous completion, use the Registry and Wait
($REGISTRYW) system service. The $REGISTRYW system service is
identical to the $REGISTRY system service, except that $REGISTRYW
returns to the caller after the system completes the requested
operation. For additional information about system service
completion, see the Synchronize ($SYNCH) system service.
This system service is 64-bit compatible.
Format
SYS$REGISTRY [efn] ,func ,0 ,itmlst ,[iosb or iosa_64]
[,astadr or astadr_64] [,astprm or astprm_64]
[,timeout]
C Prototype
int sys$registry (unsigned int efn, unsigned int func, void *,
void *itmlst, struct _iosb *iosb, ...);
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be used by $REGISTRY. If you do not
specify the event flag, the system defaults to event flag 0. The
event flag is initially cleared by $REGISTRY and then set when
the operation completes.
func
VMS Usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function code specifying the action that $REGISTRY is to perform.
The func argument is a longword containing this function code.
The function code can contain function modifiers. For more
information on function modifiers, see the Function Modifiers
section.
A single call to $REGISTRY can specify only one function code.
All function codes require additional information to be passed in
the call with the itmlst argument.
itmlst
VMS 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 supplying information that the system will use to
perform the function specified by the func argument.
The itmlst argument is the address of the item list. The item
list consists of one or more sets of item descriptors. Each
descriptor is either an item_list_3 or item_list_64b format.
Some function codes allow you to specify multiple operations in
a single call. In this case, you must place the REG$_SEPARATOR
item code between each set of item codes. Each request, separated
by a REG$_SEPARATOR item code, can contain the item codes in any
order.
You can specify item codes as either input or output parameters.
Input parameters modify functions, set context, or describe
the information to be returned. Output parameters return the
requested information.
For item_list_3 lists, you must terminate the list with a
longword of 0. For item_list_64b lists, you must terminate the
list with a quadword of 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
iosb or iosa_64
OpenVMS usage:status_block
type: buffer
access: write only
mechanism: by reference
Status block to receive the final completion status and
information of the $REGISTRY operation.
If multiple operations are requested for a function code, the
value returned in iosb is either SS$_NORMAL or SS$_REGERROR.
A more specific return status for each operation is returned in
the REG$_RETURNSTATUS item code (if specified).
The iosb argument is the address of the $REGISTRY status block.
Refer to the OpenVMS System Services Reference Manual to view the
diagram.
When $REGISTRY begins execution, it clears the quadword I/O
status block if you specify the iosb argument.
Although the iosb argument is optional, Compaq 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 system 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 $REGISTRY service. The
condition value returned in R0 provides information about the
success or failure of the service call itself; the condition
value returned in the I/O status block provides information about
the success or failure of the service operation.
To assess the success or failure of the call to $REGISTRY
accurately, you must first check the condition value returned
in R0. If R0 contains a successful value, you must check the
condition value in the I/O status block.
The following table defines the item descriptor fields:
Descriptor
Field Definition
Status A longword specifying the final status of the
$REGISTRY service. If you request multiple
operations for a function code, the system returns
either SS$_NORMAL or SS$_REGERROR to iosb. This
field is set to 0 (zero) when the operation
begins.
Reserved A reserved longword.
astadr or astadr_64
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $REGISTRY completes. The
astadr argument is the address of this routine. If you specify
astadr, the AST routine executes at the same access mode as the
caller of the $REGISTRY service.
If the $REGISTRY service is not called successfully (that is,
if it returns an error immediately), the AST routine is not
executed.
astprm or astprm_64
VMS 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 specifies this
longword parameter.
timeout
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Timeout value specifies the number of seconds allotted to
$REGISTRY to perform the request. If the Registry server does
not complete the request within the time you allot, $REGISTRY
returns REG-F-NORESPONSE.
|
204 - $REGISTRYW (Alpha Only)
|
Interface to the OpenVMS Registry database server.
The $REGISTRY service supports both asynchronous and synchronous
operations. For asynchronous completion, use the Registry
($REGISTRY) system service.
For synchronous completion, use the Registry and Wait
($REGISTRYW) system service. The $REGISTRYW system service is
identical to the $REGISTRY system service, except that $REGISTRYW
returns to the caller after the system completes the requested
operation. For additional information about system service
completion, see the Synchronize ($SYNCH) system service.
This system service is 64-bit compatible.
Format
SYS$REGISTRYW [efn] ,func ,0 ,itmlst ,[iosb or iosa_64]
[,astadr or astadr_64] [,astprm or astprm_64]
[,timeout]
C Prototype
int sys$registryw (unsigned int efn, unsigned int func, void
*, void *itmlst, struct _iosb *iosb, ...);
|
205 - $RELEASE GALAXY LOCK (Alpha Only)
|
Releases ownership 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 OpenVMS Alpha Partitioning and Galaxy
Guide.
Format
SYS$RELEASE_GALAXY_LOCK handle
C Prototype
int sys$release_galaxy_lock (unsigned __int64 lock_handle);
205.1 - Arguments
handle
OpenVMS usage:galaxy lock handle
type: quadword (unsigned)
access: read
mechanism: input by value
The 64-bit lock handle that identifies the lock to be released.
This value is returned by SYS$CREATE_GALAXY_LOCK.
|
206 - $RELEASE VP (VAX Only)
|
On VAX systems, terminates the current process' status as a
vector consumer.
Format
SYS$RELEASE_VP
206.1 - Arguments
None.
Deletes the specified holder record from the target identifier's
list of holders.
Format
SYS$REM_HOLDER id ,holder
C Prototype
int sys$rem_holder (unsigned int id, struct _generic_64
*holder);
207.1 - Arguments
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of target identifier whose holder is deleted when
$REM_HOLDER completes execution. The id argument is a longword
containing the identifier value.
holder
OpenVMS usage:rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Identifier of holder being deleted when $REM_HOLDER completes
execution. The holder argument is the address of a quadword
containing the UIC identifier of the holder in the first longword
and the value of 0 in the second longword.
Removes the specified identifier record and all its holder
records (if any) from the rights database.
Format
SYS$REM_IDENT id
C Prototype
int sys$rem_ident (unsigned int id);
208.1 - Argument
id
OpenVMS usage:rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of identifier deleted from rights database when
$REM_IDENT completes execution. The id argument is a longword
containing the identifier value.
Requests reschedule of a process.
Format
SYS$RESCHED
C Prototype
int sys$resched (void);
209.1 - Arguments
None.
|
210 - $RESTORE VP EXCEPTION (VAX Only)
|
On VAX systems, restores the saved exception state of the vector
processor.
Format
SYS$RESTORE_VP_EXCEPTION excid
210.1 - Argument
excid
OpenVMS usage:context
type: longword (unsigned)
access: read only
mechanism: by reference
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION.
The excid argument is the address of a longword containing this
ID.
|
211 - $RESTORE VP STATE (VAX Only)
|
On VAX systems, allows an AST routine or condition handler to
restore the vector state of the mainline routine.
Format
SYS$RESTORE_VP_STATE
211.1 - Arguments
None.
Causes a process previously suspended by the Suspend Process
($SUSPND) service to resume execution or cancels the effect of a
subsequent suspend request.
Format
SYS$RESUME [pidadr] ,[prcnam]
C Prototype
int sys$resume (unsigned int *pidadr, void *prcnam);
212.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be resumed. The
pidadr argument is the address of a longword containing the PID.
The pidadr argument can refer to a process running on the local
node or a process running on another node in the cluster.
You must specify the pidadr argument to delete processes in other
UIC groups.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the process to be resumed. The prcnam argument is the
address of a character string descriptor pointing to the process
name.
A process running on the local node can be identified with a 1-
to 15-character string. To identify a process on a particular
node on a cluster, specify the full process name, which includes
the node name as well as the process name. The full process name
can contain up to 23 characters.
You can use the prcnam argument to resume only processes in the
same UIC group as the calling process, because process names
are unique to UIC groups, and the operating system uses the UIC
group number of the calling process to interpret the process
name specified by the prcnam argument. You must use the pidadr
argument to delete processes in other UIC groups.
Removes the specified identifier from the rights list of the
process or the system. If the identifier is listed as a holder
of any other identifier, the appropriate holder records are also
deleted.
Format
SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]
C Prototype
int sys$revokid (unsigned int *pidadr, void *prcnam, struct
_generic_64 *id, void *name, unsigned int
*prvatr, unsigned int segment);
213.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) number of the process affected when
$REVOKID completes execution. The pidadr argument is the address
of a longword containing the PID of the process to be affected.
You use -1 to indicate the system rights list. When pidadr is
passed, it is also returned; therefore, you must pass it as a
variable rather than a constant.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name on which $REVOKID operates. The prcnam argument
is the address of a character string descriptor containing the
process name. The maximum length of the name is 15 characters.
Because the UIC group number is interpreted as part of the
process name, you must use pidadr to specify the rights list
of a process in a different group.
id
OpenVMS usage:rights_id
type: quadword (unsigned)
access: modify
mechanism: by reference
Identifier and attributes to be removed when $REVOKID completes
execution. The id argument is the address of a quadword
containing the binary identifier code to be removed in the first
longword and the attributes in the second longword.
Symbol values are offsets to the bits within the longword. You
can also obtain the values as masks with the appropriate bit set
using the prefix KGB$M rather than KGB$V. The following symbols
for each bit position are defined in the system macro library
($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows unprivileged holders of the
identifier to remove it from or add it
to the process rights database by using
the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS Makes any access rights of the identifier
null and void. This attribute is intended
as a modifier for a resource identifier or
the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge
disk space to the identifier. It is used
only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to
create and maintain protected subsystems
by assigning the Subsystem ACE to the
application images in the subsystem.
You must specify either id or name. Because the id argument is
returned as well as passed if you specify name, you must pass it
as a variable rather than a constant in this case.
name
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the identifier removed when $REVOKID completes execution.
The name argument is the address of a descriptor pointing to the
name of the identifier.
prvatr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes of the deleted identifier. The prvatr argument is
the address of a longword used to store the attributes of the
identifier.
Closes all files opened by OpenVMS RMS for the image or process
and halts I/O activity. This routine performs a $CLOSE service
for each file opened for processing.
Format
SYS$RMSRUNDWN buf-addr ,type-value
C Prototype
int sys$rmsrundwn ( void *buf-addr, unsigned char
*type-value);
214.1 - Arguments
buf-addr
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor
A descriptor pointing to a 22-byte buffer that is to receive the
device identification (16 bytes) and the file identification (6
bytes) of an improperly closed output file. The buf-addr argument
is the address of the descriptor that points to the buffer.
type-value
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value
A single byte code that specifies the type of I/O rundown to be
performed. The type-value argument is the actual value used.
This type of code has the following values and meanings:
0 Rundown of image and indirect I/O for process permanent
files.
1 Rundown of image and process permanent files. The caller's
mode must not be user.
2 Abort RMS I/O. The caller's mode must be either executive
or kernel (the system calls the I/O rundown control routine
with this argument for process deletion).
|
215 - $SAVE VP EXCEPTION (VAX Only)
|
On VAX systems, saves the pending exception state of the vector
processor.
Format
SYS$SAVE_VP_EXCEPTION excid
215.1 - Argument
excid
OpenVMS usage:context
type: longword (unsigned)
access: read only
mechanism: by reference
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION.
The excid argument is the address of a longword containing this
ID.
Scans the intrusion database for suspects or intruders during a
login attempt, audits login failures and updates records, or adds
new records to the intrusion database.
Format
SYS$SCAN_INTRUSION logfail_status ,failed_user ,job_type
,[source_terminal] ,[source_node]
,[source_user] ,[source_address]
,[failed_password] ,[parent_user]
,[parent_id] ,[flags]
C Prototype
int sys$scan_intrusion (unsigned int logfail_status,
void *failed_user, unsigned int
job_type, void *source_terminal, void
*source_node, void *source_user, void
*source_address, void *failed_password,
void *parent_user, unsigned int
parent_id, unsigned int flags);
216.1 - Arguments
logfail_status
OpenVMS usage:status code
type: longword (unsigned)
access: read only
mechanism: by value
Reason why the user's login attempt failed. The logfail_status
argument is a longword containing the login failure status code.
The logfail_status argument can contain any valid message code.
For example, the value of the logfail_status argument is SS$_
NOSUCHUSER if the user name the user entered does not exist on
the system.
If the logfail_status argument contains a failure status, the
service performs a suspect scan. Here, the service searches the
intrusion database for intruder suspects as well as intruders.
If the value of the logfail_status argument is a successful
message, such as SS$_NORMAL, the service scans the database only
for intruders. For more information about how the database works,
refer to the OpenVMS Guide to System Security.
failed_user
OpenVMS usage:char_string or item_list_3
type: character-coded text string or longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length string descriptor or by
reference
If the CIA$M_ITEMLIST flag is FALSE:
This argument is the user name associated with the unsuccessful
login attempt. The failed_user argument is the address of a
character-string descriptor pointing to the failed user name.
A failed user name consists of 1 to 32 alphanumeric characters.
If the CIA$M_ITEMLIST flag is TRUE:
The failed_user argument is the address of a 32-bit item list. If
the item list is used, one item, the CIA$_FAILED_USERNAME item,
must be present in the item list.
The following table lists the valid item descriptions for the
failed_user argument:
Item Description
CIA$_FAILED_ Address of a buffer containing the failed user
USERNAME name.
CIA$_SCSNODE Address of the 8-character null-padded SCS
node name on which the intrusion happened.
CIA$_USER_DATA Address of a 256-byte buffer, available for
passing third party specified data.
job_type
OpenVMS usage:job type
type: longword (unsigned)
access: read only
mechanism: by value
Type of job that failed. The job_type argument is a longword
indicating the type of job that failed.
The $JPIDEF macro defines the following values for the job_type
argument:
o JPI$K_BATCH
o JPI$K_DETACHED
o JPI$K_DIALUP
o JPI$K_LOCAL
o JPI$K_NETWORK
o JPI$K_REMOTE
source_terminal
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Source terminal where the login attempt is occurring. The source_
terminal argument is the address of a character-string descriptor
pointing to the device name of the terminal from which the login
attempt originates.
A source terminal device name consists of 1 to 64 alphanumeric
characters, including underscores (_) and colons (:).
source_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the node from which the user's login attempt originates.
The source_node argument is the address of a character-string
descriptor pointing to the source node name string.
A source node name consists of 1 to 1024 characters. No specific
characters, format, or case is required for a source node name
string.
source_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
User name associated with the login attempt. The source_user
argument is the address of a character-string descriptor pointing
to the source user name string.
A source user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($) and underscores (_).
source_addr
OpenVMS usage:node address
type: descriptor
access: read only
mechanism: by reference
Source DECnet for OpenVMS address from which the login attempt
originates. The source_addr argument is the address of a
descriptor containing the source node address.
failed_password
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Password the user entered for the login attempt. The failed_
password argument is the address of a character-string descriptor
pointing to the plaintext password the user entered to log in.
A failed password is a password of 0 to 32 characters that did
not allow the user to log in to the system. This argument is not
stored in the intrusion database and is only used for auditing
during break-in attempts.
parent_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Parent process name of the failed login. The parent_user argument
is the address of a character-string descriptor pointing to the
parent process name of the failed login process.
A parent process name consists of 1 to 15 characters. This
argument should be specified only for failed spawn commands.
parent_id
OpenVMS usage:process_id
type: longword (unsigned)
access: read only
mechanism: by value
Process identification of the parent process from which the login
was attempted. The parent_id argument is a longword containing
the parent process identification.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Operational instructions for the service. The flags argument is a
longword bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $CIADEF macro defines
the following valid names for the $SCAN_INTRUSION service:
Symbolic Name Description
CIA$M_NOAUDIT If set, this flag indicates that the service
should instruct the security server to not
audit the login failure or the break-in
attempt. If the flag is set, you are expected
to do your own auditing.
CIA$M_IGNORE_ Specifies that the service should not wait for
RETURN the return status from the security server. No
return status from the server's function will
be returned to the caller.
CIA$M_ITEMLIST If FALSE, the failed_user argument is a
character string. If TRUE, this argument is
a 32-bit item list.
CIA$M_REAL_ If set, indicates that the user name passed as
USERNAME the failed user name is read and known to the
system.
CIA$M_SECONDARY_ Indicates that the failed password passed to
PASSWORD the service was the secondary password. If the
flag is clear, the password is assumed to be
the primary password.
Schedules the awakening (restarting) of a process that has placed
itself in a state of hibernation with the Hibernate ($HIBER)
service.
Format
SYS$SCHDWK [pidadr] ,[prcnam] ,daytim ,[reptim]
C Prototype
int sys$schdwk (unsigned int *pidadr, void *prcnam, struct
_generic_64 *daytim, struct _generic_64
*reptim);
217.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be awakened. The
pidadr argument is the address of a longword containing the PID.
The pidadr argument can refer to a process running on the local
node or a process running on another node in the OpenVMS Cluster
system.
You must specify the pidadr argument to awaken processes in other
UIC groups.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the process to be awakened. The prcnam is the address
of a character string descriptor pointing to the process name. A
process running on the local node can be identified with a string
of from 1 to 15 characters.
To identify a process on a particular node on a cluster, specify
the full process name, which includes the node name as well as
the process name. The full process name can contain up to 23
characters.
You can use the prcnam argument to awaken only processes in the
same UIC group as the calling process because process names are
unique to UIC groups, and the operating system uses the UIC
group number of the calling process to interpret the process
name specified by the prcnam argument. You must use the pidadr
argument to awaken processes in other UIC groups.
daytim
OpenVMS usage:date_time
type: quadword
access: read only
mechanism: by reference
Time at which the process is to be awakened. The daytim argument
is the address of a quadword containing this time in the system
64-bit time format. A positive time value specifies an absolute
time at which the specified process is to be awakened. A negative
time value specifies an offset (delta time) from the current
time.
reptim
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time interval at which the wakeup request is to be repeated.
The reptim argument is the address of a quadword containing this
time interval. The time interval must be expressed in delta time
format.
The time interval specified cannot be less than 10 milliseconds;
if it is, $SCHDWK automatically increases it to 10 milliseconds.
If you do not specify reptim, a default value of 0 is used, which
specifies that the wakeup request is not to be repeated.
Affects process scheduling. This service is intended for use by a
class scheduler process.
Format
SYS$SCHED func ,p1 ,p2 ,p3
C Prototype
int sys$sched (unsigned int func, unsigned int *p1, unsigned
int *p2, unsigned int *p3);
218.1 - Arguments
func
OpenVMS usage:function_code
type: longword (unsigned)
access: write only
mechanism: by value
Function code specifying the action $SCHED is to perform. The
func argument is a longword containing this code.
Refer to the OpenVMS System Services Reference Manual for a list
of the valid function codes for $SCHED.
p1, p2, p3
OpenVMS usage:longword
type: longword (unsigned)
access: varies
mechanism: varies
The meaning of the p1, p2, and p3 arguments depends on the
function code specified in the func argument, and is defined
in the Function Codes section.
Enables or disables the delivery of asynchronous system traps
(ASTs) for the access mode from which the service call was
issued.
Format
SYS$SETAST enbflg
C Prototype
int sys$setast (char enbflg);
219.1 - Argument
enbflg
OpenVMS usage:boolean
type: byte (unsigned)
access: read only
mechanism: by value
Value specifying whether ASTs are to be enabled. The enbflg
argument is a byte containing this value. The value 1 enables
AST delivery for the calling access mode; the value 0 disables
AST delivery.
Establishes a request for notification when an OpenVMS Cluster
configuration event occurs.
Format
SYS$SETCLUEVT event ,astadr ,[astprm] ,[acmode] ,[handle]
C Prototype
int sys$setcluevt (unsigned int event, void
(*astadr)(__unknown_params), int
astprm, unsigned int acmode, struct
_generic_64 *handle);
220.1 - Arguments
event
OpenVMS usage:event_code
type: longword (unsigned)
access: read only
mechanism: by value
Event code indicating the type of cluster configuration event for
which an AST is to be delivered. The event argument is a value
indicating which type of event is of interest.
Each event type has a symbolic name. The $CLUEVTDEF macro defines
the following symbolic names:
Symbolic Name Description
CLUEVT$C_ADD One or more OpenVMS nodes have been added to
the OpenVMS Cluster system.
CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed
from the OpenVMS Cluster system.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Notification AST routine to receive control after a change in
OpenVMS Cluster configuration occurs.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Optional AST parameter to be passed to the AST service routine.
The astprm argument is a longword value containing the AST
parameter.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Optional access mode at which the configuration event AST is to
execute. The acmode argument is a longword containing the access
mode.
Each access mode has a symbolic name. The $PSLDEF macro defines
the following symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The value of the access mode must not be more privileged than the
access mode of the caller.
handle
OpenVMS usage:identifier
type: quadword (unsigned)
access: write only
mechanism: by reference
Optional identifier to receive a value that uniquely identifies
this AST request. $SETCLUEVT sets this handle to a unique value
so that it can later be used to identify the request in the
$CLRCLUEVT and $TSTCLUEVT services.
Allows you to read and change the default directory string for
the process.
Format
SYS$SETDDIR [new-dir-addr] ,[length-addr] ,[cur-dir-addr]
C Prototype
int sys$setddir (void *newdiraddr, unsigned short int
*lengthaddr, void *curdiraddr);
221.1 - Arguments
new-dir-addr
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
A descriptor of the new default directory. The new-dir-addr
argument is the address of the descriptor that points to the
buffer containing the new directory specification that RMS will
use to set the new process-default directory. If the default
directory is not to be changed, the value of the new-dir-addr
argument should be 0.
length-addr
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
A word that is to receive the length of the current default
directory. The length-addr argument is the address of the word
that will receive the length. If you do not want this value
returned, specify the value 0.
cur-dir-addr
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
A descriptor of a buffer that is to receive the current default
directory string. The cur-dir-addr argument is the address of the
descriptor that points to the buffer area that is to receive the
current directory string.
Allows you to read and write the default file protection for the
process.
Format
SYS$SETDFPROT [new-def-prot-addr] ,[cur-def-prot-addr]
C Prototype
int sys$setdfprot (unsigned short int *newdefprotaddr,
unsigned short int *curdefprotaddr);
222.1 - Arguments
new-def-prot-addr
OpenVMS usage:file_protection
type: word (unsigned)
access: read only
mechanism: by reference
A word that specifies the new default file protection
specification. The new-def-prot-addr argument is the address
of the word that specifies the desired protection. If you do not
want the process-default file protection to be changed, specify
the value 0.
cur-def-prot-addr
OpenVMS usage:file_protection
type: word (unsigned)
access: write only
mechanism: by reference
A word that is to receive the current default file protection
specification. The cur-def-prot-addr argument is the address of
the word that receives the current process-default protection. If
you do not want the current default file protection, specify the
value 0.
Sets an event flag in a local or common event flag cluster.
The condition value returned by $SETEF indicates whether the
specified flag was previously set or clear. After the event flag
is set, processes waiting for the event flag to be set resume
execution.
Format
SYS$SETEF efn
C Prototype
int sys$setef (unsigned int efn);
223.1 - Argument
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set. The efn argument is a
longword containing this number; however, $SETEF uses only the
low-order byte.
Two local event flag clusters are local to the process: cluster 0
and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and
cluster 1 contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster
3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
contains event flag numbers 96 to 127.
Assigns a condition handler address to the primary, secondary, or
last chance exception vectors, or removes a previously assigned
handler address from any of these three vectors.
Format
SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]
C Prototype
int sys$setexv (unsigned int vector, int
(*addres)(__unknown_params), unsigned
int acmode, void *(*(prvhnd)));
224.1 - Arguments
vector
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Vector for which a condition handler is to be established or
removed. The vector argument is a longword value. The value
0 (the default) specifies the primary exception vector; the
value 1, the secondary vector; and the value 2, the last chance
exception vector.
addres
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Condition handler address to be established for the exception
vector specified by the vector argument. The addres argument is
a longword value containing the address of the condition handler
routine.
If you do not specify addres or specify it as the value 0, the
condition handler address already established for the specified
vector is removed; that is, the contents of the longword vector
is set to 0.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the exception vector is to be modified.
The acmode argument is a longword containing the access mode. The
$PSLDEF macro defines symbols for the four access modes.
The most privileged access mode used is the access mode of the
caller. Exception vectors for access modes more privileged than
the caller's access mode cannot be modified.
prvhnd
OpenVMS usage:procedure value
type: longword (unsigned)
access: write only
mechanism: by reference
Previous condition handler address contained by the specified
exception vector. The prvhnd argument is the address of a
longword into which $SETEXV writes the handler's procedure value.
Changes the value of, or recalibrates, the system time.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$SETIME [timadr]
C Prototype
int sys$setime (struct _generic_64 *timadr);
225.1 - Argument
timadr
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
New absolute time value for the system time, specifying the
number of 100-nanosecond intervals since 00:00 o'clock, November
17, 1858. The timadr argument is the 32-bit address (on VAX
systems) or the 32- or 64-bit address (on Alpha systems) of a
quadword containing the new system time value. A negative (delta)
time value is invalid.
If you do not specify the value of timadr or specify it as 0,
$SETIME recalibrates the system time using the time-of-year
clock.
Sets the timer to expire at a specified time.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]
C Prototype
int sys$setimr (unsigned int efn, struct _generic_64 *daytim,
void (*astadr)(__unknown_params), unsigned
__int64 reqidt, unsigned int flags);
226.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag to be set when the timer expires. The efn argument
is a longword value containing the number of the event flag;
however, $SETIMR uses only the low-order byte.
If you do not specify efn, event flag 0 is set.
When $SETIMR first executes, it clears the specified event flag
or event flag 0.
daytim
OpenVMS usage:date_time
type: quadword
access: read only
mechanism: by 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Time at which the timer expires. The daytim argument is the
64-bit address (on Alpha systems) or the 32-bit address (on
VAX systems) of a quadword time value. A positive time value
specifies an absolute time at which the timer expires; a negative
time value specifies an offset (delta time) from the current
time.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
AST service routine that is to execute when the timer expires.
The astadr argument is the 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of the procedure value
of this routine. If you do not specify the value of astadr or
specify it as 0 (the default), no AST routine executes.
The AST routine, if specified, executes at the access mode of the
caller.
reqidt
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Identification of the timer request. The reqidt argument is a
longword value containing a number that uniquely identifies the
timer request. If you do not specify reqidt, the value 0 is used.
To cancel a timer request, the identification of the timer
request (as specified by reqidt in $SETIMR) is passed to the
Cancel Timer ($CANTIM) service (as the reqidt argument).
If you want to cancel specific timer requests but not all timer
requests, be sure to specify a nonzero value for reqidt in the
$SETIMR call; $CANTIM interprets an identification value of 0 as
a request to cancel all timer requests.
You can specify unique values for reqidt for each timer request
or give the same value to related timer requests. This permits
selective canceling of a single timer request, a group of related
timer requests, or all timer requests.
If you specify the astadr argument in the $SETIMR call, the value
specified by the reqidt argument is passed as a parameter to the
AST routine. If the AST routine requires more than one parameter,
specify an address for the value of reqidt; the AST routine
can then interpret that address as the beginning of a list of
parameters.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of bit flags for the set timer operation. Currently,
only bit 0 is used for the flags argument. When the low bit (bit
0) is set, it indicates that this timer request should be in
units of CPU time, rather than elapsed time. When bit 0 is clear
(the default), the timer request is in units of elapsed time. The
flags argument is optional.
Establishes a routine to receive control after a power recovery
is detected.
Format
SYS$SETPRA astadr ,[acmode]
C Prototype
int sys$setpra (int (*astadr)(__unknown_params), unsigned int
acmode);
227.1 - Arguments
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
Power recovery AST routine to receive control when a power
recovery is detected. The astadr argument is the address of this
routine.
If you specify astadr as the value 0, an AST is not delivered to
the process when a power recovery is detected.
The system passes one parameter to the specified AST routine.
This parameter is a longword value containing the length of time
that the power was off, expressed as the number of 1/100th-of-a-
second intervals that have elapsed.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode at which the power recovery AST routine is to
execute. The acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the access modes.
The most privileged access mode used is the access mode of the
caller.
Changes the base priority of the process. The base priority is
used to determine the order in which executable processes are to
run.
Format
SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg]
,[nullarg]
C Prototype
int sys$setpri (unsigned int *pidadr, void *prcnam, unsigned
int pri, unsigned int *prvpri, unsigned int
*pol, unsigned int *prvpol);
228.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process whose priority is to
be set. The pidadr argument is the address of the PID. The pidadr
argument can refer to a process running on the local node or a
process running on another node in the cluster.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name of the process whose priority is to be changed. The
prcnam argument is the address of a character string descriptor
pointing to the process name.
A process running on the local node can be identified with a 1-
to 15-character string. To identify a process on a particular
node on a cluster, specify the full process name, which includes
the node name as well as the process name. The full process name
can contain up to 23 characters.
You can use the prcnam argument only on behalf of processes in
the same UIC group as the calling process. To set the priority
for processes in other groups, you must specify the pidadr
argument.
pri
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
New base priority to be established for the process. The pri
argument is a longword value containing the new priority.
Priorities that are not real time are in the range 0 through
15; real-time priorities are in the range 16 through 31.
If the specified priority is higher than the base priority of the
target process, and if the caller does not have ALTPRI privilege,
then the base priority of the target process is used.
prvpri
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Base priority of the process before the call to $SETPRI. The
prvpri argument is the address of a longword into which $SETPRI
writes the previous base priority of the process.
policy
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
On Alpha systems, address of a longword containing the new
scheduling policy for the process.
The $JPIDEF macro defines the following symbols for the policy
argument:
Symbol Meaning
JPI$K_DEFAULT_ The normal scheduling policy. The priority
POLICY interval for this policy is defined as
[0..n], such that priorities [0..15] are
interactive and priorities [16..n] are real
time.
JPI$K_PSX_FIFO_ POSIX FIFO scheduling policy. The priority
POLICY interval for this policy is defined as
[n..m] real-time priorities.
JPI$K_PSX_RR_POLICY POSIX round-robin policy. The priority
interval for this policy is defined as
[n..m] real-time priorities.
prvpol
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
On Alpha systems, address of a longword into which the previous
scheduling policy for the process is written. If the policy
argument is null, no change in policy is requested and prvpol
returns the current policy.
The valid priority intervals for specific scheduling policies
might change in the future. Applications should, therefore,
not use embedded numeric constants for scheduling priority, but
should use the appropriate $GETSYI item codes to fetch the legal
priority intervals. The application can then dynamically select
a priority value that is within the interval. The $GETSYI item
codes are:
o SYI$_DEF_PRIO_MAX, SYI$_DEF_PRIO_MIN
o SYI$_PSXFIFO_PRIO_MAX, SYI$_PSXFIFO_PRIO_MIN
o SYI$_PSXRR_PRIO_MAX, SYI$_PSXRR_PRIO_MIN
Refer to the $GETSYI service description in the OpenVMS System
Services Reference Manual for more information about these item
codes.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
Allows a process to establish or to change its own process name.
Format
SYS$SETPRN [prcnam]
C Prototype
int sys$setprn ( void *prcnam);
229.1 - Argument
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name to be given to the calling process. The prcnam
argument is the address of a character string descriptor pointing
to a 1- to 15-character process name string. If you do not
specify prcnam, the calling process is given no name.
Allows a process to change the protection on a page or range of
pages.
Format
SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]
C Prototype
int sys$setprt (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, unsigned int
prot, unsigned char *prvprt);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages whose
protection is to be changed. The inadr argument is the address of
a 2-longword array containing, in order, the starting and ending
process virtual addresses.
Addresses are adjusted up or down to fall on CPU-specific page
boundaries. Only the virtual page number portion of each virtual
address is used; the low-order byte-within-page bits are ignored.
If the starting and ending virtual addresses are the same, the
protection is changed for a single page.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference or descriptor
Starting and ending virtual addresses of the range of pages whose
protection was actually changed by $SETPRT. The retadr argument
is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
If an error occurs while the protection is being changed, $SETPRT
writes into retadr the range of pages that were successfully
changed before the error occurred. If no pages were affected
before the error occurred, $SETPRT writes the value -1 into each
longword of the 2-longword array.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $SETPRT. The acmode
argument is a longword containing the access mode. The $PSLDEF
macro defines symbols for the access modes.
The $SETPRT service uses whichever of the following two access
modes is least privileged: (1) the access mode specified by
acmode or (2) the access mode of the caller. To change the
protection of any page in the specified range, the resultant
access mode must be equal to or more privileged than the access
mode of the owner of that page.
prot
OpenVMS usage:page_protection
type: longword (unsigned)
access: read only
mechanism: by value
Page protection to be assigned to the specified pages. The prot
argument is a longword value containing the protection code. Only
bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro defines the following symbolic names for the
protection codes:
Symbol Description
PRT$C_NA No access
PRT$C_KR Kernel read only
PRT$C_KW Kernel write
PRT$C_ER Executive read only
PRT$C_EW Executive write
PRT$C_SR Supervisor read only
PRT$C_SW Supervisor write
PRT$C_UR User read only
PRT$C_UW User write
PRT$C_ERKW Executive read; kernel write
PRT$C_SRKW Supervisor read; kernel write
PRT$C_SREW Supervisor read; executive write
PRT$C_URKW User read; kernel write
PRT$C_UREW User read; executive write
PRT$C_URSW User read; supervisor write
OpenVMS Alpha systems convert PRT$C_NA to the next highest
protection, kernel-read.
If you specify the protection as the value 0, the protection
defaults to kernel read only.
prvprt
OpenVMS usage:page_protection
type: byte (unsigned)
access: write only
mechanism: by reference
Protection previously assigned to the last page in the range.
The prvprt argument is the address of a byte into which $SETPRT
writes the protection of this page. The prvprt argument is useful
only when protection for a single page is being changed.
|
231 - $SETPRT 64 (Alpha Only)
|
On Alpha systems, allows a process to change the protection on a
page or range of pages.
This service accepts 64-bit addresses.
Format
SYS$SETPRT_64 start_va_64 ,length_64 ,acmode ,prot
,return_va_64 ,return_length_64 ,return_prot_64
C Prototype
int sys$setprt_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, unsigned
int prot, void *(*(return_va_64)), unsigned
__int64 *return_length_64, unsigned int
*return_prot_64);
231.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the range of pages whose
protection is to be changed. The specified virtual address will
be rounded down to a CPU-specific boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space whose protection is to
be changed. The specified length will be rounded up to a CPU-
specific page boundary so that it includes all CPU-specific pages
in the requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $SETPRT_64. The acmode
argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. To change the protection of any page in the specified
range, the resultant access mode must be equal to or more
privileged than the access mode of the owner of that page.
prot
OpenVMS usage:page_protection
type: longword (unsigned)
access: read only
mechanism: by value
Page protection to be assigned to the specified pages. The prot
argument is a longword value containing the protection code. Only
bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro for MACRO-32 and the include file PRTDEF.H for
C define the symbolic names for the protection codes.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the range of pages whose
protection was actually changed. The return_va_64 argument is
the 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range whose protection was
actually changed. The return_length_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which
the service returns the length of the virtual address range in
bytes.
return_prot_64
OpenVMS usage:page_protection
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Protection previously assigned to the last page in the range.
The return_prot_64 argument is the 32- or 64-bit virtual address
of a naturally aligned longword into which $SETPRT_64 writes the
protection of this page. The return_prot_64 argument is useful
only when protection for a single page is being changed.
Enables or disables specified privileges for the calling process.
Format
SYS$SETPRV [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]
C Prototype
int sys$setprv (char enbflg, struct _generic_64 *prvadr, char
prmflg, struct _generic_64 *prvprv);
232.1 - Arguments
enbflg
OpenVMS usage:boolean
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the specified privileges are to be
enabled or disabled. The enbflg argument is a longword value.
The value 1 indicates that the privileges specified in the prvadr
argument are to be enabled. The value 0 (the default) indicates
that the privileges are to be disabled.
prvadr
OpenVMS usage:mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference
Privileges to be enabled or disabled for the calling process. The
prvadr argument is the address of a quadword bit vector wherein
each bit corresponds to a privilege that is to be enabled or
disabled.
Each bit has a symbolic name. The $PRVDEF macro defines these
names. You form the bit vector by specifying the symbolic
name of each desired privilege in a logical OR operation. The
following table provides the symbolic name and description of
each privilege:
User
Privilege Symbolic Name Description
ACNT PRV$M_ACNT Create processes for which no
accounting is done
ALLSPOOL PRV$M_ALLSPOOL Allocate a spooled device
ALTPRI PRV$M_ALTPRI Set (alter) any process priority
AUDIT PRV$V_AUDIT Generate audit records
BUGCHK PRV$M_BUGCHK Make bugcheck error log entries
BYPASS PRV$M_BYPASS Bypass all protection
CMEXEC PRV$M_CMEXEC Change mode to executive
CMKRNL PRV$M_CMKRNL Change mode to kernel
DIAGNOSE PRV$M_DIAGNOSE Can diagnose devices
DOWNGRADE PRV$V_DOWNGRADE Can downgrade classification
EXQUOTA PRV$M_EXQUOTA Can exceed quotas
GROUP PRV$M_GROUP Group process control
GRPNAM PRV$M_GRPNAM Place name in group logical name
table
GRPPRV PRV$V_GRPPRV Group access by means of system
protection field
IMPERSONATE PRV$M_ Create detached processes under
IMPERSONATE another UIC
IMPORT PRV$V_IMPORT Mount a nonlabeled tape volume
LOG_IO PRV$M_LOG_IO Perform logical I/O operations
MOUNT PRV$M_MOUNT Issue mount volume QIO
NETMBX PRV$M_NETMBX Create a network device
OPER PRV$M_OPER All operator privileges
PFNMAP PRV$M_PFNMAP Map to section by physical page
frame number
PHY_IO PRV$M_PHY_IO Perform physical I/O operations
PRMCEB PRV$M_PRMCEB Create permanent common event flag
clusters
PRMGBL PRV$M_PRMGBL Create permanent global sections
PRMMBX PRV$M_PRMMBX Create permanent mailboxes
PSWAPM PRV$M_PSWAPM Change process swap mode
READALL PRV$V_READALL Possess read access to everything
SECURITY PRV$V_SECURITY Can perform security functions
SETPRV PRV$M_SETPRV Set any process privileges
SHARE PRV$M_SHARE Can assign a channel to a
nonshared device
SHMEM PRV$M_SHMEM Allocate structures in memory
shared by multiple processors
SYSGBL PRV$M_SYSGBL Create system global sections
SYSLCK PRV$M_SYSLCK Queue systemwide locks
SYSNAM PRV$M_SYSNAM Place name in system logical name
table
SYSPRV PRV$M_SYSPRV Access files and other resources
as if you have a system UIC
TMPMBX PRV$M_TMPMBX Create temporary mailboxes
UPGRADE PRV$V_UPGRADE Can upgrade classification
VOLPRO PRV$M_VOLPRO Override volume protection
WORLD PRV$M_WORLD World process control
If you do not specify prvadr or assign it the value 0, the
privileges are not altered.
prmflg
OpenVMS usage:boolean
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the privileges are to be affected
permanently or temporarily. The prmflg argument is a longword
value. The value 1 specifies that the privileges are to be
affected permanently, that is, until you change them again
by using $SETPRV or until the process is deleted. The value 0
(the default) specifies that the privileges are to be affected
temporarily, that is, until the current image exits (at which
time the permanently enabled privileges of the process will be
restored).
Setting the prmflg argument to nonzero changes privilege bits in
both the CURPRIV mask and the PROCPRIV mask.
prvprv
OpenVMS usage:mask_privileges
type: quadword (unsigned)
access: write only
mechanism: by reference
Privileges previously possessed by the calling process. The
prvprv argument is the address of a quadword bit vector wherein
each bit corresponds to a privilege that was previously either
enabled or disabled. If you do not specify prvprv or assign it
the value 0, the previous privilege mask is not returned.
Allows a process to specify what action system services should
take when system resources required for their execution are
unavailable.
CAUTION
Disabling resource waiting should be performed with caution,
as doing so can have unexpected effects on constituent
sharable images and runtime libraries.
Format
SYS$SETRWM [watflg]
C Prototype
int sys$setrwm ( char watflg);
233.1 - Argument
watflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether system services should wait for
required resources. The watflg argument is a longword value. The
value 0 (the default) specifies that system services should wait
until resources needed for their execution become available.
The value 1 specifies that system services should return failure
status immediately when resources needed for their execution are
unavailable.
The operating system enables resource wait mode for all
processes. You can disable resource wait mode only by calling
$SETRWM.
If resource wait mode is disabled, it remains disabled until it
is explicitly reenabled or until the process is deleted.
Controls whether a process automatically unshelves files.
Format
SYS$SETSHLV [pidadr] ,[prcnam] ,[shlvflg]
C Prototype
int sys$setshlv (unsigned int *pidadr, void *prcnam, unsigned
int shlvflg);
234.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process. The pidadr argument
is the address of the PID. The pidadr argument can only refer to
a process running on the local node. You cannot modify a process
on a remote node.
You must specify the pidadr argument to modify a process whose
UIC group number is different from that of the calling process.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name of the process. The prcnam argument is the address
of a character string descriptor pointing to the process name.
You identify a process with a 1- to 15-character string.
You can only use the prcnam argument to modify a process in the
same UIC group as the calling process. To modify a process in
another UIC group, you must specify the pidadr argument.
shlvflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Value specifying whether automatic unshelving is to be turned on
or off. The shlvflg argument is a longword containing this value.
The value 0 turns automatic unshelving on. The value 1 turns
automatic unshelving off.
234.2 - Description
The Set Automatic Unshelving service controls whether a process
automatically unshelves files.
The pidadr and prcnam default to the current process. If the
longword at address pidadr is 0, the PID of the target process is
returned.
The setting for automatic unshelving is inherited by
subprocesses.
The DCL command SET PROCESS/[NO]AUTOUNSHELVE also controls
automatic unshelving for a process; refer to the OpenVMS DCL
Dictionary for details.
Required Access or Privileges
Depending on the operation, the calling process might need one of
the following privileges to use $SETSHLV:
o GROUP privilege to modify a process in the same group, unless
the target process has the same UIC as the calling process.
o WORLD privilege to modify any process in the system.
Required Quota
None
Related Services
$GETJPI
234.3 - Condition Values Returned
SS$_WASCLR The service completed successfully. Automatic
unshelving was previously on.
SS$_WASSET The service completed successfully. Automatic
unshelving was previously off.
SS$_ACCVIO An argument was not accessible by the caller.
SS$_BADPARAM The shlvflg argument was invalid.
SS$_IVLOGNAM The prcnam argument was invalid. The process
name string had either 0 characters or more
than 15 characters.
SS$_NONEXPR The specified process did not exist, or the
specified process identification was invalid.
SS$_NOPRIV The caller did not have the privilege to
modify other processes.
SS$_REMOTE_PROC The specified process was not on the local
node. The service cannot modify a process on a
remote node.
Allows a process to change the size of its supervisor, executive,
and kernel stacks by altering the values in the stack limit and
base arrays held in P1 (per-process) space.
Format
SYS$SETSTK inadr ,[retadr] ,[acmode]
C Prototype
int sys$setstk (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
235.1 - Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Range of addresses that express the stack's new limits. The inadr
argument is the address of a 2-longword array containing, in
order, the address of the top of the stack and the address of the
base of the stack. Because stacks in P1 space expand from high
to low addresses, the address of the base of the stack must be
greater than the address of the top of the stack.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Range of addresses that express the stack's previous limits. The
retadr argument is the address of a 2-longword array into which
$SETSTK writes, in the first longword, the previous address of
the top of the stack and, in the second longword, the previous
address of the base of the stack.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the stack to be altered. The acmode argument is
a longword containing the access mode. The $PSLDEF macro defines
symbols for the four access modes. The most privileged access
mode used is the access mode of the caller.
If acmode specifies user mode, $SETSTK performs no operation and
returns the SS$_NORMAL condition value.
Allows a process to control whether it can be swapped out of the
balance set.
Format
SYS$SETSWM [swpflg]
C Prototype
int sys$setswm (char swpflg);
236.1 - Argument
swpflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the process can be swapped. The
swpflg argument is a longword value. The value 0 (the default)
enables process swap mode, meaning the process can be swapped.
The value 1 disables process swap mode, meaning the process
cannot be swapped.
Modifies the user authorization file (UAF) record for a specified
user.
Format
SYS$SETUAI [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg]
,[nullarg] ,[nullarg]
C Prototype
int sys$setuai (unsigned int efn, unsigned int *contxt, void
*usrnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm);
237.1 - Arguments
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
contxt
OpenVMS usage:longword
type: longword (unsigned)
access: modify
mechanism: by reference
A longword used to maintain authorization file context. The
contxt argument is the address of a longword to receive a $SETUAI
context value. On the initial call, this longword should contain
the value -1. On subsequent calls, the value of the contxt
argument from the previous call should be passed back in.
usrnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the user whose UAF record is modified. The usrnam
argument is the address of a descriptor pointing to a character
text string containing the user name. The user name string can
contain a maximum of 32 alphanumeric characters.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information from the specified UAF
record is to be modified. The itmlst argument is the address of a
list of one or more item descriptors, each of which specifies an
item code. The item list is terminated by the item code 0 or by
the longword 0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
|
238 - $SETUP AVOID PREEMPT
|
Performs initial setup for process preemption avoidance.
Format
SYS$SETUP_AVOID_PREEMPT enable
C Prototype
int sys$setup_avoid_preempt (int enable);
238.1 - Arguments
enable
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Enables or disables preemption avoidance. If the enable argument
is set to 1, preemption avoidance is enabled; if 0, preemption
avoidance is disabled.
Modifies the characteristics of a device or the paths used to
access that device.
For synchronous completion, use the Set Device Characteristics
and Wait ($SET_DEVICEW) service. The $SET_DEVICEW service is
identical to the $SET_DEVICE service, except that $SET_DEVICEW
returns to the caller only after the requested action has taken
effect.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service.
Format
SYS$SET_DEVICE [efn] [,chan] [,devnam] ,itmlst [,iosb]
[,astadr] [,astprm] [,nullarg]
C Prototype
int sys$set_device (unsigned int efn, unsigned short int chan,
void *devnam, void *itmlst, struct _iosb
*iosb, void (*astadr)(__unknown_params),
int astprm, struct_generic_64 *nullarg);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $SET_DEVICE returns the
requested information. The efn argument is a longword containing
this number; however, $SET_DEVICE uses only the low-order byte.
Upon request initiation, $SET_DEVICE clears the specified event
flag (or event flag 0 if efn was not specified). Then, when $SET_
DEVICE returns the requested information, it sets the specified
event flag (or event flag 0).
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word containing
this number.
To identify a device to $SET_DEVICE, you can specify either the
chan or devnam parameters, but you should not specify both. If
you specify both arguments, the chan argument is used.
If you specify neither chan nor devnam, $SET_DEVICE uses a
default value of 0 for chan.
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
The name of the device about which $SET_DEVICE is to modify the
characteristics or path settings. The devnam argument is the
address of a character string descriptor pointing to this name
string.
The device name string can be either a physical device name
or a logical name. If the first character in the string is an
underscore (_), the string is considered a physical device name;
otherwise, the string is considered a logical name and logical
name translation is performed until either a physical device name
is found or the system default number of translations has been
performed.
If the device name string contains a colon (:), the colon and
the characters that follow it are ignored.
To identify a device to $SET_DEVICE, you can specify either the
chan or devnam argument, but you should not specify both. If both
arguments are specified, the chan argument is used.
If you specify neither chan nor devnam, $SET_DEVICE uses a
default value of 0 for chan.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
Currently, $SET_DEVICE allows only one valid item list entry.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb argument is the address of the quadword I/O status
block. See iosb in the $GETDVI system service description for
more information.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $SET_DEVICE completes.
The astadr argument is the address of this routine.
If you specify astadr, the AST routine executes at the same
access mode as the caller of the $SET_DEVICE 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.
nullarg
OpenVMS usage:null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
Placeholding argument reserved to Compaq and should be zero.
Modifies the characteristics of a device or the paths used to
access that device.
The $SET_DEVICEW completes synchronously; that is, it returns to
the caller only after the requested action has taken effect.
Format
SYS$SET_DEVICEW [efn] [,chan] [,devnam] ,itmlst [,iosb]
[,astadr] [,astprm] [,nullarg]
C Prototype
int sys$set_devicew (unsigned int efn, unsigned short
int chan, void *devnam, void
*itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm,
struct_generic_64 *nullarg);
|
241 - $SET IMPLICIT AFFINITY (Alpha Only)
|
On Alpha systems, controls or retrieves the activation state
for the implicit affinity system capability of a specific kernel
thread or of the global process default.
This service accepts 64-bit addresses.
Format
SYS$SET_IMPLICIT_AFFINITY [pidadr] [,prcnam] [,state]
[,cpu_id] [,prev_mask]
C Prototype
int sys$set_implicit_affinity (unsigned int *pidadr, void
*prcnam, struct _generic_64
*state, int cpu_id, struct
_generic_64 *prev_mask);
241.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Process identification (PID) of a kernel thread whose implicit
affinity is to be modified or returned. The pidadr argument is
the 32- or 64-bit address of a longword that contains the PID.
Process selection is made through a combination of the pidadr and
prcnam arguments. If neither are specified or if both have a zero
value, the service operations are made to the user capability
mask of the current kernel thread of the current calling process.
The pidadr argument takes precedence over the prcnam argument
where both are supplied in the service call.
If the bit constant CAP$M_IMPLICIT_DEFAULT_ONLY is specified in
the state argument, then the implicit affinity state portion of
the default capability mask is modified or returned instead.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Process name of the process whose implicit affinity capability
state is to be modified or returned. The prcnam argument is the
32- or 64-bit address of a character string descriptor pointing
to the process name string. A process can be identified with a
1- to 15-character string. The service operations are made to
the user capability mask of the initial thread of the specified
process.
If pidadr and prcnam are both specified, then pidadr is modified
or returned and prcnam is ignored. If neither argument is
specified, then the context of the current kernel thread of the
calling process is modified or returned.
state
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
State options that can be selected for the affected thread's
implicit affinity. The state argument is a pointer to a quadword
bit vector wherein a bit corresponds to a requested state for
the implicit affinity feature. Only the bits specified below are
used; the remainder of the quadword bits are reserved.
Each option (bit) has a symbolic name, defined in the $CAPDEF
macro. The state argument is constructed by performing a logical
OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:
Symbolic Name Description
CAP$M_IMPLICIT_ Indicates the specified operations are to
DEFAULT_ONLY be performed on the global cell instead
of on a specific kernel thread. This bit
supersedes any individual kernel thread
specified in pidadr or prcnam. Specifying
this bit constant applies the implicit
affinity operations to all newly created
processes.
CAP$M_IMPLICIT_ Indicates that the implicit affinity
AFFINITY_SET capability bit is to be set for the
specified kernel thread. This is mutually
exclusive with CAP$M_IMPLICIT_AFFINITY_
CLEAR.
CAP$M_IMPLICIT_ Indicates that the implicit affinity
AFFINITY_CLEAR capability bit is to be cleared for the
specified kernel thread. This is mutually
exclusive with CAP$M_IMPLICIT_AFFINITY_
SET.
cpu_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Identifier of the CPU requested as the first CPU on which this
kernel thread is to execute. The cpu_id is a longword containing
this number, which is in the supported range of individual CPUs
from 0 to SYI$_MAX_CPUS -1.
If no explicit CPU is needed, specifying a value of -1 in
this argument indicates the system is to select the initial
association based on system dynamics and load balancing.
Note that, regardless of what explicit CPU is supplied to this
argument, it will be taken only as a suggestion. This service
will attempt to make the requested association, but it will be
superseded by another CPU if the system dynamics are adversely
affected by the operation.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Previous implicit affinity state mask for the specified kernel
thread before execution of this call to $SET_IMPLICIT_AFFINITY.
The prev_mask argument is the 32- or 64-bit address of a quadword
into which $SET_IMPLICIT_AFFINITY writes a bit mask specifying
the implicit affinity state.
The current state of the kernel thread's current implicit
affinity feature can be determined by testing the returned
mask with the symbolic bit definitions described for the state
argument. These bit definitions are found in the $CAPDEF macro.
|
242 - $SET PROCESS PROPERTIESW (Alpha Only)
|
Sets a simple value associated with a process.
Format
SYS$SET_PROCESS_PROPERTIESW mbz1 ,mbz2 ,mbz3 ,property ,value
,prev_value
C Prototype:
int sys$set_process_propertiesw (unsigned int mbz1, unsigned
int mbz2, unsigned int
mbz3, unsigned int property,
unsigned __int64 value,
unsigned __int64 *prev_value);
242.1 - Arguments
mbz1,mbz2,mbz3
type:
access:
mechanism: 0
Reserved for future use by Compaq. Must be specified as 0.
property
OpenVMS usage:integer
type: longword (unsigned)
access: read only
mechanism: by value
A constant that selects which property to set.
Valid values for property are defined by the $PPROPDEF macro as
follows:
Property Code Description
PPROP$C_HOME_RAD: The Resource Affinity Domain (RAD) to
which the process is assigned. Newly
mapped memory in the process will
come from the home RAD of the process.
Currently mapped memory will not move into
the new home RAD unless $PURGWS is issued.
Valid values are integers between 0 and
the maximum RAD on the system. Valid home
RADs must also contain either memory or
CPUs.
Note: OpenVMS support for RADs is
available only on the new AlphaServer
GS series systems. For more information
about using RADs, refer to the OpenVMS
Alpha Partitioning and Galaxy Guide.
PPROP$C_PARSE_STYLE_ The type of command parsing to use. This
TEMP: value is set only for the life of the
image. The value reverts to the permanent
style on image rundown. Valid values
are: PARSE_STYLE$C_TRADITIONAL and PARSE_
STYLE$C_EXTENDED.
PPROP$C_PARSE_STYLE_ The type of command parsing to use. This
PERM: value is set for the life of the process
unless the style is set again. Valid
values are: PARSE_STYLE$C_TRADITIONAL
and PARSE_STYLE$C_EXTENDED.
value
OpenVMS usage:integer
type: quadword (unsigned)
access: read
mechanism: by value
New property value.
prev_value
OpenVMS usage:access_mode
type: quadword (unsigned) address of a quadword value
access: write
mechanism: by reference
The address of a quadword that will receive the previous value of
the property.
|
243 - $SET RESOURCE DOMAIN
|
Controls the association between a calling process and resource
domains.
Format
SYS$SET_RESOURCE_DOMAIN func ,rsdm_id ,domain_number
,[nullarg] ,[access] ,[acmode]
C Prototype
int sys$set_resource_domain (unsigned int func, unsigned
int *rsdm_id, unsigned int
domain_number, unsigned int
nullarg, unsigned int access,
unsigned int acmode);
243.1 - Arguments
func
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function code specifying the action that $SET_RESOURCE_DOMAIN
is to perform. The func argument is a longword containing this
function code.
See the Function Codes section in the OpenVMS System Services
Reference Manual for a description of $SET_RESOURCE_DOMAIN
function codes.
rsdm_id
OpenVMS usage:longword
type: longword (unsigned)
access: write only to join, read only to leave
mechanism: by reference
Resource domain identification. The rsdm_id argument is the
address of a longword specifying the association of the calling
process with the resource domain.
The RSDM$_JOIN_DOMAIN function returns a resource domain
identification. The RSDM$_LEAVE function requires the rsdm_id
argument as input to specify which resource domain association
the process is leaving.
The resource domain identification can be used as input to the
$ENQ and $ENQW system services.
domain_number
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Domain number that identifies the resource domain. The domain_
number argument is a longword value containing the resource
domain number.
The domain_number argument is required for the RSDM$_JOIN_DOMAIN
function but ignored for the RSDM$_LEAVE function.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholder reserved to Compaq. You must specify 0.
access
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Types of access desired when using the lock management services
within the resource domain. The access argument is a longword
bit mask specifying the access types required; these can include
read, write, and lock.
The following table lists the symbols that the $RSDMDEF macro
defines, their descriptions, and the lock management system
services that might require each type of access:
Access
Symbol Description System Service
RSDM$M_READ Read lock value $DEQ, $ENQ, $ENQW, $GETLKI,
blocks $GETLKIW
RSDM$M_WRITE Write lock $DEQ, $ENQ, $ENQW,
value blocks
RSDM$M_LOCK Take locks $ENQ, $ENQW
The service grants the desired access, provided your process has
the necessary access rights to the resource domain. If you do not
specify the access argument or if you specify 0, $SET_RESOURCE_
DOMAIN attempts to access the domain in the following order:
1. Read, write, lock
2. Read, lock
3. Write, lock
4. Lock
The access attempt terminates with the first success.
The access argument defaults to 0. It is ignored for the RSDM$_
LEAVE function.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode requested for the association to the resource domain.
The most privileged access mode granted is the access mode of the
caller. Locks cannot be taken from access modes less privileged
than the access mode of the association.
The acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the following symbols for the access modes:
Symbolic Access Privilege
Name Mode Rank
PSL$C_KERNEL Kernel High
PSL$C_EXEC Executive -
PSL$C_SUPER Supervisor -
PSL$C_USER User Low
The acmode argument is optional for the RSDM$_JOIN_DOMAIN
function. If you do not specify the acmode argument, the access
mode is set to the access mode of the calling process. The acmode
argument is ignored for the RSDM$_LEAVE function.
Modifies the security characteristics of a protected object.
Format
SYS$SET_SECURITY [clsnam] ,[objnam] ,[objhan] ,[flags]
,[itmlst] ,[contxt] ,[acmode]
C Prototype
int sys$set_security (void *clsnam, void *objnam, unsigned
int *objhan, unsigned int flags, void
*itmlst, unsigned int *contxt, unsigned
int *acmode);
244.1 - Arguments
clsnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the object class. The clsnam argument is the address of
a descriptor pointing to a string that contains the name of the
object class.
The following is a list of the protected object class names:
CAPABILITY
COMMON_EVENT_CLUSTER
DEVICE
FILE
GLXGRP_GLOBAL_SECTION
GLXSYS_GLOBAL_SECTION
GROUP_GLOBAL_SECTION
ICC_ASSOCIATION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME
objnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the protected object whose associated security profile
is going to be retrieved. The objnam argument is the address
of a descriptor pointing to a string containing the name of the
protected object.
The format of an object name is class specific. The following
table lists object names and describes their formats:
Object Class Object Name Format
CAPABILITY A character string. Currently, the only
capability object is VECTOR.
COMMON_EVENT_ Name of the event flag cluster, as defined
CLUSTER in the Associate Common Event Flag Cluster
($ASCEFC) system service.
DEVICE Standard device specification, described in
the OpenVMS User's Manual.
FILE Standard file specification, described in the
OpenVMS User's Manual.
GROUP_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
ICC_ASSOCIATION ICC security object name node::association_
name. The special node name, ICC$::, refers
to entries in the clusterwide registry. For
registry entries, the Access Access Type does
not apply.
LOGICAL_NAME_TABLE Table name, as defined in the Create Logical
Name Table ($CRELNT) system service.
QUEUE Standard queue name, as described in the Send
to Job Controller ($SNDJBC) system service.
RESOURCE_DOMAIN An identifier or octal string enclosed in
brackets.
SECURITY_CLASS Any class name shown in the Object Class
column of this table, or a class name
followed by a period (.) and the template
name. Use the DCL command SHOW SECURITY to
display possible template names.
SYSTEM_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
VOLUME Volume name or name of the device on which
the volume is mounted.
objhan
OpenVMS usage:object_handle
type: longword (unsigned)
access: read only
mechanism: by reference
Data structure identifying the object to address. The objhan
argument is an address of a longword containing the object
handle. You can use the objhan argument as an alternative to the
objnam argument; for example, a channel number clearly specifies
the file open on the channel and can serve as an object handle.
The following table shows the format of the object classes:
Object Class Object Handle Format
COMMON_EVENT_ Event flag number
CLUSTER
DEVICE Channel number
FILE Channel number
RESOURCE_DOMAIN Resource domain identifier
VOLUME Channel number
flags
OpenVMS usage:flags
type: mask_longword
access: read only
mechanism: by value
Mask specifying processing options. The flags argument is a
longword bit vector wherein a bit, when set, specifies the
corresponding option. The flags argument requires the contxt
argument.
The following table describes each flag:
Symbolic Name Description
OSS$M_LOCAL Do not update the master profile for the
specified object. This flag allows you to call
$SET_SECURITY several times to modify a local
copy of a profile; once the modifications are
satisfactory, you can clear the OSS$M_LOCAL flag,
set the OSS$M_RELCTX flag, and have $SET_SECURITY
update the master profile. The flag applies only
to calls made with the contxt argument.
OSS$M_RELCTX Release the context structure at the completion
of this request.
The $OSSDEF macro defines symbolic names for the flag bits. You
construct the flags argument by specifying the symbolic names of
each desired option.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the process or
processes is to be modified. The itmlst argument is the address
of a list of item descriptors, each of which describes an item
of information. The list of item descriptors is terminated by a
longword of 0.
With the item list, the user modifies the protected object's
characteristics. The user defines which security characteristics
to modify. If this argument is not present, only the flags
argument is processed. Without the itmlst argument, you can
only manipulate the security profile locks or release contxt
resources.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Value used to maintain protected object processing context when
dealing with a single protected object across multiple $GET_
SECURITY/$SET_SECURITY calls. Whenever the context value is
nonzero, the class name, object name, or object handle arguments
are disregarded. An input value of 0 indicates that a new context
should be established.
Because an active context block consumes process memory, be sure
to release the context block by setting the RELCTX flag when the
profile processing is complete. $SET_SECURITY sets the context
argument to 0 once the context is released.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the object protection check. The acmode
argument is the address of a longword containing the access mode.
The acmode argument defaults to kernel mode; however, the system
compares acmode with the caller's access mode and uses the least
privileged mode. The access modes are defined in the system macro
$PSLDEF library.
Compaq recommends that this argument be omitted (passed as zero).
|
245 - $SET SYSTEM EVENT (Alpha Only)
|
Establishes a request for notification when an OpenVMS system
event occurs.
Format
SYS$SET_SYSTEM_EVENT event ,astadr ,astprm ,acmode ,flags
,handle
C Prototype
int sys$set_system_event (unsigned int event, void
(*astadr)(__unknown_params), int
astprm, unsigned int acmode, unsigned
int flags, struct _generic_64 *
handle);
245.1 - Arguments
event
OpenVMS usage:event_code
type: longword (unsigned)
access: read only
mechanism: by value
Event code indicating the type of system event for which an AST
is to be delivered. The event argument is a value indicating
which type of event is of interest.
Each event type has a symbolic name. The $SYSEVTDEF macro defines
the following symbolic names:
Symbolic Name Description
SYSEVT$C_ADD_MEMBER One or more OpenVMS instances have
joined the OpenVMS Galaxy sharing
community.
SYSEVT$C_DEL_MEMBER One or more OpenVMS instances have
left the OpenVMS Galaxy sharing
community.
SYSEVT$C_ADD_ACTIVE_CPU One or more processors have become
active within this OpenVMS instance.
SYSEVT$C_DEL_ ACTIVE_CPU One or more processors have become
inactive within this OpenVMS
instance.
SYSEVT$C_ADD_CONFIG_CPU One or more CPUs have been added to
the set of available CPUs for this
OpenVMS instance.
SYSEVT$C_DEL_CONFIG_CPU One or more processors have been
removed from this OpenVMS instance.
SYSEVT$C_TDF_CHANGE The system's time differential factor
has changed.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32-bit or 64-bit reference
Notification AST routine to receive control after a change in
OpenVMS system configuration occurs.
astprm
OpenVMS usage:user_arg
type: quadword
access: read only
mechanism: by value
The quadword AST parameter to be passed to the AST routine.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode at which the system event AST is to execute. The
acmode argument is a longword containing the access mode.
Each access mode has a symbolic name. The $PSLDEF macro defines
the following symbols for the four access modes.
Symbolic Name Description
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The value of the access mode is maximized with the access mode of
the caller.
flags
type:
access:
mechanism: 0
Defined in SYSEVTDEF.
SYSEVT$M_REPEAT_ When this flag is set, event notification
NOTIFY is repeated.
handle
OpenVMS usage:handle
type: quadword (unsigned)
access: read/write
mechanism: by reference
The virtual address of a naturally aligned quadword for the event
handle.
Searches for and returns information about records in the
intrusion database matching the caller's specifications.
Format
SYS$SHOW_INTRUSION user_criteria ,intruder ,intruder_len
,breakin_block ,[flags] ,[context]
C Prototype
int sys$show_intrusion (void *user_criteria, void *intruder,
unsigned short int *intruder_len, void
*breakin_block, unsigned int flags,
unsigned int *context);
246.1 - Arguments
user_criteria
OpenVMS usage:char_string or item_list_3
type: character-coded text string or longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length string descriptor or by
reference
If the CIA$M_ITEMLIST flag is FALSE:
The user_criteria argument is the description of intruder
or suspect. The user_criteria argument is the address of a
character-string descriptor pointing to a buffer containing the
user criteria to match an intrusion record's user specification
in the intrusion database.
The user_criteria argument is a character string of between 1 and
1058 bytes containing characters to match the user specification
on records in the intrusion database.
A user specification is any combination of the suspect's or
intruder's source node name, source user name, source DECnet
for OpenVMS address, local failed user name, local terminal,
or the string UNKNOWN. The user specification for an intrusion
record is based on the input to the $SCAN_INTRUSION service and
the settings of the LGI system parameter. For more information,
refer to the OpenVMS Guide to System Security.
Wildcards are allowed for the user_criteria argument.
For more information about using wildcards to scan the intrusion
database, see the $SHOW_INTRUSION Description section in the
OpenVMS System Services Reference Manual.
If the CIA$M_ITEMLIST flag is TRUE:
The user_criteria argument is now the address of an 32-bit item
list. If the item list is used, one item, the CIA$_USER_CRITERIAL
item, must be present in the item list.
The following table lists the valid item descriptions for the
user_criteria argument:
Item Description
CIA$_OUTPUT_LIST Address of an 8192-byte buffer into which the
service writes the associated node information
for the returned intrusion record.
CIA$_SCSNODE_LIST Address of a list of 8-character null-padded
SCS nodenames for which the caller wants to
see intrusion information about.
CIA$_USER_ Address of a buffer, 1-1058 bytes long,
CRITERIAL containing the intruder or suspect.
If a CIA$_SCSNODE_LIST item is provided, an intrusion record will
only be returned if it originated on one of the nodes specified.
If a CIA$_SCSNODE_LIST item is not provided, records from all
nodes will be candidates for display. Multiple CIA$_SCSNODE_LIST
items are permitted in the item list.
If a CIA$_OUTPUT_LIST item is provided, the item is filled with
node-count records on return. The returned intrusion record will
have a breakin block with a valid attempt-count field. The node-
count records will have the name and attempt-count for each node
represented.
intruder
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
User specification of the matched intruder or suspect record in
the intrusion database. The intruder argument is the address of
a character-string descriptor pointing to a buffer to receive
the user specification of the matched record in the intrusion
database.
The intruder argument is a 1058-byte string that will receive
the user specification of a record in the intrusion database
that matches the specifications in the user_criteria and flags
arguments.
intruder_len
OpenVMS usage:string length
type: longword (unsigned)
access: write only
mechanism: by reference
Length of returned string in the intrusion buffer. The intruder_
len argument is the address of a longword to receive the length
of the returned intrusion buffer.
The possible range of the intruder_len argument is 0 to 1058
bytes. If the longword specified by the argument contains a 0
after the call to the service, either the service did not find a
record that matched the user criteria in the intrusion database,
or there are no more matching items in the intrusion database.
breakin_block
OpenVMS usage:record
type: block of 2 words (unsigned), 1 longword (unsigned),
and 1 quadword (unsigned)
access: write only
mechanism: by reference
Block to receive various information in the intrusion database
about a record matching the user criteria.
Refer to the OpenVMS System Services Reference Manual to view the
breakin_block argument diagram and descriptor fields table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Type of records in the intrusion database about which information
is to be returned. The flags argument is a longword bit mask
wherein each bit corresponds to an option.
Each option has a symbolic name. The $CIADEF macro defines the
following valid names:
Symbolic Name Description
CIA$M_ALL All records will be shown. If the flags
argument is omitted, this value is assumed.
CIA$M_INTRUDERS Only intruder records matching the criteria
specified by the user_criteria argument will
be returned. The value of the flag field in
the break-in block will always be 1.
CIA$M_ITEMLIST If FALSE, the user_criteria argument is a
character string. If TRUE, this argument is a
32-bit item list.
CIA$M_SUSPECTS Only suspect records matching the criteria
specified by the user_criteria argument will
be returned. The value of the flag field in
the break-in block will always be 0.
Each of these options is mutually exclusive.
context
OpenVMS usage:context
type: longword (unsigned)
access: write only
mechanism: by reference
Context information to keep between related calls to the $SHOW_
INTRUSION service. The context argument is the address of a
longword that receives a context from the service.
The initial value contained in the unsigned longword pointed to
by the context argument must be 0. The contents of the unsigned
longword must not be changed after the service has set its value.
If the contents of the context argument are changed between calls
to the service, SS$_BADCONTEXT will be returned.
Contexts become invalid after one-half hour of non-use. This
means that if you call the $SHOW_INTRUSION service with a
wildcard in the user_criteria argument and do not call the
service to get the next matching record within one-half hour,
the context becomes invalid. If the context has become invalid,
you must restart your search of the intrusion database from the
beginning by resetting the context to 0.
Returns the address of a 64-bit signal array. A 32-bit signal
array and a mechanism array are passed to a condition handler
when it is called. $SIGNAL_ARRAY_64 provides the address of the
64-bit signal array, which might be required for programs that
use 64-bit address space.
This service accepts 64-bit addresses.
Format
SYS$SIGNAL_ARRAY_64 mcharg, sigarg_64
C Prototype
int sys$signal_array_64 (unsigned __int64 mcharg, unsigned
__int64 sigarg_64);
247.1 - Arguments
mcharg
OpenVMS usage:mechanism array
type: vector quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference, array reference
The mechanism array. The mcharg argument is the 32- or 64-bit
address of this array, which was passed to the condition handler.
$SIGNAL_ARRAY_64 uses this structure to determine the 64-bit
signal array address.
sigarg_64
OpenVMS usage:64-bit signal array
type: vector quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference, array reference
The 32- or 64-bit address of the 64-bit signal array is returned
in this argument.
Writes a user-specified message to the system error log file,
preceding it with the date and time.
Format
SYS$SNDERR msgbuf
C Prototype
int sys$snderr (void *msgbuf);
248.1 - Argument
msgbuf
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Message to be written to the error log file. The msgbuf argument
is the address of a character string descriptor pointing to the
message text.
Creates, stops, and manages queues and the batch and print jobs
in those queues. The $SNDJBC service completes asynchronously;
to synchronize the completion of most operations, use the Send to
Job Controller and Wait ($SNDJBCW) service.
Format
SYS$SNDJBC [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
C Prototype
int sys$sndjbc (unsigned int efn, unsigned short int func,
unsigned int nullarg, void *itmlst, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $SNDJBC completes. The
efn argument is a longword containing this number; however,
$SNDJBC uses only the low-order byte.
When you queue the request, $SNDJBC clears the specified event
flag (or event flag 0 if efn was not specified). Then, when the
operation completes, $SNDJBC sets the specified event flag (or
event flag 0).
func
OpenVMS usage:function_code
type: word (unsigned)
access: read only
mechanism: by value
Function code specifying the function that $SNDJBC is to perform.
The func argument is a word containing this function code. The
$SJCDEF macro defines the names of each function code.
You can specify only one function code in a single call to
$SNDJBC. Most function codes require or allow for additional
information to be passed in the call. You pass this information
by using the itmlst argument, which specifies a list of one or
more item descriptors. Each item descriptor in turn specifies an
item code, which modifies, restricts, or otherwise affects the
action designated by the function code.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved to Compaq.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list supplying information to be used in performing the
function specified by the func argument. The itmlst argument is
the address of the item list. The item list consists of one or
more item descriptors, each of which specifies an item code. The
item list is terminated by an item code of 0 or by a longword of
0.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagram and descriptor fields table.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block into which $SNDJBC writes the completion status
after the requested operation has completed. The iosb argument is
the address of the I/O status block.
At request initiation, $SNDJBC sets the value of the quadword
I/O status block to 0. When the requested operation completes,
$SNDJBC writes a condition value in the first longword of the
I/O status block. It writes the value 0 into the second longword;
this longword is unused and reserved for future use.
The condition values returned by $SNDJBC in the I/O status
block are usually condition values from the JBC facility. These
condition values are defined by the $JBCMSGDEF macro. In some
cases, the condition value returned by $SNDJBC can be an error
return from a system service or an OpenVMS RMS service that
is used in executing the request. For the SJC$_SYNCHRONIZE_JOB
request, the condition value returned is the completion status of
the requested job.
The condition values returned from the JBC facility are listed in
the Condition Values Returned in the I/O Status Block section.
Though this argument is optional, Compaq 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 $SNDJBC 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 $SNDJBC, 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 reference
AST service routine to be executed when $SNDJBC completes. The
astadr argument is the address of this routine.
If specified, the AST routine executes at the same access mode as
the caller of $SNDJBC.
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 this longword
parameter.
The Send to Job Controller and Wait and $GETQUI services together
provide the user interface to the Job Controller (JBC) facility.
The $SNDJBCW service allows you to create, stop, and manage
queues and the jobs in those queues. Queues can be generic,
batch, execution, or output queues. Jobs can be batch or print
jobs.
The $SNDJBCW service queues a request to the job controller. For
most operations, $SNDJBCW completes synchronously; that is, it
returns to the caller after the operation completes; however, if
the requested operation is a pause queue, stop queue, or abort
job operation, $SNDJBCW returns to the caller after queuing
the request. There is no way to synchronize completion of these
operations. Also, $SNDJBCW does not wait for a job to complete
before it returns to the caller. To synchronize completion of a
job, the caller must specify the SJC$_SYNCHRONIZE_JOB function
code.
The $SNDJBCW service is identical to the Send to Job Controller
($SNDJBC) service except that $SNDJBC completes asynchronously;
the $SNDJBC service returns to the caller immediately after
queuing the request, without waiting for the operation to
complete.
The $SNDJBC and $SNDJBCW services supersede the Send Message to
Symbiont Manager ($SNDSMB) and Send Message to Accounting Manager
($SNDACC) services. You should write new programs using $SNDJBC
or $SNDJBCW, instead of $SNDSMB or $SNDACC. You should convert
old programs using $SNDSMB or $SNDACC to use $SNDJBC or $SNDJBCW,
as convenient.
Format
SYS$SNDJBCW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
C Prototype
int sys$sndjbcw (unsigned int efn, unsigned short int func,
unsigned int nullarg, void *itmlst, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm);
Performs the following functions:
o Sends a user request to operator terminals
o Sends a user cancellation request to operator terminals
o Sends an operator reply to a user terminal
o Enables an operator terminal
o Displays the status of an operator terminal
o Initializes the operator log file
Format
SYS$SNDOPR msgbuf ,[chan]
C Prototype
int sys$sndopr (void *msgbuf, unsigned short int chan);
251.1 - Arguments
msgbuf
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
User buffer specifying the operation to be performed and the
information needed to perform that operation. The msgbuf argument
is the address of a character string descriptor pointing to the
buffer.
The format and contents of the buffer vary with the requested
operation; however, the first byte in any buffer is the request
code, which specifies the operation to be performed. The $OPCMSG
macro defines the symbolic names for these request codes.
The following table shows each operation that $SNDOPR performs
and the request code that specifies that operation:
Request Code Corresponding Operation
OPC$_RQ_ Sends a user cancellation request to specified
CANCEL operator terminals. You use this request code
to notify one or more operators that a previous
request is to be canceled. To specify OPC$_RQ_
CANCEL, you must also specify the chan argument.
OPC$_RQ_LOGI Initializes the operator log file.
OPC$_RQ_ Sends an operator reply to a user who has made a
REPLY request. Operators use this request code to report
the status of a user request. The format of the
message buffer for this request is the format
of the reply found in the user's mailbox after
the call to $SNDOPR completes. All functions of
$SNDOPR that deliver a reply to a mailbox do so in
the format described for this request code.
OPC$_RQ_RQST Sends a user request to operator terminals. This
request code is used to make an operator request.
If you specify a reply to the request (by using
the chan argument), the operator request is kept
active until the operator responds.
OPC$_RQ_ Reports the status of an operator terminal.
STATUS Operators use this request to display the operator
classes for which the specified terminal is
enabled and a list of outstanding requests.
OPC$_RQ_ Enables an operator terminal. You use this request
TERME to enable a specified terminal to receive operator
messages.
Refer to the OpenVMS System Services Reference Manual to view the
diagrams depicting the message buffer for each of these request
codes.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Channel assigned to the mailbox to which the reply is to be sent.
The chan argument is a longword value containing the number of
the channel. If you do not specify chan or specify it as the
value 0 (the default), no reply is sent.
If a reply from the operator is desired, you must specify the
chan argument.
|
252 - $START ALIGN FAULT REPORT (Alpha Only)
|
On Alpha systems, initializes user image alignment fault
reporting.
Format
SYS$START_ALIGN_FAULT_REPORT report_method ,report_buffer
,buffer_length
C Prototype
int sys$start_align_fault_report (int report_method,
void *report_buffer, int
buffer_length);
252.1 - Arguments
report_method
OpenVMS usage:longword_signed
type: longword (signed)
access: read
mechanism: by value
Method by which image alignment faults are to be reported.
The following table shows valid values for the report_method
argument:
Value Meaning
AFR$C_ Alignment fault PCs and fault addresses are saved
BUFFERED in a user-supplied buffer.
AFR$C_ Alignment faults are elevated to user mode
EXCEPTION exceptions.
report_buffer
OpenVMS usage:address
type: longword (unsigned)
access: read
mechanism: by reference
The 32-bit address of the buffer into which to write the fault
data. The report_buffer argument is needed only if the value of
the report_method argument is AFR$C_BUFFERED.
buffer_length
OpenVMS usage:byte count
type: longword (signed)
access: read
mechanism: by value
Length of the buffer specified in the report_buffer argument.
The buffer must have a minimum size of AFR$K_USER_LENGTH +
32. However, a larger buffer allows for more information to be
collected.
Starts a new transaction.
Format
SYS$START_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[timout] ,[acmode]]
C Prototype
int sys$start_trans (unsigned int efn, unsigned int flags,
struct _iosb *iosb,...);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag that is set when the service completes.
If this argument is omitted, event flag 0 is set.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the service. The flags argument is
a longword bit mask in which each bit corresponds to an option
flag. The $DDTMDEF macro defines symbolic names for these option
flags. All undefined bits must be 0. If this argument is omitted,
no flags are set.
The flags currently defined are shown in the following table:
Flag Description
DDTM$M_NONDEFAULT Set this flag if you do not want the new
transaction to be the default transaction of
the calling process.
If this flag is clear, the new transaction
becomes the default transaction of the
calling process. An error is returned if
this flag is clear and the calling process
already has a default transaction.
DDTM$M_PROCESS Set this flag if you do not want the DECdtm
transaction manager to try to abort the
transaction if the current image terminates.
If this flag is clear, when the current
image terminates (normally or abnormally),
the DECdtm transaction manager will abort
the transaction if it has not already
committed.
An error is returned if this flag is set and
the caller is in user mode.
DDTM$M_SYNC Set this flag to specify that successful
synchronous completion is to be indicated
by returning SS$_SYNCH. When SS$_SYNCH is
returned, the AST routine is not called, the
event flag is not set, and the I/O status
block is not filled in.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block in which the completion status of the service is
returned as a condition value.
Refer to the OpenVMS System Services Reference Manual to view the
I/O status block diagram.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST routine that is executed when the service completes. The
astadr argument is the address of this routine. This routine is
executed in the access mode of the caller.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter that is passed to the AST routine specified by the
astadr argument.
tid
OpenVMS usage:transaction_id
type: octaword (unsigned)
access: write only
mechanism: by reference
Address of an octaword in which the service returns the
identifier of the new transaction.
timout
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Timeout for the new transaction. This is the time at which the
DECdtm transaction manager is to abort the transaction if the
transaction has not already committed.
The time value is a binary number, in units of 100 nanoseconds.
A positive time value specifies an offset from the system base
time. The system base time is 00:00 hours November 17, 1858.
A negative time value specifies an offset from the current time
to some time in the future.
The transaction is aborted at the next timer interval if you
specify either a zero time value or any time in the past.
If this argument is omitted, the new transaction has no timeout.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
The least privileged access mode that the calling process must
be in to end the transaction by calling $END_TRANS. Note that the
calling process can end the transaction by calling $ABORT_TRANS
from any access mode.
The access mode that the calling process must be in to end the
transaction by calling $END_TRANS is whichever is the least
privileged of the following:
o The access mode of the caller
o The access mode specified by the acmode argument
If the acmode argument is omitted, it defaults to the access mode
of the caller.
Starts a new transaction.
$START_TRANSW always waits for the request to complete before
returning to the caller. Other than this, it is identical to
$START_TRANS.
|
255 - $STOP ALIGN FAULT REPORT (Alpha Only)
|
On Alpha systems, disables user image alignment fault reporting.
Format
SYS$STOP_ALIGN_FAULT_REPORT
C Prototype
int sys$stop_align_fault_report (void);
255.1 - Arguments
None.
|
256 - $STOP SYS ALIGN FAULT REPORT (Alpha Only)
|
On Alpha systems, disables systemwide alignment fault reporting.
Format
SYS$STOP_SYS_ALIGN_FAULT_REPORT
C Prototype
int sys$stop_sys_align_fault_report (void);
256.1 - Arguments
None.
Saves or restores the process image rights for the current
protected subsystem.
Format
SYS$SUBSYSTEM enbflg
C Prototype
int sys$subsystem (unsigned int enbflg);
257.1 - Argument
enbflg
OpenVMS usage:boolean
type: longword (unsigned)
access: read only
mechanism: by value
Value specifying whether the protected subsystem identifiers are
to be saved or restored. If the enbflg argument is set to 0, the
active subsystem is saved. If it is set to 1, the subsystem is
restored.
Allows a process to suspend itself or another process.
Format
SYS$SUSPND [pidadr] ,[prcnam] ,[flags]
C Prototype
int sys$suspnd (unsigned int *pidadr, void *prcnam, unsigned
int flags);
258.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be suspended. The
pidadr argument is the address of the longword PID.
The pidadr argument can refer to a process running on the local
node or a process running on another node in the OpenVMS Cluster
system.
You must specify the pidadr argument to suspend a process whose
UIC group number is different from that of the calling process.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the process to be suspended. The prcnam argument is the
address of a character string descriptor pointing to the process
name. A process running on the local node can be identified with
a 1- to 15-character string.
To identify a process on a particular node on a cluster, specify
the full process name, which includes the node name as well as
the process name. The full process name can contain up to 23
characters.
A process name is implicitly qualified by its UIC group number.
Because of this, you can use the prcnam argument only to suspend
processes in the same UIC group as the calling process.
To suspend processes in other groups, you must specify the pidadr
argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of bit flags specifying options for the suspend
operation. Currently, only bit 0 is used for the flags argument.
When bit 0 is set, the process is suspended at kernel mode and
ASTs are not deliverable to the process.
To request a kernel mode suspend, the caller must be in either
kernel mode or executive mode. The default (bit 0 is clear) is
to suspend the process at supervisor mode, where executive or
kernel mode ASTs can be delivered to the process. If executive
or kernel mode ASTs have been delivered to a process suspended at
supervisor mode, that process will return to its suspended state
after the AST routine executes.
Checks the completion status of a system service that completes
asynchronously.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$SYNCH [efn] ,[iosb]
C Prototype
int sys$synch (unsigned int efn, struct _iosb *iosb);
259.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag specified in the call to the system
service whose completion status is to be checked by $SYNCH.
The efn argument is a longword containing this number; however,
$SYNCH uses only the low-order byte.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
I/O status block specified in the call to the system service
whose completion status is to be checked by $SYNCH. The iosb
argument is the address of this quadword I/O status block.
Converts 128-bit Coordinated Universal Time (UTC) format to 64-
bit system format or 64-bit system format to 128-bit UTC format
based on the value of the convert flag.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$TIMCON [smnadr] ,[utcadr] ,cvtflg
C Prototype
int sys$timcon (struct _generic_64 *smnadr, unsigned int
*utcadr [4], unsigned long int cvtflg);
260.1 - Arguments
smnadr
OpenVMS usage:date_time
type: quadword (unsigned)
access: read/write
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
The 64-bit system format value that $TIMCON will use in the
conversion. The smnadr argument will be read from or written to
based on the value of the cvtflg argument. The smnadr is required
when converting UTC time to 64-bit system format.
utcadr
OpenVMS usage:coordinated universal time
type: utc_date_time
access: read/write
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
UTC time value that $TIMCON will use in the conversion. The
utcadr argument will be read from or written to based on the
value of the cvtflg argument. The utcadr argument is required
when converting 64-bit system format to UTC time.
cvtflg
OpenVMS usage:conversion flag
type: longword (unsigned)
access: read only
mechanism: by value
A longword indicating the direction of the conversion. If the
cvtflg value is 0, UTC time is converted to 64-bit system value.
If the cvtflg value is 1, 64-bit system format is converted to
UTC time.
Returns information about a logical name.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$TRNLNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
C Prototype
int sys$trnlnm (unsigned int *attr, void *tabnam, void
*lognam, unsigned char *acmode, void *itmlst);
261.1 - Arguments
attr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Attributes controlling the search for the logical name. The attr
argument is the 32-bit address (on VAX systems) or the 32- or 64-
bit address (on Alpha systems) of a longword bit mask specifying
these attributes.
Each bit in the longword corresponds to an attribute and has a
symbolic name. The $LNMDEF macro defines these symbolic names.
To specify an attribute, use its symbolic name or set its
corresponding bit. All undefined bits in the longword have the
value 0.
If you do not specify this argument or specify it as the value 0
(no bits set), the following attribute is not used:
Attribute Description
LNM$M_CASE_ If set, $TRNLNM does not distinguish between
BLIND uppercase and lowercase letters in the logical
name to be translated.
LNM$M_ If set, $TRNLNM does not translate the current
INTERLOCKED logical name until any clusterwide logical
name modifications in progress are completed.
This attribute is not set by default. If
your application requires translation using
the most recent definition of a clusterwide
logical name, use this attribute to ensure that
the translation is stalled until all pending
modifications have been made.
tabnam
OpenVMS usage:logical_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 logical name table or the name of a searchlist
logical name that translates the name of one or more tables
in which to search for the specified logical name. The tabnam
argument is the 32-bit address (on VAX systems) or the 32- or 64-
bit address (on Alpha systems) of a descriptor pointing to this
name. This argument is required.
The name must be entered in uppercase letters. (This requirement
differs from the $CRELNT system service, which automatically
changes tabnam to uppercase.)
If the table name is not the name of a logical name table, it is
assumed to be a logical name and is translated iteratively until
either the name of a logical name table is found or the number
of translations allowed by the system have been performed. If
the table name translates to a list of logical name tables, the
tables are searched in the specified order.
lognam
OpenVMS usage:logical_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)
Logical name about which information is to be returned. The
lognam argument is the 32-bit address (on VAX systems) or the
32- or 64-bit address (on Alpha systems) of a descriptor pointing
to the logical name string. This argument is required.
acmode
OpenVMS usage:access_mode
type: byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Access mode to be used in the translation. The acmode argument is
the 32-bit address (on VAX systems) or the 32- or 64-bit address
(on Alpha systems) of a byte specifying the access mode. The
$PSLDEF macro defines symbolic names for the four access modes.
When you specify the acmode argument, $TRNLNM ignores all
names (both logical names and table names) at access modes less
privileged than the specified access mode. The specified access
mode is not checked against that of the caller.
If you do not specify acmode, $TRNLNM performs the translation
without regard to access mode; however, the translation process
proceeds from the outermost to the innermost access modes. Thus,
if two logical names with the same name but at different access
modes exist in the same table, $TRNLNM translates the name with
the outermost access mode.
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 describing the information that $TRNLNM is to return.
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 specifies or controls an item of
information to be returned. 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.
Refer to the OpenVMS System Services Reference Manual to view the
item code diagrams and descriptor fields tables.
Simulates the occurrence of a cluster configuration event to test
the functionality of the notification AST.
Format
SYS$TSTCLUEVT [handle] ,[acmode] ,[event]
C Prototype
int sys$tstcluevt (unsigned int *handle, unsigned int acmode,
unsigned int event);
262.1 - Arguments
handle
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification of the asynchronous system trap (AST) to be
tested. The handle argument uniquely identifies the request and
is returned when the $SETCLUEVT service is called.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which a configuration event AST is to be
triggered. The acmode argument is a longword containing the
access mode.
Each access mode has a symbolic name. The $PSLDEF macro defines
the following symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
event
OpenVMS usage:event_code
type: longword (unsigned)
access: read only
mechanism: by value
Event code indicating the type of configuration for which an AST
is to be triggered.
Each event type has a symbolic name. The $CLUEVTDEF macro defines
the following symbolic names:
Symbolic Name Description
CLUEVT$C_ADD One or more OpenVMS nodes have been added to
the OpenVMS Cluster system.
CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed
from the OpenVMS Cluster system.
Unlocks pages that were previously locked in memory by the Lock
Pages in Memory ($LCKPAG) service. Locked pages are automatically
unlocked and deleted at image exit.
Format
SYS$ULKPAG inadr ,[retadr] ,[acmode]
C Prototype
int sys$ulkpag (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the pages to be
unlocked. The inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses.
Only the virtual page number portion of each virtual address is
used; the low-order byte-within-page bits are ignored. If the
starting and ending virtual addresses are the same, a single page
is unlocked.
If more than one page is being unlocked and you need to determine
specifically which pages had been previously unlocked, you should
unlock the pages one at a time, that is, one page per call
to $ULKPAG. The condition value returned by $ULKPAG indicates
whether the page was previously unlocked.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference or descriptor
Starting and ending process virtual addresses of the pages
actually unlocked by $ULKPAG. The retadr argument is the address
of a 2-longword array containing, in order, the starting and
ending process virtual addresses.
If an error occurs while multiple pages are being unlocked,
retadr specifies those pages that were successfully unlocked
before the error occurred. If no pages were successfully
unlocked, both longwords in the retadr array contain the value
-1.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the symbols for the four access modes.
The most privileged access mode used is the access mode of the
caller. To unlock any specified page, the resultant access mode
must be equal to or more privileged than the access mode of the
owner of that page.
|
264 - $ULKPAG 64 (Alpha Only)
|
On Alpha systems, unlocks pages that were previously locked in
memory by the Lock Pages in Memory ($LCKPAG_64) service.
This service accepts 64-bit addresses.
Format
SYS$ULKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$ulkpag_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
264.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be unlocked. The
specified virtual address will be rounded down to a CPU-specific
page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be unlocked. The specified
length will be rounded up to a CPU-specific page boundary so that
it includes all CPU-specific pages in the requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. To unlock any specified page, the resultant access mode
must be equal to or more privileged than the access mode of the
owner of that page.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the unlocked virtual
address range. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range unlocked. The
return_length_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
Unlocks pages that were previously locked in the working set by
the Lock Pages in Working Set ($LKWSET) service.
Format
SYS$ULWSET inadr ,[retadr] ,[acmode]
C Prototype
int sys$ulwset (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference-array reference or descriptor
Starting and ending virtual addresses of the pages to be
unlocked. The inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses.
Only the virtual page number portion of each virtual address is
used; the low-order byte-within-page bits are ignored. If the
starting and ending virtual address are the same, a single page
is unlocked.
If more than one page is being unlocked and you need to determine
specifically which pages had been previously unlocked, you should
unlock the pages one at a time, that is, one page per call
to $ULWSET. The condition value returned by $ULWSET indicates
whether the page was previously unlocked.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference or descriptor
Starting and ending process virtual addresses of the pages that
were actually unlocked by $CRMPSC. The retadr argument is the
address of a 2-longword array containing, in order, the starting
and ending process virtual addresses.
If an error occurs while multiple pages are being unlocked,
retadr specifies those pages that were successfully unlocked
before the error occurred. If no pages were successfully
unlocked, both longwords in the retadr array contain the value
-1.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the symbols for the four access modes.
The most privileged access mode used is the access mode of the
caller. To unlock any specified page, the resultant access mode
must be equal to or more privileged than the access mode of the
owner of that page.
|
266 - $ULWSET 64 (Alpha Only)
|
On Alpha systems, unlocks a virtual address range that was
previously locked in the working set by the Lock Pages in Working
Set ($LKWSET_64) service.
This service accepts 64-bit addresses.
Format
SYS$ULWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$ulwset_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, void
*(*(return_va_64)), unsigned __int64
*return_length_64);
266.1 - Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be unlocked from the
working set. The specified virtual address will be rounded down
to a CPU-specific page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address space to be unlocked from the
working set. The specified length will be rounded up to a CPU-
specific page boundary so that it includes all CPU-specific pages
in the requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. To unlock any specified page, the resultant access mode
must be equal to or more privileged than the access mode of the
owner of that page.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The lowest process virtual address of the unlocked virtual
address range. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the virtual address range unlocked. The
return_length_64 argument is the 32- or 64-bit virtual address
of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
Unwinds the procedure call stack.
Format
SYS$UNWIND [depadr] ,[newpc]
C Prototype
int sys$unwind (unsigned int *depadr, void *newpc);
267.1 - Arguments
depadr
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Depth to which the procedure call stack is to be unwound. The
depadr argument is the address of a longword value. The value 0
specifies the call frame of the procedure that was executing when
the condition occurred (that is, no call frames are unwound); the
value 1 specifies the caller of that frame; the value 2 specifies
the caller of the caller of that frame, and so on.
If depadr specifies the value 0, no unwind occurs and $UNWIND
returns a successful condition value in R0.
If you do not specify depadr, $UNWIND unwinds the stack to the
call frame of the procedure that called the procedure that
established the condition handler that is calling the $UNWIND
service. This is the default and the normal method of unwinding
the procedure call stack.
newpc
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by value
New value for the program counter (PC); this value replaces the
current value of the PC in the call frame of the procedure that
receives control when the unwinding operation is complete. The
newpc argument is a longword value containing the address at
which execution is to resume.
Execution resumes at this address when the unwinding operation is
complete.
If you do not specify newpc, execution resumes at the location
specified by the PC in the call frame of the procedure that
receives control when the unwinding operation is complete.
Writes all modified pages in an active private or global section
back into the section file on disk. One or more I/O requests are
queued, based on the number of pages that have been modified.
Format
SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb]
,[astadr] ,[astprm]
C Prototype
int sys$updsec (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, char updflg,
unsigned int efn, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm);
Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference-array reference or descriptor
Starting and ending virtual addresses of the pages that are to
be written to the section file if they have been modified. The
inadr argument is the address of a 2-longword array containing,
in order, the starting and ending process virtual addresses.
Addresses are adjusted up or down to CPU-specific pages.
Only the virtual page number portion of each virtual address is
used; the low-order byte-within-page bits are ignored.
$UPDSEC scans pages starting at the address contained in the
first longword specified by inadr and ending at the address
contained in the second longword. Within this range, $UPDSEC
locates read/write pages that have been modified and writes
them (contiguously, if possible) to the section file on disk.
Unmodified pages are also written to disk if they share the same
cluster with modified pages.
If the starting and ending virtual addresses are the same, a
single page is written to the section file if the page has been
modified.
The address specified by the second longword might be smaller
than the address specified by the first longword.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference or descriptor
Addresses of the first and last pages that were actually queued
for writing, in the first $QIO request, back to the section file
on disk. The retadr argument is the address of a 2-longword array
containing, in order, the addresses of the first and last pages.
Addresses always are adjusted up or down to fall on CPU-specific
boundaries.
If $UPDSEC returns an error condition value in R0, each longword
specified by retadr contains the value -1. In this case, an event
flag is not set, no asynchonous system trap (AST) is delivered,
and the I/O status block is not written to.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the service is performed. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the symbols for the four access modes.
The most privileged access mode used is the access mode of the
caller. A page cannot be written to disk unless the access mode
used by $UPDSEC is equal to or more privileged than the access
mode of the owner of the page to be written.
updflg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Update specifier for read/write global sections. The updflg
argument is a longword value. The value 0 (the default) specifies
that all read/write pages in the global section are to be written
to the section file on disk, whether or not they have been
modified. The value 1 specifies that the caller is the only
or the last process having the global section mapped for write
access and that only modified pages should be written to the
section file on disk.
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag to be set when the section file on disk is actually
updated. The efn argument is a longword specifying the number of
the event flag; however, $UPDSEC uses only the low-order byte.
If you do not specify efn, event flag 0 is used.
When you invoke $UPDSEC, the specified event flag or event flag 0
is cleared; when the update operation is complete, the event flag
is set.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block to receive the final completion status of the
updating operation. The iosb argument is the address of the
quadword I/O status block.
When you invoke $UPDSEC, the I/O status block is cleared. After
the update operation is complete, that is, when all I/O to the
disk is complete, the I/O status block is written as follows:
o The first word contains the condition value returned by $QIO,
indicating the final completion status.
o The first bit in the second word is set only if an error
occurred during the I/O operation and the error was a hardware
write error. The remaining bits of the second word are zeros.
o The second longword contains the virtual address of the first
page that was not written.
Though this argument is optional, Compaq 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 $SYNCH 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 $UPDSEC. 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
$UPDSEC, 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 reference-procedure reference or descriptor
AST routine to be executed when the section file has been
updated. The astadr argument is the address of this routine.
If you specify astadr, the AST routine executes at the access
mode from which the section file update was requested.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST routine. The astprm
argument is this longword parameter.
Writes all modified pages in an active private or global section
back into the section file on disk. One or more I/O requests are
queued, based on the number of pages that have been modified.
The $UPDSECW service completes synchronously; that is, it returns
to the caller after writing all updated pages.
For asynchronous completion, use the Update Section File on Disk
($UPDSEC) service; $UPDSEC returns to the caller after queuing
the update request, without waiting for the pages to be updated.
In all other respects, $UPDSECW is identical to $UPDSEC. For
all other information about the $UPDSECW service, refer to the
description of $UPDSEC.
Format
SYS$UPDSECW inadr [,retadr] [,acmode] [,updflg] [,efn] [,iosb]
[,astadr] [,astprm]
C Prototype
int sys$updsecw (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, char updflg,
unsigned int efn, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm);
|
270 - $UPDSEC 64 (Alpha Only)
|
On Alpha systems, writes all pages (or only those pages modified
by the current process) in an active private or global disk
file section back into the section file on disk. One or more
I/O requests are queued to perform the write operation.
The $UPDSEC_64 service completes asynchronously. For synchronous
completion, use the Update Global Section File on Disk and Wait
($UPDSEC_64W) service.
This service accepts 64-bit addresses.
Format
SYS$UPDSEC_64 start_va_64 ,length_64 ,acmode ,updflg ,efn
,iosa_64 ,return_va_64 ,return_length_64
[,astadr_64 [,astprm_64]]
C Prototype
int sys$updsec_64 (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, unsigned
int updflg, unsigned int efn, struct _iosa
*iosa_64, void *(*(return_va_64)), unsigned
__int64 *return_length_64,...);
Arguments
start_va_64
OpenVMS usage:address
type: quadword address
access: read only
mechanism: by value
The starting virtual address of the pages to be written to the
section file. The specified virtual address is rounded down to a
CPU-specific page boundary.
length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: read only
mechanism: by value
Length of the virtual address range to be written to the section
file. The length specified is rounded up to a CPU-specific
page boundary so that it includes all CPU-specific pages in the
requested range.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the service is performed. The
acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values
for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User
The most privileged access mode used is the access mode of the
caller. A page cannot be written to disk unless the access mode
used by $UPDSEC_64 is equal to or more privileged than the access
mode of the owner of the page to be written.
updflg
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The update specifier for read/write global sections. The updflg
argument is a longword value. The value 0 (the default) specifies
that all read/write pages in the global section are to be written
to the section file on disk, whether or not they have been
modified. The value UPDFLG$M_WRT_MODIFIED specifies that the
caller is the only process actually writing the global section
and that only those pages that were actually modified by the
caller are to be written to the section file on disk.
Definitions for this flag can be found in the file SECDEF.H in
SYS$STARLET_C.TLB for C and in $SECDEF in STARLET.MLB for macro.
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read_only
mechanism: by value
The event flag to be set when the section file on disk is
actually updated. The efn argument is a longword specifying the
number of the event flag; however, this service only uses the
low-order byte. If you do not specify the efn, event flag 0 is
used.
When you invoke $UPDSEC_64, the specified event flag or event
flag 0 is cleared. When the update operation is complete, the
event flag is set.
iosa_64
OpenVMS usage:io_status_area
type: IOSA structure
access: write only
mechanism: by 32- or 64-bit reference
The I/O status area to receive the final completion status of
the updating operation. The iosa_64 argument is the 32- or 64-
bit virtual address of the I/O status area. The I/O status area
structure is 32 bytes in length.
The I/O status area structure definition can be found in
$IOSADEF in STARLET.MLB for macro and in the file IOSADEF.H in
SYS$STARLET_C.TLB for C.
When you call SYS$UPDSEC_64, the I/O status area is cleared.
After the update operation is complete (that is, when all I/O
to the disk is complete), the I/O status block is written as
follows:
o isoa$l_status (offset 0)
The first word contains the condition value return by SYS$QIO,
indicating the final completion status.
The first bit in the second word is set only if an error
occurred during the I/O operation and the error was a hardware
write error. The remaining bits of the second word are zeros.
o iosa$l_resd (offset 4)
This field is reserved for future use by Compaq. The value in
this field is unpredictable.
o iosa$q_count_q (offset 8)
This field is reserved for future use by Compaq. The value in
this field is unpredictable.
o iosa$ph_upsec_nowrt_va (offset 16)
This field contains the virtual address of the first byte in
the first disk block that was not written. In the case of an
I/O error, this virtual address indicates the disk block for
which the error occurred.
o iosa$q_resq (offset 24)
This field is reserved for future use by Compaq. The value in
this field is unpredictable.
return_va_64
OpenVMS usage:address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference
The process virtual address of the first page that was actually
queued for writing (in the first I/O request) back to the section
file on the disk. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the
service returns the virtual address.
return_length_64
OpenVMS usage:byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The length of the first I/O request to write modified pages back
to the section file on disk. The return_length_64 argument is
the 32- or 64-bit virtual address of a naturally aligned quadword
into which the service returns the length of the virtual address
range, in bytes, written by the first I/O request.
astadr_64
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference
The asynchronous system trap (AST) routine to be executed when
the section file has been updated. The astadr_64 argument is
the 32- or 64-bit address of this routine. If you specify the
astadr_64 argument, the AST routine executes at the access mode
from which the section file update was requested.
astprm_64
OpenVMS usage:user_arg
type: quadword
access: read only
mechanism: by value
The AST parameter to be passed to the AST routine. The astprm_64
argument is a quadword argument that is passed to the AST
routine.
|
271 - $UPDSEC 64W (Alpha Only)
|
On Alpha systems, writes all modified pages in an active private
or global disk file section back into the section file on disk.
Zero or more I/O requests are queued, based on the number of
pages that have been modified.
The $UPDSEC_64W service completes synchronously; that is, it
returns to the caller after writing all updated pages.
In all other respects, $UPDSEC_64W is identical to $UPDSEC_64.
For all other information about the $UPDSEC_64W service, refer to
the help for $UPDSEC_64.
This service accepts 64-bit addresses.
Format
SYS$UPDSEC_64W start_va_64 ,length_64 ,acmode ,updflg ,efn
,iosa_64 ,return_va_64 ,return_length_64
[,astadr_64 [,astprm_64]]
C Prototype
int sys$updsec_64w (void *start_va_64, unsigned __int64
length_64, unsigned int acmode, unsigned
int updflg, unsigned int efn, struct _iosa
*iosa_64, void *(*(return_va_64)), unsigned
__int64 *return_length_64,...);
Verifies that a proxy exists and returns a valid local user for
the caller to use to create a local login.
Format
SYS$VERIFY_PROXY rem_node ,rem_user ,[proposed_user]
,local_user ,local_user_length ,[flags]
C Prototype
int sys$verify_proxy (void *rem_node, void *rem_user, void
*proposed_user, void *local_user,
unsigned short int *local_user_len,
unsigned int flags);
272.1 - Arguments
rem_node
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote node name of the proxy to be verified. The rem_node
argument is the address of a character-string descriptor pointing
to the remote node name string.
A remote node name consists of 1 to 1024 characters. No specific
characters, format, or case are required for a remote node name
string. All node names are converted to their DECnet for OpenVMS
full name unless the PRX$M_BYPASS_EXPAND flag is set with the
flags argument.
Wildcards are not recognized. If you specify a wildcard character
in the rem_node argument, it is ignored and assumed to be part of
the requested node name.
rem_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Remote user name of the proxy to be verified. The rem_user
argument is the address of a character-string descriptor pointing
to the user name string.
A remote user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($), underscores (_), and brackets
([ ]). Any lowercase characters specified are automatically
converted to uppercase.
The rem_user argument can be specified in user identification
code (UIC) format ([group, member]). Brackets are allowed only
if the remote user name string specifies a UIC. Group and member
are character-string representations of octal numbers with no
leading zeros.
Wildcards are not allowed for the remote user specification. If
wildcard characters are present in the string specified by the
rem_user argument, the service returns SS$_BADPARAM.
proposed_user
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Local user the caller suggests be used for the proxy login.
The proposed_user argument is the address of a character-string
descriptor pointing to the proposed local user name.
The proposed local user consists of 1 to 32 alphanumeric
characters, including dollar signs ($) and underscores (_).
Any lowercase characters specified are automatically converted to
uppercase.
See the $VERIFY_PROXY Description section in the OpenVMS System
Services Reference Manual for information about the interaction
of this argument with the return value of the local_user
argument.
local_user
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
Local user the caller must use for a proxy login. The local_user
argument is the address of a 32-byte character-string descriptor
pointer to receive the local user name the caller must use for a
proxy login for the proxy with the remote node name specified by
the rem_node argument and the remote user name specified by the
rem_user argument.
A local user name is a 32-character blank padded string of
alphanumeric characters, including dollar signs ($) and
underscores (_).
local_user_length
OpenVMS usage:output length
type: word (unsigned)
access: write only
mechanism: by reference
Length of the returned local user name in the local_user
argument. The local_user_length argument is the address of an
unsigned word to receive the length, in bytes, of the character
string returned in the local_user argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Functional specification for the service and type of user the
local_user argument represents. The flags argument is a longword
bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $PRXDEF macro defines
the following symbolic name:
Symbolic Name Description
PRX$M_BYPASS_ The service should not convert the node name
EXPAND specified in the rem_node argument to its
corresponding DECnet for OpenVMS full name.
If this flag is set, it is the caller's
responsibility to ensure that the fully
expanded node name is passed into the service.
Tests a specific event flag and returns immediately if the flag
is set; otherwise, the process is placed in a wait state until
the event flag is set.
Format
SYS$WAITFR efn
C Prototype
int sys$waitfr (unsigned int efn);
273.1 - Argument
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag for which to wait. The efn argument is a
longword containing this number; however, $WAITFR uses only the
low-order byte.
Activates a process that has placed itself in a state of
hibernation with the Hibernate ($HIBER) service.
This service accepts 64-bit addresses.
Format
SYS$WAKE [pidadr] ,[prcnam]
C Prototype
int sys$wake (unsigned int *pidadr, void *prcnam);
274.1 - Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference
Process identification (PID) of the process to be activated. The
pidadr argument is the 32- or 64-bit address of a longword that
contains the PID. The pidadr argument can refer to a process
running on the local node or a process running on another node in
the cluster.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Process name of the process to be activated. The prcnam argument
is the 32- or 64-bit address of a 32- or 64-bit character string
descriptor pointing to the process name. A process running on the
local node can be identified with a 1 to 15 character string.
To identify a process on a particular node in a cluster, specify
the full process name, which includes the node name as well as
the process name. The full process name can contain up to 23
characters.
The process name is implicitly qualified by the UIC group number
of the calling process. For this reason, you can use the prcnam
argument only if the process to be activated is in the same UIC
group as the calling process. To activate a process in another
UIC group, you must specify the pidadr argument.
Allows a process to specify a set of event flags for which it
wants to wait.
Format
SYS$WFLAND efn ,mask
C Prototype
int sys$wfland (unsigned int efn, unsigned int mask);
275.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag within the event flag cluster to be
used. The efn argument is a longword containing this number;
however, $WFLAND uses only the low-order byte. Specifying the
number of an event flag within the cluster serves to identify the
event flag cluster.
There are two local event flag clusters: cluster 0 and cluster
1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1
contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster
3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
contains event flag numbers 96 to 127.
mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Event flags for which the process is to wait. The mask argument
is a longword bit vector wherein a bit, when set, selects the
corresponding event flag for which to wait.
Allows a process to specify a set of event flags for which it
wants to wait.
Format
SYS$WFLOR efn ,mask
C Prototype
int sys$wflor (unsigned int efn, unsigned int mask);
276.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag within the event flag cluster to be
used. The efn argument is a longword containing this number;
however, $WFLOR uses only the low-order byte. Specifying the
number of an event flag within the cluster serves to identify the
event flag cluster.
There are two local event flag clusters: cluster 0 and cluster
1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1
contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster
3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
contains event flag numbers 96 to 127.
mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Event flags for which the process is to wait. The mask argument
is a longword bit vector wherein a bit, when set, selects the
corresponding event flag for which to wait.
[legal]
[privacy]
[GNU]
[policy]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.