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