Arguments

id

Binary identifier value whose holders are found by $FIND_HOLDER. The
id argument is a longword containing the binary
identifier value.

holder

OpenVMS usage:

rights_holder

type:

quadword (unsigned)

access:

write only

mechanism:

by reference

Holder identifier returned when $FIND_HOLDER completes execution. The
holder argument is the address of a quadword
containing the holder identifier. The first longword contains the UIC
of the holder with the high-order word containing the group number and
the low-order word containing the member number. The second longword
contains the value 0.

attrib

OpenVMS usage:

mask_longword

type:

longword (unsigned)

access:

write only

mechanism:

by reference

Mask of attributes associated with the holder record specified by
holder. The attrib argument is the
address of a longword containing the attribute mask.

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 following are the symbols for each bit
position:

Bit Position

Meaning When Set

KGB$V_DYNAMIC

Allows holders of the identifier to remove it from or add it to the
process rights list by using the DCL command SET RIGHTS_LIST. For more
information on SET RIGHTS_LIST, refer to the OpenVMS DCL Dictionary.

KGB$V_NOACCESS

Makes any 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 the holder of an identifier to charge disk space to the
identifier. It is used only for file objects.

KGB$V_SUBSYSTEM

Allows holders of an identifier to create and maintain protected
subsystems by assigning the Subsystem ACE to the application images in
the subsystem.

contxt

OpenVMS usage:

context

type:

longword (unsigned)

access:

modify

mechanism:

by reference

Context value used while searching for all the holders of the specified
identifier when executing $FIND_HOLDER. The contxt
argument is the address of a longword containing the context value.
When calling $FIND_HOLDER repeatedly, contxt must be
set initially to 0 and the resulting context of each call to
$FIND_HOLDER must be presented to each subsequent call. After the
argument is passed to $FIND_HOLDER, you must not modify its value.

Description

The Find Holder of Identifier service returns the holder of the
specified identifier. To determine all the holders of the specified
identifier, you call SYS$FIND_HOLDER repeatedly until it returns the
status code SS$_NOSUCHID, which indicates that $FIND_HOLDER has
returned all identifiers, cleared the context longword, and deallocated
the record stream. If you complete your calls to $FIND_HOLDER before
SS$_NOSUCHID is returned, you use the $FINISH_RDB service to clear the
context value and deallocate the record stream.

Note that when you use wildcards with this service, the records are
returned in the order in which they were originally written. (This
action results from the fact that the first record is located on the
basis of the identifier. Thus, all the target records have the same
identifier or, in other words, they have duplicate keys, which leads to
retrieval in the order in which they were written.)

Condition Values Returned

The
id argument cannot be read by the caller, or the
holder,
attrib, or
contxt argument cannot be written by the caller.

SS$_IVCHAN

The contents of the
contxt longword are not valid.

SS$_INSFMEM

The process dynamic memory is insufficient for opening the rights
database.

SS$_IVIDENT

The specified identifier or holder identifier is of invalid format.

SS$_NOIOCHAN

No more rights database context streams are available.

SS$_NOSUCHID

The specified identifier does not exist in the rights database, or no
further holders exist for the specified identifier.

RMS$_PRV

The user does not have read 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.

Deallocates the record stream and clears the context value used with
$FIND_HELD, $FIND_HOLDER, or $IDTOASC.

On Alpha 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 (Alpha)

mechanism:

by 32-bit reference (VAX)

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.

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,
refer to the OpenVMS Record Management Services Reference Manual.

C Prototype

Arguments

pidadr

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.

C Prototype

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

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

The format for each of the ACE types is described in the following
sections and the byte offsets and type values for each ACE type are
defined in the $ACEDEF system macro library.