OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

The AST routine executes at the access mode of the caller of $QIO.

astprm

OpenVMS usage:	user_arg
type:	quadword unsigned (Alpha); longword unsigned (VAX)
access:	read only
mechanism:	by 64-bit value (Alpha)
mechanism:	by 32-bit value (VAX)

AST parameter to be passed to the AST service routine. On Alpha systems, the astprm argument is a quadword value containing the AST parameter. On VAX systems, the astprm argument is a longword value containing the AST parameter.

p1 to p6

OpenVMS usage:	varying_arg
type:	quadword (unsigned) (Alpha); longword unsigned (VAX)
access:	read only
mechanism:	by 32- or 64-bit reference or by 64-bit value depending on the I/O function (Alpha)
mechanism:	by 32-bit reference or by 32-bit value depending on the I/O function (VAX)

Optional device-specific and function-specific I/O request parameters. For example, the p1 parameter usually specifies a buffer by reference. Other parameters, such as the buffer size, disk block number, or carriage control are often passed by value.

For more information about these parameters, see the OpenVMS I/O User's Reference Manual.

Description

The Queue I/O Request service operates only on assigned I/O channels and only from access modes that are equal to or more privileged than the access mode from which the original channel assignment was made.
The $QIO service uses system dynamic memory to construct a database to queue the I/O request and might require additional memory depending on the queued device.
For $QIO, you can synchronize completion (1) by specifying the astadr argument to have an AST routine execute when the I/O completes or (2) by calling the Synchronize ($SYNCH) service to await completion of the I/O operation. The $QIOW service completes synchronously, and it is the best choice when synchronous completion is required.
For information about how to use the $QIO service for network operations, refer to the DECnet for OpenVMS Networking Manual.
Required Access or Privileges

LOG_IO or PHY_IO is required, depending upon the device type and the requested operation. DIAGNOSE is required to issue a $QIO with an associated diagnostic buffer. In addition, read or write access is generally required for the device. For more information, see the Security Guide.
Required Quota

The $QIO service uses the following quotas:

The process's quota for buffered I/O limit (BIOLM) or direct I/O limit (DIOLM)
The process's buffered I/O byte count (BYTLM) quota
The process's AST limit (ASTLM) quota, if an AST service routine is specified

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $IO_CLEANUP, $IO_PERFORM, $IO_SETUP, $IO_FASTPATH, $MOUNT, $PUTMSG, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully. The I/O request was successfully queued.

SS$_ABORT A network logical link was broken.

SS$_ACCVIO Either the I/O status block cannot be written by the caller, or the parameters for device-dependent function codes are specified incorrectly.

SS$_CONNECFAIL The connection to a network object timed out or failed.

SS$_DEVOFFLINE The specified device is off line and not currently available for use.

SS$_EXQUOTA The process has (1) exceeded its AST limit (ASTLM) quota, (2) exceeded its buffered I/O byte count (BYTLM) quota, (3) exceeded its buffered I/O limit (BIOLM) quota, (4) exceeded its direct I/O limit (DIOLM) quota, or (5) requested a buffered I/O transfer smaller than the buffered byte count quota limit (BYTLM), but when added to other current buffer requests, the buffered I/O byte count quota was exceeded.

SS$_FILALRACC A logical link is already accessed on the channel (that is, a previous connect on the channel).

SS$_ILLEFC You specified an illegal event flag number.

SS$_INSFMEM The system dynamic memory is insufficient for completing the service.

SS$_INVLOGIN The access control information was invalid at the remote node.

SS$_IVCHAN You specified an invalid channel number, that is, a channel number of 0, or you failed to specify a channel number.

SS$_IVIDENT You specified a channel number greater than the number of channels assigned for the process.

SS$_IVDEVNAM The NCB has an invalid format or content.

SS$_LINKABORT The network partner task aborted the logical link.

SS$_LINKDISCON The network partner task disconnected the logical link.

SS$_LINKEXIT The network partner task was started, but exited before confirming the logical link (that is, $ASSIGN to SYS$NET).

SS$_NOLINKS No logical links are available. The maximum number of logical links as set for the executor MAXIMUM LINKS parameter was exceeded.

SS$_NOPRIV The specified channel does not exist or was assigned from a more privileged access mode, or the process does not have the necessary privileges to perform the specified functions on the device associated with the specified channel.

SS$_NOSUCHNODE The specified node is unknown.

SS$_NOSUCHOBJ The network object number is unknown at the remote node; or for a TASK= connect, the named DCL command procedure file cannot be found at the remote node.

SS$_NOSUCHUSER The remote node could not recognize the login information supplied with the connection request.

SS$_NOT64DEVFUNC On Alpha systems, this fatal condition value is returned under the following circumstances: (1) The caller has specified a 64-bit virtual address in the P1 device dependent parameter but the device driver does not support 64-bit addresses with the requested I/O function. (2) The caller has specified a 64-bit address for a diagnostic buffer but the device driver does not support 64-bit addresses for diagnostic buffers. (3) Some device drivers might also return this condition value when 64-bit buffer addresses are passed using the P2 through P6 parameters and the driver does not support a 64-bit address with the requested I/O function.

SS$_PATHLOST The path to the network partner task node was lost.

SS$_PROTOCOL A network protocol error occurred. This error is most likely due to a network software error.

SS$_REJECT The network object rejected the connection.

SS$_REMRSRC The link could not be established because system resources at the remote node were insufficient.

SS$_SHUT The local or remote node is no longer accepting connections.

SS$_THIRDPARTY The logical link was terminated by a third party (for example, the system manager).

SS$_TOOMUCHDATA The task specified too much optional or interrupt data.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

SS$_UNREACHABLE The remote node is currently unreachable.

Condition Values Returned in the I/O Status Block

Device-specific condition values; the OpenVMS I/O User's Reference Manual lists these condition values for each device.

$QIOW

Queues an I/O request to a channel associated with a device.
The $QIOW service completes synchronously; however, Compaq recommends that you use an IOSB with this service to avoid premature completion.
For asynchronous completion, use the Queue I/O Request ($QIO) service.
In all other respects, $QIOW is identical to $QIO. For more information about $QIOW, refer to the description of $QIO.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$QIOW [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]

C Prototype

int sys$qiow (unsigned int efn, unsigned short int chan, unsigned int func, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5, __int64 p6);

$READEF

Returns the current status of all 32 event flags in a local or common event flag cluster and indicates whether the specified event flag is set or clear.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$READEF efn ,state

C Prototype

int sys$readef (unsigned int efn, unsigned int *state);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of any event flag in the cluster whose status is to be returned. The efn argument is a longword containing this number; however, $READEF uses only the low-order byte. Specifying an event flag within a cluster requests that $READEF return the status of all event flags in that cluster.
There are two local event flag clusters, which are local to the process: cluster 0 and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1 contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127.
state

OpenVMS usage: mask_longword

type: longword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

State of all event flags in the specified cluster. The state argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword into which $READEF writes the state (set or clear) of the 32 event flags in the cluster.

Condition Values Returned

SS$_WASCLR The service completed successfully. The specified event flag is clear.

SS$_WASSET The service completed successfully. The specified event flag is set.

SS$_ACCVIO The longword that is to receive the current state of all event flags in the cluster cannot be written by the caller.

SS$_ILLEFC You specified an illegal event flag number.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$RELEASE_VP (VAX Only)

On VAX systems, terminates the current process's status as a vector consumer.

Format

SYS$RELEASE_VP

Arguments

None.

Description

The Release Vector Processor service terminates the current process's 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.

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

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

Contents

Index

privacy and legal statement

4527PRO_075.HTML

SS$_NORMAL	The service completed successfully. The I/O request was successfully queued.
SS$_ABORT	A network logical link was broken.
SS$_ACCVIO	Either the I/O status block cannot be written by the caller, or the parameters for device-dependent function codes are specified incorrectly.
SS$_CONNECFAIL	The connection to a network object timed out or failed.
SS$_DEVOFFLINE	The specified device is off line and not currently available for use.
SS$_EXQUOTA	The process has (1) exceeded its AST limit (ASTLM) quota, (2) exceeded its buffered I/O byte count (BYTLM) quota, (3) exceeded its buffered I/O limit (BIOLM) quota, (4) exceeded its direct I/O limit (DIOLM) quota, or (5) requested a buffered I/O transfer smaller than the buffered byte count quota limit (BYTLM), but when added to other current buffer requests, the buffered I/O byte count quota was exceeded.
SS$_FILALRACC	A logical link is already accessed on the channel (that is, a previous connect on the channel).
SS$_ILLEFC	You specified an illegal event flag number.
SS$_INSFMEM	The system dynamic memory is insufficient for completing the service.
SS$_INVLOGIN	The access control information was invalid at the remote node.
SS$_IVCHAN	You specified an invalid channel number, that is, a channel number of 0, or you failed to specify a channel number.
SS$_IVIDENT	You specified a channel number greater than the number of channels assigned for the process.
SS$_IVDEVNAM	The NCB has an invalid format or content.
SS$_LINKABORT	The network partner task aborted the logical link.
SS$_LINKDISCON	The network partner task disconnected the logical link.
SS$_LINKEXIT	The network partner task was started, but exited before confirming the logical link (that is, $ASSIGN to SYS$NET).
SS$_NOLINKS	No logical links are available. The maximum number of logical links as set for the executor MAXIMUM LINKS parameter was exceeded.
SS$_NOPRIV	The specified channel does not exist or was assigned from a more privileged access mode, or the process does not have the necessary privileges to perform the specified functions on the device associated with the specified channel.
SS$_NOSUCHNODE	The specified node is unknown.
SS$_NOSUCHOBJ	The network object number is unknown at the remote node; or for a TASK= connect, the named DCL command procedure file cannot be found at the remote node.
SS$_NOSUCHUSER	The remote node could not recognize the login information supplied with the connection request.
SS$_NOT64DEVFUNC	On Alpha systems, this fatal condition value is returned under the following circumstances: (1) The caller has specified a 64-bit virtual address in the P1 device dependent parameter but the device driver does not support 64-bit addresses with the requested I/O function. (2) The caller has specified a 64-bit address for a diagnostic buffer but the device driver does not support 64-bit addresses for diagnostic buffers. (3) Some device drivers might also return this condition value when 64-bit buffer addresses are passed using the P2 through P6 parameters and the driver does not support a 64-bit address with the requested I/O function.
SS$_PATHLOST	The path to the network partner task node was lost.
SS$_PROTOCOL	A network protocol error occurred. This error is most likely due to a network software error.
SS$_REJECT	The network object rejected the connection.
SS$_REMRSRC	The link could not be established because system resources at the remote node were insufficient.
SS$_SHUT	The local or remote node is no longer accepting connections.
SS$_THIRDPARTY	The logical link was terminated by a third party (for example, the system manager).
SS$_TOOMUCHDATA	The task specified too much optional or interrupt data.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.
SS$_UNREACHABLE	The remote node is currently unreachable.

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

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

SS$_WASCLR	The service completed successfully. The specified event flag is clear.
SS$_WASSET	The service completed successfully. The specified event flag is set.
SS$_ACCVIO	The longword that is to receive the current state of all event flags in the cluster cannot be written by the caller.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

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

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

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.