HP OpenVMS System Services Reference Manual


Previous Contents Index

These categories appear in output item set entries and are specially interpreted by LOGINOUT.

These categories are restricted to the LOGINOUT client since they exist only for supporting the old style DECwindows and LGI-callouts.

ACMEVMS$K_OLD_AUTH_FLAGS

This output message category provides a series of flags that are used to construct the Authentication Flags indicating what passwords are required for the mapped user name.

These flags are used directly for DECwindows V1.2-4 and earlier in LGI$AUTHENTICATE_USER, and for calculations that are passed to LGI-callouts in cell ICR_PWDCOUNT by INTERACT/INTERACITVE_VALIDATION. It provides data abstraction from the specific SYSUAF fields.

The following table lists the flags, their bit number, and meaning:
Name Bit Number Meaning
OPENACCT 0 No password
PASSWORD_1 1 Primary password exists
PASSWORD_2 2 Secondary password exists
GENPWD 3 Passwords are not generated

This data is only supplied to LOGINOUT to support previous LGI-callout and DECwindows callout models. Other clients should follow the ACME model for user interaction.

This output item category provides a buffer that is to be filled with ACMEVMS$K_OLD_AUTH_FLAGS output message category data.

ACMEVMS$K_OLD_DECW_PWD_EXP_1

This output message category is a binary quadword indicating future password expiration.

It is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_OLD_DECW_PWD_EXP_2

This output message category is a binary quadword indicating future password expiration.

This data is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_OLD_DECW_PWD_QUALITY Output Message Category

This output message category is a binary longword indicating the failure category on password change.

This data is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_SYSUAF_070

This output message category provides a buffer that is to be filled with UAF070$ data. LOGINOUT now uses the $ACMW service, relying exclusively on UAI$_information rather than the direct manipulation of SYSUAF records. This output message category provides the same information as various UAI$_xxxx codes, but in the format of the OpenVMS V7.0 SYSUAF record. This item code allows LOGINOUT to continue supporting the LGI-callout interface. Your new software should use UAI$_xxxx item codes and avoid the ACMEVMS$K_SYSUAF_070 output message category.

This data is only supplied to LOGINOUT to support previous LGI-callout and DECwindows callout models. Other clients should follow the ACME model for user interaction.

ACMEVMS$K_OLD_TERMINAL_CONNECT

This output message category is passed from the VMS ACME to LOGINOUT to allow for changing the process name prior to auditing and to give an opportunity for the users to reconnect to any disconnected job they may have.

This data is provided only for compatibility with the historic behavior of LOGINOUT. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

VMS ACME-Specific Authentication Mechanisms

ACMEVMS$K_AUTH_MECH_ARGUS

This authentication mechanism is used by the TNT Server component used for system management from Intel machines. Its use is restricted to that client, enforced by the VMS ACME.

$ACMW

The $ACM service provides a common interface to all functions supported by the Authentication and Credentials Management (ACM) authority. The caller must specify the function code and any applicable function modifiers and item codes for the requested operation.

The $ACM service completes asynchronously; for synchronous completion, use the $ACMW form of the service.


Format

SYS$ACMW [efn], func, [context], itmlst, acmsb, [astadr], [astprm]


C Prototype

int sys$acmw (unsigned int efn, unsigned int func, struct _acmecb *context, void *itmlst, struct _acmesb *acmsb, void (*astadr)(__unknown_params), int astprm);


Description

Beginning in OpenVMS Version 7.3-2, a number of functional changes were made to SYS$ACM[W]. In the following descriptions of these changes, nonprivileged processes refer to processes running in user mode that do not have SECURITY privilege.

These changes are the following:


$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, see the HP 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_BRANCH

Authorizes a new branch to be added to a transaction.

Format

SYS$ADD_BRANCH [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,tm_name ,bid


C Prototype

int sys$add_branch (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], void *tmname, unsigned int bid [4]);


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

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 the option flag, which is described in Table SYS-15. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-15 $ADD_BRANCH Option Flag
Flag Name Description
DDTM$M_SYNC Specifies successful synchronous completion 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

The I/O status block in which the completion status of the service is returned as a condition value. See the Condition Values Returned section.

The following diagram shows the structure of the I/O status block:


astadr


OpenVMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference

The AST routine executed when the service completes, if SS$_NORMAL is returned in R0. The astadr argument is the address of the entry mask of this routine. The routine is executed in the same access mode as that of the caller of the $ADD_BRANCH service.

astprm


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

The AST parameter that is passed to the AST routine specified by the astadr argument.

tid


OpenVMS usage: trans_id
type: octaword (unsigned)
access: read only
mechanism: by reference

The identifier (TID) of the transaction for which a new branch is to be authorized.

tm_name


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

The name of the node on which the new branch is running. Note that this cannot be a cluster alias.

To ensure smooth operation in a mixed-network environment, refer to the chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for information on defining node names.

bid


OpenVMS usage: branch_id
type: octaword (unsigned)
access: write only
mechanism: by reference

An octaword in which the identifier (BID) of the new branch is returned. No other call to $ADD_BRANCH on any node ever returns the same BID value.

Description

The $ADD_BRANCH system service:

The precondition for the successful completion of $ADD_BRANCH is that the calling process must contain at least one branch of the specified transaction.

$ADD_BRANCH may fail for several reasons, including:

Postconditions on successful completion of $ADD_BRANCH are described in Table SYS-16:

Table SYS-16 Postconditions When$ADD_BRANCH Completes Successfully
Postcondition Meaning
A new branch is authorized for the transaction and its identifier is returned. The identifier (BID) of the new branch is returned in the octaword to which the bid argument points. $ADD_BRANCH uses the $CREATE_UID system service to generate the BID. No other call to $ADD_BRANCH or $CREATE_UID on any node ever returns the same BID value.
The transaction cannot commit until the new branch has been added to the transaction by a matching call to $START_BRANCH. See the description of $START_BRANCH for the definition of a "matching" call to $START_BRANCH.

There is also a wait form of the service, $ADD_BRANCHW.

Required Privileges

None

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW


Condition Values Returned

SS$_NORMAL If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ACCVIO An argument was not accessible to the caller.
SS$_BADPARAM The options flags were invalid.
SS$_EXASTLM The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA The job buffered I/O byte limit quota (BYTLM) was exceeded.
SS$_ILLEFC The event flag number was invalid.
SS$_INSFARGS A required argument was missing.
SS$_INSFMEM There was insufficient system dynamic memory for the operation.
SS$_INVBUFLEN The string passed in the tm_name argument was longer than 256 characters.
SS$_NOSUCHTID The calling process did not contain any branches in the transaction.
SS$_WRONGSTATE The transaction was in the wrong state for the attempted operation because either an abort event has occurred for the transaction, or a call to $END_TRANS to end the transaction is in progress and it is now too late to authorize new branches for the transaction.
Any IPC status An error has occurred while attempting to communicate with the node specified by the tm_name argument. The set of IPC statuses includes the set of DECnet errors.

$ADD_BRANCHW

Authorizes a new branch to be added to a transaction. $ADD_BRANCHW always waits for the request to complete before returning to the caller. Other than this, it is identical to $ADD_BRANCH.

Format

SYS$ADD_BRANCHW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,tm_name ,bid


C Prototype

int sys$add_branchw (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], void *tmname, unsigned int bid [4]);


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


Previous Next Contents Index