IPCCONNECT

Requests a connection to another process.

Syntax

IPCCONNECT  ([calldesc],destdesc[,flags][,opt],vcdesc[,result]

Parameters

calldesc (input)

32-bit integer, by value. A call socket descriptor for a call socket belonging to this process. Required for X.25 level 3 access. For TCP access, if -1, or if omitted, a call socket is created temporarily to establish the connection.

destdesc (input)

32-bit integer, by value. Destination descriptor. Describes the location of the named call socket. (this is the call socket to which the connection request will be sent). A destination descriptor can be obtained by calling IPCDEST. For TCP access you can also obtain a destination descriptor by calling IPCLOOKUP.

flags (input)

32 bits, by reference. A bit representation of various options. No flags are defined for access to the X.25 protocol. The following flag bits are defined:

flags [0] (input). (TCP only.) Makes the connection a "protected" one. A protected connection is one which only privileged users may establish or use.
flags [21] (input). (TCP only.) Enables checksumming on the Transmission Control Protocol (TCP) connection for error checking. Checksumming may also be set by the corresponding IPCRECVCN 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. Checksumming enabled by either IPCRECVCN or the network transport (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.
Checksumming is only used for connections between nodes and is not used for connections within the same node. Enabling checksumming may reduce network performance. Recommended value: 0.

opt (input)

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

call user data (code=2, length=n, n bytes) (input). For access to the X.25 protocol only. This option contains data to be inserted as the call user data (CUD) field in an X.25 packet. The maximum length for the CUD is 16 bytes. With the fast select facility, the maximum length for the CUD is 128 bytes. HP has reserved the first four bytes of the CUD for protocol addressing. The user can supply data up to 12 bytes (or 124 bytes with fast select). By setting the no address flag (protocol flags option), the user can access all 16 bytes (or 128 bytes with fast select) of the CUD. See Chapter 1 “NetIPC Fundamentals” Access to the Call User Data (CUD) Field for more information.
maximum send size (code=3, length=2; 2-byte integer). (TCP only.) This option, which must be in the range from 1 to 30,000, specifies the length of the longest message the user expects to send on this connection. The information is passed to the protocol module for internal use only. This does not mean that the user cannot send a message larger than the value that is specified in this option code. If this option is not used, the protocol module will be able to send messages at least 1024 bytes long. If the value specified 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). (TCP only.) This option, which must be in the range from 1 to 30,000, specifies the length of the longest message the user expects to receive on this connection. The information is passed to the protocol module for calculating its transmission-window size. This does not mean that the user cannot receive messages larger than the length specified with this option code. If this option is not used, the protocol module can handle messages of at least 1024 bytes long. If the value specified is smaller than a previously specified maximum receive size, then the new value is ignored.
address option (code=128, length=2; 2-byte integer) (input). (TCP only.) This option specifies the source port address of the connection request. Addresses in the range (octal) %74057 to %77777 can be used without special capabilities.
facilities set name (code=142, length=8, packed array of 8 characters) (input). For access to the X.25 protocol only. This option field is used to associate a facilities set with the virtual circuit to be created over an SVC. This option does not apply to a PVC. This is an optional parameter and defaults to the facilities set name entered while configuring the X.25 network with NMMGR on the HP 3000.
protocol flags (code=144, length=4, 4-byte buffer) (input). This option contains 32 bits of protocol-specific flags. The following flags are currently defined:
- no address (bit 17, input). (X.25 only.) This flag provides the user with access to the entire X.25 call user data field (16 bytes or 128 bytes with fast select). This option can be useful for communication with non-HP nodes.
facility field (code=145, length=n, n bytes) (input). This option field defines the part of the facility field built using the facility set. This data must follow the X.25 recommendation and is appended to the facilities from the facility set without any change. See the discussion entitled "Facility Field" in Chapter 1 “NetIPC Fundamentals” for more information.

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.

result (output)

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

Description

The IPCCONNECT intrinsic is used to establish a VC socket (for a virtual circuit) to another process. The calling process must first create a call socket for itself and obtain the destination descriptor of a call socket belonging to the other process.

A successful result means that the connection request has been initiated. The process which requested the connection (via IPCCONNECT) must then call IPCRECV with the VC socket descriptor value in order to complete the connection. IPCCONNECT is a non-blocking call: the calling process is not blocked pending completion of its request.

Only the destination descriptor and VC socket descriptor parameters are required (that is, the intrinsic is option variable).

Condition codes returned by this intrinsic are as follows:

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

Protocol-Specific Considerations

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

Table 3-2 IPCCONNECT Protocol Specific Parameters

Parameters		TCP	X.25
`flags`
	0	Protected connection	n/a
	21	Enable checksum	n/a
`opt`
	2	n/a	Call user data (CUD)
	3	Maximum send size	n/a
	4	Maximum receive size	n/a
	128	TCP source port address	n/a
	142	n/a	Facilities set name
	144	None defined	Bit 17: access to CUD
	145	n/a	Facility field

X.25 Considerations

IPCCONNECT used over a switched virtual circuit causes the X.25 protocol to send a call request packet to the node and process described by the destination socket. Over a permanent virtual circuit (PVC), a reset packet is sent.

The opt parameter CUD field is sent as the CUD field in the call request packet. Based on the setting of the opt protocol flags "no address" flag, the user has access to either 12 or 16 bytes in the CUD field. With fast select, the user has access to either 124 or 128 bytes.

For communication between HP nodes, the first four bytes of the CUD field are interpreted as an address for incoming call packets (the third and fourth bytes contain the protocol relative address). The X.25 protocol uses this data to find the proper source socket to route the incoming call. This corresponds to the relative address parameter passed when the source socket was created.

Common errors returned by IPCCONNECT in result are:

SOCKERR   0  Request completed successfully.
SOCKERR  46  Unable to interpret received path
             report.
SOCKERR  55  Exceeded protocol module's limit.
SOCKERR 116  Destination unreachable.
SOCKERR 143  Invalid facilities set.
SOCKERR 155  Invalid X.25 flags.
SOCKERR 157  No virtual circuit configured.
SOCKERR 160  Incompatible with protocol state.
SOCKERR 162  X.25 permanent virtual circuit does
             not exist.
SOCKERR 163  Permanent virtual circuit already
             established.
SOCKERR 170  Error with use of the fast select facility.
SOCKERR 171  Invalid facility field opt record entry.

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

TCP Access

If a call socket descriptor is not supplied, or if the specified value is -1, a "ghost" socket is created for the purpose of setting up the connection. This temporary socket is destroyed before the IPCCONNECT call is complete.

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 cross-system communication. On both the HP 3000 and HP 1000 checksumming can be enabled by setting bit 21 in the flags parameter.

Send and receive sizes — 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, specify a send size within the correct range. For example, if the HP 3000 node sends 16,000 bytes, the HP 1000 node can call IPCRECV twice, receiving the first 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 ipcconnect() call is executed on the HP 9000 node, checksumming is always enabled. Therefore checksumming is always enabled for the HP 3000-to-HP 9000 connection.

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

Send and receive sizes — 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. For example, if the PC node sends 60,000 bytes, the HP 3000 node can call IPCRECV twice, receiving the first 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.