|
|
|
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 "Cause and Diagnostic Codes"
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
wrtdata parameter 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 acknowledgment. (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 "readdata Meanings".
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 3-4 "IPCCONTROL Protocol
Specific Parameters" outlines parameters that are specific to the
particular protocol you are accessing.
Table 3-4 IPCCONTROL Protocol Specific Parameters
| 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 protocol activity | n/a |
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 "Error Messages"
|
