|
|
|
Releases a descriptor and any resources associated with it.
Syntax
IPCSHUTDOWN ( descriptor [,flags] [,opt] [,result] )
Parameters
- descriptor (input)
- 32-bit integer, by value. The socket to be released. May be a
call socket, destination, or VC socket descriptor.
- flags
- 32 bits, by reference. A bit representation of various options.
The following flag is defined:
flag [17] — (TCP only.) graceful release of connection.
- opt
- Record or byte array, by reference. A list of options, with
associated information. The following option is defined:
- clear user data (code=2, length=n, n bytes) (input). (X.25
only.) If the fast select facility was used in the connection
request, and the connection was accepted, you can include a clear
user data field which can contain up to 128 bytes of data. For
more information, see the discussion of the fast select facility
in Chapter 1 "NetIPC Fundamentals" of this
manual.
- reason code (code=143, length=2) (input). (X.25 only.) This
option allows you to include cause and diagnostic values in the
X.25 clear packets when a connection is closed down. The first
byte contains the cause and the second byte contains the
diagnostic code. A list of cause and diagnostic codes used with NS
X.25 protocol access is contained in Appendix B
"Cause and Diagnostic Codes" If DTE originated, the cause code
will always be zero.
- result (output)
- 32-bit integer, by reference. The error code returned; zero if no
error.
Description
The IPCSHUTDOWN intrinsic permits the creating process to close a
call socket or a VC socket descriptor or to release a connection. The
descriptor is the only required parameter (option variable).
IPCSHUTDOWN can be called to release a call socket descriptor, a
destination descriptor, or a VC socket descriptor. Since systems resources are
used up as long as call sockets and destination sockets exist, you should
release them whenever they are no longer needed.
The call socket is needed as long as a process expects to receive a connection
request on that socket. A process which receives a connection request can
release the call sockets any time after the connection request is received via
IPCRECVCN, as long as no other connection requests are expected for
that call socket. For more information on IPCSHUTDOWN, refer to
"Shutting Down Sockets and Connections" at the beginning of this chapter.
Condition codes returned by this intrinsic are:
- CCE — Succeeded.
- CCL — Failed.
- CCG — Not returned by this intrinsic.
This intrinsic cannot be called in split stack mode.
Protocol-Specific Considerations
The following Table 3-11 "IPCSEND Protocol
Specific Parameters" outlines parameters that are specific to the
particular protocol you are accessing.
Table 3-11 IPCSEND Protocol Specific Parameters
| Parameters |
TCP |
X.25 |
| flags | | |
| 17 | Graceful release of connection | n/a |
| opt | | |
| 2 | n/a | Clear user data |
| 143 | n/a | Reason code |
X.25 Considerations
Shutting down an X.25 connection causes a clear packet to be sent by X.25 over
an SVC, unless the virtual circuit is already cleared. You can specify the
cause and diagnostic fields in the opt parameter (code=143)
that will be included in the clear packet over an SVC. Over a public data
network (PDN), the cause may not be transmitted to the remote node.
When used with direct access to level 3, the intrinsic IPCSHUTDOWN
can only be called in waited mode. The intrinsic will not return until the
request is completed. X.25 direct access to level 3 does not support the
graceful release bit. As a suggestion, to ensure that no data packets
are lost before the clear packet is sent, use the D bit option in the last
IPCSEND. This would assure end-to-end acknowledgment of this message
before issuing the IPCSHUTDOWN to clear the virtual circuit. Another
method is to send an unimportant message as the last message. (See example 2
in Chapter 4 "NetIPC Examples" for an example of this
method.)
Common errors returned by IPCSHUTDOWN in result are.
SOCKERR 0 Request completed successfully.
SOCKERR 54 Invalid call socket descriptor.
SOCKERR 66 Invalid connection descriptor.
SOCKERR 67 Connection failure detected.
SOCKERR 142 Invalid call user data opt record entry.
SOCKERR 170 Error with use of the fast select facility.
A complete table of SOCKERRs is included in
Appendix C "Error Messages"
TCP
If graceful release is specified and supported by the remote process, the
requestor of a graceful release will go to a simplex-in state (that is, able
only to receive, unable to send) and the remote process will go to a
simplex-out state. The VC remains in this state until the remote process shuts
down its socket, at which time all resources are released. See "Shutting Down
a Connection" in Chapter 1 "NetIPC Fundamentals" for
the steps to take in implementing a graceful release shutdown.
If graceful release is selected, a SOCKERR 102 result will be returned if any
of the following conditions exists:
- A connection request has been received, but the connection has not been
accepted.
- The connection has already been gracefully released, and the process is
therefore in a simplex-in state.
- A connection request has been issued, but the connection has not yet
been established.
- The connection has been aborted.
- The protocol module (part of the NS transport) does not support graceful
release.
- Data is being sent from the connection. This could occur, for example,
if IPCSEND was called in nowait mode and has not yet
completed.
Cross-System Considerations For TCP
The following are cross-system programming considerations for this intrinsic:
HP 3000 to HP 1000:
Socket shut down — The HP 3000 provides a graceful release flag
(flag 17) that is not available on the HP 1000. Do not set the
graceful release flag on the HP 3000. Otherwise, the HP 1000 will not perform
a normal shutdown. If the HP 3000 process sets the graceful release flag, the
HP 1000 IPCRecv call will return a NetIPC error 68 (No more data).
The HP 1000 process should handle error 68 as if it were an error 64
(Connection aborted by peer). After receiving an error 68, subsequent
IPCRecv calls on the HP 1000 will return an error 109 (Remote
connection has already graceful released the socket).
HP 3000 to HP 9000:
Socket shut down — The HP 3000 provides a graceful release flag
that is not available on the HP 9000. If the graceful release flag (flag
17) is set on the HP 3000, the HP 9000 will respond as though it were a
normal shutdown. The HP 3000 does not support shared sockets; the HP 9000 does.
Shared sockets are destroyed only when the descriptor being released is the
sole descriptor for that socket. Therefore, the HP 9000 process may take
longer to close the connection than expected.
HP 3000 to PC NetIPC:
Socket shut down — The HP 3000 provides a graceful release flag
that is not available on the PC. If the graceful release flag (flag
17) is set on the HP 3000, the PC will respond as though it were a normal
shutdown.
|
