Defining and starting a named counter server region

You activate a named counter pool in an MVS™ image by starting up a named counter server region for that pool. You can start the server as a started task, started job, or as a batch job.

The server region program, DFHNCMN

The named counter server region program is called DFHNCMN and must be run from an APF-authorized library. DFHNCMN is supplied in the CICS® authorized library, CICSTS31.CICS.SDFHAUTH.

SYSIN and SYSPRINT DD statements

The server reads its initialization parameters from a SYSIN data set, and writes messages and statistics to a print file, for which it requires a SYSPRINT DD statement.

Startup parameters

The named counter pool server requires some parameters in the start-up JCL. You can specify these in the PARM string, or in the SYSIN data set, or in a combination of both. When a parameter is specified in both places, the PARM value overrides the SYSIN value (because the PARM can be overridden on the MVS START command).

The most important parameter is the pool name, which is mandatory. Among other things, the pool name is used to form, with the prefix DFHNC, the server name (giving DFHNC.poolname).

The easiest way to ensure that all pool-related parameters are consistent across MVS images is to use the same SYSIN parameter data set (or an identical copy of it) for all servers accessing the same pool, and to specify in the PARM field any parameters that vary between servers.

For details of all the parameters, see Named counter server parameters.

Named counter server REGION parameter

Use the JCL REGION parameter to ensure that the named counter server region has enough storage to process the maximum number of named counter requests that can be executing concurrently.

The named counter server typically uses less than one megabyte of storage above 16MB and less than 20KB below 16MB.

During server initialization, the server acquires all the available storage above 16MB, as determined by the REGION parameter, then releases 5% of it for use by operating system services. It also acquires 5% of the free storage below 16MB for use in routines that require 24-bit addressable storage.

After initialization, the server uses AXM page allocation services to manage its storage. Server statistics indicate how much storage is actually allocated and used within the storage areas above and below 16MB, which are called AXMPGANY and AXMPGLOW in the statistics.

If a task in the server region or a cross-memory request runs out of storage, this is likely to result in AXM terminating that task or request using a simulated abend with system completion code 80A to indicate a GETMAIN failure. Although the server can usually continue processing other requests in this case, running out of storage in a critical routine can cause the server to terminate. Therefore, it is best to ensure that the REGION size is large enough to eliminate this risk.

Named counter server JCL example

Figure 58. Sample JCL to start a named counter server address space
//MVSnNC1 JOB  ...
//NCSERVER EXEC PGM=DFHNCMN,REGION=32M,TIME=NOLIMIT   Named counter server
//STEPLIB  DD   DSN=CICSTS31.CICS.SDFHAUTH,DISP=SHR   Authorized library
//SYSPRINT DD   SYSOUT=*                              Messages and statistics
//SYSIN    DD   *
POOLNAME=MVSnNC1                                Pool name
/*
Note:
You are recommended to specify TIME=NOLIMIT. The server task remains in a wait during most normal processing, because server processing is performed under the client CICS region TCB. If you omit the TIME subparameter, your server job could fail with abend S522 (wait limit exceeded), depending on the JWT value specified in the SMFPRMxx member of SYS1.PARMLIB.

Named counter server parameters

Parameters are specified in the form KEYWORD=value, where keywords can optionally be specified in mixed case to improve readability. If you specify more than one parameter in the PARM field or on the same SYSIN input line, the parameters must be separated by a comma. Any text following one or more spaces is taken as a descriptive comment. Any parameter line which starts with an asterisk or a space is assumed to be a whole line comment.

You can enter some parameter keywords in more than one form, such as in abbreviated or truncated form.

The main parameters are listed on the server print file during start-up.

Pool name parameter

This parameter, POOLNAME, is always required:

POOLNAME=name
specifies the 8-character name of the named counter pool. This is appended by the server to the prefix DFHNC to create its own server name, as in DFHNC.poolname, and also to the prefix DFHNCLS_ to create the name of the coupling facility list structure, as in DFHNCLS_poolname.

This parameter is valid only at server initialization, and must always be specified.

This keyword can be abbreviated to POOL.

Statistics parameters

Use the following parameters to specify server statistics options:

ENDOFDAY={00:00|hh:mm}
specifies the time of day, in hours and minutes, when the server is to collect and reset end-of-day statistics.
Note:
If the STATSOPTIONS parameter specifies NONE, the server still writes end-of-day statistics to the print file.

The valid range of times is from 00:00 to 24:00.

This keyword can be abbreviated to EOD.

STATSINTERVAL={03:00|hh:mm}
specifies the statistics collection interval, in the range 1 minute to 24 hours. This parameter is ignored if the STATSOPTIONS parameter specifies NONE.

The time interval can range from 00:01 to 24:00.

This keyword can be abbreviated to STATSINT.

STATSOPTIONS={NONE|SMF|PRINT|BOTH}
specifies whether the server is to produce interval statistics, and the destination for the statistics it produces.
NONE
The server does not produce any interval statistics.
SMF
The server produces interval statistics and writes them to the current SMF data set only.
PRINT
The server produces interval statistics and writes them to the server's print file only.
BOTH
The server produces interval statistics and writes them to the current SMF data set and to the server's print file.

This keyword can be abbreviated to STATSOPT.

Automatic restart manager (ARM) parameters

During server initialization, the server unconditionally registers with ARM except when the server program is invoked with either the UNLOAD or the RELOAD functions. The server will not start if the registration fails.

Use the following parameters to override default processing for the automatic restart manager:

ARMELEMENTNAME=elementname
specifies the automatic restart manager element name, up to 16 characters, to identify the server to ARM for automatic restart purposes. The permitted characters for the element name are A to Z 0-9 $ # @ and the underscore symbol (_).

The default identifier is of the form DFHNCnn_poolname, where NC represents the server type, nn is the &SYSCLONE value for the system (which can be either one or two characters), and poolname is the name of the pool served by the server.

This parameter is only valid at server initialization.

This keyword can be abbreviated to ARMELEMENT or ARMELEMNAME.

ARMELEMENTTYPE=elementtype
specifies the automatic restart manager element type, up to 8 characters for use in ARM policies as a means of classifying similar elements. The permitted characters for the element type are A to Z 0-9 $ # and @.

The default element type is SYSCICSS.

This parameter is only valid at server initialization.

This keyword can be abbreviated to ARMELEMTYPE.

List structure parameter

These parameters specify list structure attributes. They are used only for the initial allocation of resources when the pool list structure is being created, which occurs the first time you start a server for a pool.

POOLSIZE={0|number}
specifies the initial amount of coupling facility storage to be allocated for the pool list structure, expressed as kilobytes in the form number K, megabytes in the form number M or gigabytes in the form number G.
0
The special value 0 means that the server is to obtain an initial allocation using the parameters specified in the CFRM policy. If the CFRM policy specifies an INITSIZE value for the structure, this determines the initial allocation, otherwise the maximum SIZE value is allocated.
number
A non-zero value specifies an initial amount of storage to be allocated, overriding the INITSIZE parameter in the CFRM policy. This value is generally rounded up by MVS to the next multiple of 256K. The valid range of values is 1K to 2G, but should not be greater than the value specified on the SIZE parameter.

It is generally preferable to omit this parameter, and specify the structure size using the INITSIZE parameter in the CFRM policy. The POOLSIZE option can, however, be useful if the structure is being reallocated or reloaded, and the CFRM policy has not been updated to reflect the required size.

Note:
If the value is greater than the value specified on the CFRM SIZE parameter, the server POOLSIZE parameter is ignored and the initial allocation is based on the parameters specified in the CFRM policy.

This parameter is valid only at server initialization and is only used when the structure is first allocated.

Debug trace parameters

These parameters are provided only for intensive debug tracing.

Using these options in a production environment could have a significant impact on performance and cause the print file to grow very rapidly, using up spool space.

Trace messages from cross-memory requests can be lost if they are generated faster than the trace print subtask can print them. In this event, the trace only indicates how many messages were lost.

CFTRACE={OFF|ON}
specifies the coupling facility interface debug trace option.
OFF
Coupling facility interface debug trace is disabled.
ON
Coupling facility interface debug trace produces trace messages on the print file, indicating the main parameters to the coupling facility request interface, and the result from the IXLLIST macro.

This keyword can also be specified as TRACECF.

RQTRACE={OFF|ON}
specifies the request debug trace option.
OFF
Request debug trace is disabled.
ON
Request debug trace produces trace messages on the print file, indicating the main parameters on entry to each cross-memory request, and the results on exit.

This keyword can also be specified as TRACERQ=.

Warning parameters

Use these parameters to modify the thresholds at which warning messages are issued when the structure becomes nearly full.

ENTRYWARN={80|number}
specifies the percentage of list structure entries in use at which warning messages should be first triggered.

The valid range is from 1 to 100 per cent.

ENTRYWARNINC={5|number}
specifies the percentage increase (or decrease) of entries in use before the next warning message should be triggered (reduced to 1 when the next increase would otherwise reach 100). After the first warning, additional messages are issued as the number of elements increases and decreases. These messages stop when the number of entries in use has fallen at least this percentage below the initial warning level.

The valid range is from 1 to 100 per cent.

[[ Contents Previous Page | Next Page Index ]]