IPCRECVCN

Receives a connection request on a call socket.

Syntax

IPCRECVCN  (calldesc,vcdesc[,flags][,opt][,result])

Parameters

calldesc (input)

32-bit integer, by value. Call socket descriptor. The socket descriptor for a call socket belonging to this process.

vcdesc (output)

32-bit integer, by reference. The returned VC socket descriptor, a number identifying a VC socket belonging to this process through which data can be sent or received. This descriptor can be used in other intrinsics.

flags (input)

32 bits, by reference. A bit representation of various options. The following flags are defined:

flags [0] — protected (input). (TCP only.) Ensures that the connection will be "protected" (privileged users only).
flags [18] — defer (input). Causes the reply to the connection request to be deferred. The intrinsic will complete when a connection request is received, but the virtual circuit will not be established. The IPCCONTROL intrinsic can be used later to accept or reject the connection.
flags [21] — checksum (input). (TCP only.) Enables checksum on the Transmission Control Protocol (TCP) connection for error checking. Checksum may also be set by the corresponding IPCCONNECT call. If either side specifies "checksum enabled" then the connection will be checksummed. TCP checksum may be enabled globally, over all connections, when configuring the Network Transport. See the NS 3000/XL NMMGR Screens Reference Manual for details on Network Transport configuration.
Checksum enabled by either IPCCONNECT or TCP (remote or local) configuration overrides a 0 setting (checksum disabled) for this flag. Checksum error checking is handled at the link level and is not normally required at the user level.
In fact, checksumming is only used for connections between nodes and is not used for connections within the same node. Enabling checksum may reduce network performance. Recommended value: 0.
flags [25] — discarded (output). For X.25 protocol access. Indicates that the call user data (CUD) or the facility field was present, but that the data had to be discarded or truncated. If the call user data option (code=5) is not specified the call user data is discarded. If the CUD or the facility field buffer is not long enough to contain the data, this flag is set and the data is truncated.

opt (input)

Record or byte array, by reference. A list of options, with associated information. The following options are defined:

maximum send size (code=3, length=2; 2-byte integer) (input). (TCP only). This option, which must be in the range from 1 to 30,000, specifies the length of the longest message that the user expects to send on this connection. The information is passed to the protocol module. If this option is not specified, then the protocol module will be able to handle messages at least 1,024 bytes long. If the specified value is smaller than a previously specified maximum send size, then the new value is ignored.
maximum receive size (code=4, length=2; 2-byte integer) (input). (TCP only.) This option, which must be in the range from 1 to 30,000, specifies the length of the longest message that the user expects to receive on this connection. The information is passed to the protocol module. If this option is not specified, then the protocol module will be able to handle messages at least 1,024 bytes long. If the specified value is smaller than a previously specified maximum receive size, then the new value is ignored.
call user data (code=5, length=n, n bytes) (output), (X.25 only.) This option provides a buffer for the return of the call user data (CUD) field from an X.25 packet. If call user data is present, but this option is not supplied, the discarded flag [25] is set. If the buffer is not long enough to contain the data, the data is truncated and the discarded flag is set.
calling node address (code=141, length=8; 8-byte array) (output). An output parameter that is used to contain the address of the requestor.
For TCP, the first two bytes of the array contain the remote socket's port address and the next four types contain the remote node's internet protocol address. The remaining bytes are unused.
For X.25 protocol access, the X.25 address of the calling node is returned in this field. The format of the record is equivalent to 16 nibbles (or BCD digits) in which the first nibble is the address length (ranging from 1 to 15), and the following 15 nibbles contains the calling address. The calling node address is not available if the call originated from a PAD.
You can use READOPT to obtain the output of this parameter.
protocol flags (code=144, length4; 4-byte buffer) (output). This option contains 32 bits of protocol-specific flags. The following flags are currently defined:
- Fast select (bit 7, output). (X.25 only.) If this flag is set, the fast select facility has been used in the connection request.
- Fast select restricted (bit 8, output). (X.25 only.) This flag only has meaning if the previous flag was set. If this flag is set, the fast select facility has been used in the connection request with restriction on response. This means that if the deferred flag was set, then the connection can be rejected (only) by using IPCCONTROL (and up to 128 bytes of CUD can be returned). If this flag is not set, but the fast select (bit 7) was set, the connection can be accepted or rejected by using IPCCONTROL, and up to 128 bytes of CUD can be returned.
- request from PAD (bit 14, output). (X.25 only.) This flag indicates that the connection request is coming from a PAD as opposed to a connection coming from a host.
- calling node address available (bit 16, output). (X.25 only.) This flag indicates that the calling node X.25 address was present.
Facility field (code=145, length=n, n bytes) (output). (X.25 only.) This option provides a buffer for the return of the facility field. If the facility field is present, but this buffer is not supplied, then the discarded flag (bit 25) is set.
If the buffer is not long enough to contain all of the data, then the data is truncated and the discarded flag (bit 25) is set. This buffer should be at least 109 bytes long to ensure receipt of the facility field. The received buffer contains the facilities exactly as they were received from the network.

result (output)

32-bit integer, by reference. The error code returned; zero if no error.

Description

The IPCRECVCN intrinsic allows a process to receive a connection request and establish a connection (virtual circuit). The connection is identified by the returned VC socket descriptor. The calling process can then employ the IPCSEND and IPCRECV intrinsics to send and receive data on the connection. A maximum of one unreceived connection request may be queued to a call socket.

If the calling process sets the defer reply to connection request flag (flags [18]), this intrinsic will complete when a connection request is received, but the virtual circuit will not be established. The calling process must use IPCCONTROL to either accept or reject the request. This feature is useful if an application must defer replying to the connection request and then, depending upon the identity of the requestor, decide to reject or accept the request.

The calling process may also specify whether TCP checksumming is to be enabled. Checksumming is usually disabled unless it is included by the remote protocol module or if the TCP checksumming flag (flags [21]) is set. When checksumming is enabled, performance is usually degraded because of increased overhead.

If this intrinsic is called in nowait mode, the data structures for the connection are created when the call to IOWAIT completes. They are not created with the initial call to IPCRECVCN. Therefore the address of the VC socket descriptor parameter is retained by NetIPC, and the descriptor's value is returned to that location when IOWAIT completes. The VC socket descriptor parameter must be global to both the IPCRECVCN and the IOWAIT intrinsic calls. NetIPC also retains the flags parameter.

The only required parameters are the calldesc and vcdesc parameters (option variable). Condition codes returned by this intrinsic are:

CCE — Succeeded.
CCL — Failed.
CCG — Not returned by this intrinsic.

Condition codes returned by the call to IOWAIT are:

CCE — Succeeded.
CCL — Failure in NetIPC (for example, resource problems, VC socket descriptor bounds) or protocol module. In the event of a NetIPC failure the connection request will still be pending, allowing the user to correct the problem and issue another call to IPCRECVCN.
CCG — Connection established but a noncritical error (for example, flags parameter out of bounds) occurred.

The IPCRECVCN intrinsic cannot be called in split stack mode.

Protocol-Specific Considerations

The following Table 3-9 “IPCRECVCN Protocol Specific Parameters” outlines parameters that are specific to the particular protocol you are accessing.

Table 3-9 IPCRECVCN Protocol Specific Parameters

Parameters		TCP	X.25
flags
	0	Protected connection	n/a
	21	Enable checksum	n/a
	25	n/a	Discarded
opt
	3	Maximum send size	n/a
	4	Maximum receive size	n/a
	5	n/a	Received CUD
	141	Calling node's IP address	Calling node's X.25 address
	144	n/a	Bit 7:fast select
			Bit 8: fast select restricted
			Bit 14: PAD
			Bit 16: calling node address available flag
	145	n/a	Facility field

X.25 Considerations

IPCRECVCN is used with switched virtual circuits (SVCs) only.

The call user data field returned in the opt parameter (code=5) is used by X.25 as follows. The first four bytes of the call user data field is used to determine the destination call (source) socket. The incoming call is sent to the call socket whose relative protocol address matches the first four bytes of the call user data. See the discussion for IPCCREATE for more information on protocol relative addresses.

Call acceptance can be affected by the X.25 configuration of the security field in the SVC path table which can limit access to a node by specifying which remote X.25 addresses are allowed to communicate with the node. See the X.25 XL System Access Configuration Guide for more information about security features.

Common errors returned by IPCRECVCN in result are:

SOCKERR   0  Request completed successfully.
SOCKERR  59  Socket timeout.
SOCKERR 107  Transport is going down.

A complete table of SOCKERRs is included in Appendix C “Error Messages”

TCP

The calling process may also specify whether checksumming is to be employed by the protocol modules (i.e., TCP) that support it. For TCP, checksumming is usually disabled unless it is included by the remote protocol module or if the TCP checksumming flag (flags [21]) is set. When checksumming is enabled, performance is usually degraded because of increased overhead.

Cross-System Considerations For TCP

The following are cross-system programming considerations for this intrinsic:

HP 3000 to HP 1000:

Checksumming — TCP checksumming will be enabled for both sides of the connection if it is enabled by either side for HP 3000 to HP 1000 connections. On both the HP 3000 and HP 1000 checksumming can be enabled by setting bit 21 in the flags parameter.

Send and receive size — The HP 3000 send and receive size range is 1 to 30,000 bytes. The HP 1000 send and receive size range is 1 to 8,000 bytes. Although the ranges are different, you must specify a send size within the correct range for the respective receiving system; otherwise, an error will occur. For example, if the HP 3000 node sends 16,000 bytes, the HP 1000 node can call IPCRECV twice receiving 8,000 bytes the first time and the second 8,000 bytes the second time.

Note that the default send and receive sizes are different on different HP systems. On the HP 3000, the default send and receive size is less than or equal to 1,024 bytes. On the HP 1000 the default send and receive size is 100 bytes.

HP 3000 to HP 9000:

Checksumming — When the ipcrecvcn() call is executed on the HP 9000 node, checksumming is always enabled.

Send and receive sizes — The HP 3000 send and receive size range is 1 to 30,000 bytes. The HP 9000 send and receive size range is 1 to 32,767 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

Note that the default send and receive sizes are different on different HP systems. On the HP 3000, the default send and receive size is less than or equal to 1,024 bytes. On the HP 9000, the default send and receive size is 100 bytes.

HP 3000 to PC NetIPC

Checksumming — With PC NetIPC, the TCP checksum option cannot be turned on. But if the HP 3000 requires it, the TCP checksum is in effect on both sides of the connection. On the HP 3000, enabling/disabling checksumming with NetIPC intrinsics allows you to override the checksumming decision made during network transport configuration for this particular process.

Send and receive size — The HP 3000 send and receive size range is 1 to 30,000 bytes. The PC send and receive size range is 1 to 65,535 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system. For example, if the PC node sends 60,000 bytes, the HP 3000 node can call IPCRECV twice, receiving 30,000 bytes the first time and the second 30,000 bytes the second time.

Note that the default send and receive sizes are different on different HP systems. On the HP 3000, the default send and receive size is less than or equal to 1,024 bytes.