Using the named counter CALL interface

In addition to the CICS® named counter API, CICS provides a call interface that you can use from a batch application to access the same named counters. This could be important where you have an application that uses both CICS and batch programs, and both need to access the same named counter to obtain unique numbers from a specified range. The call interface does not depend on CICS services, therefore it can also be used in applications running under any release of CICS.

The named counter call interface does not use CICS command-level API, therefore the system initialization parameter CMDPROT=YES has no effect. If the interface is called from a CICS application program that is excuting in user key, it switches to CICS key while processing the request but CICS does not attempt to verify that the program has write access to the output parameter fields.

The first request by an application region that addresses a particular pool automatically establishes a connection to the server for that pool. This connection is associated with the current MVS™ TCB (which for CICS is the quasi-reentrant (QR) TCB) and normally lasts until the TCB terminates at end of job. This connection can only be used from the TCB under which the connection was established. A request issued from another TCB will establish a separate connection to the server.

Note:
The named counter server interface uses MVS name/token services internally. A consequence of this is that jobs using the named counter interface cannot use MVS checkpoint/restart services (as described in APAR OW06685).

Application programming considerations

To use the named counter callable interface:

  1. Ensure your application programs include the appropriate copybook that defines the parameter list definition for the application programming language. The copybook defines symbolic constants for the function codes and return codes, and also defines the callable entry point for high level languages. The copybook name is of the form DFHNCxxx where xxx indicates the programming language, as follows:
    ASM or EQU for Assembler
    C for C/C++
    COB for COBOL
    PLI for PL/I 
  2. Ensure the application program is link-edited with the callable interface linkage routine, DFHNCTR.
  3. Ensure the named counter server interface module, DFHNCIF, and the options table, DFHNCOPT, are available to the CICS region. That is, these objects must be in a STEPLIB library, in a linklist library, or in the LPA. To support CICS application programs that run in user key, DFHNCIF must be loaded from an APF-authorized library. The default option table and the named counter server interface module are supplied in CICSTS31.CICS.SDFHLINK.

CICS provides copybooks for all the supported languages:

Assembler
The standard assembler named counter interface definitions are provided in copybook DFHNCASM. Include these in your application programs using COPY DFHNCASM within a constant CSECT area. The symbolic values are defined as static fullword constants, in fhe form NC_name DC F'nnn'. For example:
NC_BROWSE_NEXT DC F'7'

An alternative set of definitions is provided as symbolic equated values in copy book DFHNCEQU. These symbols are all of the form NC_EQU_name to avoid conflict with the static constants. Note that when these equated values are used for function codes or return code comparisons, they should be used as address constant values, so that for example the function code NC_ASSIGN can be replaced by a reference to =A(NC_EQU_ASSIGN).

The syntax of the assembler version of the call to the named counter interface is as follows:

CALL DFHNCTR,(function,return_code,pool_selector,counter_name,        X
            value_length,current_value,minimum_value,maximum_value,   X
            counter_options,update_value,compare_min,compare_max),VL

The CALL macro must specify the VL option to set the end of list indication, as shown in the following example:

CALL DFHNCTR,(NC_ASSIGN,RC,POOL,NAME,CTRLEN,CTR),VL
C/C++
The named counter interface definitions for C/C++ are provided in header file DFHNCC. The symbolic constant names are in upper case. The function name is dfhnctr, in lower case.
COBOL
The named counter interface definitions for COBOL are provided in copybook DFHNCCOB.

COBOL does not allow underscores within names, therefore the symbolic names provided in copy book DFHNCCOB use a hyphen instead of an underscore (for example NC-ASSIGN and NC-COUNTER-AT-LIMIT).

Note that the RETURN-CODE special register is set by each call, which affects the program overall return code if it is not explicitly set again before the program terminates.

PL/I
The named counter interface definitions for PL/I are provided in include file DFHNCPLI.

Syntax

The syntax of the named counter call is as follows:

Figure 82. DFHNCTR call syntax-PL/I illustration
CALL DFHNCTR(function,return_code,pool_selector,counter_name,
             value_length,current_value,minimum_value,maximum_value,
             counter_options,update_value,compare_min,compare_max);
Notes:
  1. All functions that refer to a named counter require at least the first four parameters, but the remaining parameters are optional, and trailing unused parameters can be omitted.

    If you do not want to use an imbedded optional parameter, either specify the default value or ensure that the parameter list contains a null address for the omitted parameter. For an example of a call that omits an optional parameter, see Example of DFHNCTR calls with null parameters.

  2. The NC_FINISH function requires the first three parameters only.
function
specifies the function to be performed, as a 32-bit integer, using one of the following symbolic constants.
NC_CREATE
Create a new named counter, using the initial value, range limits, and default options specified on the current_value, minimum_value, maximum_value, update_value and counter_options parameters.

If you omit an optional value parameter, the new named counter is created using the default for the omitted value. For example, if you omit all the optional parameters, the counter is created with an initial value of 0, a minimum value of 0, and a maximum value of high values (the double word field is filled with X'FF').

NC_ASSIGN
Assign the current value of the named counter, then increment it ready for the next request. When the number assigned equals the maximum number specified for the counter, it is incremented finally to a value 1 greater than the maximum. This ensures that any subsequent NC_ASSIGN requests for the named counter fail (with NC_COUNTER_AT_LIMIT) until the counter is reset using the NC_REWIND function, or automatically rewound by the NC_WRAP counter option (see the counter_options parameter).

This operation can include a conditional test on the current value of the named counter, using the compare_min and compare_max parameters.

The server returns the minimum and maximum values if you specify these fields on the call parameter list and the request is successful.

You can use the counter_options parameter on the NC_ASSIGN request to override the counter options set by the NC_CREATE request.

You can use the update_value parameter to specify the increment to be used on this request only for the named counter (the default increment is 1). This enables you to obtain a range of numbers on a single request. For more information, see the description of the update_value parameter.

Note that the named counter is incremented by update_value after the current value is assigned. For example:

If the current value is 109
and update_value specifies 25

the named counter server returns 109 and sets the current value to 134 ready for the next NC_ASSIGN request, effectively assigning numbers in the range 109 through 133. The increment can be any value between zero and the limit is determined by the minimum and maximum values set for the named counter. Thus the increment limit is ((maximum_value plus 1) minus minimum value). An increment of zero causes NC_ASSIGN to operate the same as NC_INQUIRE, except for any comparison options.

When the increment is greater than 1, and the named counter is near the maximum limit, the server may not be able to increment the current number by the whole value of the specified increment. This situation occurs when incrementing the counter would exceed the maximum value plus 1. You control what action the named counter server takes in this situation through the counter_options NC_NOREDUCE | NC_REDUCE, and NC_NOWRAP | NC_WRAP. See counter_options parameter for information about the operation of these options.

NC_BROWSE_FIRST
Return the details of the first named counter with a name greater than or equal to the specified name, and update the counter_name field accordingly.
NC_BROWSE_NEXT
Return the details of the next named counter with a name greater than the specified name, and update the counter_name field accordingly.
NC_DELETE
Delete the specified named counter. The server returns the current_value, minimum_value, maximum_value, and counter_options if you specify these fields on the parameter list and the request is successful.
NC_FINISH
Terminate the connection between the current MVS task (TCB) and the named counter server for the specified pool. If a further request is made to the same pool, a new connection is established.

This function does not apply to a specific counter, therefore the only parameters required are the function, the return code and the pool name.

Use this function only when there is a special reason to terminate the connection (for example, to allow the server to be shut down).

NC_INQUIRE
Return the details (current_value, minimum_value, maximum_value and counter_options) of a named counter without modifying it. The current value is the value to be returned on the next NC_ASSIGN call. If the maximum value of the named counter has already been assigned, the server returns a current value one greater than the maximum value.
NC_REWIND
Reset the named counter to its minimum value. This function is valid only when the last number permitted by the maximum value has been assigned, leaving the counter in the NC_COUNTER_AT_LIMIT condition. If an NC_ASSIGN call causes the server to assign the last number for the named counter, use the NC_REWIND function to reset the counter.

This operation can include a conditional test on the current value of the named counter, using the compare_min and compare_max parameters.

The server returns the new current value, minimum value, and maximum value if you specify these fields on the parameter list and the request is successful.

If any option parameter or update_value parameter was specified on an NC_ASSIGN request which failed because the named counter was at its limit, the same parameter values must also be specified on the NC_REWIND request, so that it can check whether the original NC_ASSIGN would still fail. The NC_REWIND request is suppressed with return code 102 (NC_COUNTER_NOT_AT_LIMIT) whenever the corresponding NC_ASSIGN request would succeed.

If the NC_WRAP option is in effect, or the update_value parameter is zero, NC_REWIND is suppressed because NC_ASSIGN always succeeds with these conditions. See the counter_options parameter for information about the NC_WRAP option.

NC_UPDATE
Set the named counter to a new value. This operation can include a conditional test on the current value of the named counter, using the compare_min and compare_max parameters.

You specify the new value on the update_value parameter. If you don't specify a new value, the named counter remains unchanged.

You can specify a valid counter_options override parameter (or a null address) with this function, but counter options have no effect. Specify either a null address or NC_NONE as the counter_options parameter.

return_code
specifies a 32-bit integer field to receive the return code. The same information is also returned in register 15, which for COBOL callers is stored in the RETURN-CODE special register.

Each return code has a corresponding symbolic constant. See Return codes for details of these.

pool_selector
specifies an 8-character pool selection parameter that you use to identify the pool in which the named counter resides.

This parameter is optional. If you omit the pool selection parameter, a string of 8 blank X'40') characters is assumed.

The acceptable characters for pool_selector are A through Z, 0 through 9, $ @ # and _ (underscore) but the first character cannot be numeric or an underscore. The parameter should be padded to fill 8 characters with trailing spaces as necessary. The parameter can be all spaces to use the default pool for the current region, provided this is mapped by the options table to a valid non-blank named counter name).

Depending on the named counter options table in use, you can use the pool selector parameter either as an actual pool name, or as a logical pool name that is mapped to a real pool name through the options table. The default options table assumes:

Note:
The default pool name for the call interface is DFHNC001. The default pool name for the EXEC CICS API is defined by the NCPLDFT system initialization parameter.

See Named counter options table for information about the pool selection parameter in the DFHNCOPT options table.

counter_name
specifies a 16-byte field containing the name of the named counter, padded if necessary with trailing spaces.

The acceptable characters for the name are A through Z, 0 through 9, $ @ # and _ (underscore) but the first character cannot be numeric or an underscore. The parameter should be padded to fill 16 characters with trailing spaces as necessary.

You are recommended to use names that have a common prefix of up to 8 bytes to avoid conflicts with other applications. Any named counters used internally by CICS have names starting with DFH.

For the NC_BROWSE_FIRST and NC_BROWSE_NEXT functions, the actual name is returned in this field, which must be a variable for this purpose. For all other functions, this can be a constant.

value_length
specifies a 32-bit integer field indicating the length of each named counter value field. Values can be in unsigned format (where the high order bit is part of the value), or in positive signed format (where the high order bit is reserved for a zero sign bit). To use unsigned format, specify the length in bytes, in the range 1 to 8, corresponding to 8 to 64 bits. To use values in signed format, specify the length in bytes as a negative number in the range -1 to -8, corresponding to 7 to 63 bits. For compatibility with the named counter EXEC interface, this should be set to -4 for counters that are handled as fullword signed binary values (COUNTER) and 8 for counters that are handled as doubleword unsigned binary values (DCOUNTER).

If no value parameters are used on the call, you can either omit all the trailing unused parameters completely, including the value length, or specify value_length as 0.

When input values are shorter than 8 bytes, they are extended with high-order zero bytes to the full 8 bytes used internally. When output values are returned in a short value field, the specified number of low-order bytes are returned, ignoring any higher-order bytes. However, if the value is too large to be represented correctly within the field, then a warning return code might be set, as described in Checking for result overflow.

current_value
specifies a variable to be used for:

For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. The default value is low values (binary zeroes). The value can either be within the range specified by the following minimum and maximum values, or it can be one greater than the maximum value, in which case the counter has to be reset using the NC_REWIND function before it is used. No sign check is made for this field, but a value that has the sign bit set would normally be rejected by the server as being inconsistent with the counter limits. For a counter that has a range consisting of all signed numbers, the counter at limit value does have the sign bit set, and this can be used as a valid input value.

For all other counter functions, this parameter is an output (receiver) field and must be defined as a variable.

minimum_value
specifies a variable to be used for:

For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. The default value is low values (binary zeroes).

For all other functions, this parameter is an output (receiver) field and must be defined as a variable.

maximum_value
specifies a variable to be used for:

For the NC_CREATE function this parameter is an input (sender) field and can be defined as a constant. If you specify a non-zero value_length parameter but omit maximum_value, then maximum_value defaults to high values (or, for signed variables, the largest positive value) for the specified length. If the value_length parameter is omitted or is specified as zero, then maximum_value defaults to eight bytes of high values. However, if the minimum value is all low values and the maximum value is eight bytes of high values, the maximum value is reduced to allow some reserved values to be available to the server for internal use.

For all other functions, this parameter is an output (receiver) field and must be defined as a variable.

counter_options
specifies an optional fullword field to indicate named counter options that control wrapping and increment reducing. The valid options are represented by the symbolic values NC_WRAP or NC_NOWRAP and NC_REDUCE or NC_NOREDUCE. The default options are NC_NOWRAP and NC_NOREDUCE.
NC_NOWRAP
The server does not automatically rewind the named counter back to the minimum value in response to an NC_ASSIGN request that fails with the NC_COUNTER_AT_LIMIT condition. With NC_NOWRAP in force, and the named counter in the NC_COUNTER_AT_LIMIT condition, the NC_ASSIGN function is inoperative until the counter is reset by an NC_REWIND request (or the counter option reset to NC_WRAP).
NC_WRAP
The server automatically performs an NC_REWIND in response an NC_ASSIGN request for a counter that is in the NC_COUNTER_AT_LIMIT condition. The server sets the current value of the named counter equal to the minimum value, returns the new current value to the caller, and increments the named counter.
NC_NOREDUCE
If the range of numbers remaining to be assigned (the difference between the current value and the maximum value plus 1) is less than the increment specified on the update_value parameter, the assign fails (unless NC_WRAP is in force). NC_NOREDUCE, with NC_NOWRAP, means the NC_ASSIGN request fails with the NC_COUNTER_AT_LIMIT condition.

For example, if a request specifies an update value of 15 when the current number is 199 990 and the counter maximum number is defined as 199 999, the NC_REQUEST fails because the increment would cause the current number to exceed 200 000.

NC_REDUCE
If the range of numbers remaining to be assigned (the difference between the current value and the maximum value plus 1) is less than the increment specified on the update_value parameter, the increment is reduced and the assign succeeds. In this case, the NC_ASSIGN request has been assigned a range of numbers less than that specified by the update_value, and the named counter is left in the NC_COUNTER_AT_LIMIT condition. Subsequent NC_ASSIGN requests will fail until the named counter is reset with an NC_REWIND request.

The options specified on NC_CREATE are stored with the named counter and are used as the defaults for other named counter functions. You can override the options on NC_ASSIGN, NC_REWIND or NC_UPDATE requests. If you don't want to specify counter_options on a DFHNCTR call, specify the symbolic constant NC_NONE (equal to zero) as the input parameter (or specify a null address).

For the NC_CREATE, NC_ASSIGN, NC_REWIND, and NC_UPDATE functions, this parameter is an input field.

For the NC_DELETE, NC_INQUIRE, and NC_BROWSE functions, this parameter is an output field, which returns the options specified on NC_CREATE.

update_value
specifies the value to be used to update the counter. For NC_ASSIGN, this is the increment to be added to the current counter value (after the current number is assigned). See the NC_ASSIGN option on the function parameter for information on how specifying an increment other than 1 can affect an assign operation.

For NC_UPDATE, this is the new current value for the named counter.

compare_min
specifies a value to be compared with the named counter's current value. If you specify a value, this parameter makes the NC_ASSIGN, NC_REWIND or NC_UPDATE operation conditional on the current value of the named counter being greater than or equal to the specified value. If the comparison is not satisfied, the operation is rejected with a counter-out-of-range return code (RC 103).

If you omit this parameter by specifying a null address, the server does not perform the comparison.

compare_max
specifies a value to be compared with the named counter's current value. If you specify a value, this parameter makes the NC_ASSIGN, NC_REWIND or NC_UPDATE operation conditional on the current value of the named counter being less than or equal to the specified value. If the comparison is not satisfied, the operation is rejected with a counter-out-of-range return code (RC 103).

If you specify high values (X'FF') for this parameter, the server does not perform the comparison. You must specify (X'FF') in all the bytes specified by the value_length parameter.

If the compare_max value is less than the compare_min value, the valid range is assumed to wrap round, in which case the current value is considered to be in range if it satisfies either comparison, otherwise both comparisons must be satisfied.

Checking for result overflow

The call interface checks for results which do not fit into the specified size of result field, or which overflow into the sign bit when signed variables are used.

If a result field (counter_value, minimum_value or maximum_value) has been defined as a signed variable by specifying value_length as a negative value, the call interface checks for results that overflow into the sign bit. In this case, the operation completes normally but the return code NC_RESULT_OVERFLOW is set. As a special case, a result value for a counter which is at its limit value is not checked for this form of overflow, to avoid setting the return code unnecessarily. This means that if a query is made to a counter which is at its limit, and whose maximum value is the maximum positive value, a negative number might be returned as the current counter value without causing this return code.

If a result field (counter_value, minimum_value or maximum_value) is too short to contain the full non-zero part of the result, the operation completes normally, but one of the following return codes is set:

If a 4-byte unsigned counter that has a maximum of high values has reached its limit value, the return code NC_RESULT_CARRY is set, and the counter value is zero.

Example of DFHNCTR calls with null parameters

If you omit an optional parameter on a DFHNCTR call, ensure that the parameter list is built with a null address for the missing parameter. The example that follows illustrates how to issue, from a COBOL program, an NC_CREATE request with some parameters set to null addresses.

DFHNCTR call with null addresses for omitted parameters: In this example, the parameters used on the call are defined in the WORKING-STORAGE SECTION, as follows:

Call parameter COBOL variable Field definition
function 01 FUNCTION PIC S9(8) COMP VALUE +1.
return_code 01 NC-RETURN-CODE. PIC S9(8) COMP VALUE +0.
pool_selector 01 NC-POOL-SELECTOR PIC X(8).
counter_name 01 NC-COUNTER-NAME PIC X(16).
value_length 01 NC_VALUE-LENGTH PIC S9(8) COMP VALUE +4.
current_value 01 NC-CURRENT-VALUE PIC S9(8) VALUE +0.
minimum_value 01 NC-MIN-VALUE PIC S9(8) VALUE +0.
maximum_value 01 NC-MAX-VALUE PIC S9(8) VALUE -1.
counter_options 01 NC-OPTIONS PIC S9(8) COMP VALUE +0.
update_value 01 NC-UPDATE-VALUE PIC S9(8) VALUE +1.
compare_min 01 NC-COMP-MIN PIC S9(8) VALUE +0.
compare_max 01 NC-COMP-MAX PIC S9(8) VALUE +0.

The variable used for the null address is defined in the LINKAGE SECTION, as follows:

       LINKAGE SECTION.
         01  NULL-PTR         USAGE IS POINTER.

Using the data names specified in the WORKING-STORAGE SECTION as described above, and the NULL-PTR name as described in the LINKAGE SECTION, the following illustrates a call to a named counter server where value_length, current_value, minimum_value and counter_options are the only optional parameters specified. The others are allowed to default, or, in the case of trailing optional parameters, omitted altogether.

       NAMED-COUNTER SECTION.
      *
           SET ADDRESS OF NULL-PTR TO NULLS.
      *
           MOVE   1     TO  FUNCTION.
           MOVE 100     TO  NC-MIN-VALUE  NC-CURRENT-VALUE.
           MOVE NC-WRAP TO  NC-OPTIONS.
           MOVE "DFHNC001" TO NC-POOL-SELECTOR.
           MOVE "CUSTOMER_NUMBER" TO NC-COUNTER-NAME.
           CALL 'DFHNCTR' USING  FUNCTION NC-RETURN-CODE NC-POOL-SELECTOR
                          NC-COUNTER-NAME  NC-VALUE-LENGTH  NC-CURRENT-VALUE
                          NC-MIN-VALUE  NULL-PTR  NC-OPTIONS. 

Return codes

There are three warning return codes (1-3) for the named counter call interface, which indicate result overflows for a request that otherwise completed normally. If more than one warning return code applies for the same request, the highest applicable warning return code is set.

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 list that follows, 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 lready 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 should be able to 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, which a program may 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 CICS 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 is unable to establish a connection to the server for the appropriate named counter pool. Further information can be found in an AXM services message in the CICS 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 CICS job log and the server job log.
307 (NC_NAME_TOKEN_ERROR)
An IEANTxx name/token service call within 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, could not 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. One reason, for example, for this 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 anmd retry until it succeeds, with the result that the application program sees 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.
[[ Contents Previous Page | Next Page Index ]]