DEFINE COUNTER and DEFINE DCOUNTER

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 name of the fullword counter name field. The name can contain upper case letters, digits or underscore characters including the symbols $, #, and @, padded to 16 bytes with trailing spaces. Note that the name cannot start with a number or an underscore. It is recommended that the name should start with a systematic prefix unique to the application.  Any counters used by CICS itself use the prefix DFH. 

DCOUNTER(name)

Specifies the 16-byte name of the doubleword counter name field. The name can contain upper case letters, digits or underscore characters including the symbols $, #, and @, padded to 16 bytes with trailing spaces. Note that the name cannot start with a number or an underscore. It is recommended that the name should start with a systematic prefix unique to the application. Any counters used by CICS itself 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').

NOSUSPEND

Specifies an immediate return to the application program during a coupling facility structure rebuild. If you omit the NOSUSPEND parameter, the request is retried until it is successful. If you specify NOSUSPEND, the request fails immediately, and CICS returns BUSY, RESP2=500.

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

128 BUSY

RESP2 values:

500

The NOSUSPEND option was specified on the command, and the coupling facility structure is not currently available during a rebuild.

Default action: terminate the task abnormally.

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.