The named counter callable interface determines the actual pool name in response to a DFHNCTR call by referring to the DFHNCOPT options table. When a pool selector value is encountered for the first time, the pool name is determined via the options table. The name is then saved and used for all subsequent requests for the same pool selector from the same TCB. This continues for the life of the TCB or until the NC_FINISH function is used specifying that pool selector value. CICS® supplies a default DFHNCOPT in source form, which you can customize and generate using the DFHNCO macro. A typical use of the options table is to enable production and test regions to use a different counter pool without needing to change the pool name in application programs.
To avoid the need to maintain multiple versions of the options table, you can use table entries to select pools based not only on the pool selection parameter specified on the DFHNCTR call, but also on the job name and APPLID of the CICS region. You can also specify the name of a user exit program to be called to make the pool selection.
Define an options table using one or more invocations of the DFHNCO macro. Each invocation generates an options table entry that defines the pool name or user exit program to be used whenever any selection conditions specified on the entry satisfy an application program request. The first entry automatically generates the table header, including the CSECT statement. Follow the last entry with an END statement specifying the table module entry point, DFHNCOPT.
The DFHNCOPT options table parameters are illustrated in Figure 56.
DFHNCO [POOLSEL={(generic_values)|*},]
[JOBNAME={(generic_values)|*},]
[APPLID={(generic_values)|*},]
{POOL={YES|NO|name} | CALL=programname}
Terminate the last DFHNCO entry with the
following END statement:
END DFHNCOPT
The POOLSEL, JOBNAME, and APPLID parameters specify optional selection conditions to determine whether the entry applies to the current request. You can specify each of these operands as
Each name comprises the characters that can appear on the appropriate parameter, plus the wild-card characters * to match any sequence of zero or more non-blank characters, and % to match any single non-blank character. When multiple generic name are specified, the selection condition is satisfied if any one of them matches. A blank pool selector value can be matched using a null POOLSEL operand, for example POOLSEL= or POOLSEL=().
Specifying POOLSEL=, or POOLSEL=() is the equivalent of specifying 8 blanks.
If you omit the POOLSEL keyword, it defaults to *.
If you omit the JOBNAME keyword, it defaults to *.
If you omit the APPLID keyword, it defaults to *.
The program named can be link-edited with the options table, which generates a weak external reference (WXTRN), or it can be loaded dynamically the first time it is used. The program is called using standard MVS™ linkage in AMODE 31, with a standard save area and parameter list pointing to four fields, in the following order:
The end-of-list bit is set in the last parameter address.
The program should be reentrant and should be linked with RMODE ANY, so that it (and the option table if linked with the program) can be loaded above the line. Temporary working storage can be acquired and released using MVS GETMAIN and FREEMAIN. As this program is only called when a new pool selection value is used, the use of GETMAIN and FREEMAIN should not affect performance.
The exit program cannot use any CICS services. If it is used in a CICS region, it must avoid using any MVS services which could result in a long wait, as it will normally be executed under the CICS quasi-reentrant (QR) TCB.
The user exit program indicates its result by setting one of the following return codes in register 15:
The default options table, supplied in CICSTS31.CICS.SDFHLINK, contains the following entries:
DFHNCO POOLSEL=DFHNC*,POOL=YES
DFHNCO POOL=
END DFHNCOPT
With the default options table in use, any pool selector parameter that specifies a string beginning with DFHNC is taken to be an actual pool name, indicated by POOL=YES in the table entry. Any other value, including a value of all spaces, is assigned the default pool name, indicated by the POOL= table entry without a POOLSEL parameter.
The source for this default table is supplied in CICSTS31.CICS.SDFHSAMP.
To ensure that your CICS region can load the named counter options table, install the link-edited table into a CICS authorized library in STEPLIB. Alternatively you can install the table in a suitable library in the LINK list.
[[ Contents Previous Page | Next Page Index ]]