Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $FIND_HOLDER

> Returns the holder of a specified identifier.

### Format

> SYS$FIND_HOLDER id ,[holder] ,[attrib] ,[contxt]

### C Prototype

> int sys$find_holder (unsigned int id, struct _generic_64 *holder, unsigned int *attrib, unsigned int *contxt);

### Arguments

> #### id

> OpenVMS usage: | rights_id
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

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

> Required Access or Privileges

> Read access to the rights database is required to obtain information about identifiers marked HOLDER_HIDDEN.

> Required Quota

> None

> Related Services

> $ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $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 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.

## $FINISH_RDB

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

> 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, refer to 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.)

## $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 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.

> Alarm ACE

> The access Alarm ACE generates a security alarm. Its format is as follows:

The following table describes the ACE fields and lists the symbol name for each:

Field | Symbol Name | Description
--- | --- | ---
Length | ACE$B_SIZE | Byte containing the length in bytes of the ACE buffer
Type | ACE$B_TYPE | Byte containing the type value ACE$C_ALARM
Flags | ACE$W_FLAGS | Word containing Alarm ACE information and ACE type-independent information
Access | ACE$L_ACCESS | Longword containing a mask indicating the access modes to be watched
Alarm name | ACE$T_AUDITNAME | Character string containing the alarm name

The flag field contains information specific to Alarm ACEs and information applicable to all types of ACEs. The following symbols are bit offsets to the Alarm ACE information:

Bit Position | Meaning When Set
--- | ---
ACE$V_SUCCESS | Indicates that the alarm is raised when access is successful
ACE$V_FAILURE | Indicates that the alarm is raised when access fails

The following symbols are bit offsets to ACE information that is independent of ACE type:

Bit Position | Meaning When Set
--- | ---
ACE$V_DEFAULT | This ACE is added to the ACL of any file created in the directory whose ACL contains this ACE. This bit is applicable only for an ACE in a directory file's ACL.
ACE$V_HIDDEN | This ACE is application dependent. You cannot use the DCL ACL commands and the ACL editor to change the setting; the DCL command DIRECTORY/ACL does not display it.
ACE$V_NOPROPAGATE | This ACE is not propagated among versions of the same file.
ACE$V_PROTECTED | This ACE is not deleted if the entire ACL is deleted; instead, you must delete this ACE explicitly.

The following symbol values are offsets to bits within the access mask. You can also obtain the symbol values as masks with the appropriate bit set using the prefix ACE$M rather than ACE$V:

Bit | Meaning When Set
--- | ---
ACE$V_READ | Read access is monitored.
ACE$V_WRITE | Write access is monitored.
ACE$V_EXECUTE | Execute access is monitored.
ACE$V_DELETE | Delete access is monitored.
ACE$V_CONTROL | Modification of the access field is monitored.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_041.HTML