Query a named counter. Use COUNTER for fullword signed
counters and DCOUNTER for doubleword unsigned counters.
QUERY COUNTER
>>-QUERY--COUNTER(name)--+------------+--+------------------+--->
'-POOL(name)-' '-VALUE(data-area)-'
>--+--------------------+--+--------------------+--------------><
'-MINIMUM(data-area)-' '-MAXIMUM(data-area)-'
Conditions: INVREQ, LENGERR
This command is threadsafe.
QUERY DCOUNTER
>>-QUERY--DCOUNTER(name)--+------------+------------------------>
'-POOL(name)-'
>--+------------------+--+--------------------+----------------->
'-VALUE(data-area)-' '-MINIMUM(data-area)-'
>--+--------------------+--------------------------------------><
'-MAXIMUM(data-area)-'
Conditions: INVREQ
This command is threadsafe.
Description
These counter commands return
the current, maximum, and minimum values for the named counter.
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 Named counter servers .
- 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
- 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.
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 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.