Return codes

The KDCADMI return code consists of a main code and a subcode. The main code tells you whether the requested function has been executed or whether the execution has been initiated in a task (return code KC_MC_OK), or whether execution could not be carried out (return code not equal to KC_MC_OK). The subcode contains further information pertaining to the main code returned if the subcode is not equal to KC_SC_NO_INFO.

The code is returned in the following data structure:

typedef struct
{  KC_MAINCODE     mc;
   KC_SUBCODE      sc;
} KC_ADM_RETCODE;

UTM returns the code in the retcode field of the parameter area. If it is not possible to access the entire length of the parameter area or if the area is not oriented toward word boundaries, then UTM sets the return code KCRCCC=70Z and the return code KCRCDC=A100 in the return code area of the communication area. The service is aborted with PEND ER.

Both the main codes and the subcodes are defined as enumeration type (enum) in the header file. KDCADMI therefore returns a numeric constant.

In order to facilitate the diagnostics process when an error occurs, you can have the main codes and the subcodes listed in the form of strings (e.g. "KC_MC_OK"). For this, in your program, you must define the symbolic name KC_ADM_GEN_STRING using the #define statement before you include kcadminc.h.

#define KC_ADM_GEN_STRING
#include kcadminc.h

General return codes (independent of operation codes)

The following table lists the return codes that can be returned for any operation (i.e. for all operation codes) executed using KDCADMI. Other return codes only arise in conjunction with certain operation codes. These return codes are listed in the descriptions of the individual operation codes.

Main code = KC_MC_OK

The function was executed or a task was initiated to execute the function.

Subcode:

KC_SC_NO_INFO

Main code = KC_MC_VERS_DATA_NOT_SUPPORTED

A version of the data structure which is not supported by UTM was specified in the version_data field of the parameter area.

Subcode:

KC_SC_NO_INFO

Main code = KC_MC_VERSION_NOT_SUPPORTED

A version of the program interface which is not supported by UTM was specified in the version field of the parameter area.

Subcode:

KC_SC_NO_INFO

Main code = KC_MC_AREA_INVALID

One of the data areas passed in a KDCADMI call cannot be accessed over its entire length because, for example, the area address is invalid or the required length of the area is not allocated.

Subcodes:

KC_SC_ID_AREA

The identification area cannot be accessed over its entire length.

KC_SC_SEL_AREA

The selection area cannot be accessed over its entire length.

KC_SC_DATA_AREA

The data area cannot be accessed over its entire length,
or the address of the parameter area is within the data area.

Main code = KC_MC_NO_ADM_TAC

The transaction code that initiated the administration call does not have the privileges required to execute the operation requested (administration privileges or ADM-READ privileges)

Subcode:

KC_SC_NO_INFO

Main code = KC_MC_PAR_INVALID

An invalid value was specified or a field was not set in the parameter area.

Subcodes:

KC_SC_RETCODE

The retcode field of the parameter area was not set to KC_RC_NIL.

KC_SC_OPCODE

The operation code specified in the opcode field of the parameter area is invalid.

KC_SC_SUBOPCODE1

The operation modifier specified in the subopcode1 field of the parameter area is invalid.

KC_SC_SUBOPCODE2

The operation modifier specified in the subopcode2 field of the parameter area is invalid.

KC_SC_TYPE

The object type specified in the obj_type field of the parameter area is invalid.

KC_SC_NUMBER

The number of objects specified in the obj_number field of the parameter area is invalid.

KC_SC_ID_LTH

The length specified in the id_lth field of the parameter area is invalid.

Possible reasons:

• id_lth is not equal to the length of the name field for the object type.

• id_lth > 0, although no identification area may be passed.

KC_SC_SELECT_LTH

The length specified in the select_lth field of the parameter area is invalid.

Possible reasons:

• select_lth is not equal to the length of the data structure for the object type.

• select_lth > 0, although selection is not allowed.

KC_SC_DATA_LTH

The length specified in the data_lth field of the parameter area is invalid.

Possible reasons:

• data_lth is not equal to the length of the data structure for the object type or, for KC_GET_OBJECT, it is smaller than obj_number * length of the data structure for the object
  type.

• data_lth > 0, but no data area was passed.

• data_lth > 16 MB.

KC_SC_NUMBER_RET

The number_ret field of the parameter area was not set to binary zero.

KC_SC_DATA_LTH_RET

The data_lth_ret field of the parameter area is not set to binary zero.

Main code = KC_MC_FUNCT_NOT_SUPPORTED

The operation requested is not supported by the operating system or by the version of the operating system under which the application is running.
This return code is returned by UTM when, for example, an operation has been requested in a UTM application on Unix, Linux or Windows systems that is only defined for UTM applications on BS2000 systems.

Subcode:

KC_SC_NO_INFO