Get the next number from the named counter in the specified
pool. Use COUNTER for fullword signed counters and DCOUNTER for doubleword
unsigned counters.
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
This command is threadsafe.
GET DCOUNTER
>>-GET--DCOUNTER(name)--+------------+--VALUE(data-area)-------->
'-POOL(name)-'
>--+---------------------------------+--+------+---------------->
'-INCREMENT(data-area)-+--------+-' '-WRAP-'
'-REDUCE-'
>--+-----------------------+--+-----------------------+--------><
'-COMPAREMIN(data-area)-' '-COMPAREMAX(data-area)-'
Conditions: INVREQ, LENGERR, SUPPRESSED
This command is threadsafe.
Description
These counter commands obtain,
from the named counter server, the current number from the named counter
in the specified pool, and updates the current number by the default,
or by a specified, increment. The default increment is 1.
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 (or doubleword unsigned
binary value for DCOUNTER), a value to compare with the current value
of the named counter, and makes the result of the GET command conditional
on the comparison:
- If the current value to assign is less than, or equal to, the
value specified on the COMPAREMAX parameter, the current value is
returned, and the response is normal.
- If the current value is greater than the specified value, CICS returns
an exception condition.
Normally, the COMPAREMAX value is greater than the COMPAREMIN
value and the current value must satisfy both comparisons (that is,
it must be between the two values or equal to one of them).
You
can specify a COMPAREMAX value that is less than the COMPAREMIN value.
In this situation, the current value is considered to be in range
if it satisfies either the COMPAREMIN or the COMPAREMAX comparison.
- COMPAREMIN(data-value)
- Specifies, as a fullword signed binary value (or doubleword unsigned
binary value for DCOUNTER), a value to compare with the current value
of the named counter, and makes the result of the GET command conditional
on the comparison:
- If the current value to assign is equal to, or greater than, the
value specified on the COMPAREMIN parameter, the current value is
returned, and the response is normal.
- If the current value is less than the specified value, CICS returns
an exception condition.
Note: You can specify a COMPAREMIN value that is greater than
the COMPAREMAX value. 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 (or 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 one number for each call.
For example, 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 use 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 Named counter servers .
- 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 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 to rewind the
named counter automatically if it is in a counter-at-limit condition,
thus avoiding the error condition that would otherwise result.
If
the named counter is in the counter-at-limit condition, or the increment
specified without the REDUCE option would cause the counter-at-limit
condition, the counter server acts as follows:
- It resets the current value of the named counter equal to the
minimum value defined for the counter.
- It returns the new current value to the application program, with
DFHRESP(NORMAL).
- It pdates the current value by the required increment ready for
the next request.
If you omit the WRAP option, and the counter-at-limit
condition is reached, CICS returns SUPPRESSED, RESP2=101.
Conditions
- 16 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 is in message DFHNC0441 in the application 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 cannot establish a connection to the server for
the selected named counter pool. Further information is in an AXM
services message (AXMSCnnnn) in the application
job log.
- 306
- An abend occurred during server processing of a request. Further
information is in a message in the application job log and the server
job log.
- 308
- The DFHNCOPT options table module, required to resolve a pool
name, cannot 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 that matches 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.
- 22 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 that 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.
- 72 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
- One of the following:
- The current value of the named counter is not within the range
specified by the COMPAREMAX and COMPAREMIN parameters,
when both are specified
- The current value of the named counter is greater than the COMPAREMAX parameter
or less than the COMPAREMIN parameter, when only
one option is specified.
Default action: terminate the task abnormally.