 |
» |
|
|
|
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: CCG — Not returned by this intrinsic.
This intrinsic may not be called in split stack mode. Protocol-Specific ConsiderationsThe 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 |
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” |
