Application programming considerations

To use the named counter callable interface you need to consider the following in your application program.

About this task

  1. Ensure that your application programs include the appropriate copybook that defines the parameter list definition for the application programming language. The copybook defines symbolic constants for the function codes and return codes, and also defines the callable entry point for high-level languages. The copybook name is of the form DFHNC xxx where xxx indicates the programming language, as follows:
    ASM
    or
    EQU
    for Assembler
    C
    for C/C++
    COB
    for COBOL
    PLI
    for PL/I
  2. Ensure that the application program is link-edited with the callable interface linkage routine, DFHNCTR.
  3. Ensure the named counter server interface module, DFHNCIF, and the options table, DFHNCOPT, are available to the CICS region. That is, these objects must be in a STEPLIB library, in a linklist library, or in the LPA. To support CICS application programs that run in user key, DFHNCIF must be loaded from an APF-authorized library. The default option table and the named counter server interface module are supplied in CICSTS54.CICS .SDFHLINK.

CICS provides copybooks for all the supported languages:

Assembler
The standard assembler named counter interface definitions are provided in copybook DFHNCASM. Include these in your application programs using COPY DFHNCASM within a constant CSECT area. The symbolic values are defined as static fullword constants, in the form NC_ name DC F' nnn '. For example:
NC_BROWSE_NEXT DC F'7'

An alternative set of definitions is provided as symbolic equated values in copy book DFHNCEQU. These symbols are all of the form NC_EQU_ name to avoid conflict with the static constants. Note that when these equated values are used for function codes or return code comparisons, they should be used as address constant values, so that for example the function code NC_ASSIGN can be replaced by a reference to =A(NC_EQU_ASSIGN).

The syntax of the assembler version of the call to the named counter interface is as follows:
CALL DFHNCTR,(
function,return_code,pool_selector,counter_name,
X
value_length,current_value,minimum_value,maximum_value,
X
counter_options,update_value,compare_min,compare_max
),VL
The CALL macro must specify the VL option to set the end of list indication, as shown in the following example:
CALL DFHNCTR,(NC_ASSIGN,RC,POOL,NAME,CTRLEN,CTR),VL
C/C++
The named counter interface definitions for C/C++ are provided in header file DFHNCC. The symbolic constant names are in uppercase. The function name is dfhnctr , in lowercase.
COBOL
The named counter interface definitions for COBOL are provided in copybook DFHNCCOB.

Earlier versions of COBOL that are supported by CICS do not allow underscores in names. The symbolic names provided in copy book DFHNCCOB therefore use a hyphen instead of an underscore (for example NC-ASSIGN and NC-COUNTER-AT-LIMIT).

Note that the RETURN-CODE special register is set by each call, which affects the program overall return code if it is not explicitly set again before the program terminates.

PL/I
The named counter interface definitions for PL/I are provided in include file DFHNCPLI.


dfhp3c00204.html | Timestamp icon Last updated: Monday, 5 June 2017