OpenAPI Function Reference

This chapter provides details about each OpenAPI function. It begins with a description of the generic parameters that are common to each OpenAPI function. It then lists the output parameters for which the OpenAPI allocates and manages memory. It also describes each OpenAPI function and provides its syntax and a description of its parameters.

Note: For a description of non-standard C data types used in OpenAPI parameter blocks, see OpenAPI Data Types.

Generic Parameters

Each OpenAPI function parameter block has a common substructure. This substructure contains generic parameters for handling asynchronous processing and for communicating the return status of the OpenAPI function.

The substructure is the first element in most parameter blocks:

typedef struct _IIAPI_GENPARM
{
      II_VOID      (II_FAR II_CALLBACK *gp_callback)
                   (II_PTR closure, II_PTR parmBlock);
      II_PTR        gp_closure;
      II_BOOL       gp_completed;
      IIAPI_STATUS  gp_status;
      PTR           gp_errorHandle;
} IIAPI_GENPARM;

The generic parameters are as follows:

• gp_callback

  Type: input

  The address of the application function to be invoked when the OpenAPI function completes its tasks, or NULL. If this parameter is NULL, the application can poll for completion by examining gp_completed; otherwise, it must be an address to the callback with the following syntax:

  II_EXTERN II_VOID II_FAR II_CALLBACK callback (II_PTR closure, II_PTR parmBlock);

• gp_closure

  Type: input

  The value of the input argument to the function addressed by gp_callback. OpenAPI does not interpret the value of this parameter, but simply passes it to the callback function unchanged. The application uses this parameter to pass any information it wishes to the callback.

• gp_completed

  Type: immediate and delayed output

  The indication that the task has been completed and the callback function has been invoked. If so, this parameter is TRUE; otherwise, it is FALSE.

• gp_status

  Type: delayed output

  The status of the OpenAPI function upon its completion.

  The following value is returned if the function completes without an error:

  IIAPI_ST_SUCCESS

  The following values indicate that a message (including which type of message) was returned by the server; the message information is available through gp_errorHandle:

  IIAPI_ST_MESSAGE
  IIAPI_ST_WARNING
  IIAPI_ST_ERROR

  The following value is returned when a function that normally returns information has nothing to return:

  IIAPI_ST_NO_DATA

  The following value is returned for general failures, which will have additional information available through gp_errorHandle:

  IIAPI_ST_FAILURE

  The following values are returned when the OpenAPI is unable to provide additional information because of the error:

  IIAPI_ST_NOT_INITIALIZED
  IIAPI_ST_INVALID_HANDLE
  IIAPI_ST_OUT_OF_MEMORY

• gp_errorHandle

  Type: delayed output

  Additional information associated with the completion of the OpenAPI function. If non-NULL, this parameter will be a handle that can be passed to IIapi_getErrorInfo(). If NULL, no additional information is available.

How Memory is Managed for Data Input and Output

An application allocates memory for each OpenAPI function argument and its input parameters. The application also allocates memory for the output parameters, with the exception of the parameters listed in the following table. These parameters are allocated by OpenAPI:

The output parameters allocated by OpenAPI are maintained until the application calls IIapi_close() with the statement handle associated with these parameters. To retain the information after IIapi_close() is invoked, the application copies the parameters into its own buffers.