HP 3000 Manuals HP 3000 Manuals
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,
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 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 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.
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 IPCRECVtwice, 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 IPCRECVtwice, 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.