Application programming considerations
To use the named counter callable interface you need to consider the following in your application program.
About this task
- 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 - Ensure that the application program is link-edited with the callable interface linkage routine, DFHNCTR.
- 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 ),VLThe 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.