 |
HP OpenVMS System Services Reference Manual
The event_mask argument is a longword bit mask that is
the logical OR of each bit set, where each bit corresponds to an event.
The $DDTMDEF module defines a symbolic name for each flag bit.
Table SYS-25 describes the flags. All undefined bits must be 0.
If this argument is omitted, the following events are requested:
- Abort events
- Commit events
- One-phase commit events
- Prepare events
Table SYS-25 $DECLARE_RM Event Selection Flags
| Flag Name |
Description |
|
DDTM$M_EV_ABORT
|
Specifies that abort events are to be reported to the RM participants
associated with the new RMI. If this flag is set, when an abort event
occurs for a transaction, the DECdtm transaction manager delivers an
abort event report to each RM participant in the transaction that is
associated with the new RMI.
|
|
DDTM$M_EV_COMMIT
|
Specifies that commit events are to be reported to the RM participants
associated with the new RMI.
If this flag is set, when the DECdtm transaction manager decides
that the outcome of a transaction is commit, it delivers a commit event
report to each RM participant in the transaction that is associated
with the new RMI.
|
|
DDTM$M_EV_PREPARE
|
Specifies that prepare events are to be reported to the RM participants
associated with the new RMI.
If this flag is set, when the DECdtm transaction manager initiates
the commit protocol (in response to a call to $END_TRANS) to determine
the outcome of a transaction, it reports a prepare event to each RM
participant in the transaction that is associated with the new RMI.
The acknowledgment of a prepare event is a vote on the outcome of
the transaction. See $ACK_EVENT for more information.
|
|
DDTM$M_EV_TRANS_START
|
Specifies that events of type Transaction Started are to be reported to
the new RMI. Events of type Transaction Started are:
- Default transaction started events.
- Non-default transaction-started events.
If this flag is set, the DECdtm transaction manager will report one of
these events to the new RMI whenever a new branch in the calling
process is added to a transaction, provided that the access mode of the
new branch is not more privileged than the access mode of the new RMI.
The acknowledgment of that event report may add a new RM participant
associated with the new RMI to that transaction. See the description of
the
acmode argument for a discussion of access modes.
|
Description
The $DECLARE_RM system service creates a new Resource Manager instance
(RMI) in the calling process and returns its identifier.
Preconditions for successful completion of $DECLARE_RM include:
- The local node must have a DECdtm transaction log.
- The TP_SERVER process must be running on the local node.
When $DECLARE_RM completes successfully, a new RMI is created in the
calling process, and its identifier is returned. The new RMI has no RM
participants. They are added to transactions by subsequent calls to
$JOIN_RM or $ACK_EVENT.
DECdtm events for the RMI and its RM participants, as specified by
event_mask, are reported to the specified event
handler.
If an RM does not specify DDTM$M_EV_PREPARE, its RM participants do not
have a vote on the outcome of their transactions. The DECdtm
transaction manager assumes that their votes are "yes".
If an RM does not specify DDTM$M_EV_ABORT or DDTM$M_EV_COMMIT, DECdtm
forgets the involvement of the RM participant associated with the RMI
in the transaction when the corresponding event occurs.
A one-phase commit event is reported to an RM participant if:
- Both the DDTM$M_EV_PREPARE and DDTM$M_EV_COMMIT flags are set.
- It is the only RM participant in the transaction.
- It is running in the process that started the transaction (the
process that called $START_TRANS).
The new RMI is deleted from the calling process:
- On termination of the calling process.
- On termination of the current image, if the access mode of the RMI
was user mode.
- On successful completion of a call to $FORGET_RM in the calling
process that passes its identifier.
There is also a wait form of the service, $DECLARE_RMW.
Required Privileges
None
Required Quotas
BYTLM, ASTLM
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,
$CREATE_UID, $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
|
Either the options flags were invalid or the event mask flags were
invalid.
|
|
SS$_EXASTLM
|
The process AST limit (ASTLM) 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
part_name argument was too long.
|
|
SS$_NOLOG
|
The local node did not have a transaction log.
|
|
SS$_TPDISABLED
|
The TP_SERVER process was not running on the local node.
|
$DECLARE_RMW
Creates a new Resource Manager instance (RMI) in the calling process.
$DECLARE_RMW always waits for the request to complete before returning
to the caller. Other than this, it is identical to $DECLARE_RM.
Format
SYS$DECLARE_RMW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id
,event_handler ,[part_name] [,[rm_context] ,[acmode] ,[tm_log_id]
,[event_mask]]
C Prototype
int sys$declare_rmw (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
*rm_id, void (*event_handler)(__unknown_params),...);
$DELETE
The Delete service removes an existing record from a relative or
indexed file. You cannot use this service when processing sequential
files.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
$DELETE_BUFOBJ (Alpha and I64)
On Alpha and I64 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);
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.
Description
The Delete Buffer Object system service deletes the buffer object
identified by the buffer_handle_64 argument. The
associated memory is made free to be paged, swapped, or deleted.
Buffer objects are also automatically deleted at image rundown.
Required Privileges
None
Required Quota
None
Related Services
$CREATE_BUFOBJ_64
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
buffer_handle_64 argument cannot be read by the caller.
|
|
SS$_BADPARAM
|
The
buffer_handle_64 argument is not a valid buffer handle.
|
|
SS$_NOPRIV
|
The buffer object was created by a more privileged access mode than the
caller's access mode.
|
$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 HP 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.
Description
This service invalidates the OpenVMS Galaxy lock and deletes it. The
memory for the lock is not truly deleted; however, it is put on a free
list for later use.
Required Access or Privileges
CMKRNL, SHMEM
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE,
$DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_BADLCKTBL
|
Galaxy lock table is corrupt.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_LOCKINUSE
|
Invalid operation; lock is in use.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEN
|
Operation requires SHMEM privilege.
|
$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 HP 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);
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.
Description
This service deletes an OpenVMS Galaxy lock table. If there are no
longer any mappers of the locktable section, the table is deleted.
Required Access or Privileges
CMKRNL, SHMEM
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK,
$DELETE_GALAXY_LOCK, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE,
$RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEM
|
Operation requires SHMEM privilege.
|
$DELETE_INTRUSION
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);
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 HP 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_CRITERIAL
|
Address of a buffer, 1-1058 bytes long, 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_RETURN
|
The service should not wait for 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
user_criteria argument is a character string. If TRUE,
this argument is a 32-bit item list.
|
Description
The Delete Intrusion Records service deletes from the intrusion
database a set of records matching the criteria you specify in the
user_criteria argument. All records matching the
criteria you specify are deleted. You do not have to call the service
more than once to delete a set of records.
For example, if you specify an asterisk (*) for the
user_criteria argument, the service deletes all
records in the intrusion database with one call.
Required Access or Privileges
$DELETE_INTRUSION requires access to the intrusion database. You must
have SECURITY privilege to access the database.
Required Quota
None
Related Services
$SCAN_INTRUSION, $SHOW_INTRUSION
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
user_criteria argument cannot be read.
|
|
SS$_BADBUFLEN
|
The length of the
user_criteria argument is out of range.
|
|
SS$_BADPARAM
|
An invalid flag was specified in the
flags argument.
|
|
SS$_NOSECURITY
|
The caller does not have SECURITY privilege.
|
|
|
|
|
This service can also return any of the following messages passed from
the security server:
|
|
|
|
|
SECSRV$_CIADBEMPTY
|
No records in the intrusion database.
|
|
SECSRV$_NOSUCHINTRUDER
|
No records matching the specified criteria were found in the intrusion
database.
|
|
SECSRV$_SERVERNOTACTIVE
|
The security server is not currently active. Try the request again
later.
|
$DELETE_PROXY
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);
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_EXPAND
|
The service should not convert the node name 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_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.
|
|
PRX$M_EXACT
|
The service should match exactly the remote node and remote user and
ignore wildcards.
|
Description
The Delete Proxy service deletes a proxy from, or modifies an existing
proxy in, the proxy database.
|
