Fetching Error Information

Two types of errors can be reported: errors in the use or operation of the OpenAPI, and errors reported by the DBMS.

There are two types of OpenAPI function: asynchronous functions which interact with the DBMS, and synchronous functions which interact only with the OpenAPI. Both types of function report errors using their control blocks, but in different ways.

The control block for asynchronous functions contains an IIAPI_GENPARM structure, which has a gp_status member and a gp_errorHandle member. The control block for a synchronous function has only a “status” member, the exact name of which will depend on the function. For instance, in the case of the IIAPI_INITPARM for the IIapi_initialize() function, its status member is called in_status.

In the event of an error, detected by the OpenAPI or the DBMS, the status is set to IIAPI_ST_ERROR or greater.

In the event of an error in an asynchronous function, the gp_errorHandle member of its IIAPI_GENPARM structure may be set. The error handle can be used to fetch detailed error messages by calling IIapi_getErrorInfo(). Because a single fault may cause multiple messages it has to be called repeatedly, until it returns IIAPI_ST_NO_DATA.

Note

IIAPI_ST_ERROR indicates an error. The DBMS session remains usable and the application can continue.

IIAPI_ST_FAILURE indicates the DBMS session has failed but if there is an error handle then additional information will be available using IIapi_getErrorInfo(). The DBMS session may no longer be usable.

Important

The OpenAPI allocates the buffers used for error messages. They are released when the application executes IIapi_close(). Copy any required error information before doing so.

Warning

Failing to call IIapi_close() will create a memory leak.

Download

 1import pyngres as py
 2...
 3
 4def get_error_reports(genParm):
 5    '''return a list of error reports'''
 6
 7    error_reports = []
 8    status = genParm.gp_status
 9
10    if status >= py.IIAPI_ST_ERROR:
11        # get error information if it is available
12        errorHandle = genParm.gp_errorHandle
13        if errorHandle:
14            gep = py.IIAPI_GETEINFOPARM()
15            gep.ge_errorHandle = errorHandle
16
17            while True: 
18                py.IIapi_getErrorInfo(gep)
19                if gep.ge_status == py.IIAPI_ST_NO_DATA:
20                    break
21
22                #  get any additional information to complete the message
23                if gep.ge_serverInfoAvail:
24                    serverInfo = gep.ge_serverInfo.contents
25
26                    svr_id_error = serverInfo.svr_id_error
27                    svr_local_error = serverInfo.svr_local_error
28                    svr_id_server = serverInfo.svr_id_server
29                    svr_server_type = serverInfo.svr_server_type
30                    svr_severity = serverInfo.svr_severity
31                    svr_parmCount = serverInfo.svr_parmCount
32                   
33                    # process the whole svr_parmCount-sized array
34                    for i in range(svr_parmCount):
35                        svr_parmDescr = serverInfo.svr_parmDescr[i]
36                        svr_parmValue = serverInfo.svr_parmValue[i]
37                        ...
38
39                message = gep.ge_message.decode()
40                SQLSTATE = gep.ge_SQLSTATE.decode()
41                error_code = gep.ge_errorCode
42                error_report = (status,error_code,SQLSTATE,message)
43                error_reports.append(error_report)
44        else:
45            # report status as an unmappable error
46            message = py.IIAPI_ST_MSG[status]
47            SQLSTATE = py.II_SS5000K_SQLSTATE_UNAVAILABLE 
48            error_code = 39100 # E_GE98BC_OTHER_ERROR, unmappable error
49            error_report = (status,error_code,SQLSTATE,message)
50            error_reports.append(error_report)
51
52    return error_reports

Download