 |
HP OpenVMS System Services Reference Manual
This service can also return status values from the following system
services: $CLREF, $SYNCH, $PERSONA_EXTENSION_LOOKUP, and $PERSONA_QUERY.
$REGISTRYW (Alpha and I64)
On Alpha and I64 systems, interface to the OpenVMS Registry database
server.
The $REGISTRY service supports both asynchronous and synchronous
operations. For asynchronous completion, use the Registry ($REGISTRY)
system service.
For synchronous completion, use the Registry and Wait ($REGISTRYW)
system service. The $REGISTRYW system service is identical to the
$REGISTRY system service, except that $REGISTRYW returns to the caller
after the system completes the requested operation. For additional
information about system service completion, see the Synchronize
($SYNCH) system service.
This system service is 64-bit compatible.
Format
SYS$REGISTRYW [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or
astadr_64] [,astprm or astprm_64] [,timeout]
C Prototype
int sys$registryw (unsigned int efn, unsigned int func, void *, void
*itmlst, struct _iosb *iosb, ...);
$RELEASE
The Release service unlocks the record specified by the contents of the
record file address (RAB$W_RFA) field of the RAB.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$RELEASE_GALAXY_LOCK (Alpha Only)
Releases ownership of an OpenVMS Galaxy lock.
Note that this system service is supported only in an OpenVMS Alpha
Galaxy environment.
For more information about programming with OpenVMS Galaxy system
services, see the HP OpenVMS Alpha Partitioning and Galaxy Guide.
Format
SYS$RELEASE_GALAXY_LOCK handle
C Prototype
int sys$release_galaxy_lock (unsigned __int64 lock_handle);
Arguments
handle
| OpenVMS usage: |
galaxy lock handle |
| type: |
quadword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The 64-bit lock handle that identifies the lock to be released. This
value is returned by SYS$CREATE_GALAXY_LOCK.
Description
This service releases ownership of an OpenVMS Galaxy lock. Because a
Galaxy lock can be acquired multiple times by the same owner (nested
ownership), the lock is not released until the ownership count goes to
zero. If the lock ownership is completely released and there are other
threads waiting for the lock, they are released from their wait states.
Required Access or Privileges
Write access to lock.
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE,
$DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKOP
|
Invalid lock operation.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
$RELEASE_VP (VAX Only)
On VAX systems, terminates the current process' status as a vector
consumer.
Format
SYS$RELEASE_VP
Arguments
None.
Description
The Release Vector Processor service terminates the current process'
status as a vector consumer. The $RELEASE_VP service waits for all
pending vector instructions and vector memory operations to complete.
It then declares that the process no longer needs a vector-present
processor. As a result, the process relinquishes its use of the
processor's vector registers and can be scheduled on another processor
in the system.
In systems that do not have vector-present processors but do have the
VAX Vector Instruction Emulation facility (VVIEF) in use, this service
relinquishes the process's use of VVIEF. VVIEF remains mapped in the
process's address space.
Required Access or Privileges
None
Required Quota
None
Related Services
$RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
$REMOVE
The Remove service deletes a file name from a directory. It is the
reverse of the Enter service.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$REM_HOLDER
Deletes the specified holder record from the target identifier's list
of holders.
Format
SYS$REM_HOLDER id ,holder
C Prototype
int sys$rem_holder (unsigned int id, struct _generic_64 *holder);
Arguments
id
| OpenVMS usage: |
rights_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Binary value of target identifier whose holder is deleted when
$REM_HOLDER completes execution. The id argument is a
longword containing the identifier value.
holder
| OpenVMS usage: |
rights_holder |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Identifier of holder being deleted when $REM_HOLDER completes
execution. The holder argument is the address of a
quadword containing the UIC identifier of the holder in the first
longword and the value of 0 in the second longword.
Description
The Remove Holder Record from Rights Database service removes the
specified holder record from the target identifier's list of holders.
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_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
holder argument cannot be read by the caller.
|
|
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$_NORIGHTSDB
|
The rights database does not exist.
|
|
SS$_NOSUCHID
|
The specified identifier does not exist in the rights database, or the
specified holder 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.
$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:
- 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.
- 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.
|
$RESTORE_VP_EXCEPTION (VAX Only)
On VAX systems, restores the saved exception state of the vector
processor.
Format
SYS$RESTORE_VP_EXCEPTION excid
Argument
excid
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. The
excid argument is the address of a longword containing
this ID.
Description
The Restore Vector Processor Exception State service restores from
memory the vector exception state saved by a prior call to
$SAVE_VP_EXCEPTION. After a routine invokes this service, the next
vector instruction issued within the process causes the restored vector
exception to be reported.
By default, when an AST or condition handler interrupts the execution
of a mainline routine, the operating system saves the mainline
routine's vector state, including its vector exception state. Any other
routine that executes synchronously with, or asynchronously to,
currently executing vectorized code and that performs vector operations
itself must preserve the preempted routine's vector exception state
across its own execution. It does so by using the $SAVE_VP_EXCEPTION
and $RESTORE_VP_EXCEPTION services.
Used together, these services ensure that vector exceptions occurring
as a result of activity in the original routine are serviced by
existing condition handlers within that routine.
In systems that do not have vector-present processors but do have the
VAX Vector Instruction Emulation facility (VVIEF) in use, VVIEF
emulates the function of this service.
Required Access or Privileges
None
Required Quota
BYTLM
Related Services
$RELEASE_VP, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. The service also returns this
status when executed in a system that does not have vector-present
processors and that does not have the VAX Vector Instruction Emulation
facility (VVIEF) loaded.
|
|
SS$_ACCVIO
|
The caller cannot read the exception ID longword.
|
|
SS$_NOSAVPEXC
|
No saved vector exception state exists for this exception ID.
|
$RESTORE_VP_STATE (VAX Only)
On VAX systems, allows an AST routine or condition handler to restore
the vector state of the mainline routine.
Format
SYS$RESTORE_VP_STATE
Arguments
None.
Description
The Restore Vector State service allows an AST routine or a condition
handler to restore the vector state of the process's mainline routine.
By default, when an asynchronous routine (AST routine or condition
handler) interrupts the execution of a mainline routine, the operating
system creates a new vector state when the routine issues its first
vector instruction. At this point, the vector state of the mainline
routine is inaccessible to the asynchronous routine. If the
asynchronous routine must manipulate the vector state of the mainline
routine, it first calls $RESTORE_VP_STATE to restore the mainline's
vector state.
In systems that do not have vector-present processors but do have the
VAX Vector Instruction Emulation facility (VVIEF) in use, VVIEF
emulates the functions of this service.
This service can be called only from a routine running in user mode.
Required Access or Privileges
None
Required Quota
None
Related Services
$RELEASE_VP, $RESTORE_VP_EXCEPTION, $SAVE_VP_EXCEPTION
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. Vector state of the mainline has
been restored. The service also returns this status when executed in a
system that does not have vector-present processors and that does not
have the VAX Vector Instruction Emulation facility (VVIEF) loaded.
|
|
SS$_BADSTACK
|
Bad user stack encountered.
|
|
SS$_BADCONTEXT
|
The mainline vector state is corrupt.
|
|
SS$_WRONGACMODE
|
The system service was called from an access mode other than user mode.
|
$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:
- GROUP privilege to resume execution of a process in the same group
unless the process has the same UIC as the calling process
- WORLD privilege to resume execution of any process in the system
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.)
|
|
