IPCSHUTDOWN

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.