Get the next number from the named counter.

GET COUNTER
>>-GET--COUNTER(name)--+------------+--VALUE(data-area)--------->
'-POOL(name)-'
>--+----------------------------------+--+------+--------------->
'-INCREMENT(data-value)-+--------+-' '-WRAP-'
'-REDUCE-'
>--+------------------------+--+------------------------+------><
'-COMPAREMIN(data-value)-' '-COMPAREMAX(data-value)-'
Conditions: INVREQ, LENGERR, SUPPRESSED

GET DCOUNTER
>>-GET--DCOUNTER(name)--+------------+--VALUE(data-area)-------->
'-POOL(name)-'
>--+---------------------------------+--+------+---------------->
'-INCREMENT(data-area)-+--------+-' '-WRAP-'
'-REDUCE-'
>--+-----------------------+--+-----------------------+--------><
'-COMPAREMIN(data-area)-' '-COMPAREMAX(data-area)-'
Conditions: INVREQ, SUPPRESSED
Description
These counter commands obtain, from
the named counter server, the current number from the named counter in the
specifed pool, and updates the current number by the default, or by a specified,
increment. The default increment is 1. COUNTER operates with fullword signed binary
values, and DCOUNTER operates with doubleword unsigned binary values.
You
can use the COMPAREMAX and COMPAREMIN options to obtain a number only if it
falls within a specified range, or is above or below a specified value.
For
information about specifying fullword and doubleword variables on these named
counter commands, see CICS command argument values.
Options
- COMPAREMAX(data-value)
- specifies, as a fullword signed binary
value (doubleword unsigned binary value for DCOUNTER), a value to be compared
with the named counter's current value, and makes the result of the GET command
conditional on the comparison:
- If the current value to be assigned is less than, or equal to, the value
specified on the COMPAREMAX parameter, the current value is returned, with
response normal
- If the current value is greater than the specified value, CICS returns an
exception condition.
The value you specify on the COMPAREMAX parameter can be less than
the value on the COMPAREMIN parameter, in which case the current value is
considered to be in range if it satisfies the COMPAREMIN or the COMPAREMAX
comparison. In the normal case where the COMPAREMIN value is less than the
COMPAREMAX value, the current value must satisfy both comparisons (that is,
it must be greater than, or equal to, the COMPAREMIN value, and be
less than, or equal to the COMPAREMAX value).
- COMPAREMIN(data-value)
- specifies, as a fullword signed binary
value (doubleword unsigned binary value for DCOUNTER), a value to be compared
with the named counter's current value, and makes the result of the GET command
conditional on the comparison:
- If the current value to be assigned is equal to, or greater than, the
value specified on the COMPAREMIN parameter, the CICS returns the current
value, with response normal
- If the current value is less than the specified value, CICS returns an
exception condition.
Note: The value you specify on the COMPAREMIN parameter can be greater
than the value on the COMPAREMAX parameter. See the COMPAREMAX parameter for
the effect of this.
- COUNTER(name)
- specifies
the name of the fullword counter from which the current number is to be assigned
to the application program. The name can be up to 16 alphanumeric characters.
If name is a variable that contains a name that
is less than 16 characters, the name must be padded with trailing blanks.
- DCOUNTER(name)
- specifies
the name of the doubleword counter from which the current number is to be
assigned to the application program. The name can be up to 16 alphanumeric
characters. If name is a variable that contains
a name that is less than 16 characters, the name must be padded with trailing
blanks.
- INCREMENT(data-value)
- specifies, as a fullword signed binary
value (doubleword unsigned binary value for DCOUNTER), an increment by which
the named counter is to be updated, instead of the default value of 1. The
counter is incremented after the current number has been assigned.
Specifying
an increment to override the default increment of 1 enables the application
program to obtain exclusive use of more than 1 number for each call. For example,
if you want to obtain exclusive use of a block of 20 numbers, specify INCREMENT(20).
See
the description of the REDUCE and WRAP options for the effect of specifying
an increment when the counter is at, or near, the maximum value.
- POOL(poolname)
- specifies an 8-character string to
be used as a pool selection parameter to select the pool in which the named
counter resides. The string can be a logical pool name, or the actual pool
name.
Valid characters for the pool selector string are A through Z,
0 through 9, $ @ # and _ (underscore). If name is
a variable that contains a name that is less than 8 characters, the name must
be padded with trailing blanks.
This parameter is optional. If you
omit the name of the pool, a pool selector value of 8 blanks is assumed.
If
there is no matching entry in the DFHNCOPT options table, CICS uses the name
specified on the NCPLDFT system initialization parameter, which specifies
the default named counter pool.
For information about generating a
named counter options table using the DFHNCO macro, see the CICS Application Programming Guide.
- REDUCE
- specifies that you want the named
counter server to reduce the specified increment if the range of numbers remaining
to be assigned is too small.
The range of numbers is too small if the
difference between the current value and the maximum value plus 1 is less
then the specified increment, in which case:
- If you specify REDUCE, the INCREMENT parameter value is reduced and the
GET request succeeds. In this case, the GET command has reserved a range
of numbers less than that specified by the INCREMENT parameter, and the current
value is updated to the maximum value plus 1.
- If you do not specify the REDUCE option, the result depends on whether
or not you specify the WRAP option. If the REDUCE and WRAP options are both
omitted, the request fails with the counter-at-limit error (SUPPRESSED, RESP2=101),
but the current number is not changed. For example, if a request specifies
an INCREMENT parameter value of 15 when the current number is 199 990 and
the counter maximum number is defined as 199 999, the GET command fails because
updating the counter by the specified increment would cause the current number
to exceed 200 000.
- VALUE(data-area)
- specifies the data area (fullword
signed data-area for COUNTER, and doubleword unsigned data-area for DCOUNTER)
into which CICS returns the current number, obtained from the named counter
server for the specified pool.
- WRAP
- specifies that you want the named
counter server automatically to perform a rewind of the named counter if it
is in a counter-at-limit condition, avoiding the error condition that would
otherwise result.
If it finds that the named counter is in the counter-at-limit
condition, or that the increment specified without the REDUCE option would
cause the condition, the server:
- Resets the current value of the named counter equal to the minimum value
defined for the counter
- Returns the new current value to the application program, with DFHRESP(NORMAL)
- Updates the current value by the required increment ready for the next
request.
If you omit the WRAP option, and the counter-at-limit condition
has been reached, CICS returns SUPPRESSED, RESP2=101.
Conditions
- INVREQ
- RESP2
values:
- 201
- Named counter not found.
- 301
- The server has reported an error code that is not understood by the named
counter interface. Generally, this is not possible unless the interface load
module, DFHNCIF, is at a lower maintenance or release level than the server
itself.
- 303
- An unexpected error, such as structure failure or loss of connectivity,
has occurred on a macro used to access the coupling facility. Further information
can be found in message DFHNC0441 in the CICS job log.
- 304
- The pool selection parameter specified in the program cannot be resolved
to a valid server name using the current options table.
- 305
- The interface is unable to establish a connection to the server for the
selected named counter pool. Further information can be found in an AXM services
message (AXMSCnnnn) in the CICS job log.
- 306
- An abend occurred during server processing of a request. Further information
can be found in a message in the CICS job log and the server job log.
- 308
- The DFHNCOPT options table module, required for resolving a pool name,
could not be loaded.
- 309
- During processing of the options table, the named counter interface encountered
an unknown entry format. Either the options table is not correctly generated,
or the DFHNCIF interface load module is not at the same release level as the
options table.
- 310
- An options table entry matching the given pool name specified a user exit
program, but the user exit program is not link-edited with the options table
and cannot be loaded.
- 311
- A response from the named counter server to the client region interface
module, DFHNCIF, indicates that a system-managed rebuild is in progress but
the EXEC CICS interface does not recognize the condition. This means that
the CICS region is at CICS TS 2.1 or earlier.
- 403
- The POOL parameter contains invalid characters or embedded spaces.
- 404
- The COUNTER parameter contains invalid characters or embedded spaces.
- 406
- The INCREMENT value is invalid. The value specified cannot be greater
than the total range of the counter ((maximum value - minimum value) + 1).
Default action: terminate the task abnormally.
- LENGERR
- LENGERR occurs for COUNTER commands only and does not apply to DCOUNTER
requests. It occurs when a counter that was defined by a DCOUNTER command
or by the CALL interface has a value which is too large to be correctly represented
as a fullword signed binary value (that is, the counter uses more than 31
bits).
In each of the three cases of overflow, the named counter server
completes the operation, and returns a warning response to CICS, which CICS
returns to your application program as the RESP2 value. The data area contains
the low-order 32 bits returned from the named counter server, which could
be a negative number.
RESP2 values:
- 001
- The current value that the server has attempted to return in the VALUE
data area has overflowed into the high-order (sign) bit (that is, the value
returned is negative).
- 002
- The current value is too large for a fullword data area by only 1 bit.
In this case, the overflow value is exactly 1.
- 003
- The current value is too large for a fullword data area by a value greater
than 1.
Default action: terminate the task abnormally.
- SUPPRESSED
- RESP2
values:
- 101
- The maximum value for the named counter has already been assigned and
the counter is in the 'counter-at-limit' condition. No more counter numbers
can be assigned until the named counter has been reset, either by a REWIND
command, or by specifying the WRAP option on the GET command.
- 103
- The current value of the named counter is:
- not within the range specified by the COMPAREMAX and COMPAREMIN parameters,
when both are specified
- greater than the COMPAREMAX parameter or less than the COMPAREMIN parameter,
when only one option is specified.
Default action: terminate the task abnormally.