Accessing the CRQ

In this section we will what happens when your DFSMShsm connects to the CRQ or disconnects from it. We also discuss the scope of commands and how they impact the CRQ.

Command scope

Commands that you issue to manipulate XCF structures have a Sysplex scope, that is the command needs to be issued once only for the sysplex. This is not true for most of the commands used by DFSMShsm. Unlike the XCF commands the scope of DFSMShsm commands that interact with the CRQ queue is generally limited to the system that they were issued from. We discuss the scope of each of the DFSMShsm commands you will be using to manipulate the CRQ in “Commands to manipulate the common recall queue” on page 84

You can use the sysplex console routing functions to direct commands to DFSMShsms active on other systems in the sysplex. If you are using the same STC name prefix in a MASH environment you can use command masking to route a command to all DFSMShsm hosts in your sysplex. We illustrate this in Figure 4-5 where one command was propagated to four hosts on three systems.

Figure 4-5 Using command masking and sysplex command routing

IEE421I RO *ALL,F HS*,Q REQ

SYSNAME RESPONSES --- SC63 ARC0101I QUERY REQUEST COMMAND STARTING ON HOST=3 ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY ARC0101I QUERY REQUEST COMMAND COMPLETED ON HOST=3 SC64 ARC0101I QUERY REQUEST COMMAND STARTING ON HOST=4 ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY ARC0101I QUERY REQUEST COMMAND COMPLETED ON HOST=4 ARC0101I QUERY REQUEST COMMAND STARTING ON HOST=A ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY ARC0101I QUERY REQUEST COMMAND COMPLETED ON HOST=A SC65 ARC0101I QUERY REQUEST COMMAND STARTING ON HOST=5 ARC0166I NO DFSMSHSM REQUEST FOUND FOR QUERY ARC0101I QUERY REQUEST COMMAND COMPLETED ON HOST=5

Chapter 4. DFSMShsm enhancements 79

Starting to use the CRQ

There are two methods available to connect your DFSMShsm hosts to the CRQ. Both use the new SETSYS COMMONQUEUE command. This command can either be included in your DFSMShsm startup parameters, ARCCMDxx, or be explicitly issued once your DFSMShsm address space is active. We discuss the syntax of this command in “SETSYS command” on page 89. The

SETSYS COMMONQUEUE(RECALL(CONNECT(basname))) command needs to be issued on to each DFSMShsm that will connect to the CRQ.

If the CRQ structure is defined in the active CFRM policy then DFSMShsm should connect successfully to the structure. Figure 4-6 shows the output from a successful connection to the structure that was defined previously in Figure 4-3.

Figure 4-6 Connecting to the CRQ structure

When DFSMShsm connects to the CRQ structure messages are received from both DFSMShsm and XCF about the status of the structure and DFSMShsm’s connection to it. The XCF status of the structure can also be displayed using the DISPLAY XCF,STR command. We provide an example in Figure 4-7. This display shows structure SYSARC_PLEX0_RCL that has been connected to by the four DFSMShsm address spaces running on the systems in our sysplex. A structure that has been defined but not yet connected to will not have the ‘ACTIVE STRUCTURE’ or ‘CONNECTION NAME’ sections in the display structure command output.

F HSM,SETSYS CQ(RECALL(CONNECT(PLEX0)) ARC0100I SETSYS COMMAND COMPLETED

IXL014I IXLCONN REQUEST FOR STRUCTURE SYSARC_PLEX0_RCL WAS SUCCESSFUL. JOBNAME: HSM ASID:

CONNECTOR NAME: HOSTCONNECTION1 CFNAME: CF02

ARC1501I CONNECTION TO STRUCTURE SYSARC_PLEX0_RCL WAS ARC1501I (CONT.) SUCCESSFUL, RC=00, REASON=00000000 IXL015I STRUCTURE ALLOCATION INFORMATION FOR

STRUCTURE SYSARC_PLEX0_RCL, CONNECTOR NAME HOSTCONNECTION1 CFNAME ALLOCATION STATUS/FAILURE REASON

--- --- CF02 STRUCTURE ALLOCATED

Figure 4-7 XCF view of the CRQ structure

When the first DFSMShsm connects to your new structure, a new XCF group will be created. If you are explicitly assigning transport classes to groups, you will need to assign one to this group as well.

D XCF,STR,STRNM=SYSARC* IXC360I 19.23.04 DISPLAY XCF STRNAME: SYSARC_PLEX0_RCL STATUS: ALLOCATED POLICY INFORMATION: POLICY SIZE : 10240 K POLICY INITSIZE: 5120 K POLICY MINSIZE : 0 K FULLTHRESHOLD : 80 ALLOWAUTOALT : NO REBUILD PERCENT: N/A PREFERENCE LIST: CF02 CF01 ENFORCEORDER : NO EXCLUSION LIST IS EMPTY

ACTIVE STRUCTURE --- ALLOCATION TIME: 03/07/2002 15:13:11 CFNAME : CF02 COUPLING FACILITY: 002064.IBM.02.000000010ECB PARTITION: D CPCID: 00 ACTUAL SIZE : 5120 K STORAGE INCREMENT SIZE: 256 K PHYSICAL VERSION: B74AF405 F5E4EF45 LOGICAL VERSION: B74AF405 F5E4EF45 SYSTEM-MANAGED PROCESS LEVEL: 8 XCF GRPNAME : IXCLO02F DISPOSITION : KEEP ACCESS TIME : 0 MAX CONNECTIONS: 32 # CONNECTIONS : 4 CONNECTION NAME ID VERSION SYSNAME JOBNAME ASID STATE

--- -- --- --- --- ---- --- HOSTCONNECTIONA 04 00040001 SC64 HSM2 004C ACTIVE HOSTCONNECTION3 03 00030005 SC63 HSM 0045 ACTIVE HOSTCONNECTION4 01 00010019 SC64 HSM 0049 ACTIVE HOSTCONNECTION5 02 0002000B SC65 HSM 0060 ACTIVE

Chapter 4. DFSMShsm enhancements 81

If SETSYS COMMONQUEUE(RECALL(CONNECT(basename)) is specified in the DFSMShsm startup parameters and the CF structure does not exist when DFSMShsm is started, then DFSMShsm will attempt, unsuccessfully, to connect to the CRQ structure. DFSMShsm will invoke an ENF Listen so that it is

automatically notified when the structure is available, then DFSMShsm will attempt to connect to it.

Once DFSMShsm has successfully connected to the CRQ structure existing recall requests are placed on the CRQ and new requests are passed to the CRQ. These recall requests will be eligible for processing by any DFSMShsm

connected to the CRQ.

Stopping access to the CRQ

You can disconnect DFSMShsm from the CRQ structure either by using the STOP command or by using the SETSYS COMMONQUEUE(RECALL(DISCONNECT)) command. We show the syntax of the DISCONNECT command in Figure 4-8. During normal operations, there should be no reason to use the

SETSYS COMMONQUEUE(RECALL(DISCONNECT)) command.

Figure 4-8 Disconnecting from the CRQ structure

There is no requirement that you explicitly disconnect DFSMShsm from the CRQ structure when you shutdown DFSMShsm. As part of its normal shutdown process DFSMShsm will disconnect from the queue. We discuss the implications of using the SETSYS COMMONQUEUE(RECALL(DISCONNECT)) command further in “Disconnecting from the common recall queue” on page 96.

If the DFSMShsm address space is in the process of shutting down in response to a STOP command, any outstanding non-batch WAIT recall request originating from this host that is on the CRQ is failed, but a new NOWAIT request is created to replace this request, so that the recall request is preserved. The new request has the same priority as the original request, but is a NOWAIT request instead of a WAIT request. NOWAIT recall requests remain available in the CRQ.

The new recall request is eligible for processing by any eligible host still connected to the CRQ. If the recall request is a batch WAIT request, it is not converted to a NOWAIT type request; it will remain on the CRQ and in CSA so the request can time out if not processed in a timely manner. The batch wait type request is eligible for processing by any eligible host still connected to the CRQ.

F HSM,SETSYS CQ(R(D))

ARC0100I SETSYS COMMAND COMPLETED ARC1502I DISCONNECTION FROM STRUCTURE SYSARC_PLEX1_RCL ARC1502I (CONT.) WAS SUCCESSFUL, RC=00, REASON=00000000

Errors connecting to the CRQ

If your structure has not been defined, or if it has been defined with a name other than you expected, DFSMShsm will not be able to successfully connect to the structure. We illustrate an example of this in Figure 4-9. In this example there was no structure named SYSARC_PLEXX_RCL defined in the CFRM policy.

Figure 4-9 Failing to connect to a structure

If you receive the RC=12 from an IXLCONN, DFSMShsm will not revert to not using a CRQ. Rather, it waits for the structure to be allocated. IXLCONN return and reason codes are documented in the MVS PROGRAMMING: Authorized Assembler Services Reference, Volume 2 SA22-7610-02.

If DFSMShsm’s connection to the CRQ is not successful, this will not stop DFSMShsm from processing recall requests placed on its local recall queue as long as there are sufficient resources available for the recalls to be processed. Figure 4-10 shows a QUERY ACTIVE command issued just after the command in Figure 4-9. The COMMONQUEUE CONNECTION STATUS is RETRY.

Figure 4-10 COMMONQUEUE CONNECYION in RETRY status

F HSM2,SETSYS CQ(R(C(PLEXX))

ARC0100I SETSYS COMMAND COMPLETED ARC1501I CONNECTION TO STRUCTURE SYSARC_PLEXX_RCL WAS ARC1501I (CONT.) UNSUCCESSFUL, RC=0C, REASON=02010C05 IXL013I IXLCONN REQUEST FOR STRUCTURE SYSARC_PLEXX_RCL FAILED. JOBNAME: HSM ASID: 0059 CONNECTOR NAME: HOSTCONNECTIONA

IXLCONN RETURN CODE: 0000000C, REASON CODE: 02010C05 CONADIAG0: 00000002 CONADIAG1: 00000008 CONADIAG2: 00000C05

ARC1540I COMMON RECALL QUEUE PLACEMENT FACTORS:

ARC1540I (CONT.) CONNECTION STATUS=RETRY,CRQPLEX HOLD STATUS=***,HOST ARC1540I (CONT.) COMMONQUEUE HOLD STATUS=NONE,STRUCTURE ENTRIES=***% ARC1540I (CONT.) FULL,STRUCTURE ELEMENTS=***% FULL ARC1541I COMMON RECALL QUEUE SELECTION FACTORS:

ARC1541I (CONT.) CONNECTION STATUS=RETRY,HOST RECALL HOLD ARC1541I (CONT.) STATUS=RECALL(TAPE),HOST COMMONQUEUE HOLD STATUS=NONE ARC0101I QUERY ACTIVE COMMAND COMPLETED ON HOST=A

Chapter 4. DFSMShsm enhancements 83

If the structure name was specified in error, you must first disconnect by issuing the SETSYS COMMONQUEUE(RECALL(DISCONNECT)) command and then specify a new SETSYS COMMONQUEUE(RECALL(CONNECT(basename))) command. If you receive the error because the structure is not yet defined in the active CFRM policy, DFSMShsm will connect to the structure when the CFRM policy that defines the structure is started.

If you are running with multiple HSMplexes and multiple CRQs, you need to take care that you actually connect the right DFSMShsm and structure. DFSMShsm will use the value you pass to it to. DFSMShsm does no checking, other than checking the structure exists for the first connector to a structure. For subsequent connectors the PLEXNAME value of the connector is checked to ensure that it matches that of the systems currently sharing the CRQ.

In Figure 4-11 we show what happened when we attempted to connect a host whose SETSYS PLEXNAME value was different to the SETSYS PLEXNAME of the currently or previously connected hosts.

Figure 4-11 Connecting to a structure with the wrong PLEXNAME value

The connection to the CRQ was not successful. In this case DFSMShsm fully disconnected from the CRQ structure. This DFSMShsm will continue processing local recall requests only.

There is no requirement that the values specified for PLEXNAME and COMMONQUEUE are the same. However when you have a one-to-one relationship between recall queues and HSMplexes it will makes operations simpler. If you are implementing multiple CRQ’s in the one HSMplex, then you will not be able to maintain this one-to-one relationship.

ARC0008I DFSMSHSM INITIALIZATION SUCCESSFUL

ARC1501I CONNECTION TO STRUCTURE SYSARC_PLEX0_RCL WAS ARC1501I (CONT.) SUCCESSFUL, RC=00, REASON=00000000

IXL014I IXLCONN REQUEST FOR STRUCTURE SYSARC_PLEX0_RCL WAS SUCCESSFUL. JOBNAME: HSM ASID: 0059 CONNECTOR NAME: HOSTCONNECTION1 CFNAME: CF02

ARC1506E AN INVOCATION OF THE COUPLING FACILITY LIST ARC1506E (CONT.) STRUCTURE IXLLSTE MACRO COMPLETED UNSUCCESSFULLY, ARC1506E (CONT.) RC=08, REASON=0C1C0859 ARC1502I DISCONNECTION FROM STRUCTURE SYSARC_PLEX0_RCL ARC1502I (CONT.) WAS SUCCESSFUL, RC=00, REASON=00000000

4.4 Commands to manipulate the common recall queue