In addition to the CICS® named counter API, CICS provides a call interface that you can use from a batch application to access the same named counters. This could be important where you have an application that uses both CICS and batch programs, and both need to access the same named counter to obtain unique numbers from a specified range. The call interface does not depend on CICS services, therefore it can also be used in applications running under any release of CICS.
The named counter call interface does not use CICS command-level API, therefore the system initialization parameter CMDPROT=YES has no effect. If the interface is called from a CICS application program that is excuting in user key, it switches to CICS key while processing the request but CICS does not attempt to verify that the program has write access to the output parameter fields.
The first request by an application region that addresses a particular pool automatically establishes a connection to the server for that pool. This connection is associated with the current MVS™ TCB (which for CICS is the quasi-reentrant (QR) TCB) and normally lasts until the TCB terminates at end of job. This connection can only be used from the TCB under which the connection was established. A request issued from another TCB will establish a separate connection to the server.
To use the named counter callable interface:
ASM or EQU for Assembler
C for C/C++
COB for COBOL
PLI for PL/I
CICS provides copybooks for all the supported languages:
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
COBOL does not allow underscores within names, therefore the symbolic names provided in copy book DFHNCCOB 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.
The syntax of the named counter call is as follows:
CALL DFHNCTR(function,return_code,pool_selector,counter_name,
value_length,current_value,minimum_value,maximum_value,
counter_options,update_value,compare_min,compare_max);
If you do not want to use an imbedded optional parameter, either specify the default value or ensure that the parameter list contains a null address for the omitted parameter. For an example of a call that omits an optional parameter, see Example of DFHNCTR calls with null parameters.
If you omit an optional value parameter, the new named counter is created using the default for the omitted value. For example, if you omit all the optional parameters, the counter is created with an initial value of 0, a minimum value of 0, and a maximum value of high values (the double word field is filled with X'FF').
This operation can include a conditional test on the current value of the named counter, using the compare_min and compare_max parameters.
The server returns the minimum and maximum values if you specify these fields on the call parameter list and the request is successful.
You can use the counter_options parameter on the NC_ASSIGN request to override the counter options set by the NC_CREATE request.
You can use the update_value parameter to specify the increment to be used on this request only for the named counter (the default increment is 1). This enables you to obtain a range of numbers on a single request. For more information, see the description of the update_value parameter.
Note that the named counter is incremented by update_value after the current value is assigned. For example:
the named counter server returns 109 and sets the current value to 134 ready for the next NC_ASSIGN request, effectively assigning numbers in the range 109 through 133. The increment can be any value between zero and the limit is determined by the minimum and maximum values set for the named counter. Thus the increment limit is ((maximum_value plus 1) minus minimum value). An increment of zero causes NC_ASSIGN to operate the same as NC_INQUIRE, except for any comparison options.
When the increment is greater than 1, and the named counter is near the maximum limit, the server may not be able to increment the current number by the whole value of the specified increment. This situation occurs when incrementing the counter would exceed the maximum value plus 1. You control what action the named counter server takes in this situation through the counter_options NC_NOREDUCE | NC_REDUCE, and NC_NOWRAP | NC_WRAP. See counter_options parameter for information about the operation of these options.
This function does not apply to a specific counter, therefore the only parameters required are the function, the return code and the pool name.
Use this function only when there is a special reason to terminate the connection (for example, to allow the server to be shut down).
This operation can include a conditional test on the current value of the named counter, using the compare_min and compare_max parameters.
The server returns the new current value, minimum value, and maximum value if you specify these fields on the parameter list and the request is successful.
If any option parameter or update_value parameter was specified on an NC_ASSIGN request which failed because the named counter was at its limit, the same parameter values must also be specified on the NC_REWIND request, so that it can check whether the original NC_ASSIGN would still fail. The NC_REWIND request is suppressed with return code 102 (NC_COUNTER_NOT_AT_LIMIT) whenever the corresponding NC_ASSIGN request would succeed.
If the NC_WRAP option is in effect, or the update_value parameter is zero, NC_REWIND is suppressed because NC_ASSIGN always succeeds with these conditions. See the counter_options parameter for information about the NC_WRAP option.
You specify the new value on the update_value parameter. If you don't specify a new value, the named counter remains unchanged.
You can specify a valid counter_options override parameter (or a null address) with this function, but counter options have no effect. Specify either a null address or NC_NONE as the counter_options parameter.
Each return code has a corresponding symbolic constant. See Return codes for details of these.
This parameter is optional. If you omit the pool selection parameter, a string of 8 blank X'40') characters is assumed.
The acceptable characters for pool_selector are A through Z, 0 through 9, $ @ # and _ (underscore) but the first character cannot be numeric or an underscore. The parameter should be padded to fill 8 characters with trailing spaces as necessary. The parameter can be all spaces to use the default pool for the current region, provided this is mapped by the options table to a valid non-blank named counter name).
Depending on the named counter options table in use, you can use the pool selector parameter either as an actual pool name, or as a logical pool name that is mapped to a real pool name through the options table. The default options table assumes:
See Named counter options table for information about the pool selection parameter in the DFHNCOPT options table.
The acceptable characters for the name are A through Z, 0 through 9, $ @ # and _ (underscore) but the first character cannot be numeric or an underscore. The parameter should be padded to fill 16 characters with trailing spaces as necessary.
You are recommended to use names that have a common prefix of up to 8 bytes to avoid conflicts with other applications. Any named counters used internally by CICS have names starting with DFH.
For the NC_BROWSE_FIRST and NC_BROWSE_NEXT functions, the actual name is returned in this field, which must be a variable for this purpose. For all other functions, this can be a constant.
If no value parameters are used on the call, you can either omit all the trailing unused parameters completely, including the value length, or specify value_length as 0.
When input values are shorter than 8 bytes, they are extended with high-order zero bytes to the full 8 bytes used internally. When output values are returned in a short value field, the specified number of low-order bytes are returned, ignoring any higher-order bytes. However, if the value is too large to be represented correctly within the field, then a warning return code might be set, as described in Checking for result overflow.
For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. The default value is low values (binary zeroes). The value can either be within the range specified by the following minimum and maximum values, or it can be one greater than the maximum value, in which case the counter has to be reset using the NC_REWIND function before it is used. No sign check is made for this field, but a value that has the sign bit set would normally be rejected by the server as being inconsistent with the counter limits. For a counter that has a range consisting of all signed numbers, the counter at limit value does have the sign bit set, and this can be used as a valid input value.
For all other counter functions, this parameter is an output (receiver) field and must be defined as a variable.
For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. The default value is low values (binary zeroes).
For all other functions, this parameter is an output (receiver) field and must be defined as a variable.
For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. If you specify a non-zero value_length parameter but omit maximum_value, then maximum_value defaults to high values (or, for signed variables, the largest positive value) for the specified length. If the value_length parameter is omitted or is specified as zero, then maximum_value defaults to eight bytes of high values. However, if the minimum value is all low values and the maximum value is eight bytes of high values, the maximum value is reduced to allow some reserved values to be available to the server for internal use.
For all other functions, this parameter is an output (receiver) field and must be defined as a variable.
For example, if a request specifies an update value of 15 when the current number is 199 990 and the counter maximum number is defined as 199 999, the NC_REQUEST fails because the increment would cause the current number to exceed 200 000.
The options specified on NC_CREATE are stored with the named counter and are used as the defaults for other named counter functions. You can override the options on NC_ASSIGN, NC_REWIND or NC_UPDATE requests. If you don't want to specify counter_options on a DFHNCTR call, specify the symbolic constant NC_NONE (equal to zero) as the input parameter (or specify a null address).
For the NC_CREATE, NC_ASSIGN, NC_REWIND, and NC_UPDATE functions, this parameter is an input field.
For the NC_DELETE, NC_INQUIRE, and NC_BROWSE functions, this parameter is an output field, which returns the options specified on NC_CREATE.
For NC_UPDATE, this is the new current value for the named counter.
If you omit this parameter by specifying a null address, the server does not perform the comparison.
If you specify high values (X'FF') for this parameter, the server does not perform the comparison. You must specify (X'FF') in all the bytes specified by the value_length parameter.
If the compare_max value is less than the compare_min value, the valid range is assumed to wrap round, in which case the current value is considered to be in range if it satisfies either comparison, otherwise both comparisons must be satisfied.
The call interface checks for results which do not fit into the specified size of result field, or which overflow into the sign bit when signed variables are used.
If a result field (counter_value, minimum_value or maximum_value) has been defined as a signed variable by specifying value_length as a negative value, the call interface checks for results that overflow into the sign bit. In this case, the operation completes normally but the return code NC_RESULT_OVERFLOW is set. As a special case, a result value for a counter which is at its limit value is not checked for this form of overflow, to avoid setting the return code unnecessarily. This means that if a query is made to a counter which is at its limit, and whose maximum value is the maximum positive value, a negative number might be returned as the current counter value without causing this return code.
If a result field (counter_value, minimum_value or maximum_value) is too short to contain the full non-zero part of the result, the operation completes normally, but one of the following return codes is set:
If a 4-byte unsigned counter that has a maximum of high values has reached its limit value, the return code NC_RESULT_CARRY is set, and the counter value is zero.
If you omit an optional parameter on a DFHNCTR call, ensure that the parameter list is built with a null address for the missing parameter. The example that follows illustrates how to issue, from a COBOL program, an NC_CREATE request with some parameters set to null addresses.
DFHNCTR call with null addresses for omitted parameters: In this example, the parameters used on the call are defined in the WORKING-STORAGE SECTION, as follows:
Call parameter | COBOL variable | Field definition |
---|---|---|
function | 01 FUNCTION | PIC S9(8) COMP VALUE +1. |
return_code | 01 NC-RETURN-CODE. | PIC S9(8) COMP VALUE +0. |
pool_selector | 01 NC-POOL-SELECTOR | PIC X(8). |
counter_name | 01 NC-COUNTER-NAME | PIC X(16). |
value_length | 01 NC_VALUE-LENGTH | PIC S9(8) COMP VALUE +4. |
current_value | 01 NC-CURRENT-VALUE | PIC S9(8) VALUE +0. |
minimum_value | 01 NC-MIN-VALUE | PIC S9(8) VALUE +0. |
maximum_value | 01 NC-MAX-VALUE | PIC S9(8) VALUE -1. |
counter_options | 01 NC-OPTIONS | PIC S9(8) COMP VALUE +0. |
update_value | 01 NC-UPDATE-VALUE | PIC S9(8) VALUE +1. |
compare_min | 01 NC-COMP-MIN | PIC S9(8) VALUE +0. |
compare_max | 01 NC-COMP-MAX | PIC S9(8) VALUE +0. |
The variable used for the null address is defined in the LINKAGE SECTION, as follows:
Using the data names specified in the WORKING-STORAGE SECTION as described above, and the NULL-PTR name as described in the LINKAGE SECTION, the following illustrates a call to a named counter server where value_length, current_value, minimum_value and counter_options are the only optional parameters specified. The others are allowed to default, or, in the case of trailing optional parameters, omitted altogether.
NAMED-COUNTER SECTION.
*
SET ADDRESS OF NULL-PTR TO NULLS.
*
MOVE 1 TO FUNCTION.
MOVE 100 TO NC-MIN-VALUE NC-CURRENT-VALUE.
MOVE NC-WRAP TO NC-OPTIONS.
MOVE "DFHNC001" TO NC-POOL-SELECTOR.
MOVE "CUSTOMER_NUMBER" TO NC-COUNTER-NAME.
CALL 'DFHNCTR' USING FUNCTION NC-RETURN-CODE NC-POOL-SELECTOR
NC-COUNTER-NAME NC-VALUE-LENGTH NC-CURRENT-VALUE
NC-MIN-VALUE NULL-PTR NC-OPTIONS.
There are three warning return codes (1-3) for the named counter call interface, which indicate result overflows for a request that otherwise completed normally. If more than one warning return code applies for the same request, the highest applicable warning return code is set.
The remaining return codes are divided into ranges (100, 200, 300, and 400®) according to their severity. Each range of non-zero return codes begins with a dummy return code that describes the return code category, to make it easy to check for values in each range using a symbolic name.
In the list that follows, the numeric return code is followed by its symbolic name.
The counter value specified on the current_value parameter for the NC_CREATE function, or the update_value for the NC_UPDATE function, cannot be less than the specified minimum value, and cannot be more than (maximum value + 1).
The increment value specified in the update_value parameter for the NC_ASSIGN or NC_REWIND function cannot be greater than the total range of the counter ( (maximum value - minimum value) + 1).