|
» |
|
|
|
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: CCG — Not returned by this intrinsic.
Condition codes returned by the call to IOWAIT are: 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 |
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” 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 TCPThe following are cross-system programming considerations
for this intrinsic: 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. 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. 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.
|