| Previous | Contents | Index |
Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned.
chan
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
I/O channel on which I/O is to be canceled. The chan argument is a word containing the channel number.
To cancel I/O on a channel, the access mode of the calling process must be equal to or more privileged than the access mode of the process that made the original channel assignment.The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota.
When a request currently in progress is canceled, the driver is notified immediately. Actual cancellation may or may not occur immediately, depending on the logical state of the driver. When cancellation does occur, the action taken for I/O in progress is similar to that taken for queued requests. For example:
- The specified event flag is set.
- The first word of the I/O status block, if specified, is set to SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if the I/O operation is in progress.
- If the asynchronous system trap (AST) is specified, it is queued.
For proper synchronization between this service and the actual canceling of I/O requests to take place, the issuing process must wait for the I/O process to complete normally. Note that the I/O has been canceled. Outstanding I/O requests are canceled automatically at image exit.
SS$_NORMAL The service completed successfully. SS$_ABORT A physical line went down during a network connect operation. SS$_CANCEL The I/O operation was canceled by executing a $CANCEL system service. SS$_EXQUOTA The process has exceeded its buffered I/O limit (BIOLM) quota. SS$_INSFMEM Insufficient system dynamic memory to cancel the I/O. SS$_IVCHAN An invalid channel was specified (that is, a channel number of 0 or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.
Deassigns (releases) an I/O channel previously acquired using the Assign I/O Channel ($ASSIGN) service.Related Functions
The equivalent Sockets API function is close() .
SYS$DASSGN chan
int sys$dassgn (unsigned short int chan);
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned.
chan
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is a word containing this number.
After all communication is completed, use the $DASSGN system service to free an I/O channel. A $DASSGN operation executed on a channel associated with a network pseudodevice does the following:
- Ends all pending operations to send or receive data at $QIO level ($CANCEL system service).
- Clears the port associated with the channel. When executing the $DASSGN system service for TCP sockets, the socket remains until the connection is closed on both the local and remote sides.
- Ends all communications with the network pseudodevice that the I/O channel identifies.
- Frees the channel associated with the network pseudodevice. An I/O channel can be deassigned only from an access mode equal to or more privileged than the access mode from which the original channel assignment was made.
I/O channels assigned from user mode are automatically deassigned at image exit.
Even after a $DASSGN has been issued, a TCP socket may remain until the TCP close timeout interval expires. The default and maximum timeout interval is either 10 minutes if the peer host is not responding or 30 seconds after acknowledging the socket close. Although the TCP socket is open, you cannot make a reference to that socket after issuing a $DASSGN. |
SS$_NORMAL The service completed successfully. SS$_IVCHAN An invalid channel number was specified (that is, a channel number of zero or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or is assigned from a more privileged access mode.
Queues an I/O request to a channel associated with a network pseudodevice.The $QIO service is completed asynchronously; that is, it returns to the caller immediately after queuing the I/O request, without waiting for the I/O operation to be completed. )
For synchronous completion, use the Queue I/O Request and Wait ($QIOW) service. The $QIOW service is identical to the $QIO service, except the $QIOW returns to the caller after the I/O operation has completed.
On Alpha systems, this service accepts 64-bit addresses.
SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm], [p1],[p2],[p3],[p4], [p5],[p6]
int sys$qio (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);
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned.
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Event flag that $QIO sets when the I/O operation completes. The efn argument is a longword value containing the number of the event flag, however, $QIO uses only the low-order byte.If efn is not specified, event flag 0 is set.
The specified event flag is set if the service terminates without queuing an I/O request.
chan
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
I/O channel that is assigned to the device to which the request is directed. The chan argument is a word value containing the number of the I/O channel.func
OpenVMS usage: function_code type: longword (unsigned) access: read only mechanism: by value
Function codes and function modifiers specifying the operation to be performed. The func argument is a longword containing the function code.For information about the network pseudodevice and TELNET device function codes and modifiers, see Section 6.2 and Section 6.3.
iosb
OpenVMS usage: io_status_block type: quadword (unsigned) access: write only mechanism: by 32-bit reference or 64-bit reference (Alpha)
I/O status block to receive the final completion status of the I/O operation. The iosb is the address of the quadword I/O status block. See Figure 5-1 for a description of the general structure of the I/O status block.When the $QIO begins executing, it clears the event flag. The $QIO also clears the quadword I/O status block if the iosb argument is specified.
Although the iosb argument is optional, Compaq 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 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 $QIO service. The condition value returned in R0 provides information about the success or failure of the service call itself; the condition values returned in the I/O status block give information on the success or failure of the service operation. Therefore, to access the success or failure of the $QIO call, check the condition values returned in both the R0 and the I/O status block.
astadr
OpenVMS usage: ast_procedure type: procedure value access: call without stack unwinding mechanism: by 32- or 64-bit reference (Alpha)
AST service routine to be executed when the I/O completes. The astadr argument is the address of the AST routine.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 32- or 64-bit value (Alpha)
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)
Optional device- and function-specific I/O request arguments. The parameter values contained in these arguments vary according to the function for which they are used. See Table 6-2 for descriptions of the network pseudodevice driver I/O function codes; see Table 6-7 through Table 6-10 for related TELNET device driver I/O function codes.
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.For TCP/IP Services, $QIO uses the following system resources:
- The process's AST limit (ASTLM) quota, if an AST service routine is specified.
- System dynamic memory, which is required to queue the I/O request. System dynamic memory requirements are protocol specific.
- Additional memory, on a device-dependent basis.
For $QIO, completion can be synchronized as follows:
- By specifying the astadr argument to have an AST routine execute when the I/O is completed.
- By calling the $SYNCH synchronize service to await completion of the I/O operation. (If you want your I/O operation to complete synchronously, use the $QIOW system service instead.)
Each function used with $QIO has its own error codes. See the error codes listed under the individual descriptions of the device driver I/O function code in the remainder of this chapter.
6.2 Network Pseudodevice Driver I/O Functions
The network pseudodevice allows physical, logical, and virtual I/O
functions. The physical and logical I/O functions are used only with
the IP layer. Table 6-2 lists the basic I/O functions and their
modifiers. The sections that follow describe in greater detail the
operation of these I/O functions.
| Function Code and Arguments | Function Modifier | Description |
|---|---|---|
| IO$_ACCESS p3,p4 |
IO$M_ACCEPT
IO$M_EXTEND IO$M_NOW |
Opens a connection. |
| IO$_ACPCONTROL p1, p2, p3, p4 | Performs an ACP (ancillary control process) operation. | |
| IO$_DEACCESS p4 |
IO$M_NOW
IO$M_SHUTDOWN |
Aborts or closes a connection. |
| IO$_READVBLK p1,p2,p3,p4,p6 |
IO$M_EXTEND
IO$M_INTERRUPT |
Reads a virtual block. |
|
IO$M_LOCKBUF
IO$M_PURGE |
Controls the buffer operations. | |
| IO$_SENSEMODE p2, p3,p4,p6 | Reads the network pseudodevice characteristics. | |
| IO$_SENSECHAR p2, p3,p4,p6 | Reads the network pseudodevice characteristics. | |
| IO$_SETMODE p1, p2, p3,p4,p5 |
IO$M_OUTBAND
IO$M_READATTN IO$M_WRTATTN |
Sets the network pseudodevice characteristics for subsequent operations. |
| IO$_SETCHAR p1, p2, p3,p4,p5 |
IO$M_OUTBAND
IO$M_READATTN IO$M_WRTEATTN |
Sets the network pseudodevice characteristics for subsequent operations. |
| IO$_WRITEVBLK p1,p2,p3,p4,p5 | IO$M_INTERRUPT | Writes a virtual block. |
Table 5-2 lists the file names of the symbol definition files. These files specify $QIO arguments (p1,p2,...p6) for applications written in the corresponding programming languages. You must invoke the symbol definition by using the appropriate include statement in your application.
When using a connection-oriented protocol, such as TCP, the IO$_ACCESS function initiates a connection and specifies a remote port number and internet address. When using a connectionless protocol, such as UDP, the IO$_ACCESS function sets the remote port number and internet address.For TCP, a connection request times out at a specified interval (75 seconds is the default). This interval can be changed by the system manager. The program can also set a specific timeout interval for a socket that it has created.
If a connection fails, you must deallocate the socket and then create a new socket before trying to reconnect.
Related Functions
p3
OpenVMS usage: socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor
The remote port number and internet address of the host to connect. The p3 argument is the address of an item_list_2 descriptor that points to the socket address structure containing the remote port number and internet address.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code.
SS$_NORMAL The service completed successfully. SS$_BADPARAM Programming error that occurred for one of the following reasons:
- $QIO system service was specified without a socket.
- An IO$_ACCESS function was specified without the address of a remote socket name ( p3 was null).
SS$_BUGCHECK Inconsistent state. Report the problem to your Compaq support representative. SS$_CANCEL The I/O operation was canceled by a $CANCEL system service. SS$_CONNECFAIL The connection to a network object timed out or failed. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_DUPLNAM A network configuration error. No ports were available for new connections. SS$_EXQUOTA The process has exceeded its socket quota or some other process quota. SS$_FILALRACC The specified socket name is already in use by one of the following:
- On a raw socket, the remote internet address was already specified on a previous IO$_ACCESS call.
- On a datagram, the remote internet address was already specified on a previous IO$_ACCESS call.
- On a stream socket, the IO$_ACCESS function targeted a stream socket that was already connected.
SS$_ILLCNTRFUNC Illegal function. SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVADDR The specified internet address was not found, or an invalid port number and internet address combination was specified with the IO$_ACCESS function. Port 0 is not allowed with the IO$_ACCESS function. SS$_IVBUFLEN The size of the socket name structure specified with the IO$_ACCESS function was invalid. SS$_LINKABORT The remote socket closed the connection. SS$_NOLICENSE The Compaq TCP/IP Services for OpenVMS license is not present. SS$_PROTOCOL A network protocol error occurred. The address family specified in the socket address structure is not supported. SS$_REJECT The network connection is rejected for one of the following reasons:
- An attempt was made to connect to a remote socket that is already connected.
- An error was encountered while establishing the connection
- The peer socket refused the connection request or is closing the connection.
SS$_SHUT The local or remote node is no longer accepting connections. SS$_SUSPENDED The system detected a condition that might cause the operation to block. SS$_TIMEOUT A TCP connection timed out before the connection could be established. SS$_UNREACHABLE The remote node is currently unreachable.
| Previous | Next | Contents | Index |