IBM Support

CSQE022E Structure CSQ_ADMIN unusable, size is too small

Troubleshooting


Problem

You try to add another IBM™ MQ for z/OS® queue manager to the Queue Sharing Group (QSG) or migrate to a new CFLEVEL. You receive error messages.

Symptom

CSQE022E Structure CSQ_ADMIN unusable, size is too small
CSQV086E QUEUE MANAGER ABNORMAL TERMINATION REASON=00C53000

Cause

CSQ_ADMIN must be large enough to contain a minimum of 1000 list entries for each queue manager in the queue-sharing group (meaning they were added by the CSQ5PQSG utility). The structure is used by the queue managers in the QSG to ensure integrity of data when recovery is required, coordinate serialized access to queues and generally manage the shared queues environment.

If ALLOWAUTOALT(YES) is specified in the POLICY, the calculation of list entries is made against the maximum capacity of the admin structure rather than its current capacity.

You might also get the CSQE022E error after an upgrade to a different Coupling Facility level.

Resolving The Problem


Increase the size of the structure by using one of the following options, which are outlined in the description of CSQE022E and described in the next steps. See Calculating the structure size farther down in this item.
 
  • If the structure is allocated and the Coupling Facility Resource Manager (CFRM) policy allows the size of the structure to be increased (if the structure is not at its maximum size), issue the z/OS® command

    /SETXCF START,ALTER,STRNAME=<struc-name>,SIZE=<newsize>

    You issue this command while the queue managers are running.

    For more information about this command, see SETXCF START Command. That reference indicates you can use the following command to determine the maximum structure size allowed.

    /DISPLAY XCF,STRUCTURE,STRNAME=<strname>
  • If the structure is not allocated, alter the policy to specify a larger INITSIZE for the structure.
 
  • If the policy does not allow the size to be increased or you require a size greater than the structure maximum size (SIZE), you need to:

    - Update the structure INITSIZE/SIZE in the CFRM policy.

    - Activate the new CFRM policy

    /SETXCF START,POLICY,TYPE=CFRM,POLNAME=<policyname>

    - Resolve the pending policy change by either stopping all queue managers and restarting or performing a structure rebuild, for example

    /SETXCF START,REBUILD,STRNM=MQ$1CSQ_ADMIN,LOCATION=NORMAL

    where: MQ$1 is replaced with your QSG name.

  • Note: The REBUILD inherits attributes from the structure, such as ENTRY:ELEMENT ratio and the number of EMCs. Initially, the CSQ_ADMIN structure has a 1:2 ratio. Depending on factors such as the size of Units of Work (UOWs), those attributes can change, affecting the INITSIZE and SIZE requirements.



    If you need to destroy the existing CSQ_ADMIN structure and reallocate it, so that it is re-created in line with the CFSIZER calculations, the following procedure were verified on the development lab's test systems:
    1. Stop all queue managers:
      /<cpf> STOP QMGR MODE(QUIESCE)
      where: cpf is the command prefix for your queue manager
    2. Delete existing structure with:
      /SETXCF FORCE,STR,STRNAME=xxxxCSQ_ADMIN
      where: xxxx is replaced with your QSG name
    3. Start all queue managers:
      /<cpf> START QMGR

    When the first queue manager is started, it causes a new instance of the CSQ_ADMIN structure to be allocated by using the attributes in the policy and as specified by IBM MQ on the IXLCONN.

    NOTE: All queue managers defined in the QSG must be started to allow the admin structure to be fully rebuilt. Until the admin structure rebuild is complete, some functions of IBM MQ that rely on data in the admin structure are unavailable.



Calculating the structure size
 
  • The number of ENTRIES you get for a particular SIZE depends on the CF level. The relative values of INITSIZE/SIZE, the ENTRIES:ELEMENT ratio, and the number of EMCs also has a bearing for an existing structure.
  • The web-based CFSIZER tool can be used to calculate the INITSIZE and SIZE for newly defined or existing structures.
     
  • See the section "What size CF structures should be defined?" in SupportPac MP16. It says:

    "Consider making SIZE double INITSIZE. Consider making MINSIZE equal to INITSIZE, particularly if ALLOWAUTOALT(YES) is specified.

    It is recommended to define SIZE to be not more than double INITSIZE. The value of SIZE is used by the system to preallocate certain control storage in case that size is ever attained. A high SIZE to INITSIZE ratio could effectively waste a significant amount of CF storage.

    If the entire CF reaches an installation-defined or defaulted-to percent full threshold as determined by "structure full" monitoring, the system considers reducing the size of any structures with unused space that are defined with ALLOWAUTOALT(YES).

    For this reason, we advise consideration of making MINSIZE equal to SIZE so that IBM structures will not be made too small. This is particularly important for the CSQ_ADMIN structure which could cause failure of shared queue operations if it became too small."


    For more information, see Requesting Structure Size in the z/OS MVS™ Setting Up a Sysplex manual. To paraphrase Understanding MINSIZE/INITSIZE/SIZE correlation:

    When only SIZE is specified, or INITSIZE and SIZE are equal, the CF can allocate space to accommodate the structure itself based on the single value. When both SIZE and INITSIZE are specified and are different, the CF must allocate space to accommodate the structure itself PLUS space for CF internal controls to allow for potential expansion of the structure from INITSIZE to SIZE. The space for both the structure and the internal controls must come from the INITSIZE amount of space. If SIZE is sufficiently larger than INITSIZE, either the structure might end up so small that it is effectively unusable, or the allocation might fail altogether.


    For the CSQ_ADMIN structure, there is not a strong requirement either for or against the use of ALLOWAUTOALT. Provided the SIZE of the structure is sufficient to accommodate any peaks in workload, including committing large UOWs, a configuration of ALLOWAUTOALT(NO) and INITSIZE equal to SIZE does not cause any issues for IBM MQ. If the peak space requirement is much larger than is needed during normal workloads, the structure might have a large amount of allocated space that is rarely used.
  • The minimum required size for initial allocation of the CSQ_ADMIN structure at CFCC level 14 (based on measurements on the Hursley systems) is:

    Note: In rare cases, the 1000 elements per queue manager have proved insufficient large units of work (UOWs) are committed. If large UOWs are expected, then allocate a larger admin structure.


 
  • If you do not have a chart for the sizing needed for your CF level, estimate the size needed based on current use:

    To determine the current initsize and size, issue the z/OS® command (where MQ$1 is replaced with your QSG name):
    /D XCF,STR,STRNAME=MQ$1CSQ_ADMIN

    STRNAME: MQ$1CSQ_ADMIN
    STATUS: ALLOCATED
    TYPE: SERIALIZED LIST
    POLICY INFORMATION:
    POLICY SIZE : 61440 K
    POLICY INITSIZE: 12288 K
    POLICY MINSIZE : 9216 K
    FULLTHRESHOLD : 70
    ALLOWAUTOALT : YES
    REBUILD PERCENT: 1
    DUPLEX : DISABLED
    ALLOWREALLOCATE: YES
    PREFERENCE LIST: CF02 CF01 CF03
    ENFORCEORDER : YES
    EXCLUSION LIST IS EMPTY
  • To determine the current max entries, issue the IBM MQ command
    /<cpf> DIS CFSTATUS(CSQ_ADMIN)
    CSQM201I cpf CSQMDMSG DIS CFSTATUS DETAILS
    CFSTATUS(CSQ_ADMIN)
    TYPE(SUMMARY)
    CFTYPE(ADMIN)
    STATUS(ACTIVE)
    SIZEMAX(12288)
    SIZEUSED(1)
    ENTSMAX(6358)
    ENTSUSED(266)
    FAILTIME( )
    FAILDATE( )


    The comparable output from doing a display of CFSTRUCT and hitting F11 one time on the CSQOREXX panels is:



    In the example, there is roughly 2KB per entry (122888 divided by 6358). So if you need 7000 entries for 7 queue managers, you would need a newsize of at least 14000KB, preferably larger. The allocated size will always be a multiple of the next 256K.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"ARM Category":[{"code":"a8m0z0000001iitAAA","label":"Troubleshooting"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Version(s)","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"ARM Category":[{"code":"a8m0z0000001iitAAA","label":"Troubleshooting"}],"Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Version(s)","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

WMQ

Document Information

Modified date:
16 August 2022

UID

swg21264321

Page Feedback