C External Procedure Utility

This chapter describes the C external procedure utility used to create the functions of a user shared library.

The external C procedure provides several APIs which help a user to implement a user shared library. These APIs are referred to as C External Procedure Utility.

The functions included in the external C procedure utility are:

• SQLExtProcAllocMemory

• SQLExtProcRaiseError

• SQLExtProcRaiseErrorWithMsg

Using these functions requires understanding of the ExtProcContext structure provided by Tibero. To create a user shared library and register it as a PMS, particular actions are needed as explained in this chapter.

---

Using External C Procedure Utility

To use the external C procedure utility, it must be defined in the same way as in both the tbEPA process and the user shared library.

To specify this information in the tbEPA process, the WITH CONTEXT clause must be defined when the user shared library is registered as PSM. The first parameter of the user shared library function must be always ExtProcContext *. The ExtProcContext is defined in the extproc.h file, and used by the tbEPA process to handle the functions of the External C Procedure utility.

Precautions for Creating a User Shared Library

To allow users to create the functions of a user shared library using the external C procedure utility, Tibero provides the extproc.h file, located in the $TB_HOME/client/include directory. The functions use the file to access the external C procedure utility. To write a user shared library function which calls any function from the external C procedure utility, the library must contain the extproc.h file.

The following is an example.

#include "extproc.h"

char * get_encrypted_string(ExtProcContext *epc, char *str)
{
  ...
}

Precautions for Registering User Shared Library Function as PSM

In the “Function and PSM Object Mapping”, users can see the [WITH CONTEXT] clause. This informs DBMS that the client application is currently accessing the C external procedure utility. To execute the PSM, the service routine sends the information to the tbEPA process.

Then, the tbEPA process loads the library and sends the pointer of ExtProcContext as the first parameter to the client application.

CREATE OR REPLACE FUNCTION ext_get_enc_char (chr CHAR(10)) 
       RETURN CHAR
       AS LANGUAGE C
       LIBRARY extproc
       NAME "get_encrypted_string" 
       WITH CONTEXT
       PARAMETERS(CONTEXT, chr string);

The first parameter of the PARAMETERS clause must be always CONTEXT.

When WITH CONTEXT is specified alone without PARAMETERS, users must be aware that the parameter number 1 is CONTEXT, and the parameter 2 and the subsequent parameters are the PSM parameters.

---

C External Procedure Utility Functions

This chapter describes the functions provided in the C external procedure utility.

SQLExtProcAllocMemory

In a user shared library, memory is allocated dynamically. Generally, the malloc and calloc functions are used to dynamically allocate memory at runtime, but if these functions are used as return values, users may have difficulty in deciding when to free the memory.

To address this problem, the external C procedure utility provides the SQLExtProcAllocMemory function. With this function, memory is dynamically allocated and does not need to be freed. The allocated memory is automatically freed after the function is executed.

The following is the syntax of the SQLExtProcAllocMemory function.

Syntax

SQLPOINTER SQLExtProcAllocMemory(ExtProcContext *, size_t size);

Parameter

Parameter	Description
ExtProcContext *	Pointer of the ExtProcContext structure.
size	Size of the memory to be allocated.

Return value

Success or Failure	Description
Success	Returns a pointer to the beginning of the allocated memory.
Failure	Returns a NULL value.

Example

#include <string.h> 
#include "extproc.h" 
#include "sqlcli.h"

char * my_concat(ExtProcContext *epc, char *str1, char *str2)
{
    char *ret_str; 
    uint size;
    
    size = strlen(str1) + strlen(str2) + 1;
    ret_str = (char *) SQLExtProcAllocMemory(epc, size);
    
    strcpy(ret_str, str1); 
    strcat(ret_str, str2);
    
    return ret_str;
}

SQLExtProcRaiseError

Users may encounter an error or a necessity to issue an error while executing functions for a user shared library. In these cases, they can implement error handling process in the PSM using its return value. However, the error handling process is necessary not only for the user shared library functions but also for all the locations in which their corresponding PMSs are used.

To address this problem, the C external procedure utility provides a function of the shared library which directly raises a DBMS error using SQLExtProcRaiseError. The errors thrown by the function of the shared library include DIVIDE BY ZERO, NUMBER EXCEEDS PRECISION, etc. This function is also available in "Callback Service".

The following is the syntax of the SQLExtProcRaiseError function.

Syntax

void SQLExtProcRaiseError(ExtProcContext *, int errcode);

Parameter

Parameter	Description
ExtProcContext *	Pointer to the ExtProcContext structure.
errcode	Number of the error code. (For more information about the error code, refer to "Tibero Error Reference Guide".)

Example

/* ExtProcContext *epc */
SQLExtProcRaiseErrorWithMsg(epc, 20100, "User exit procedure");

SQLExtProcRaiseErrorWithMsg

Like the SQLExtProcRaiseError function, this function raises an error. This function can also raise a user-defined error.

The following is the syntax of the SQLExtProcRaiseErrorWithMsg function.

Syntax

void SQLExtProcRaiseErrorWithMsg(ExtProcContext *, int errcode, char *errmsg);

Parameter

Parameter	Description
ExtProcContext *	Pointer to the ExtProcContext structure.
errcode	User-defined error code (20000 ~ 20999).
*errmsg	User-defined error message.

Example

/* ExtProcContext *epc */
SQLExtProcRaiseErrorWithMsg(epc, 20100, "User exit procedure");