Return codes

The remaining return codes are divided into ranges (100, 200, 300, and 400) according to their severity. Each range of non-zero return codes begins with a dummy return code that describes the return code category, to make it easy to check for values in each range using a symbolic name.

In the following list, the numeric return code is followed by its symbolic name.

0 (NC_OK)

The request completed normally.

1 (NC_RESULT_OVERFLOW)

The result value overflowed into the sign bit.

2 (NC_RESULT_CARRY)

The result value overflowed, and the leading part was exactly equal to 1.

3 (NC_RESULT_TRUNCATED)

The result value overflowed, and the leading part was greater than 1.

100 (NC_COND)

Return codes in this range indicate that a conditional function did not succeed because the condition was not satisfied:

101 (NC_COUNTER_AT_LIMIT)

An NC_ASSIGN function is rejected because the previous request for this named counter obtained the maximum value and the counter is now at its limit. New counter values cannot be assigned until an NC_REWIND function call is issued to reset the counter.

102 (NC_COUNTER_NOT_AT_LIMIT)

An NC_REWIND FUNCTION is rejected because the named counter is not at its limit value. This is most likely to occur when another task has already succeeded in resetting the counter with an NC_REWIND.

103 (NC_COUNTER_OUT_OF_RANGE)

The current value of the named counter is not within the range specified on the compare_min and compare_max parameters.

200 (NC_EXCEPTION)

Return codes in this range indicate an exception condition that an application program can handle:

201 (NC_COUNTER_NOT_FOUND)

The named counter cannot be found.

202 (NC_DUPLICATE_COUNTER_NAME)

An NC_CREATE function is rejected because a named counter with the specified name already exists.

203 (NC_SERVER_NOT_CONNECTED)

An NC_FINISH function is rejected because no active connection exists for the selected pool.

300 (NC_ENVIRONMENT_ERROR)

Return codes in this range indicate an environment error. These are serious errors, normally caused by some external factor, that a program might not to be able to handle.

301 (NC_UNKNOWN_ERROR)

The server has reported an error code that is not understood by the 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 (NC_NO_SPACE_IN_POOL)

A new counter cannot be created because there is insufficient space in the named counter pool.

303 (NC_CF_ACCESS_ERROR)

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 application job log.

304 (NC_NO_SERVER_SELECTED)

The pool selection parameter specified in the program cannot be resolved to a valid server name using the current options table.

305 (NC_SERVER_NOT_AVAILABLE)

The interface cannot establish a connection to the server for the appropriate named counter pool. Further information can be found in an AXM services message in the application job log.

306 (NC_SERVER_REQUEST_FAILED)

An abend occurred during server processing of a request. Further information can be found in a message in the aplication job log and the server job log.

307 (NC_NAME_TOKEN_ERROR)

An IEANT xx name/token service call in the named counter interface module gave an unexpected return code.

308 (NC_OPTION_TABLE_NOT_FOUND)

The DFHNCOPT options table module, required for resolving a pool name, cannot be loaded.

309 (NC_OPTION_TABLE_INVALID)

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 (NC_USER_EXIT_NOT_FOUND)

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 (NC_STRUCTURE_UNAVAILABLE)

The named counter server list structure is temporarily unavailable. For example, one reason for this situation is that a z/OS® system-managed rebuild is in progress.

Note: The EXEC CICS interface to the named counter uses the CALL interface internally, but it hides this return code from the application program by waiting for one second and retrying the request. The EXEC CICS interface continues this wait and retries until it succeeds, with the result that the application program has only a time delay, not an error response. You can use the same technique in your application programs that use the CALL interface.

400 (NC_PARAMETER_ERROR)

Return codes in this range indicate a parameter error, generally the result of a coding error in the calling program.

401 (NC_INVALID_PARAMETER_LIST)

The parameter list is invalid for one of the following reasons:

• Too few parameters are specified (less than four, or less than three for the NC_FINISH function)
• Too many parameters are given (more than eight)
• A parameter address is zero
• The end-of-list marker is missing.

402 (NC_INVALID_FUNCTION)

The function code parameter is not in the supported range.

403 (NC_INVALID_POOL_NAME )

The pool selection parameter contains characters that are not allowed, or embedded spaces.

404 (NC_INVALID_COUNTER_NAME)

The counter_name parameter contains characters that are not allowed, or embedded spaces.

405 (NC_INVALID_VALUE_LENGTH)

The value length parameter is not in the range 0 to 8.

406 (NC_INVALID_COUNTER_VALUE)

The specified counter value or increment value is inconsistent with the minimum and maximum limits for the counter.

The counter value specified on the current_value parameter for the NC_CREATE function, or the update_value for the NC_UPDATE function, cannot be less than the specified minimum value, and cannot be more than (maximum value + 1).

The increment value specified in the update_value parameter for the NC_ASSIGN or NC_REWIND function cannot be greater than the total range of the counter ( (maximum value - minimum value) + 1).

407 (NC_INVALID_COUNTER_LIMIT)

The maximum value is less than the minimum value.

408 (NC_INVALID_OPTIONS)

The value of the counter_options parameter is invalid. It is either a value that does not correspond to any defined option, or it is a value that represents some mutually exclusive options.