Extending Shared Queues using Shared Message Datasets

In this blog entry I will talk about what Shared Message Datasets (SMDS) are, what problem(s) they solve and how to implement and manage SMDS in your Queue Sharing Group (QSG).

What are Shared Message Datasets?

Currently, shared message queues and their message data are stored in structures that are built in the Coupling Facility.  These structures are defined with a fixed size, so all message queues assigned to a particular structure, are constrained by this size.  Once a CF structure is full, the reason code 2192 is issued, indicating that the storage medium for that queue is full. In V7.1 new function mode, a new construct called a Shared Message Dataset has been introduced to prevent CF structures from filling up.  The SMDS is a linear VSAM dataset much like a pageset for non-shared queues today, but is associated with a CF structure.

Implementing Shared Message Datasets

Before we can implement a SMDS architecture all queue managers in the queue sharing group need to have the OPMODE=(NEWFUNC ,710) set in the ZPARM.  Once this has been set, and the queue managers have been restarted we can now allocate the Shared Message Datasets.

Each Queue Manager in the queue sharing group will have its own copy of the SMDS for a coupling facility structure.  This is designated by the use of an * in the DSGROUP parameter of the CFSTRUCT definition. 

See below:

                             Queue Manager                                         Queue Manager

                                    QMA1                                                      QMB1

                                        /                                                                 \

                                      /                   Queue Sharing Group               \

                                    /                              (QM01)                             \

    'MQVS.QM01.QMA1.SHAREQ.SMDS'                                                     'MQVS.QM01.QMB1.SHAREQ.SMDS'

                                                                CFSTRUCT

                                                                 (SHAREQ)

                                             

                                                            DSGROUP('MQVS.QM01.*.SHAREQ.SMDS')

You can see the DSGROUP attribute is MQVS.QM01.*.SHAREQ.SMDS. The queue manager will take the * and substitute its name for the SMDS it is to use.

Now, let’s create and format the shared message datasets we want to use.  This is done using two utilities, IDCAMS and CSQJUFMT.

//CRESMDSA   JOB (ABCD,1234),'J LANG',CLASS=C,MSGCLASS=H

//*

//***********************************************************

//*   Allocate the SMDSs

//***********************************************************

//DEFINE   EXEC PGM=IDCAMS,REGION=4M

//SYSPRINT DD  SYSOUT=*

//SYSIN    DD  *

   DELETE 'MQVS.QM01.QMA1.SHAREQ.SMDS' ERASE CLUSTER

   SET MAXCC=0

   DEFINE CLUSTER                        -

          (NAME(MQVS.QM01.QMA1.SHAREQ.SMDS) -

           MEGABYTES(200 300)    -

           LINEAR                        -

           DATACLAS(DCXVSM)              -

           SHAREOPTIONS(2 3) )           -

       DATA                              -

          (NAME(MQVS.QM01.QMA1.SHAREQ.SMDS.DATA) )

/*

//***********************************************************

//*   Format the SMDS

//***********************************************************

//FORM     EXEC PGM=CSQJUFMT,COND=(0,NE),REGION=0M

//STEPLIB  DD  DSN=MQM.SCSQANLE,DISP=SHR

//         DD  DSN=MQM.SCSQAUTH,DISP=SHR

//SYSUT1   DD  DISP=OLD,DSN=MQVS.QM01.QMA1.SHAREQ.SMDS

//SYSPRINT DD  SYSOUT=*

The job above is for the QMA1 queue manager…you will also need to change the QMA1 to QMB1 and run the job again. Also you will notice a DATACLAS above, this is telling IDCAMS that this VSAM file has extended addressability and can be expanded past the 4GB limit.  It can actually grow to 16TB given that you have that amount of DASD available.

So now we have our shared message datasets for each of our queue managers in the queue sharing group, and we also have each queue manager running with the OPMODE=(NEWFUNC ,710). So we have two options, we can alter our current CTSTRUCT to Level 5 and set the appropriate variables, or we can create a new CFSTRUCT set to Level 5.  If we are creating a new struct, work will need to be done in the coupling facility policy to allocate this new structure, and the new policy will need to be started to become active.  For the second option you can get with your z/OS systems programmer and they will handle that portion.

For now, let’s look at altering a current CFSTRUCT.

It is easiest to do this in a batch job since several new attributes need to be set at the same time.

//SMDSJOBA  JOB (ABCD,1234),'J LANG',

//    CLASS=C,

//    MSGCLASS=H

//*

//EXTRACT EXEC PGM=CSQUTIL,PARM='QMA1'

//STEPLIB  DD DSN=MQM.SCSQANLE,DISP=SHR

//         DD DSN=MQMQ.QMA1.SCSQAUTH,DISP=SHR

//         DD DSN=MQM.SCSQAUTH,DISP=SHR

//SYSPRINT DD SYSOUT=*

//SYSIN    DD *

COMMAND DDNAME(INPUT)

/*

//*

//INPUT    DD *

ALTER                                                          -

 CFSTRUCT('SHAREQ')                                            -

 DESCR('Level 5 CFSTRUCT')                                     -

 CFLEVEL(5)                                                    -

 RECOVER(YES)                                                  -

 OFFLOAD(SMDS) see note 1                                      -

 OFFLD1TH(70)  see note 2                                      -

 OFFLD1SZ(32K)     “                                           -

 OFFLD2TH(80)      “                                           -

 OFFLD2SZ(4K)      “                                           -

 OFFLD3TH(90)      “                                           -

 OFFLD3SZ(0K)      “                                           -

 DSGROUP('MQVS.QM01.*.SHAREQ.SMDS')                            -

 DSBLOCK(256K)                                                 -

 DSBUFS(100)                                                   -

 DSEXPAND(YES)                                                 -

 RECAUTO(NO)                                                   -

 CFCONLOS(TERMINATE)

/*

//*

Note 1: When changing the level of a CFSTRUCT to 5, the OFFLOAD parameter must be set to DB2 or SMDS.  In our case, we are using shared message datasets due to the performance impact of using DB2. (this topic is for another paper)

Note 2: There are three sets of offload rules that the queue manager uses. These contain the percentage that the coupling facility structure must reach before the rule kicks in.  In our listing above, we have the following:

            OFFLD1TH(70) – When the coupling facility reaches 70% full

            OFFLD1SZ(32K) – New messages greater than 32K go to the SMDS

            OFFLD2TH(80) – When the coupling facility reaches 80% full

            OFFLD2SZ(4K) – New messages greater than 4K go to the SMDS

            OFFLD3TH(90) – When the coupling facility reaches 90% full

            OFFLD3SZ(32K) – New messages greater than 0K go to the SMDS

Special Note: There is still some data stored in the coupling facility for a message that is offloaded to the SMDS, so the larger your messages are, the more benefit you will get from using SMDS.  The 3^rd rule here, says that if the CF is 90% full, all new messages go to the SMDS.  For messages that are under 140 bytes, you will not benefit from this rule, and the CF will still become 100% full because while it is moving let’s say 100 bytes messages to the SMDS, it is using more space than that to control the pointers to these messages.

So now we have our CF at level 5, and we have our SMDS allocated.  You need to make sure the that the queue manager started task ID’s have UPDATE access to the SMDS VSAM datasets. (RACF Rules). The owning queue manager will have its SMDS open for UPDATE, other queue managers in the group will have all other SMDS’s open for READONLY.

There are several new commands that system programmers have available to them to aid in the management of the SMDS. Below are a few of the most common: (you will use your own queue manager name)

/-QMA1 DIS  SMDSCONN(QMA1) CFSTRUCT(SHAREQ)

Display the status and availability to the SMDS by the queue manager.

Output:

CSQM201I –QMA1 CSQMDRTC  DIS SMDSCONN DETAILS

SMDSCONN(QMA1)

CFSTRUCT(SHAREQ)

OPENMODE(UPDATE)

STATUS(OPEN)

AVAIL(NORMAL)

EXPANDST(NORMAL)

 END SMDSCONN DETAILS

/-QMA1 START SMDSCONN(QMA1) CFSTRUCT(SHAREQ)

Start the connection to the SMDS from the queue manager. This will allocate and open

the SMDS if it is new, otherwise it automatically happens.

Output:

-QMA1 CSQMSSMD ' START SMDSCONN' NORMAL COMPLETION

The change you will see from the start will be shown by displaying the connection.

While running a job to load the queue, you will see expansion messages in the queue manager address space if it is allocating more space for the SMDS…this is much like normal page set expansion.

CSQE213I -QMA1 CSQEDSS2 SMDS(QMA1) CFSTRUCT(SHAREQ) 

data set MQVS.QM01.QMA1.SHAREQ.SMDS is now 98% full

CSQE239I -QMA1 CSQEDSS2 SMDS(QMA1) CFSTRUCT(SHAREQ) 

data set MQVS.QM01.QMA1.SHAREQ.SMDS has become full so new large 

messages can no longer be stored in it

CSQE212I -QMA1 CSQEDSI1 Formatting is complete for 

SMDS(QMA1) CFSTRUCT(SHAREQ) data set MQVS.QM01.QMA1.SHAREQ.SMDS

CSQE217I -QMA1 CSQEDSI1 Expansion of SMDS(QMA1) 

CFSTRUCT(SHAREQ) data set MQVS.QM01.QMA1.SHAREQ.SMDS was successful

 76860 pages added, total pages 128160

While this is happening, your job, or channels will be paused until the expansion completes.

Other SMDS commands: (for a complete list of parameters, see MQ Command Reference)

ALTER SDMS (qmgr|*) CFSTRUCT(cfname) DSBUFS(number)

     DSEXPAND(yes|no|)

DISPLAY SMDS (qmgr|*) CFSTRUCT(cfname) WHERE(filter)

DISPLAY SMDSCONN (qmgr|*) CFSTRUCT(cfname) WHERE(filter)

RESET SMDS (qmgr or *) CFSTRUCT(cfname)    ACCESS(enabled|disabled) STATUS(failed|recovered)

START SMDSCONN (qmgr or *) CFSTRUCT(cfname)

     CMDSCOPE(‘ ‘|qmgr|*)

STOP SMDSCONN (qmgr or *) CFSTRUCT(cfname)

     CMDSCOPE(‘ ‘|qmgr|*)

Optional parameter

Testing:

I had two CF structures established of the same size.  One was at Level 4, one was at Level 5 with a SMDS assigned to the CFSTRUCT.  I attempted to put 50,000 messages that were 40,000 bytes each.  In the Level 4 CFSTRUCT, I was able to load 4710 messages in the queue before the RC 2192 was returned stating that the CF was full.  In the Level 5 structure with the SMDS assigned, once the CF level reached 70%, the data started going to the SMDS and I was able to put all 50,000 messages on the shared queue.