 |
HP OpenVMS System Services Reference Manual
$FINISH_RDB
Deallocates the record stream and clears the context value used with
$FIND_HELD, $FIND_HOLDER, or $IDTOASC.
On Alpha and Integrity server systems, this service accepts 64-bit
addresses.
Format
SYS$FINISH_RDB contxt
C Prototype
int sys$finish_rdb (unsigned int *contxt);
Argument
contxt
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by 32- or 64-bit reference |
Context value to be cleared when $FINISH_RDB completes execution. The
contxt argument is a longword containing the address
of the context value.
Description
The Terminate Rights Database Context service clears the context
longword and deallocates the record stream associated with a sequence
of rights database lookups performed by the $IDTOASC, $FIND_HOLDER, and
$FIND_HELD services.
If you repeatedly call $IDTOASC, $FIND_HOLDER, or $FIND_HELD until
SS$_NOSUCHID is returned, you do not need to call $FINISH_RDB because
the record stream has already been deallocated and the context longword
has already been cleared.
Required Access or Privileges
None
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,
$ERAPAT, $FIND_HELD, $FIND_HOLDER, $FORMAT_ACL, $FORMAT_AUDIT,
$GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER,
$MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID,
$SET_SECURITY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
contxt argument cannot be written by the caller.
|
|
SS$_IVCHAN
|
The contents of the
contxt longword are not valid.
|
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,
see the OpenVMS Record Management Services Reference Manual.
$FLUSH
The Flush service writes out all modified I/O buffers and file
attributes associated with the file. This ensures that all record
activity up to the point at which the Flush service executes is
actually reflected in the file.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$FORCEX
Causes an Exit ($EXIT) service call to be issued on behalf of a
specified process.
Format
SYS$FORCEX [pidadr] ,[prcnam] ,[code]
C Prototype
int sys$forcex (unsigned int *pidadr, void *prcnam, unsigned int code);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process to be forced to exit. The
pidadr argument is the address of a longword
containing the PID.
The pidadr argument can refer to a process running on
the local node or a process running on another node in the OpenVMS
Cluster system.
The pidadr argument is optional but must be specified
if the process that is to be forced to exit is not in the same UIC
group as the calling process.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name of the process that is to be forced to exit. The
prcnam argument is the address of a character string
descriptor pointing to the process name string. A process running on
the local node can be identified with a 1- to 15-character string. To
identify a process on a particular node in a cluster, specify the full
process name, which includes the node name as well as the process name.
The full process name can contain up to 23 characters.
The prcnam argument can be used only on behalf of
processes in the same UIC group as the calling process. To force
processes in other groups to exit, you must specify the
pidadr argument. This restriction exists because the
operating system interprets the UIC group number of the calling process
as part of the specified process name; the names of processes are
unique to UIC groups.
code
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Completion code value to be used as the exit parameter. The
code argument is a longword containing this value. If
you do not specify the code argument, the value 0 is
passed as the completion code.
Description
The Force Exit service causes an Exit service call to be issued on
behalf of a specified process.
If you specify neither the pidadr nor the
prcnam argument, the caller is forced to exit and
control is not returned.
If the longword at address pidadr is 0, the PID of the
target process is returned.
The Force Exit system service requires system dynamic memory.
The image executing in the target process follows normal exit
procedures. For example, if any exit handlers have been specified, they
gain control before the actual exit occurs. Use the Delete Process
($DELPRC) service if you do not want a normal exit.
When a forced exit is requested for a process, a user-mode asynchronous
system trap (AST) is queued for the target process. The AST routine
causes the $EXIT service call to be issued by the target process.
Because the AST mechanism is used, user mode ASTs must be enabled for
the target process, or no exit occurs until ASTs are reenabled. Thus,
for example, a suspended process cannot be stopped by $FORCEX. The
process that calls $FORCEX receives no notification that the exit is
not being performed.
If an exit handler resumes normal processing, the process will not
exit. In particular, if the program is written in Ada and there is a
task within the program that will not terminate, the program will not
exit.
The $FORCEX service completes successfully if a force exit request is
already in effect for the target process but the exit is not yet
completed.
Required Access or Privileges
Depending on the operation, the calling process might need a certain
privilege to use $FORCEX:
- You need GROUP privilege to force an exit for a process in the same
group that does not have the same UIC as the calling process.
- You need WORLD privilege to force an exit for any process in the
system.
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $GETJPI, $GETJPIW, $HIBER,
$PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification cannot be written by the caller.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for the operation.
|
|
SS$_IVLOGNAM
|
The process name string has a length equal to 0 or greater than 15.
|
|
SS$_NONEXPR
|
The specified process does not exist, or an invalid process
identification was specified.
|
|
SS$_NOPRIV
|
The process does not have the privilege to force an exit for the
specified process.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the cluster.
|
|
SS$_REMRSRC
|
The remote node has insufficient resources to respond to the request.
(Bring this error to the attention of your system manager.)
|
|
SS$_UNREACHABLE
|
The remote node is a member of the cluster but is not accepting
requests. (This is normal for a brief period early in the system boot
process.)
|
$FORGET_RM
Deletes a Resource Manager instance (RMI) from the calling process.
Format
SYS$FORGET_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id
C Prototype
int sys$forget_rm (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
rm_id);
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 listed in Table SYS-37. All undefined bits must be 0. If this
argument is omitted, no flags are used.
Table SYS-37 $FORGET_RM 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 $FORGET_RM 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.
rm_id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The identifier of the RMI to be deleted from the calling process.
Description
The $FORGET_RM system service:
- Deletes the specified Resource Manager instance (RMI) from the
calling process.
- Tries to abort all transactions that have not already committed and
that have Resource Manager (RM) participants associated with that RMI.
- Removes all RM participants associated with the RMI from their
transactions.
- Implicitly acknowledges all unacknowledged event reports delivered
to that RMI or to its RM participants. The reply given in the implicit
acknowledgment depends on the type of the event as follows:
Table SYS-38 $FORGET_RM's Implicit Acknowledgments
| Type of Event |
Reply |
|
Abort
|
SS$_NORMAL
|
|
Commit
|
SS$_REMEMBER
|
|
Prepare
|
SS$_VETO (with the DDTM$_SEG_FAIL reason code)
|
|
One-phase commit
|
SS$_VETO
|
|
Default transaction started
|
SS$_NORMAL
|
|
Nondefault transaction started
|
SS$_NORMAL
|
Preconditions for the successful completion of $FORGET_RM are:
- The calling process must contain the specified RMI.
- The access mode of the caller must be the same as or more
privileged than that of the specified RMI.
Postconditions on successful completion of $FORGET_RM are described in
Table SYS-39:
Table SYS-39 Postconditions When$FORGET_RM Completes Successfully
| Postcondition |
Meaning |
|
The specified RMI is deleted from the calling process.
|
The result is that:
- Its identifier is invalid. Any subsequent calls to $JOIN_RM or
$FORGET_RM that pass its identifier will fail.
- The DECdtm transaction manager will deliver no more event reports
to that RMI.
|
|
There are no RM participants associated with the RMI.
|
Removes all RM participants associated with the specified RMI from
their transactions. Thus the DECdtm transaction manager will deliver no
more event reports to those RM participants.
For an RM participant that had an unacknowledged event report, the
postconditions are the same as those of the appropriate implicit
acknowledgment (see Table SYS-38) except that the RM participant is
always removed from the transaction.
|
|
There are no unacknowledged event reports delivered to the RMI or its
RM participants.
|
All unacknowledged event reports are implicitly acknowledged by this
call to $FORGET_RM (see Table SYS-38). Thus a subsequent call to
$ACK_EVENT that acknowledges one of these event reports will fail.
|
|
Quotas are returned.
|
Returns the following quotas:
- The BYTLM quota consumed by the call to $DECLARE_RM that created
the RMI.
- The ASTLM quotas consumed by all calls to $JOIN_RM or $ACK_EVENT
that added RM participants associated with the RMI.
|
Note that when a process terminates (normally or abnormally), a
$FORGET_RM is automatically performed for each RMI in that process. And
when an image terminates (normally or abnormally), a $FORGET_RM is
automatically performed for each user mode RMI in that process.
There is also a wait form of the service, $FORGET_RMW.
Required Privileges
None
Required Quotas
None
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,
$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW,
$END_TRANS, $END_TRANSW, $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
|
An option flag was 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$_WRONGACMODE
|
The access mode of the caller was less privileged than that of the RMI.
|
|
SS$_NOSUCHRM
|
The calling process did not contain the specified RMI.
|
$FORGET_RMW
Deletes a Resource Manager instance (RMI) from the calling process.
$FORGET_RMW always waits for the request to complete before returning
to the caller. Other than this, it is identical to $FORGET_RM.
Format
SYS$FORGET_RMW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id
C Prototype
int sys$forget_rmw (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
rm_id);
$FORMAT_ACL
Formats the specified access control entry (ACE) into a text string.
Format
SYS$FORMAT_ACL aclent ,[acllen] ,aclstr ,[width] ,[trmdsc] ,[indent]
,[accnam] ,[nullarg]
C Prototype
int sys$format_acl (void *aclent, unsigned short int *acllen, void
*aclstr, unsigned short int *width, void *trmdsc, unsigned short int
*indent, unsigned int *accnam, int (*routin)(__unknown_params));
Arguments
aclent
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Description of the ACE formatted when $FORMAT_ACL completes execution.
The aclent argument is the address of a descriptor
pointing to a buffer containing the description of the input ACE. The
first byte of the buffer contains the length of the ACE; the second
byte contains a value that identifies the type of ACE, which in turn
determines the ACE format.
For more information about the ACE format, see the Description section.
acllen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the output string resulting when $FORMAT_ACL completes
execution. The acllen argument is the address of a
word containing the number of characters written to
aclstr.
aclstr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Formatted ACE resulting when $FORMAT_ACL completes its execution. The
aclstr argument is the address of a string descriptor
pointing to a buffer containing the output string.
width
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Maximum width of the formatted ACE resulting when $FORMAT_ACL completes
its execution. The width argument is the address of a
word containing the maximum width of the formatted ACE. If this
argument is omitted or contains the value 0, an infinite length display
line is assumed. When the width is exceeded, the character specified by
trmdsc is inserted.
trmdsc
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Line termination characters used in the formatted ACE. The
trmdsc argument is the address of a descriptor
pointing to a character string containing the termination characters
that are inserted for each formatted ACE when the width has been
exceeded.
indent
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Number of blank characters beginning each line of the formatted ACE.
The indent argument is the address of a word
containing the number of blank characters that you want inserted at the
beginning of each formatted ACE.
accnam
| OpenVMS usage: |
access_bit_names |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Names of the bits in the access mask when executing the $FORMAT_ACL.
The accnam argument is the address of an array of 32
quadword descriptors that define the names of the bits in the access
mask. Each element points to the name of a bit. The first element names
bit 0, the second element names bit 1, and so on.
You can call LIB$GET_ACCNAM to retrieve the access name table for the
class of object whose ACL is to be formatted.
If you omit accnam, the following names are used:
| Bit |
Name |
|
Bit 0
|
READ
|
|
Bit 1
|
WRITE
|
|
Bit 2
|
EXECUTE
|
|
Bit 3
|
DELETE
|
|
Bit 4
|
CONTROL
|
|
Bit 5
|
BIT_5
|
|
Bit 6
|
BIT_6
|
.
.
.
|
|
|
Bit 31
|
BIT_31
|
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to HP.
Description
The Format Access Control List Entry service formats the specified
access control entry (ACE) into text string representation. There are
seven types of ACE:
- Alarm ACE
- Application ACE
- Audit ACE
- Creator ACE
- Default Protection ACE
- Identifier ACE
- Subsystem ACE
|
