Update the current value of a named counter. Use COUNTER
for fullword signed counters and DCOUNTER for doubleword unsigned
counters.
UPDATE COUNTER
>>-UPDATE--COUNTER(name)--+------------+--VALUE(data-value)----->
'-POOL(name)-'
>--+------------------------+--+------------------------+------><
'-COMPAREMIN(data-value)-' '-COMPAREMAX(data-value)-'
Conditions: INVREQ, SUPPRESSED
This command is threadsafe.
UPDATE DCOUNTER
>>-UPDATE--DCOUNTER(name)--+------------+--VALUE(data-area)----->
'-POOL(name)-'
>--+-----------------------+--+-----------------------+--------><
'-COMPAREMIN(data-area)-' '-COMPAREMAX(data-area)-'
Conditions: INVREQ, SUPPRESSED
This command is threadsafe.
Description
These counter commands set a
new current value for the named counter.
You can use the COMPAREMAX
and COMPAREMIN options to set a new current value 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 UPDATE command conditional
on the comparison:
- If the current value to assign is less than, or equal to, the
value specified for the COMPAREMAX parameter, the current value is
reset 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 UPDATE command conditional
on the comparison:
- If the current value to assign is equal to, or greater than, the
value specified for the COMPAREMIN parameter, the current value is
reset 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 named counter for which the current
number is to be reset to the value specified on the value parameter.
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 named counter for which the current
number is to be reset to the value specified on the value parameter.
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.
- 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-value)
- Specifies the new number to set as the current value for the named
counter, using a fullword signed binary value for COUNTER and a doubleword
unsigned value for DCOUNTER.
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 VALUE parameter is invalid. You cannot set the current value
to less than the minimum value, or greater than the maximum value
plus 1.
Default action: terminate the task abnormally.
- 72 SUPPRESSED
- RESP2 values:
- 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.