SHUTDOWN call

One way to terminate a network connection is to issue the CLOSE call which attempts to complete all outstanding data transmission requests prior to breaking the connection. The SHUTDOWN call can be used to close one-way traffic while completing data transfer in the other direction. The HOW parameter determines the direction of traffic to shutdown.

When the CLOSE call is used, the SETSOCKOPT OPTVAL LINGER parameter determines the amount of time the system waits before releasing the connection. For example, with a LINGER value of 30 seconds, system resources (including the IMS™ or CICS® transaction) remain in the system for up to 30 seconds after the CLOSE call is issued. In high volume, transaction-based systems like CICS and IMS, this can impact performance severely.

If the SHUTDOWN call is issued, when the CLOSE call is received, the connection can be closed immediately, rather than waiting for the 30-second delay.

If you issue SHUTDOWN for a socket that currently has outstanding socket calls pending, see Table 1 to determine the effects of this operation on the outstanding socket calls.

Table 1. Effect of SHUTDOWN socket call
Socket calls in local program	Local program		Remote program
Socket calls in local program	SHUTDOWN SEND	SHUTDOWN RECEIVE	SHUTDOWN RECEIVE	SHUTDOWN SEND
Write calls	Error number EPIPE on first call		Error number EPIPE on second call*
Read calls		Zero length return code		Zero length return code
* If you issue two write calls immediately, both might be successful, and an EPIPE error number might not be returned until a third write call is issued.

The following requirements apply to this call:

Requirement	Description
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
Amode:	31-bit or 24-bit
ASC mode:	Primary address space control (ASC) mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space

Figure 1 shows an example of SHUTDOWN call instructions.

Figure 1. SHUTDOWN call instruction example

    WORKING-STORAGE SECTION.
        01 SOC-FUNCTION  PIC X(16) VALUE IS 'SHUTDOWN'.
        01 S             PIC 9(4)  BINARY.
        01 HOW           PIC 9(8)  BINARY.
        01 END-FROM      PIC 9(8)  BINARY VALUE 0.
        01 END-TO        PIC 9(8)  BINARY VALUE 1.
        01 END-BOTH      PIC 9(8)  BINARY VALUE 2.
        01 ERRNO         PIC 9(8)  BINARY.
        01 RETCODE       PIC S9(8) BINARY.       
 
    PROCEDURE DIVISION.
         CALL 'EZASOKET' USING SOC-FUNCTION S HOW ERRNO RETCODE.

For equivalent PL/I and assembler language declarations, see Converting parameter descriptions.