CSLZSHUT: shutdown request

CSLZSHUT is a programming interface that enables you to shut down one or more CSL components from an authorized IMSplex member. Because CSLZSHUT is sent as a message, control is returned to the program that issued the request after the message is sent.

CSLZSHUT allows you to terminate:

A single CSL manager (ODBM, OM, RM, or SCI)
A CSL and all of its components on a single z/OS® image
A CSL and all of its components for an IMSplex across multiple z/OS images

The CSLZSHUT request is sent as a message, so control returns to the program that issued the request after the request is sent.

To shut down a single CSL component, send the CSLZSHUT FUNC=QUIESCE,SCOPE=CSLMEMBER message to the component you want to shut down.

To shut down a CSL and all of its components on a single z/OS image, either:

Send a CSLZSHUT FUNC=QUIESCE,SCOPE=CSLLOCAL message to the SCI that is active on the z/OS image that contains the CSL to be shut down.
Send a CSLZSHUT FUNC=QUIESCE,SCOPE=CSLLOCAL,OSNAME=xxxx message to any SCI active in the IMSplex (where xxxx is the z/OS image where the CSL to be shut down is active). SCI sends a CSLZSHUT request to all of the CSL components to be shut down.

To shut down the CSL on an entire IMSplex, send a CSLZSHUT FUNC=QUIESCE,SCOPE=CSLPLEX message to any SCI active in the IMSplex. SCI sends a CSLZSHUT request to all the CSL components in the IMSplex.

CSLZSHUT syntax

Use FUNC=DSECT to include equate (EQU) statements in your program for the CSLZSHUT parameter list length and the CSLZSHUT return and reason codes.


>>-CSLZSHUT----FUNC=DSECT--------------------------------------><

CSLZSHUT QUIESCE syntax

Use FUNC=QUIESCE to request that a CSL component shut down normally. Any work that the CSL component is currently processing is completed, and then the component shuts down. After processing the request, that component will not accept any new work.


>>-CSLZSHUT----FUNC=QUIESCE-| A |------------------------------><

A

|--SCITOKEN=scitokenaddress------------------------------------->

>--+-SCOPE=CSLMEMBER--MBRNAME=mbrnameaddress--+----------------->
   +-SCOPE=CSLLOCAL--+----------------------+-+   
   |                 '-OSNAME=osnameaddress-' |   
   '-SCOPE=CSLPLEX----------------------------'   

>--PARM=parmaddress--RETCODE=returncodeaddress------------------>

>--RSNCODE=reasoncodeaddress------------------------------------|

If the component that is being shut down is an SCI, the IMSplex members that are currently registered with that SCI are not deregistered before SCI terminates. This can impact event notification. These IMSplex members cannot communicate with other IMSplex members because their SCI is shut down. If one or more of the "orphaned" members is shut down or fails, the other IMSplex members are not notified of the shutdown or failure event until SCI comes back online.

Notification of the shutdown or failure depends on the authorization level of the members. If the terminating member is non-authorized, other members are notified when SCI restarts. If the terminating member is authorized, other authorized members, including orphaned authorized members, are notified before SCI restarts.

CSLZSHUT parameters

MBRNAME=symbol MBRNAME=(r2-r12)

(Required if SCOPE=CSLMEMBER) - Specifies the 8-byte CSL member name to which to send the shutdown request.

OSNAME=symbol

OSNAME=(r2-r12)

(Optional if SCOPE=CSLLOCAL) - Specifies the 8-byte name of the CSL, running on the z/OS image, that is to be shut down. If the OSNAME parameter is specified and the SCI is not active on the z/OS image specified, the command will not be processed.

PARM=symbol

PARM=(r1-r12)

(Required) - Specifies the CSLZSHUT parameter list. The length of the parameter list must be equal to the parameter list length EQU value defined by ZSHUT_PARMLN.

RETCODE=symbol

RETCODE=(r2-r12)

(Required) - Specifies a 4-byte field to receive the return code on output. SCI return codes are defined in CSLSRR. Possible return codes are described in the following table.

RSNCODE=symbol

RSNCODE=(r2-r12)

(Required) - Specifies a 4-byte field to receive the reason code on output. SCI reason codes are defined in CSLSRR. Possible return codes are described in the following table.

SCITOKEN=symbol

SCITOKEN=(r2-r12)

(Required) - Specifies a 16-byte field containing the SCI token. This token uniquely identifies this connection to SCI. The SCI token was returned by a successful CSLSCREG FUNC=REGISTER request.

SCOPE=CSLMEMBER | CSLLOCAL | CSLPLEX

(Required) - Specifies the scope of the CSL termination. Valid values for the SCOPE parameter are:

CSLMEMBER: This requests the CSL component receiving the request to shut itself down. CSLMEMBER can be processed by any CSL component.
CSLLOCAL: This requests that the CSL components on a single z/OS image be shut down. If the OSNAME parameter is also specified, the CSL components on that particular z/OS image are shut down. If the OSNAME parameter is specified and the SCI is not active on the z/OS image specified, the command will not be processed. If the OSNAME parameter is not specified, the SCI receiving the message shuts down the CSL on the local z/OS image. Only an SCI can process a SCOPE=CSLLOCAL request. If this request is sent to other CSL components, it is ignored.
CSLPLEX: This requests that the CSL components in an entire IMSplex be shut down. Only an SCI can process a SCOPE=CSLPLEX request. If this request is sent to other CSL components, it is ignored.

CSLZSHUT return and reason codes

The following table lists the return and reason codes that can be returned on a CSLZSHUT macro request. Also included is the meaning of a reason code (that is, what possibly caused it).

Table 1. CSLZSHUT return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The request completed successfully.
X'xx000008'	X'00002050'	The caller of the service attempted to pass an invalid parameter list. The request is rejected. "xx" identifies the component to set the return code.