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