HP OpenVMS System Services Reference Manual


Previous Contents Index


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

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:

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:

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:


Previous Next Contents Index