HP 3000 Manuals HP 3000 Manuals
IPCCONTROL
Performs special operations.
Syntax
__________________________________________________________________________________
| |
| |
| IPCCONTROL ( descriptor, request [, wrtdata] [, wlen] [, readdata] [, rlen]|
| [, flags] [, result]) |
| |
__________________________________________________________________________________
Parameters
descriptor (input)
32-bit integer, by value. Either a call socket descriptor or a VC socket
descriptor.
request (input)
32-bit integer, by value. The value supplied indicates what control
operation is to be performed.
* 1 = Enable nowait (asynchronous) I/O for the specified call socket or
VC socket descriptor.
* 2 = Disable nowait (asynchronous) I/O for the specified call socket
or VC socket descriptor; perform waited (blocking) calls only.
* 3 = Change the default timeout (initially 60 seconds) for waited and
nowait I/O (receive operations only). The wrtdata (two bytes) and
wlen parameters are required with this request. The timeout is
specified in tenths of a second.
* 9 = Accept a connection request that is in the deferred state. This
request is valid only over connection sockets in the connection
pending state. To reject a connection request, see request code 15.
The call must be accepted before attempting to send or receive data
over the connection. No readdata is associated with this request.
For this request, the wrtdata parameter can (optionally) contain
information in the format of the opt parameter used in the other
intrinsics. The valid codes are:
* code 2--(X.25 only.) This option field contains data to be sent
as user data in the call accepted or clear indication packet.
The maximum length for X.25 call user data (CUD) is 16 bytes. If
the fast select facility has been used, the maximum length is 128
bytes.
* code 145--(X.25 only.) This option field defines the part of the
facility field to be appended to the facility field built using
the received facilities. The maximum length of this field is 109
bytes. This buffer has to follow the X.25 recommendation and is
appended to the facility field built based on the information
contained in the call request.
* 10 = Send a reset packet (X.25 only.) This request is valid only
over connection sockets. The wrtdata parameter (2 bytes) can
contain the cause (byte 1) and diagnostic (byte 2) fields to be
included in the reset packet sent by the X.25 protocol. The cause
field may be overwritten by the PDN. If configured as a DTE, the
cause will always be 0, irrespective of the value entered. Suggested
value for the cause field is 0 (zero), DTE originated. No readdata
is associated with this request.
* 11 = Send an interrupt packet (X.25 only.) This request is valid
only over connection sockets. The wrtdata parameter can contain
from 1 to 32 bytes of user data that will be inserted in the
interrupt packet sent by the X.25 protocol.
* 12 = Reason for error or event (X.25 only.) This request returns the
reason for the NetIPC error or event on an X.25 connection in the
readdata parameter. The first byte of readdata contains the type of
packet that caused the error or the unsolicited even (Clear, Reset,
Interrupt). The second byte contains the length of the clear user
data field or the length of the interrupt data field. The third and
fourth bytes contain the cause and diagnostic fields.
Beginning with byte 5 there can be either clear user data or
interrupt data. There can be up to 128 bytes of clear user data if
the type of packet is clear and if the fast select facility was used
at the beginning of the communication. There can be up to 32 bytes
of interrupt data if the type of packet is interrupt.
This request is valid only over an X.25 connection socket after a
communications line error has occurred. Possible cause and
diagnostic codes generated by X.25 are listed in Appendix B.
The type of packets returned are:
* 10 = Clear packet received
* 11 = Reset packet received
* 12 = Interrupt packet received
If no event is reported, readdata contains zeros. If the error was
caused by a clear packet, the connection is lost, and the user must
use IPCSHUTDOWN to clear the connection. There is no wrtdata
associated with this request.
* 13 = Set no activity timeout (X.25 only.) This request is only valid
on connection sockets. The wrtdata parameter contains the timeout
value in minutes (16-bit positive integer). If not specified, the
default value of zero will be passed to wrtdata disabling the timer.
After a timeout, IPCSHUTDOWN must be used to remove the connection
socket. There is no readdata associated with this request.
* 14 = Return local node name. If this request is used, the
fully-qualified local node name is returned in readdata.
* 15 = Reject a connection request that is in the deferred state. The
VC socket is automatically deleted after this request.
For X.25, this request causes the protocol to send a clear packet
with the cause field set to zero (DTE originated) and the diagnostic
field set to 64. This request is valid only over connection sockets
in the connection pending state.
For this request, the wrtdata parameter can (optionally) contain
information in the format of the opt parameter used in the other
intrinsics. The valid codes are:
* code 2--(X.25 only.) This option field contains data to be sent
as user data in the call accepted or clear indication packet.
The maximum length for X.25 call user data (CUD) is 16 bytes. If
the fast select facility has been used, the maximum length is 128
bytes.
* code 145--(X.25 only.) This option field defines the part of the
facility field to be appended to the facility field built using
the received facilities. The maximum length of this field is 109
bytes. This buffer has to follow the X.25 recommendation and is
appended to the facility field built based on the information
contained in the call request.
* 256 = Enable nowait receives; disable nowait sends.
* 257 = Enable nowait sends; disable nowait receives.
* 258 = Abort outstanding nowait receives.
* 259 = Enable user-level NetIPC tracing. This request causes NetIPC
intrinsic calls (both initiation and completion of I/O requests) to
be traced.
* code 131--Indicates that the data portion of the wrtdata
parameter contains the trace file name. If omitted, the trace
file is named SOCK####, where #### are four randomly chosen
digits, and placed in the caller's group and account.
* code 132--Indicates that the data portion of the wrtdata
parameter contains a 2-byte value representing the number of
records allotted to the trace file. If omitted, or if this value
is zero, the default is 1024 records.
* code 133--Indicates that the data portion of the wrtdataparameter
contains a 2-byte value representing the maximum number of bytes
of user data which you wish to trace. If omitted, or if the
value is -1, the default is 2000 bytes (a zero value means zero
bytes). The largest amount of user data which may be traced is
8,192 bytes.
* 260 = Disable user-level NetIPC tracing.
* 261 = Enable immediate acknowledgement. (TCP only.) Instructs the
TCP protocol module to acknowledge received frames immediately. Note
that use of option 261 can degrade performance of the user's
processes.
* 262 = Change the timeout for waited and no-wait sends. The default
is timeout disabled.
* 514 = Available to processes running in privileged mode only. Over
an open connection, if the previous call was an IPCCONNECT, the two
byte local TCP address is returned in the readdata buffer. Over an
open connection, if the previous call was an IPCRECVCN, two bytes of
the remote TCP address and four bytes of the remote IP address are
returned in the readdata buffer. The rlen parameter returns the
length of readdata.
wrtdata (input)
Record or byte array, by reference. If the request is to change the
default timeout, ( request code 3 or 262) the value in the first two
bytes of the wrtdata buffer will become the new timeout, in tenths of a
second. A zero value indicates an indefinite timeout: a call to IOWAIT
returns only after the next I/O request completes.
If the request is to enable tracing, ( request code 259) or for X.25
requests 9 or 15, this parameter may (optionally) contain information in
the same format as the opt parameter in other intrinsics.
wlen (input)
32-bit integer, by value. Length in bytes of the wrtdata parameter.
readdata (output)
Record or byte array, by reference. If the request enables tracing, the
trace file's name is returned in this parameter. If the request asks for
the socket's address, that address is returned here. If the request is
for the local node name, the fully qualified node name is returned in
readdata.
rlen (input/output)
32-bit integer, by reference. The maximum number of bytes that you
expect to receive in the readdata parameter. If readdata returns the
trace file name, rlen returns the length of this name, in bytes. If
readdata returns the socket's address, rlen will return the byte length
of the address.
flags (input)
32 bits, by reference. A bit representation of various options. The
following flag is defined:
flags [31] (input)--(TCP only.) If NetIPC tracing is enabled ( request =
259), this flag indicates that Transport Layer protocol activity (headers
and internal messages) should also be traced.
result (output)
32-bit integer, by reference. The error code returned; zero if no error.
Description
The IPCCONTROL intrinsic is used to perform various special operations on
sockets. This intrinsic is option variable. All requests require the
descriptor and request parameters except request 14 which requires
request and readdata only. The timeout requests (code 3 or 262) also
require the wrtdata parameter. For tracing, socket address requests,
and the local node name, information may be returned in the readdata
buffer.
Request code 3 is used to set a receive timeout value as specified in
wrtdata (two bytes). Zero (0) may be used to indicate no timeout. The
timeout value is measured in tenths of a second. The default value is 60
seconds with the timeout enabled.
Request code 3 and the no activity timeout for X.25 (code 13) are
independent timers. Setting one has no influence on the other. Both
timers can be operational at the same time.
Request code 262 is used to set a send timeout value as specified in
wrtdata (two bytes). Zero (0) may be used to indicate no timeout. If
timeouts are enabled, the timer will expire the number of timeout seconds
(as specified in wrtdata) after completion of the last send. The
default value is timeout NOT enabled. There is only one send timer per
connection. It will be running any time there is an outstanding send.
That is, if nowait I/O is used, it will run until IOWAIT completes for
all sends.
For a waited send, the timer will run until the intrinsic completes. If
multiple nowait sends are issued, the timer will be restarted for each
send initiated and for each IOWAIT completed with sends still
outstanding. If a send timer expires before a send completes, the
connection must be shutdown.
Request codes 9 and 15 allow the user to accept or reject a connection
that is in the deferred-connection state (see IPCRECVCN). If the
connection request is accepted, the connection can receive and send data
upon the completion of IPCCONTROL. If the connection is rejected, all
resources allocated for the connection are returned and the requestor is
notified of the rejection.
When requesting the descriptor's address (request code 514), readdata has
the meanings shown in Table 3-3.
Table 3-3. readdata Meanings
---------------------------------------------------------------------------------------------
| | |
| Descriptor Type | Address Meaning |
| | |
---------------------------------------------------------------------------------------------
| | |
| call socket | port address of socket (for TCP, length=2 |
| | bytes) |
| | |
---------------------------------------------------------------------------------------------
| | |
| connection from IPCCONNECT | local port address of connection socket |
| | (for TCP, length=2 bytes) |
| | |
---------------------------------------------------------------------------------------------
| | |
| connection from IPCRECVCN | remote port address of connection socket in |
| | bytes 0 and 1, remote internet address of |
| | node in bytes 2 through 5. (6 bytes total |
| | length) |
| | |
---------------------------------------------------------------------------------------------
Condition codes returned by this intrinsic are:
* CCE--Succeeded.
* CCL--Failed
* CCG--Not returned by this intrinsic.
This intrinsic may not 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-4.
----------------------------------------------------------------------------------------------
| | | |
| Parameters | TCP | X.25 |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| request | | |
| | | |
| |
| | | |
| 10 | n/a | Send reset |
| | | |
| |
| | | |
| 11 | n/a | Send interrupt |
| | | |
| |
| | | |
| 12 | n/a | Reason for error or event |
| | | |
| |
| | | |
| 13 | n/a | Set inactivity timeout |
| | | |
| |
| | | |
| 261 | Enable immediate ack | n/a |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| wrtdata | | |
| | | |
| |
| | | |
| 2 | n/a Call user data | |
| | | |
| |
| | | |
| 145 | n/a | Facility field |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| flags | | |
| | | |
| |
| | | |
| 31 | Trace transport layer | n/a |
| | protocol activity | |
| | | |
----------------------------------------------------------------------------------------------
X.25 Considerations
Common errors returned by IPCCONTROL in result are:
SOCKERR 0 Request completed successfully.
SOCKERR 59 Socket timeout.
SOCKERR 65 Connection aborted by local protocol
module.
SOCKERR 67 Connection failure detected.
SOCKERR 107 Transport is going down.
SOCKERR 160 Incompatible with protocol state.
SOCKERR 170 Error with use of fast select facility.
SOCKERR 171 Invalid facility field opt record
entry.
A complete table of SOCKERRs is included in Appendix C.