HP 3000 Manuals HP 3000 Manuals
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 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. 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 outlines parameters that are specific to the
particular protocol you are accessing.
Table 3-11. IPCSHUTDOWN Protocol Specific Parameters
----------------------------------------------------------------------------------------------
| | | |
| Parameters | TCP | X.25 |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| flags | | |
| | | |
| |
| | | |
| 17 | Graceful release of | n/a |
| | connection | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| 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 acknowledgement 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 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.
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 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.