Create a named counter in a named counter pool in the coupling
facility. Use COUNTER to create counters that are handled as fullword
signed counters and DCOUNTER to create counters that are handled as
doubleword unsigned counters.
DEFINE COUNTER
>>-DEFINE--COUNTER(name)--+------------+------------------------>
'-POOL(name)-'
>--+--------------------------------------------+--------------->
'-VALUE(data-value)--+---------------------+-'
'-MINIMUM(data-value)-'
>--+---------------------+-------------------------------------><
'-MAXIMUM(data-value)-'
Conditions: INVREQ
This command is threadsafe.
DEFINE DCOUNTER
>>-DEFINE--DCOUNTER(name)--+------------+----------------------->
'-POOL(name)-'
>--+--------------------------------------------+--------------->
'-VALUE(data-value)--+---------------------+-'
'-MINIMUM(data-value)-'
>--+--------------------+--------------------------------------><
'-MAXIMUM(data-area)-'
Conditions: INVREQ
This command is threadsafe.
Description
These counter commands create
a new named counter in a named counter pool in the coupling facility.
Although
you can use the CICS® API to operate with either fullword (signed)
or doubleword (unsigned) binary values, the named counter server stores
all values as doubleword unsigned values. Overflow conditions might
occur if, for example, you define a counter with the DCOUNTER command
and try to access it using the COUNTER command. 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-byte counter name field. The name should start with a letter and may contain letters, digits or underscore characters, padded to 16 bytes with trailing spaces. (Letters must be upper case. The national use symbols
£
, #
and @
are allowed wherever letters are allowed). It is recommended that the name should start with a systematic prefix unique to the application. Any counters used by CICS itself will use the prefix DFH
.
- DCOUNTER(name)
- Specifies the 16-byte counter name field. The name should start with a letter and may contain letters, digits or underscore characters, padded to 16 bytes with trailing spaces. (Letters must be upper case. The national use symbols
£
, #
and @
are allowed wherever letters are allowed). It is recommended that the name should start with a systematic prefix unique to the application. Any counters used by CICS itself will use the prefix DFH
.
- 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 specify the MINIMUM parameter,
you must also specify a VALUE parameter.
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 use 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 Named counter servers .
- 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
- 16 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 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 VALUE parameter is invalid. You cannot set the current value
to less than the minimum value, or 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.