Query a named counter.

QUERY COUNTER
>>-QUERY--COUNTER(name)--+------------+--+------------------+--->
'-POOL(name)-' '-VALUE(data-area)-'
>--+--------------------+--+--------------------+--------------><
'-MINIMUM(data-area)-' '-MAXIMUM(data-area)-'
Conditions: INVREQ, LENGERR

QUERY DCOUNTER
>>-QUERY--DCOUNTER(name)--+------------+------------------------>
'-POOL(name)-'
>--+------------------+--+--------------------+----------------->
'-VALUE(data-area)-' '-MINIMUM(data-area)-'
>--+--------------------+--------------------------------------><
'-MAXIMUM(data-area)-'
Conditions: INVREQ
Description
These counter commands return the current,
maximum, and minimum values for the named counter. COUNTER operates on fullword
named counters and DCOUNTER operates on doubleword named counters.
For
information about specifying fullword and doubleword variables on these named
counter commands, see CICS command argument values.
Options
- COUNTER(name)
- specifies
the 16-character name of the fullword counter being queried. Valid characters
for names are A through Z, 0 through 9, $ @ # and _ (underscore). 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 16-character name of the doubleword counter being queried. Valid characters
for names are A through Z, 0 through 9, $ @ # and _ (underscore). If name is
a variable that contains a name that is less than 16 characters, the name
must be padded with trailing blanks.
- MAXIMUM(data-area)
- specifies the data area in which CICS is
to return the maximum number for the named counter. CICS returns a fullword
signed binary value for the COUNTER command and a doubleword unsigned binary
value for the DCOUNTER command
- MINIMUM(data-area)
- specifies the data area in which
CICS is to return the minimum number for the named counter. CICS returns a
fullword signed binary value for the COUNTER command and a doubleword unsigned
binary value for the DCOUNTER command
- POOL(poolname)
- specifies the name of the pool in
which the named counter resides.
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.
- VALUE(data-area)
- specifies the data area in which
CICS is to return the current value for the named counter. CICS returns a
fullword signed binary value for the COUNTER command and a doubleword unsigned
binary value for the DCOUNTER command.
Note that, if the named counter
is in the counter-at-limit condition, CICS does not return an exception condition.
In this case, CICS returns a normal response with a value that is 1 greater
than the maximum value specified or assumed for the counter, using unsigned
addition. If the maximum value is the largest positive number that can be
held in a signed fullword, the value returned by QUERY COUNTER for a counter-at-limit
condition is the largest negative number.
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.
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 one of the
data areas has overflowed into the high-order (sign) bit (that is, the value
returned is negative).
Note: LENGERR with RESP2=001 cannot occur for a named
counter that is in the counter-at-limit condition. If the counter-at-limit
condition has been reached, the value (which could be negative) is returned
with a normal response.
- 002
- A value is too large for a fullword data area by only 1 bit. In this case,
the overflow value is exactly 1.
- 003
- A value is too large for a fullword data area by a value greater than
1.
Default action: terminate the task abnormally.