You activate a coupling facility data table pool in an MVS™ image by starting up a coupling facility data table server region for that pool. You can start the server as a started task, started job, or as a batch job.
The coupling facility data table server region program is called DFHCFMN and must be run from an APF-authorized library. DFHCFMN is supplied in the CICS® authorized library, CICSTS31.CICS.SDFHAUTH.
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.
The coupling facility data table 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 DFHCF., the server name (giving DFHCF.poolname). Optional pool-related parameters include the maximum number of tables to be supported.
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 Coupling facility data table server parameters.
Use the JCL REGION parameter to ensure that the coupling facility data table server region has enough storage to process the maximum number of data table requests that can be executing concurrently.
The number of coupling facility data table requests that each connected CICS region can have active at a time is limited to about 10. Each request requires about 40KB, therefore the REGION size should specify at least 400KB for each connected CICS region, plus a margin of about 10% for other storage areas. Thus, for a server supporting up to 5 CICS regions, specify REGION=2200K.
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, for example sequential file read and write routines.
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.
//PRODCFD1 JOB ...
//CFSERVER EXEC PGM=DFHCFMN,REGION=40M,TIME=NOLIMIT CICS CFDT Server
//STEPLIB DD DSN=CICSTS31.CICS.SDFHAUTH,DISP=SHR Authorized library
//SYSPRINT DD SYSOUT=* Messages and statistics
//SYSIN DD *
POOLNAME=PRODCFD1 Pool name
MAXTABLES=100 Allow up to 100 tables
/*
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.
The parameter descriptions that follow are divided into a number of categories:
The parameters in the above groups are all valid as initialization parameters (in the SYSIN file or PARM field), and some can also be modified by the SET command.
This parameter, POOLNAME, is always required:
This parameter is valid only at server initialization, and must always be specified.
This keyword can be abbreviated to POOL.
You can use these parameters to specify whether you want to use the optional security mechanism that the server provides, to check that CICS regions are authorized to open a coupling facility data table. They also allow you to override standard processing for this optional security.
This requires an external security manager, such as RACF®, that supports the FASTAUTH function in cross-memory mode.
This is the only security check performed by the server that is optional. The other file security checks are always performed by the server, as described in the CICS RACF Security Guide.
This parameter is valid only at server initialization.
This keyword can be abbreviated to SEC.
This parameter is valid only at server initialization.
This keyword can be abbreviated to SECCLASS.
This parameter is valid only at server initialization.
This keyword can be abbreviated to SECPREFIX or SECPRFX.
This parameter is valid only at server initialization.
This keyword can be abbreviated to SECPREFIXID.
Use the following parameters to specify server statistics options:
The valid range of times is from 00:00 to 24:00.
This keyword can be abbreviated to EOD.
The time interval can range from 00:01 to 24:00.
This keyword can be abbreviated to STATSINT.
This keyword can be abbreviated to STATSOPT.
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:
The default identifier is of the form DFHCFnn_poolname, where CF 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.
The default element type is SYSCICSS.
This parameter is only valid at server initialization.
This keyword can be abbreviated to ARMELEMTYPE.
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.
You cannot change this number without reallocating the structure, which means first deleting the existing structure (see Deleting or emptying coupling facility data table pools). If the structure is being allocated at less than its maximum size, specify a number for the maximum number of tables based on the maximum size of the structure, rather than its initial allocation size.
This parameter is valid only at server initialization and is used only when the structure is first allocated. The valid range is from 1 to 999 999.
This keyword can be abbreviated to MAXT.
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.
This parameter is valid only at server initialization and is only used when the structure is first allocated.
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.
This keyword can also be specified as TRACECF.
This keyword can also be specified as TRACERQ=.
These parameters are provided for tuning purposes, but normally you can omit these and let the server assume their default values.
The valid range is from 1 to 255.
Divide the average size of data per entry by the element size to obtain the optimum value for this ratio. However, if the structure becomes short of space and altering the ratio could improve space utilization, the server automatically adjusts the ratio according to the actual entry and element usage.
This parameter is valid only at server initialization and is used only when the structure is first allocated.
This keyword can be abbreviated to ELEMRATIO.
For current coupling facility implementations there is no known reason to use any value other than the default value of 256.
This parameter is valid only at server initialization and is only used when the structure is first allocated.
This keyword can be abbreviated to ELEMSIZE.
It is not essential to specify this parameter because the server automatically adjusts the ratio based on actual usage to improve space utilization if necessary.
This parameter is valid only at server initialization and is used only when the structure is first allocated. The valid range is from 1 to 255.
Use these parameters to modify the time intervals for the server lock wait retry mechanism. This is provided mainly as a "wake-up" mechanism to ensure that requests waiting for a record lock do not wait indefinitely in certain rare cases where a system failure or structure full condition could cause a lock release notification message to be lost. In addition, this mechanism also ensures that if a CICS task is purged while it has a request waiting for a lock, the waiting request in the server is woken up as soon as the lock wait retry interval expires. The request process then finds that the CICS task is no longer waiting for it, therefore it terminates rather than continuing to wait and hold on to server resources until the lock becomes free.
There are two times involved: a scan time interval and a wait time. The server starts its lock scan interval timing when the first request is made to wait.
This mechanism has very little effect on normal processing and the default lock wait retry parameter values are designed to suit the majority of installations.
This affects the overall duration of the lock wait timeout, because a request that starts waiting for a lock during a given scan interval is timed as if from the start of the interval. The lock scan interval should be less than the lock wait interval, and ideally should be such that the lock wait interval is an exact multiple of the lock scan interval.
You can specify this value as a number of seconds or in the time format hh:mm:ss.
The valid range is from 1 (1 second) to 24:00 (24 hours).
This keyword can be abbreviated to LOCKSCANINT.
This value can either be specified as a number of seconds or in time interval format hh:mm:ss.
The valid range is from 1 (1 second) to 24:00 (24 hours).
This keyword can be abbreviated to LOCKWAITINT.
Use these parameters to modify the thresholds at which warning messages are issued, and an automatic structure alter occurs, when the structure becomes nearly full.
The valid range is from 1 to 100 per cent.
This keyword can be abbreviated to ELEMWARN.
The valid range is from 1 to 100 per cent.
This keyword can be abbreviated to ELEMWARNINC.
The valid range is from 1 to 100 per cent.
The valid range is from 1 to 100 per cent.
Use these parameters to modify the conditions under which the server attempts an automatic alter when the structure becomes nearly full. For information about the structure alter process, see Coupling facility data table server automatic structure alter.
The valid range is from 0 to 999999999.
The valid range is from 0 to 100 per cent.
The valid range is from 0 to 999999999.
The valid range is from 0 to 100 per cent.
The valid range is from 00:00 to 24:00.
This keyword can be abbreviated to ALTERMININT.
Use these parameters to control the amount of structure space that is reserved for rewrites and server internal operations (such as tracking units of work and notifying other servers when a lock is released). For information about the effect of these parameters, see Avoiding structure full conditions.
The valid range is from 0 to 999999999.
This keyword can be abbreviated to ELEMRESERVEMIN.
The valid range is from 0 to 100.
This keyword can be abbreviated to ELEMRESERVEPC or ELEMRESPC.
The valid range is from 0 to 999999999.
This keyword can be abbreviated to ENTRYRESMIN.
The valid range is from 0 to 100.
This keyword can be abbreviated to ENTRYRESPC.
If the coupling facility data table structure is allowed to become completely full, this not only prevents the addition of new records or tables, but can also have a significant impact on performance and application function. In particular, rewrite requests can be rejected even when the size of the new data is less than or equal to the original, and server internal operations can fail, causing internal time-outs and retries.
The parameters ELEMENTRESERVEMIN, ELEMENTRESERVEPC, ENTRYRESERVEMIN and ENTRYRESERVEPC are provided to reduce the risk of the structure becoming totally full, by reserving a number of entries and elements, which can only be used for operations that normally only need extra space temporarily, such as rewrites or unit of work control operations. If a server is asked to write a new record or create a new table when the number of entries or elements remaining in the structure (as returned by each coupling facility access request) is less than or equal to the specified reserve level, the request is rejected with an indication that no space is available. Before rejecting the request, the server issues a dummy read request in order to find out the latest usage levels for the structure, in case more space has recently become available.
Using the reserved space parameters means that, even if the structure fills up very rapidly (for example, because a table is being loaded that is too large for the available space), enough space should remain to allow rewrites of existing records and allow internal communication between servers to continue normally.
Note that this mechanism cannot prevent the structure from eventually becoming totally full, as recoverable rewrites are allowed to use the reserved space temporarily, and rewrites that increase the data length will gradually use up the reserved elements. If action is not taken to prevent the structure from becoming totally full, the following effects can occur:
The coupling facility data table server monitors the total number of elements and entries in use in the structure, using information returned by the coupling facility on every request. When the numbers in use exceed the specified warning thresholds, the server issues a warning message, and this warning message is repeated each time the number in use increases beyond further thresholds.
Each time the server issues a warning, it also tests whether an automatic structure alter for the entry-to-element ratio should be issued. If any form of alter has already been issued recently (by any server or through an operator SETXCF ALTER command) and the structure space usage has remained above warning levels since the previous attempt, any further structure alter attempt is suppressed until at least the minimum interval (specified through the ALTERMININTERVAL parameter) has elapsed.
The server checks whether an automatic structure alter should be issued, by calculating how many excess elements or entries will be left when the other runs out completely, based on the ratio between the current numbers of elements and entries actually in use. If the number of excess elements or entries exceeds the number specified in the ALTERELEMMIN or ALTERENTRYMIN parameter, and the same number expressed as a percentage of the total exceeds the value specified in the ALTERELEMPC or ALTERENTRYPC parameter, an IXLALTER request is issued to alter the entry to element ratio to the actual current ratio between the number of entries and elements in use.
Only one alter request can be active at a time for a given structure. This means a server may well find that another server has already started the structure alter process, in which case its own alter is rejected. However, the system automatically notifies all servers when the structure alter is completed, giving the new numbers of elements and entries so that each server can update its own status information.
[[ Contents Previous Page | Next Page Index ]]