Defining a list structure

Define one or more coupling facility list structures for the named counter facility, each list structure representing a pool of named counters. Each named counter pool is accessed through a cross-memory server region.

Define the structure in the current coupling facility resource management (CFRM) policy, specifying the size of the structure and the preference list of coupling facilities in which it can be stored. The name of the list structure for a named counter pool is formed by adding the prefix DFHNCLS_ to your chosen pool name, giving DFHNCLS_poolname.

The CFRM policy is defined using the utility IXCMIAPU. For an example of this utility, see member IXCCFRMP in the SYS1.SAMPLIB library. An example of a policy statement for a named counter pool is shown in Figure 57.

Figure 57. Example definition of a coupling facility list structure for named counters
STRUCTURE  NAME(DFHNCLS_PRODNC1)
   SIZE(512)
   INITSIZE(256)
   PREFLIST(FACIL01,FACIL02)    

When you have updated the CFRM new policy with the new structure definition, activate the policy using the MVS™ command:

SETXCF START,POLICY,POLNAME=policyname,TYPE=CFRM.

A list structure can be allocated with an initial size and a maximum size, as specified by INITSIZE and SIZE respectively in the CFRM policy definition. All structure sizes are rounded up to the next multiple of 256KB at allocation time. Provided that space is available in the coupling facility, you can use the MVS SETXCF command to increase the structure size dynamically from its initial size towards its maximum size, making the new space available immediately to any currently active servers. If too much space is allocated, you can reduce the structure size to free up coupling facility storage for other purposes (which may take some time if the coupling facility has to move existing data out of the storage which is being freed). Note that if the size is altered in this way, you should also update the INITSIZE parameter in the policy to reflect the new size, so that the structure will not revert to its original size if it is subsequently recreated or reloaded.

Start of changeA coupling facility structure contains not only stored data but also the information needed to manage and access that data, in a similar way to a key-sequenced data set. The amount of internal control information depends on the level of functionality and performance of the coupling facility control code for the current CFLEVEL, and might increase for a higher CFLEVEL. For more information see Coupling facility storage management. The space required for a named counter pool depends on the number of different named counters you need, but the minimum size should be enough for most needs. A minimum-size structure of 256KB can hold hundred of named counters (as of CFLEVEL=14).End of change

Start of changeFor an accurate estimate of storage requirements for a list structure, use the IBM® CFSizer tool at http://www-1.ibm.com/servers/eserver/zseries/cfsizer/. The CFSizer tool is a web-based application that returns structure sizes based on the latest level of the coupling facility. If you enter the number of counters you require, the tool calculates the size of a structure that would be sufficiently large to contain at least the number of counters you specified. However, for practical operation, a reasonable proportion of free space must be available, not only to minimize the risk of the structure becoming full but also in order to avoid you receiving low space warning messages. You should aim to utilize no more than approximately 75% of the structure size. When you estimate the maximum number of counters that you require, increase that number by a third to include the free space in the calculation.End of change

Note that defining the CFRM policy statements for a list structure does not actually create the list structure. The structure is created the first time an attempt is made to connect to it, which occurs when the first named counter server that refers to the corresponding pool is started.

Note:
Before you attempt to start a named counter server make sure you have defined and started the authorized cross-memory (AXM) server environment (see Authorized cross memory (AXM) system services).

Related tasks

Setting up and running a named counter server
Defining a named counter options table
Defining and starting a named counter server region
Controlling named counter server regions
Deleting or emptying named counter pools
Changing the size of named counter pools
Unloading and reloading named counter pools
Dumping named counter pool list structures
Related reference

Named counter server overview
[[ Contents Previous Page | Next Page Index ]]