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