OpenVMS System Services Reference Manual

Document revision date: 30 March 2001

OpenVMS System Services Reference Manual

Contents

Index

$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.

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.

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 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.

$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.

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.

Contents

Index

privacy and legal statement

4527PRO_001.HTML

OpenVMS usage:	galaxy lock handle
type:	quadword (unsigned)
access:	read
mechanism:	input by value

OpenVMS usage:	wait timeout
type:	longword (unsigned)
access:	read
mechanism:	input by value

OpenVMS usage:	bit mask
type:	longword (unsigned)
access:	read
mechanism:	input by value

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.

OpenVMS usage:	rights_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

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.

OpenVMS usage:	char-string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor