 |
HP OpenVMS System Services Reference Manual
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 (Alpha, I64)
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:
- Timeout processing
Timeout processing is now enforced for
nonprivileged processes. Othe processes can request time processing by
specifying the ACME$M_TIMEOUT function modifier.
- Dialogue mode iteration limit
Nonprivileged processes are now
limited in the number of iterative requests they can make in a dialogue
sequence of calls.
$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 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:
- Authorizes a new branch to be added to the specified transaction.
- Checks, if the tm_name argument specifies a remote
node, that there is a communications link between the DECdtm
transaction manager on that node and the DECdtm transaction manager on
the local node.
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:
- The precondition was not satisfied.
- An abort event has occurred for the transaction.
- A call to $END_TRANS to end the transaction is in progress and it
is now too late to authorize a new branch for the transaction.
- The node specified by the tm_name argument was a
remote node and a failure was detected by the IPC mechanism.
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.
|
