Define a named counter.

DEFINE COUNTER
>>-DEFINE--COUNTER(name)--+------------+------------------------>
'-POOL(name)-'
>--+--------------------------------------------+--------------->
'-VALUE(data-value)--+---------------------+-'
'-MINIMUM(data-value)-'
>--+---------------------+-------------------------------------><
'-MAXIMUM(data-value)-'
Conditions: INVREQ

DEFINE DCOUNTER
>>-DEFINE--DCOUNTER(name)--+------------+----------------------->
'-POOL(name)-'
>--+--------------------------------------------+--------------->
'-VALUE(data-value)--+---------------------+-'
'-MINIMUM(data-value)-'
>--+--------------------+--------------------------------------><
'-MAXIMUM(data-area)-'
Conditions: INVREQ
Description
These counter commands create a new
named counter in a named counter pool in the coupling facility.
DEFINE
COUNTER creates counters that are handled as fullword signed binary
values, and DEFINE DCOUNTER creates counters that are handled as doubleword unsigned binary
values.
Note: Although the CICS® API allows you to operate with either
fullword (signed) or doubleword (unsigned) binary values, the named counter
server stores all values as doubleword unsigned values. This can give
rise to overflow conditions if, for example, you define a counter with the
DCOUNTER command and try to access it using the COUNTER command. You should
always access a named counter using commands from the same command set that
you used to define the 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 named counter to be created. All value fields
for this counter are handled as fullword signed binary values. 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 named counter to be created. All value fields
for this counter are handled as doubleword unsigned binary values. 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-value)
- specifies the maximum number for
the named counter, using a fullword signed binary value for COUNTER and a
doubleword unsigned value for DCOUNTER. This is the maximum number that can
be assigned on a GET command, after which the counter must be reset by a REWIND
command.
If you omit the MAXIMUM parameter, the named counter is defined
with a default maximum of high-values (X'7FFFFFFF' for the signed
fullword case, or a doubleword filled with X'FF').
- MINIMUM(data-value)
- specifies the minimum number for
the named counter, using a fullword signed binary value for COUNTER and a
doubleword unsigned value for DCOUNTER. This is the value to which a named
counter is reset as a result of a REWIND command.
If you omit the MINIMUM
parameter, the named counter is defined with a default minimum of low-values
(a fullword or doubleword filled with X'00').
- POOL(name)
- specifies an 8-character string to
be used as a pool selection parameter to select the pool in which the named
counter is to be created. 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.
- VALUE(data-value)
- specifies the initial number at which
the new named counter is to start, using a fullword signed binary value for
COUNTER and a doubleword unsigned value for DCOUNTER.
You can specify a
number that is equal to, or greater than, the minimum value, up to the maximum
value plus 1. If you specify an initial number that is equal to the maximum
value plus 1, the counter is created with the counter-at-limit condition set
and it cannot be used until it is rewound.
If you omit both the VALUE
and MINIMUM parameters, the named counter is created with an initial value
of zero. If you omit VALUE but specify a MINIMUM , the translator issues an
error; the VALUE parameter is required if you specify the MINIMUM parameter.
Conditions
- INVREQ
- RESP2 values:
- 202
- Duplicate counter name. A named counter of this name already exists.
- 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.
- 302
- The server cannot create the new named counter because there is not enough
space in the named counter pool.
- 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 system
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 VALUE parameter is invalid. Initial values cannot be less than the
minimum value, and cannot be greater than the maximum value plus 1.
- 407
- The MINIMUM or MAXIMUM parameter is invalid. Either the MAXIMUM parameter
specifies a value that is less than the minimum value, or (for COUNTER only)
one of the parameters specifies a negative value.
Default action: terminate the task abnormally.