HP OpenVMS System Services Reference Manual


Previous Contents Index


$REM_IDENT

Removes the specified identifier record and all its holder records (if any) from the rights database.

Format

SYS$REM_IDENT id


C Prototype

int sys$rem_ident (unsigned int id);


Argument

id


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

Binary value of identifier deleted from rights database when $REM_IDENT completes execution. The id argument is a longword containing the identifier value.

Description

The Remove Identifier from Rights Database service removes from the rights database the specified identifier record, all its holder records (if any), and all records in identifiers that the deleted identifier held.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The specified identifier is of invalid format.
SS$_NORIGHTSDB The rights database does not exist.
SS$_NOSUCHID The specified identifier does not exist in the rights database.
RMS$_PRV The user does not have write 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, see the OpenVMS Record Management Services Reference Manual.


$RENAME

You can use the Rename service to change the name, type, or version of a file, or to move a file to another directory by changing its directory specification. However, you cannot use this service to move a file to another device.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$RESCHED

Requests reschedule of a process.

Format

SYS$RESCHED


C Prototype

int sys$resched (void);


Arguments

None.

Description

The Reschedule Process service requests that the set of runnable processes on the system be evaluated by their priority, with the potential result that the current process may be descheduled and requeued.

$RESCHED is intended to allow a process running at priority n to voluntarily relinquish the remainder of its run quantum to another process of the same priority. When the set of all runnable processes is evaluated, one of the following will occur:

  1. The process executing $RESCHED will be descheduled, while another process of equal or higher priority is selected to run. The descheduled process is placed at the end of its priority queue and all other processes at that priority will run before the process that called $RESCHED runs again. When the process does run again, $RESCHED completes and returns control to the application.
  2. If, after the evaluation of all runnable processes, the process that executed $RESCHED remains the highest-priority runnable process, that process remains current and continues to run. In this case, $RESCHED returns immediately.

Required Access or Privileges

None

Required Quota

None

Related Services

None


Condition Values Returned

SS$_NORMAL The service completed successfully.

$RESUME

Causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or cancels the effect of a subsequent suspend request.

Format

SYS$RESUME [pidadr] ,[prcnam]


C Prototype

int sys$resume (unsigned int *pidadr, void *prcnam);


Arguments

pidadr


OpenVMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference

Process identification (PID) of the process to be resumed. 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 cluster.

You must specify the pidadr argument to delete processes in other UIC groups.

prcnam


OpenVMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Name of the process to be resumed. The prcnam argument is the address of a character string descriptor pointing to the process name.

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

You can use the prcnam argument to resume only processes in the same UIC group as the calling process, because process names are unique to UIC groups, and the operating system uses the UIC group number of the calling process to interpret the process name specified by the prcnam argument. You must use the pidadr argument to delete processes in other UIC groups.


Description

The Resume Process service (1) causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or (2) cancels the effect of a subsequent suspend request.

If you specify neither the pidadr nor prcnam argument, the resume request is issued on behalf of the calling process.

If the longword value at address pidadr is 0, the PID of the target process is returned.

If one or more resume requests are issued for a process that is not suspended, a subsequent suspend request completes immediately; that is, the process is not suspended. No count of outstanding resume requests is maintained.

Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $RESUME:

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $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$_IVLOGNAM The specified process name has a length of 0 or has more than 15 characters.
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 resume the execution of 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.)

$REVOKID

Removes the specified identifier from the rights list of the process or the system. If the identifier is listed as a holder of any other identifier, the appropriate holder records are also deleted.

Format

SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]


C Prototype

int sys$revokid (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name, unsigned int *prvatr, unsigned int segment);


Arguments

pidadr


OpenVMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference

Process identification (PID) number of the process affected when $REVOKID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use --1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant.

prcnam


OpenVMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Process name on which $REVOKID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group.

id


OpenVMS usage: rights_id
type: quadword (unsigned)
access: modify
mechanism: by reference

Identifier and attributes to be removed when $REVOKID completes execution. The id argument is the address of a quadword containing the binary identifier code to be removed in the first longword and the attributes in the second longword.

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 following symbols for each bit position are defined in the system macro library ($KGBDEF):
Bit Position Meaning When Set
KGB$V_DYNAMIC Allows unprivileged holders of the identifier to remove it from or add it to the process rights database by using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS Makes any access 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 holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.

name


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Name of the identifier removed when $REVOKID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier.

prvatr


OpenVMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference

Attributes of the deleted identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier.

Description

The Revoke Identifier from Process service removes the specified identifier from the rights list of the process or the system. If the identifier is listed as a holder of any other identifier, the appropriate holder records are also deleted.

The result of passing the pidadr or the prcnam argument, or both, to $REVOKID is summarized in the following table.

Note that a value of 0 in either of the following tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.
prcnam pidadr Result
Omitted Omitted Current process ID is used; process ID is not returned.
Omitted 0 Current process ID is used; process ID is returned.
Omitted Specified Specified process ID is used.
Specified Omitted Specified process name is used; process ID is not returned.
Specified 0 Specified process name is used; process ID is returned.
Specified Specified Specified process ID is used and process name is ignored.

The result of passing either the name or the id argument, or both, to SYS$REVOKID is summarized in the following table:
name id Result
Omitted Omitted Illegal. The INSFARG condition value is returned.
Omitted Specified Specified identifier value is used.
Specified Omitted Specified identifier name is used; identifier value is not returned.
Specified 0 Specified identifier name is used; identifier value is returned.
Specified Specified Specified identifier value is used and identifier name is ignored.

Because the Revoke Identifier from Process service removes the specified identifier from the rights list of the process or the system, this service is meant for use by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant for use by the general system user.

Required Access or Privileges

You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT


Condition Values Returned

SS$_WASCLR The service completed successfully; the rights list did not contain the specified identifier.
SS$_WASSET The service completed successfully; the rights list already held the specified identifier.
SS$_ACCVIO The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; name cannot be read; or prvatr cannot be written.
SS$_INSFARG You did not specify either the id or the name argument.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.
SS$_IVLOGNAM You specified an invalid process name.
SS$_NONEXPR You specified a nonexistent process.
SS$_NOPRIV The caller does not have CMKRNL privilege or is not running in executive or kernel mode; or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.
SS$_NOSUCHID The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.
SS$_NOSYSNAM The operation requires SYSNAM privilege.
SS$_RIGHTSFULL The rights list of the process or system is full.
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, see the OpenVMS Record Management Services Reference Manual.


$REWIND

The Rewind service sets the context of a record stream to the first record in the file. RMS alters the context of the next record to indicate the first record as being the next record.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$RMSRUNDWN

Closes all files opened by OpenVMS RMS for the image or process and halts I/O activity. This routine performs a $CLOSE service for each file opened for processing.

Format

SYS$RMSRUNDWN buf-addr ,type-value


C Prototype

int sys$rmsrundwn (void *buf-addr, unsigned char *type-value);


Arguments

buf-addr


OpenVMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor

A descriptor pointing to a 22-byte buffer that is to receive the device identification (16 bytes) and the file identification (6 bytes) of an improperly closed output file. The buf-addr argument is the address of the descriptor that points to the buffer.

type-value


OpenVMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value

A single byte code that specifies the type of I/O rundown to be performed. The type-value argument is the actual value used.

This type of code has the following values and meanings:
0 Rundown of image and indirect I/O for process permanent files.
1 Rundown of image and process permanent files. The caller's mode must not be user.
2 Abort RMS I/O. The caller's mode must be either executive or kernel (the system calls the I/O rundown control routine with this argument for process deletion).


Description

The RMS Rundown service closes all files opened by OpenVMS RMS for the image or process and halts I/O activity. This routine performs a $CLOSE service for each file opened for processing. In addition to closing all files and terminating I/O activity, the I/O rundown control routine releases all locks held on records in shared files, clears buffers, and returns other resources allocated for file processing. You should continue to call the rundown control routine until you receive the success completion status code of RMS$_NORMAL.

Note that, prior to the execution of the $CLOSE service, the rundown control routine cancels all outstanding file operations specified in a File Access Block (FAB) or any QIO requests related to file operations (an Open, Create, or Extend service, for example). It also cancels any read/write requests to nondisk devices such as terminals or mailboxes prior to the execution of the $CLOSE service, resulting in possible loss of data. All read/write requests of disk I/O buffers, however, are allowed to complete, which guarantees that none of the data written to disk files will be lost.

There is no predefined macro of the form $RMSRUNDWN_G or $RMSRUNDWN_S to call this service.

Required Access or Privileges

None

Required Quota

None

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CLOSE, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SETDDIR, $SETDFPROT, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR


Condition Values Returned

RMS$_NORMAL The service completed successfully.
RMS$_CCF The I/O rundown routine cannot close the file.
RMS$_IAL The argument list is invalid. An output file could not be closed successfully, and the user buffer could not be written.


Previous Next Contents Index