|
HP OpenVMS Systems Documentation |
|
HP TCP/IP Services for OpenVMS
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Previous | Contents | Index |
This chapter provides detailed information about the OpenVMS system services for writing network applications. The chapter also describes the network pseudodevice driver and TELNET port driver I/O functions used with the $QIO system service.
The descriptions of the system services and I/O function codes are targeted specifically for network application programmers. For a general description of these system services and I/O function codes, see the HP OpenVMS System Services Reference manuals.
Table 6-1 lists the equivalent Sockets API function for each system service and $QIO I/O function code in this chapter. See Chapter 4 for descriptions of the Sockets API functions.
| OpenVMS System Service | Sockets API Function or Description |
|---|---|
| $ASSIGN | socket() |
| $CANCEL | close() |
| $DASSGN | close() |
| $QIO | |
| Network Pseudodevice I/O Function Codes: | |
| IO$_ACCESS | connect() |
| IO$_ACCESS|IO$M_ACCEPT | accept() |
| IO$_ACPCONTROL | gethostbyname(), gethostbyaddr(), getnetbyname(), getnetbyaddr() |
| IO$_DEACCESS | close() |
| IO$_DEACCESS|IO$M_SHUTDOWN | shutdown() |
| IO$_READVBLK | read(), recv(), recvfrom(), recvmsg() |
| IO$_SENSEMODE | getsockopt(), ioctl(), getpeername(), getsockname() |
| IO$_SENSECHAR | getsockopt(), ioctl(), getpeername(), getsockname() |
| IO$_SETMODE | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_SETCHAR | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_WRITEVBLK | send(), sendto(), sendmsg(), write() |
| TELNET Port Driver I/O Function Codes: | |
| IO$_TTY_PORT | |
| IO$M_TN_STARTUP | Binds a socket to a TELNET terminal device. |
| IO$M_TN_SHUTDOWN | Breaks a previously bound socket terminal connection. |
| IO$_TTY_PORT_BUFIO | |
| IO$M_TN_SENSEMODE | Reads parameters associated with the device. |
| IO$M_TN_SETMODE | Writes parameters associated with the device. |
This section describes the OpenVMS system services used to write network applications.
Detailed information about each argument is listed for each I/O function. The following format is used to describe each argument:
argument-name
| OpenVMS usage: | OpenVMS data type |
| type: | argument data type |
| access: | argument access |
| mechanism: | argument passing mechanism |
The purpose of the OpenVMS usage entry is to facilitate the coding of source-language data type declarations in application programs. Ordinarily, the standard data type is sufficient to describe the type of data passed by an argument. However, within the OpenVMS operating system environment, many system routines contain arguments whose conceptual nature or complexity requires additional explanation.
To determine the correct syntax of the data type you are using, refer to the appropriate language implementation table in Appendix C.
Note that the OpenVMS usage entry is not a traditional data type (such as the standard data types of byte, word, longword, and so on). It is significant only within the context of the OpenVMS operating system and is intended solely to expedite data declarations within application programs.
Provides a calling process with an I/O channel, thereby allowing the calling process to perform I/O operations on the network pseudodevice.On Alpha and I64 systems, this service accepts 64-bit addresses.
SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags]
int sys$assign (void *devnam, unsigned short int *chan, unsigned int acmode, void *mbxnam,...);
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.
devnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: (Alpha and I64) by 32- or 64-bit descriptor-fixed-length string descriptor (VAX) by 32-bit descriptor-fixed-length string descriptor
Name of the device to which $ASSIGN is to assign a channel. The devnam argument is the address of a character string descriptor pointing to the network pseudodevice name string (either TCPIP$DEVICE: or SYS$NET:).chan
OpenVMS usage: channel type: word (unsigned) access: write only mechanism: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference
Number of the channel that is assigned. The chan argument is the address of a word into which $ASSIGN writes the channel number.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode to be associated with the channel. I/O operations on the channel can be performed only from equal or more privileged access modes. The $PSLDEF macro defines the following symbols for the four access modes:
Symbol Access Mode Numeric Value PSL$C_KERNEL Kernel 0 PSL$C_EXEC Executive 1 PSL$C_SUPER Supervisor 2 PSL$C_USER User 3 mbxnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: (Alpha and I64) by 32-bit or 64-bit descriptor-fixed-length string descriptor (VAX) by 32-bit descriptor-fixed-length string descriptor
This argument is not used.flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
An optional device-specific argument. The flags argument is a longword bit mask. For more information about the applicability of the flags argument for a particular device, refer to the OpenVMS I/O User's Reference Manual.
The $ASSIGN system service establishes a path to a device but does not check whether the calling process has the capability to do I/O operations to the device. The device drivers may apply privilege and protection restrictions. The calling process must have NETMBX privilege to assign a channel.System dynamic memory is required for the target device, and the I/O byte limit quota from the process buffer is used.
When a channel is assigned to the TCPIP$DEVICE: network pseudodevice, the network software creates a new device called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device.
When the auxiliary server creates a process for a service with the LISTEN flag set, the server creates a device socket. In order for your application to receive the device socket, assign a channel to SYS$NET, which is the logical name of a network pseudodevice, and perform an appropriate $QIO(IO$_SETMODE) operation.
Channels remain assigned either until they are explicitly deassigned with the Deassign I/O Channel ($DASSGN) service or, if they are user-mode channels, until the image that assigned the channel exits.
SS$_NORMAL The service completed successfully. SS$_ACCVIO The caller cannot read the device string or string descriptor, or the caller cannot write the channel number. SS$_DEVALLOC The device is allocated to another process. SS$_DEVLSTFULL The system maximum number of BG: device units has been reached. SS$_EXQUOTA The process has exceeded its buffered I/O byte limit (BIOLM) quota. SS$_IVDEVNAM No device name was specified, the logical name translation failed, or the device name string contains invalid characters. SS$_IVLOGNAM The device name string has a length of zero or has more than 63 characters. SS$_NOIOCHAN No I/O channel is available for assignment. SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode. SS$_NOSUCHDEV The specified device does not exist.
Cancels all pending I/O requests on a specified channel.Related Functions
SYS$CANCEL chan
int sys$cancel (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
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 and I64 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: (Alpha and I64) by 32-bit reference or 64-bit reference (VAX) by 32-bit reference
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, 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 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 determine 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: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference
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 and I64); longword unsigned (VAX) access: read only mechanism: (Alpha and I64) by 32- or 64-bit value (VAX) by 32-bit value
AST parameter to be passed to the AST service routine. On Alpha and I64 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 and I64); longword unsigned (VAX) access: read only mechanism: (Alpha and I64) by 32- or 64-bit reference or by 64-bit value depending on the I/O function (VAX) by 32-bit reference or by 32-bit value depending on the I/O function
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.
Previous Next Contents Index