 |
HP OpenVMS System Services Reference Manual
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, refer to the
HP OpenVMS Guide to System Security.
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, $MOUNT, $PUTMSG, $QIOW, $SNDERR, $SNDJBC,
$SNDJBCW, $SNDOPR, $IO_CLEANUP, $IO_PERFORM, $IO_SETUP
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 and I64 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 HP OpenVMS I/O User's Reference Manual lists these
condition values for each device.
$QIOW
The Queue I/O Request and Wait service queues an I/O request to a
channel associated with a device.
The $QIOW service completes synchronously; however, Digital 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 and I64 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);
$READ
The Read service retrieves a specified number of bytes from a file
(beginning on a block boundary) and transfers them to memory. A Read
service using block I/O can be performed on any file organization.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$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 and I64 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 and I64); 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
and I64 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.
Note that this is also the same value as SS$_NORMAL.
|
|
SS$_WASSET
|
The service completed successfully. The specified event flag is set.
Note that while the message id is the same as SS$_ACCVIO, the severity
bits are different.
|
|
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.
|
$REGISTRY (Alpha and I64)
On Alpha and I64 systems, interface to the OpenVMS Registry database
server.
The $REGISTRY service allows you to query, update, and set keys,
subkeys, and values in the OpenVMS Registry database.
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$REGISTRY [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or
astadr_64] [,astprm or astprm_64] [,timeout]
C Prototype
int sys$registry (unsigned int efn, unsigned int func, void *, void
*itmlst, struct _iosb *iosb, ...);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be used by $REGISTRY. If you do not specify
the event flag, the system defaults to event flag 0. The event flag is
initially cleared by $REGISTRY and then set when the operation
completes.
func
| OpenVMS usage: |
function_code |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Function code specifying the action that $REGISTRY is to perform. The
func argument is a longword containing this function
code. The function code can contain function modifiers. For more
information on function modifiers, see the Function
Modifiers section.
A single call to $REGISTRY can specify only one function code. All
function codes require additional information to be passed in the call
with the itmlst argument.
itmlst
| OpenVMS usage: |
32-bit item_list_3 or 64-bit item_list_64b |
| type: |
longword (unsigned) for 32-bit; quadword (unsigned) for
64-bit |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Item list supplying information that the system will use to perform the
function specified by the func argument.
The itmlst argument is the address of the item list.
The item list consists of one or more sets of item descriptors. Each
descriptor is either an item_list_3 or item_list_64b format.
Some function codes allow you to specify multiple operations in a
single call. In this case, you must place the REG$_SEPARATOR item code
between each set of item codes. Each request, separated by a
REG$_SEPARATOR item code, can contain the item codes in any order.
You can specify item codes as either input or output parameters. Input
parameters modify functions, set context, or describe the information
to be returned. Output parameters return the requested information.
For item_list_3 lists, you must terminate the list with a longword of
0. For item_list_64b lists, you must terminate the list with a quadword
of 0.
The following diagram shows the structure of an
item_list_3 descriptor:
The following diagram shows the structure of an
item_list_64b descriptor:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word that specifies the length of the buffer. The buffer either
supplies information to be used by $REGISTRY, or receives information
from $REGISTRY. The required length of the buffer varies, depending on
the item code specified. Each item code description specifies the
required length.
|
|
Item code
|
A word containing a symbolic code that describes the type of
information currently in the buffer or that is returned in the buffer.
The buffer address field points to the location of the buffer.
|
|
Buffer address
|
A longword that contains the address of the buffer that specifies or
receives the information.
|
|
Return length address
|
A longword that contains the address of a word that specifies the
actual length in bytes of the information returned by $REGISTRY. The
information resides in a buffer identified by the buffer address field.
The field applies to output item list entries only, and must be 0
(zero) for input entries. If the return length address is 0, it is
ignored.
|
iosb or iosa_64
| OpenVMS usage: |
status_block |
| type: |
buffer |
| access: |
write only |
| mechanism: |
by reference |
Status block to receive the final completion status and information of
the $REGISTRY operation.
If multiple operations are requested for a function code, the value
returned in iosb is either SS$_NORMAL or SS$_REGERROR.
A more specific return status for each operation is returned in the
REG$_RETURNSTATUS item code (if specified).
The iosb argument is the address of the $REGISTRY
status block:
When $REGISTRY begins execution, it clears the quadword I/O status
block if you specify the iosb argument.
Although the iosb argument is optional, HP strongly
recommends that you specify it for the following reasons:
- If you are using an event flag to signal the completion of the
service, you can test the I/O status block for a condition value to be
sure that the event flag was not set by an event other than service
completion.
- If you are using the $SYNCH system service to synchronize
completion of the service, the I/O status block is a required argument
for $SYNCH.
The condition value returned in R0 and the condition value returned in
the I/O status block provide information about different aspects of the
call to the $REGISTRY service. The condition value returned in R0
provides information about the success or failure of the service call
itself; the condition value returned in the I/O status block provides
information about the success or failure of the service operation.
To assess the success or failure of the call to $REGISTRY accurately,
you must first check the condition value returned in R0. If R0 contains
a successful value, you must check the condition value in the I/O
status block.
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Status
|
A longword specifying the final status of the $REGISTRY service. If you
request multiple operations for a function code, the system returns
either SS$_NORMAL or SS$_REGERROR to
iosb. This field is set to 0 (zero) when the operation
begins.
|
|
Reserved
|
A reserved longword.
|
astadr or astadr_64
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST service routine to be executed when $REGISTRY completes. The
astadr argument is the address of this routine. If you
specify astadr, the AST routine executes at the same
access mode as the caller of the $REGISTRY service.
If the $REGISTRY service is not called successfully (that is, if it
returns an error immediately), the AST routine is not executed.
astprm or astprm_64
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter to be passed to the AST service routine specified by the
astadr argument. The astprm argument
specifies this longword parameter.
timeout
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Timeout value specifies the number of seconds allotted to $REGISTRY to
perform the request. If the Registry server does not complete the
request within the time you allot, $REGISTRY returns REG-F-NORESPONSE.
Function Codes Table SYS-50 provides a summary of valid function
codes, a brief description of their function, and the OpenVMS Registry
rights identifier required to perform the function.
You can find a detailed description of each item code in the
Item Codes section.
The OpenVMS Registry identifier is required only if you do not provide a
valid NT access token and you do not have the SYSPRV privilege. If you
have a granted REG$UPDATE identifier, you can perform all the functions
in Table SYS-50.
Table SYS-50 Valid Function Codes
| Function Code |
Identifier |
Description |
|
REG$FC_CLOSE_KEY
|
REG$LOOKUP
|
Closes an open key or subkey.
|
|
REG$FC_CREATE_KEY
|
REG$UPDATE
|
Creates (and opens) a subkey.
|
|
REG$FC_DELETE_KEY
|
REG$UPDATE
|
Removes a subkey from a key.
|
|
REG$FC_DELETE_VALUE
|
REG$UPDATE
|
Removes a value from a key.
|
|
REG$FC_ENUM_KEY
|
REG$LOOKUP
|
Lists (enumerates) the subkeys of a key.
|
|
REG$FC_ENUM_VALUE
|
REG$LOOKUP
|
Lists (enumerates) the values of a key.
|
|
REG$FC_FLUSH_KEY
|
REG$UPDATE
|
Ensures that all information for the key is backed to disk.
|
|
REG$FC_MODIFY_KEY
|
REG$UPDATE
|
Modifies a key.
|
|
REG$FC_MODIFY_TREE_KEY
|
REG$UPDATE
|
Modifies a key and all its subkeys.
|
|
REG$FC_NOTIFY_CHANGE_KEY_VALUE
|
REG$UPDATE
|
Notifies when a key or value has changed.
|
|
REG$FC_OPEN_KEY
|
REG$LOOKUP
|
Opens a key or subkey.
|
|
REG$FC_QUERY_KEY
|
REG$LOOKUP
|
Fetches information about a key.
|
|
REG$FC_QUERY_VALUE
|
REG$LOOKUP
|
Fetches information about a value.
|
|
REG$FC_SEARCH_TREE_DATA
|
REG$LOOKUP
|
Searches the value data of key and its subkeys.
|
|
REG$FC_SEARCH_TREE_KEY
|
REG$LOOKUP
|
Searches the names of a key and its subkeys.
|
|
REG$FC_SEARCH_TREE_VALUE
|
REG$LOOKUP
|
Searches the values of a key and its subkeys.
|
|
REG$FC_SET_VALUE
|
REG$UPDATE
|
Changes the data associated with a value name.
|
REG$FC_CLOSE_KEY
This request releases the open resources of the specified key. If
REG$_KEYID indicates a predefined key, the system ignores the action
and returns success.
Specify the item codes as follows:
| Item Code |
Required |
Parameter Type |
|
REG$_KEYID
|
Yes
|
Input
|
|
REG$_RETURNSTATUS
|
No
|
Output
|
REG$FC_CREATE_KEY
If the key does not exist, this request creates a new subkey under the
key specified by REG$_KEYID. If the key does exist, the system does not
modify it.
If you specify the REG$_KEYRESULT item code, the system opens the
specified subkey.
The system returns the result in the REG$_DISPOSITION item code buffer.
Using this function code, you can group multiple requests into a single
call to the $REGISTRY service. To use the multiple-request feature, you
must use the REG$_SEPARATOR item code to indicate the end of the set of
item codes for the current request and that there is another request to
process.
To set a value for a key, call the $REGISTRY service with the
REG$FC_SET_VALUE function code.
Specify the item codes as follows:
| Item Code |
Required |
Parameter Type |
|
REG$_CACHEACTION
|
No
|
Input
|
|
REG$_CLASSNAME
|
No
|
Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
|
|
REG$_DISPOSITION
|
No
|
Output
|
|
REG$_KEYID
|
Yes
|
Input
|
|
REG$_KEYRESULT
|
No
|
Output
|
|
REG$_LINKPATH
|
No
|
Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
|
|
REG$_LINKTYPE
|
No
|
Input
|
|
REG$_RETURNSTATUS
|
No
|
Output
|
|
REG$_SECACCESS
|
No
|
Input
|
|
REG$_SECURITYPOLICY
|
No
|
Input
|
|
REG$_SEPARATOR
|
No
|
n/a
|
|
REG$_SUBKEYNAME
|
Yes
|
Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
|
|
REG$_VOLATILE
|
No
|
Input
|
|
