HP OpenVMS Systems Documentation

Content starts here

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming


Previous Contents Index


Chapter 6
OpenVMS System Services Reference

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.

Table 6-1 OpenVMS System Service and Equivalent Sockets API Function
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.

6.1 System Service Descriptions

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.


$ASSIGN

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.


Format

SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags]


C Prototype

int sys$assign (void *devnam, unsigned short int *chan, unsigned int acmode, void *mbxnam,...);


Returns


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.


Arguments

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.

Description

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.


Condition Values Returned

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.

$CANCEL

Cancels all pending I/O requests on a specified channel.

Related Functions

The equivalent Sockets API function is close() .


Format

SYS$CANCEL chan


C Prototype

int sys$cancel (unsigned short int chan);


Returns


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.


Arguments

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.

Description

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.


Condition Values Returned

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.

$DASSGN

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() .


Format

SYS$DASSGN chan


C Prototype

int sys$dassgn (unsigned short int chan);


Returns


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.


Arguments

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.

Description

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.

Note

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.

Condition Values Returned

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.

$QIO

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.


Format

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


C Prototype

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);


Returns


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.


Arguments

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.

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.


Previous Next Contents Index