# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# IO$_SENSEMODE/IO$_SENSECHAR

> The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more parameters (characteristics) pertaining to the network driver.

> Socket names (local and remote peer) are returned by using IO$_SENSEMODE's p3 and p4 arguments. Other parameters such as socket and protocol options, are specified in an output parameter list using the IO$_SENSEMODE p6 argument.

> IO$_SENSEMODE p3 and p4 arguments can be used with the p6 argument in a single $QIO system service to return socket names as well as socket and protocol options. IO$_SENSEMODE processes arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an error, the IOSB contains the error and argument address or the value that was at fault.

> Refer to individual argument descriptions for details about specifying the type and format of output parameters.

## Arguments

> ### p3

> OpenVMS usage: | socket_name
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by `item_list_3` descriptor

> The port number and internet address of the local name associated with the socket. The p3 argument is the address of an `item_list_3` descriptor that points to the socket address structure into which the local name is written.

> Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to specify a BSD Version 4.4 formatted socket address structure.

> Related Functions

> The Sockets API equivalent for this function is `getsockname()` .

> ### p4

> OpenVMS usage: | socket_name
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by `item_list_3` descriptor

> The port number and internet address of the remote name associated with the socket's peer. The p3 argument is the address of an `item_list_3` descriptor that points to the socket address structure into which the peer name is written.

> Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to specify a BSD Version 4.4 formatted socket address structure.

> Related Functions

> The equivalent Sockets API function is `getpeername()` .

> ### p6

> OpenVMS usage: | output_parameter_list
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by `item_list_2` descriptor

> Output parameter list describing one or more parameters to return. The p6 argument is the address of an `item_list_2` descriptor that points to and identifies the type of output parameter list.

> The following are the types of output parameter lists:

> Symbolic Name | Output Parameter List Type
> --- | ---
> TCPIP$C_SOCKOPT | Socket options
> TCPIP$C_TCPOPT | TCP protocol options
> TCPIP$C_IPOPT | IP protocol options
> TCPIP$C_IOCTL | I/O control commands

> Each `item_list_3` structure appearing in an output parameter list describes an individual parameter or item to return. See Table A-1 for details about socket option parameters; see Table A-2 for TCP protocol option parameters; and see Table A-3 for IP protocol option parameters. Unsupported socket or protocol options are ignored.

> Each `ioctl_com` structure that appears in an output parameter list contains an I/O control command --- the get IOCTL request code and its associated IOCTL structure address. See Table B-1 for details about IOCTL command parameters.

> Unsupported socket options are ignored.

The equivalent Sockets API functions are `getsockopt()` and `ioctl()` .

## Function Modifiers

> IO$M_EXTEND | Specifies the format of the socket address structure to return when used with the p3 or p4 arguments. When specified, a BSD Version 4.4 formatted socket address structure is returned.

## Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The service cannot access a buffer specified by one or more arguments.
> SS$_BADPARAM | Programming error occurred for one of the following reasons: $QIO system service was specified without a socket. Error occurred processing a socket or protocol option.
> 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$_ILLCNTRFUNC | Programming error. The operation is unsupported for one of the following reasons: An invalid IO$_SENSEMODE function for the interface was specified. The interface does not have an IOCTL routine. An IO$_SENSEMODE function that requires a socket was specified, but the device did not have one. Create a socket and then issue the function. An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets.
> SS$_INSFMEM | Insufficient system dynamic memory to complete the service.
> SS$_IVBUFLEN | The size of a socket option buffer specified with the IO$_SENSEMODE function was invalid.
> SS$_NOSUCHDEV | Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed.
> SS$_NOLINKS | The specified socket was not connected.
> SS$_NOOPER | Programming error. An attempt to get ARP information occurred without OPER privilege.
> SS$_PROTOCOL | A network protocol error occurred. The address family specified in the socket address structure is not supported.
> SS$_SHUT | The local or remote node is no longer accepting connections.
> SS$_UNREACHABLE | The remote node is currently unreachable.

# IO$_SETMODE/IO$_SETCHAR

> The IO$_SETMODE and IO$_SETCHAR functions set one or more parameters (characteristics) pertaining to the network driver.

> Sockets are created using the IO$_SETMODE p1 argument. Names are assigned to sockets using the IO$_SETMODE p3 argument. Active sockets are converted to passive sockets using the IO$_SETMODE p4 argument. Other parameters, such as socket and protocol options, are specified in an input parameter list using the IO$_SETMODE p5 argument.

> The IO$_SETMODE p1, p3, and p4 arguments can be used with the p5 argument in a single $QIO system service to set socket names as well as socket and protocol options. IO$_SETMODE processes arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects an error, the IOSB contains the error and argument address or the value that was at fault.

> Refer to individual argument descriptions for details about specifying the type and format of input parameters.

## Arguments

> ### p1

> OpenVMS usage: | socket_characteristics
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Longword specifying the protocol, socket type, and address family, of a new socket. The p1 argument is the address of the longword containing the socket characteristics.

> The newly created socket is marked privileged if the image that creates a socket runs in a process that has a privileged UIC or has BYPASS, OPER, or SYSPRV privilege.

> The following table shows protocol codes:

> Protocol | Description
> --- | ---
> TCPIP$C_TCP | TCP/IP protocol
> TCPIP$C_UDP | UDP/IP protocol
> TCPIP$C_RAW_IP | IP protocol

> Table 6-6 lists the valid socket types.

> Table 6-6 Socket Types
> Socket Type | Description
> --- | ---
> TCPIP$C_STREAM | Permits bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries.
> TCPIP$C_DGRAM | Permits bidirectional data flow with record boundaries. No provisions for sequencing, reliability, or unduplicated messages.
> TCPIP$C_RAW | Permits access to the IP layer; used to develop new protocols that are layered upon the IP layer.

> The following table shows address family codes:

> Address Family | Description
> --- | ---
> TCPIP$C_AF_INET | Internet domain (default).
> TCPIP$C_AUXS | Accept hand-off of a socket already created and initialized by the auxiliary server.

> Related Functions

> The equivalent Sockets API function is `socket()` .

> ### p3

> OpenVMS usage: | socket_name
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by `item_list_2` descriptor

> The local name (that is, port number and internet address) to assign to the socket. The p3 argument is the address of an `item_list_2` descriptor that points to the socket address structure containing the local name.

> Related Functions

> The equivalent Sockets API function is `bind()` .

> ### p4

> OpenVMS usage: | connection_backlog
> type: | byte (unsigned)
> access: | read only
> mechanism: | by value

> Maximum limit of outstanding connection requests for a socket that is connection oriented. If more connection requests are received than are specified, the additional requests are ignored so that TCP retries can succeed.

> Related Functions

> The equivalent Sockets API function is `listen()` .

> ### p5

> OpenVMS usage: | input_parameter_list
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by `item_list_2` descriptor

> Input parameter list describing one or more parameters to set. The p5 argument is the address of an `item_list_2` descriptor that points to and identifies the type of input parameter list.

> The following are the types of input parameter lists:

> Symbolic Name | Input Parameter List Type
> --- | ---
> TCPIP$C_SOCKOPT | Socket options
> TCPIP$C_TCPOPT | TCP protocol options
> TCPIP$C_IPOPT | IP protocol options
> TCPIP$C_IOCTL | I/O control commands

> Each `item_list_2` structure appearing in an input parameter list describes an individual parameter or item to set. See Table A-1 for details about socket option parameters; see Table A-2 for TCP protocol option parameters; and see Table A-3 for details about IP protocol option parameters. Unsupported socket or protocol options are ignored.

> Each `ioctl_com` structure that appears in an input parameter list contains an I/O control command --- the set IOCTL request code and its associated IOCTL structure address. See Table B-1 for details about IOCTL command parameters.

You can use one $QIO system call to set up several socket options at once.

Unsupported socket options are ignored.

To execute set IOCTL operations, you need a system UIC or SYSPRV, BYPASS, or OPER privilege.

Related Functions

The equivalent Sockets API functions are `setsockopt()` and `ioctl()` .

## Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The service cannot access a buffer specified by one or more arguments.
> SS$_BADPARAM | Programming error that occurred for one of the following reasons: $QIO system service was specified without a socket. Error occurred processing a socket or protocol option.
> 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 | Programming error. The port being bound is already in use. An attempt to bind the socket to an address and port failed.
> SS$_EXQUOTA | Programming or INET management error occurred for one of the following reasons: An attempt to create a new socket with the IO$_SETMODE function occurred, but the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter). The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter), or reduce the listen parameter (the number of sockets the listener socket can create).
> SS$_FILALRACC | Programming error. The INET address is already in use. An attempt to bind the socket to an address and port failed.
> SS$_ILLCNTRFUNC | Programming error. The operation is not supported for one of the following reasons: An invalid IO$_SETMODE function for the interface occurred that does not have an IOCTL routine. An attempt to perform an IO$_SETMODE function required a socket, but the device did not have one. Create a socket before issuing the function.
> SS$_IVADDR | Programming error. The INET address you specified using the IO$_SETMODE function was not placed into the system. This resulted in an invalid port number or INET address combination. The INET address was invalid for one of the following reasons: Port zero and INET address zero are not allowed, or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. An attempt to exceed the limit of allowable permanent entries in the ARP table occurred. An attempt to bind a raw IP socket when there are no interfaces defined in the system occurred. An attempt to bind a raw IP socket to a null INET address occurred.
> SS$_INSFMEM | Insufficient system dynamic memory to complete the service.
> SS$_IVBUFLEN | The size of a socket option buffer specified with the IO$_SETMODE function was invalid.
> SS$_NOLICENSE | Programming or system management error. A TCP/IP Services license is not present.
> SS$_NOOPER | Programming or INET management error. An attempt to execute an I/O function that needs the OPER privilege occurred.
> SS$_NOPRIV | Programming or INET management error. There are not enough privileges for the attempted operation for one of the following reasons: An attempt to broadcast an IP datagram on a process without a system UIC or SYSPRV, BYPASS, or OPER privilege occurred. An attempt to use a reserved port number lower than 1024 occurred. An attempt to access a process that requires a system UIC or SYSPRV, or BYPASS privilege occurred. An attempt to use raw IP on a privileged socket that requires the SYSPRV or BYPASS privilege occurred.
> SS$_NOSUCHDEV | Programming error or INET management error. An attempt to show or delete an ARP table entry failed because the INET address is not found.
> SS$_NOSUCHNODE | Programming error or INET management error. An attempt to delete a route from the routing table failed because the entry was not found.
> SS$_PROTOCOL | Programming error. A specified protocol or address family caused an error for one of the following reasons: An invalid protocol type was specified at socket creation. An unsupported protocol was specified. A protocol type that was not found in the internal tables was specified. The address family is unsupported for one of the following reasons: An unsupported address family with the IO$_SETMODE subfunction was specified. Instead, specify the TCPIP$C_AF_INET or TCPIP$C_UNSPEC address family. An unsupported address family for a remote INET address with the IO$_ACCESS or IO$_WRITEVBLK function was specified. Instead, specify the TCPIP$C_AF_INET address family. An unsupported address family for the local INET address with the IO$_SETMODE function was specified. Instead, specify the TCPIP$C_AF_INET address family. An unsupported address family for the INET address of the routing module was specified. Instead, specify the TCPIP$C_AF_INET address family.
> SS$_SHUT | The local or remote node is no longer accepting connections.

# IO$_SETMODE|IO$M_OUTBAND

> The IO$_SETMODE|IO$M_OUTBAND function/modifier combination requests that the asynchronous system trap (AST) for an out-of-band (OOB) character be delivered to the requesting process. This is to be done only when an OOB character is received on the socket and there is no waiting read request. The socket must be a TCP (stream) socket.

> The Enable OOB character AST function allows an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before a new AST can be delivered. This function is subject to AST quotas.

## Arguments

> ### p1

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> To enable the AST, the p1 argument is the address of the OOB character AST routine. To disable the AST, p1 equals 0.

> ### p2

> OpenVMS usage: | user_arg
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> AST parameter to be delivered to the AST routine specified by the p1 argument.

> ### p3

> OpenVMS usage: | access_mode
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Access mode to deliver the AST.

## Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ABORT | Programming, INET management, or hardware error.
> SS$_ACCVIO | Programming error. An attempt to access an invalid memory location or buffer occurred.
> SS$_BADPARAM | Programming error. A $QIO service with an invalid parameter occurred for one of the following reasons: An attempt to execute an IO$_SETMODE function (all subfunctions, except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. A socket option was specified incorrectly.
> SS$_DEVACTIVE | INET management error. An attempt to change the static INET parameters occurred. If new parameters are needed, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command.
> SS$_DEVINTACT | INET management error. The driver was not started. Issue a START COMMUNICATION command before issuing $QIO functions.
> SS$_DEVNOTMOUNT | INET management error. The INET startup procedure executed incorrectly. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again.
> SS$_DUPLNAM | Programming error. An attempt to bind a port that is already in use occurred. An attempt to bind the socket to an address and port failed.
> SS$_EXQUOTA | Programming or INET management error occurred because of one of the following reasons: An attempt to create a new socket with the IO$_SETMODE function failed because the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter). The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter), or reduce the listen parameter (the number of sockets that the listener socket can create).
> SS$_FILALRACC | Programming error. INET address is already in use. An attempt to bind the socket to an address and port failed.
> SS$_INSFMEM | Programming or system management error: Not enough resources to allocate new socket.
> SS$_ILLCNTRFUNC | Programming error. Operation is not supported because of one of the following reasons: Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. An attempt to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function.
> SS$_IVADDR | Programming error. The specified INET address is not in the system, and an invalid port number or an invalid INET address combination was specified with an IO$_SETMODE function (a bind) for one of the following reasons: An attempt to bind the address failed because the INET address is not in the system and port zero and INET address zero are not allowed. An attempt to make a permanent entry in an ARP table that was full failed. An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. An attempt was made to bind an IP socket (raw IP) to a null INET address.
> SS$_IVBUFLEN | Programming error. The socket option buffer has an invalid size.
> SS$_NOLICENSE | Programming or system management error. TCP/IP Services not present.
> SS$_NOOPER | Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege.
> SS$_NOPRIV | Programming or INET management error. Not enough privileges for the attempted operation for one of the following reasons: Broadcasting an IP datagram was denied because the process does not have a system UIC or SYSPRV, BYPASS, or OPER privilege. An attempt was made to use a reserved port number lower than 1024. An operation accesses only processes that have a system UIC or SYSPRV or BYPASS privilege. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege.
> SS$_NOSUCHDEV | Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed.
> SS$_NOSUCHNODE | Programming or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found.
> SS$_PROTOCOL | Programming error because of one of the following reasons: The protocol type specified at socket creation is not valid. The protocol is not supported. The protocol type specified is not found in the internal tables and therefore is an invalid type. The address family is not supported for one of the following reasons: The address family specified with an IO$_SETMODE function (IOCTL subfunction) is not supported. The address family should be the TCPIP$C_AF_INET or TCPIP$C_UNSPEC address family. The address family of the local INET address specified with an IO$_SETMODE (bind) function is not supported. The address family should be the TCPIP$C_AF_INET address family. The address family of the INET address specified in a request to the routing module is not supported. The address family should be the TCPIP$C_AF_INET address family.
> SS$_SHUT | The local or remote node is no longer accepting connections.

Previous | Next | Contents | Index