 |
OpenVMS System Services Reference Manual
$ABORT_TRANSW
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.
Do not call $ABORT_TRANSW from AST level, or from an access mode that
is more privileged than the DECdtm calls made by any resource manager
participant in the transaction. If you do, the $ABORT_TRANSW service
will wait indefinitely.
Format
SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]
,[reason]]
C Prototype
int sys$abort_transw (unsigned int efn, struct _iosb *iosb,...);
$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);
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.
Description
This service is used to acquire ownership of an OpenVMS Galaxy lock. If
the lock is free, the caller becomes the owner and control returns
immediately. If the lock is owned, based on the input flags and the
timeout value, either the caller will wait or an error will be returned.
The default behavior when an attempt is made to acquire a lock that is
owned, is to spin for 10 microseconds and then to wait. If a wait
timeout value was specified in the call, it is used. Otherwise the
timeout value set in the lock by $CREATE_GALAXY_LOCK will be used. This
behavior can be changed with the input flags.
If just GLOCK$C_NOSPIN is specified and the lock is owned, no spin will
be done.
If just GLOCK$C_NOWAIT is specified and the lock is owned, the caller
will only spin on the lock. If a timeout value is specified in the
call, it is used as the spin time. Otherwise, the caller will spin for
10 microseconds. If the lock does not become available during the spin,
the lock is not acquired and SS$_NOWAIT is returned.
If both GLOCK$C_NOSPIN and GLOCK$C_NOWAIT are specified and the lock is
owned, control returns immediately. The lock is not acquired and
SS$_NOWAIT is returned.
Due to system events such an OpenVMS Galaxy instance shutting down, a
lock may become owned by a non-existent entity. If this occurs, the
default behavior of $ACQUIRE_GALAXY_LOCK is to break the old lock
ownership. The caller becomes the new owner and the service returns
SS$_BROKEN. If GLOCK$C_NOBREAK is specified, $ACQUIRE_GALAXY_LOCK will
not break the lock ownership and returns SS$_NOBREAK.
Required Access or Privileges
Write access to OpenVMS Galaxy lock table contains lock to acquire.
Required Quota
None
Related Services
$CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK,
$DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_BROKEN
|
Lock acquired after lock ownership was broken.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKOP
|
Invalid lock operation.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_LOCK_TIMEOUT
|
Failed to acquire lock; request has timed out.
|
|
SS$_NOBREAK
|
Failed to acquire lock; lock ownership is broken.
|
|
SS$_NOWAIT
|
Failed to acquire lock; NOWAIT was specified.
|
$ADD_HOLDER
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);
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.
|
Description
The Add Holder Record to Rights Database service registers the
specified user as a holder of the specified identifier with the rights
database.
Required Access or Privileges
Write access to the rights database is required.
Required Quota
None
Related Services
$ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER,
$FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER,
$REM_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
holder argument cannot be read by the caller.
|
|
SS$_BADPARAM
|
The specified attributes contain invalid attribute flags.
|
|
SS$_DUPIDENT
|
The specified holder already exists in the rights database for this
identifier.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The specified identifier or holder is of an invalid format, the
specified holder is 0, or the specified identifier and holder are equal.
|
|
SS$_NORIGHTSDB
|
The rights database does not exist.
|
|
SS$_NOSUCHID
|
The specified identifier does not exist in the rights database, or the
specified holder identifier does not exist in the rights database.
|
|
RMS$_PRV
|
The user does not have write access to the rights database.
|
Because the rights database is an indexed file accessed with OpenVMS
RMS, this service can also return RMS status codes associated with
operations on indexed files. For descriptions of these status codes,
refer to the OpenVMS Record Management Services Reference Manual.
$ADD_IDENT
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);
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.
Description
The Add Identifier to Rights Database service adds the specified
identifier to the rights database.
Required Access or Privileges
Write access to the rights database is required.
Required Quota
None
Related Services
$ADD_HOLDER, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER,
$FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER,
$REM_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
name argument cannot be read by the caller, or the
resid argument cannot be written by the caller.
|
|
SS$_BADPARAM
|
The specified attributes contain invalid attribute flags.
|
|
SS$_DUPIDENT
|
The specified identifier already exists in the rights database.
|
|
SS$_DUPLNAM
|
The specified identifier name already exists in the rights database.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The format of the specified identifier is invalid.
|
|
SS$_NORIGHTSDB
|
The rights database does not exist.
|
|
RMS$_PRV
|
The user does not have write access to the rights database.
|
Because the rights database is an indexed file accessed with OpenVMS
RMS, this service can also return RMS status codes associated with
operations on indexed files. For descriptions of these status codes,
refer to the OpenVMS Record Management Services Reference Manual.
$ADD_PROXY
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);
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_EXPAND
|
The service should not convert the node name 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_RETURN
|
The service should not wait for a return status from the security
server. No return status from the server's function will be returned to
the caller.
|
Description
The Add Proxy service adds a new proxy to, or modifies an existing
proxy in, the proxy database.
Required Access or Privileges
The caller must have either SYSPRV privilege or a UIC group less than
or equal to the MAXSYSGRP system parameter.
Required Quota
None
Related Services
$DELETE_PROXY, $DISPLAY_PROXY, $VERIFY_PROXY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
rem_node,
rem_user,
local_user, or
flags argument cannot be read by the service.
|
|
SS$_BADPARAM
|
An invalid flag was specified in the
flags argument.
|
|
SS$_BADBUFLEN
|
The length of the
rem_node,
rem_user, or
local_user argument was out of range.
|
|
SS$_NOSYSPRV
|
The caller does not have access to the proxy database.
|
|
|
|
|
This service can also return any of the following messages passed from
the security server, or any OpenVMS RMS error message encountered
during operations on the proxy database:
|
|
SECSRV$_BADLOCALUSERLEN
|
The local user name length is out of range.
|
|
SECSRV$_BADNODENAMELEN
|
The node name length is out of range.
|
|
SECSRV$_BADREMUSERLEN
|
The remote user name length is out of range.
|
|
SECSRV$_DUPLICATEUSER
|
The user name specified by the
local_user argument already exists in the proxy
record's local user list.
|
|
SECSRV$_PROXYNOTACTIVE
|
Proxy processing is currently stopped. Try the request again later.
|
|
SECSRV$_SERVERNOTACTIVE
|
The security server is not currently active. Try the request again
later.
|
|
SECSRV$_TOOMANYUSERS
|
The specified proxy already has 16 local users and cannot accommodate
any more.
|
|
