C External Procedure 사용법

C External Procedure 사용법 중 PSM 파라미터와 C 파라미터를 매핑하는 방법과 Callback Service 사용하는 방법을 설명합니다.

파라미터 매핑

Library Object 내의 특정 함수를 PSM에 대응시키면 사용자 함수의 파라미터로 PSM 파라미터가 그대로 전달됩니다. 하지만 때로는 PSM으로 전달된 파라미터 중에서 일부만을 사용자 함수로 전달하고 싶거나 그 순서를 변경하고 싶을 경우가 있습니다. 또한 C 프로그래밍 언어의 int, double과 같은 타입의 파라미터로 DBMS 에서 사용하는 NULL의 개념을 표현할 수 없을 때도 마찬가지입니다.

C External Procedure에서는 이러한 요구를 지원하기 위해 PARAMETERS 문법을 제공합니다. 즉, 사용자 함수의 파라미터와 PSM 파라미터 간의 파라미터 매핑(Parameter Mapping)을 통해 해결할 수 있습니다. 본 절에서는 PARAMETERS 문법과 이를 사용하는 방법을 설명합니다.

PARAMETERS 문법

PARAMETERS 문법은 생략할 수 있으며, 이 문법을 통해 사용자 함수로 전달할 파라미터와 그 속성을 정의할 수 있습니다.

PARAMETERS 문법은 아래와 같습니다.

CREATE OR REPLACE {FUCTION | PROCEDURE | PACKAGE}
…
{IS | AS} 
LANGUAGE C
LIBRARY library_name
[NAME c_string_literal_name] 
[WITH CONTEXT]
[PARAMETERS (external_parameter[, external_parameter]...)];

PARAMETERS 문법은 함수의 파라미터 각각을 의미하는 external_parameter를 나열하여 구성합니다. 또한 external_parameter는 아래와 같이 어떤 방법으로 명시하느냐에 따라 세부 구성요소가 달라집니다.

{ CONTEXT
  | {parameter_name | RETURN} [property] [BY REFERENCE] [external_datatype]
}

CONTEXT

자세한 내용은 “C External Procedure 유틸리티”를 참고합니다.

PSM 파라미터

PSM 파라미터는 사용자 함수에 전달할 유형과 형식에 따라 BY REFERENCE, external_datatype 심볼 중에서 설정할 수 있습니다. PSM 파라미터는 PSM의 데이터 타입이 external_datatype에 대응되는 C 프로 그래밍 언어의 데이터 타입으로 순차적으로 변환되어 전달됩니다.

아래는 PSM 파라미터를 명시하는 방법을 구성요소별로 설명합니다.

parameter_name parameter_name은 사용자 함수로 전달할 PSM 파라미터의 이름을 설정하는 심볼입니다. 아래는 사용자 함수(get_sqrt)로 전달할 PSM 파라미터의 이름(num2)을 설정하는 예입니다.

CREATE OR REPLACE FUNCTION ext_get_sqrt (num1 BINARY_INTEGER,
                                   num2 BINARY_INTEGER)
       RETURN BINARY_DOUBLE AS LANGUAGE C
       LIBRARY extproc
       NAME "get_sqrt" 
       PARAMETERS(num2 int);

property property는 사용자 함수로 전달할 PSM 파라미터의 특성을 설정하는 심볼입니다. C의 데이터 타입의 경우 PSM의 데이터 타입과 달리 문자열의 최대 길이나 데이터의 NULL 허용 여부 등을 표시할 수 없습니다. 따라서 이러한 문제점을 보안하기 위해 C External Procedure에서는 아래와 같은 파라미터의 속성을 지원합니다.

속성

C의 데이터 타입

설명

INDICATOR

short

데이터의 NULL 허용 여부를 갖는 지시자(Indicator)입니다.

NULL : -1
NULL이 아닌 경우 : 0

LENGTH

int

문자열 데이터의 현재 길이로 IN, INOUT에서 사용합니다.

MAXLEN

int

문자열 데이터의 최대 길이로 OUT, INOUT, RETURN에서 사용합니다.

C의 데이터 타입은 이러한 속성을 파라미터로 전달받아 사용자 함수를 작성할 때 해당 파라미터의 데이터타입을 의미합니다.

BY REFERENCE BY REFERENCE 문은 사용자 함수로 파라미터를 전달할 때 값으로 전달할 것인지 아니면 그 값의 포인터로 전달할 것인지의 여부를 나타내는 심볼입니다. 예를 들어 문자열의 경우 C의 데이터 타입으로는 문자열의 값 자체를 담을 수 없기 때문에 char * 형태로 전달할 수 밖에 없습니다. 또한 출력 파라미터의 경우 그 값이 함수가 수행된 후에 변경되어야 하므로, 그 값에 대한 포인터 타입으로 사용자 공유 라이브러리 함수에 전달되어야 합니다. 아래는 간단하게 작성된 C 함수입니다.

<<module.c>>

void swap(short *x, short *y)
{
    short *z; 
    z = x;
    x = y; 
    y = z;
}

C 함수는 아래의 PSM 함수에서 사용할 수 있습니다. PSM 함수를 생성하는 문장에서 PARAMETERS 문법의 BY REFERENCE를 명시하면 tbEPA 프로세스는 포인터 형식으로 사용자 함수에 파라미터를 전달합니다.

예를 들면 아래와 같습니다.

SQL> CREATE OR REPLACE PROCEDURE ext_swap (x PLS_INTEGER, y PLS_INTEGER)
     IS
     LANGUAGE C
     LIBRARY libextproc
     NAME "swap"
     PARAMETERS(x BY REFERENCE, y BY REFERENCE);

external_datatype external_datatype은 PSM의 데이터 타입을 원하는 형태의 C의 데이터 타입으로 변환하기 위해 사용하는 심볼입니다. external_datatype을 생략하면 디폴트로 정의된 C의 데이터 타입으로 변환되어 사용자 함수의 파라미터로 전달됩니다. 예를 들어 변환이 가능한 C의 데이터 타입으로 전달하는 경우 tbEPA 프로세스 내부에서 사용할 수 있는 타입으로 변환한 후 사용자 함수의 파라미터로 전달합니다. 아래는 PSM과 C 함수 간의 변환이 가능한 데이터 타입입니다.

PSM의 데이터 타입

C의 데이터 타입(기본)

변환이 가능한 C의 데이터 타입

BINARY_INTEGER

PLS_INTEGE

INT

[UNSIGNED] CHAR, SHORT, INT, LONG

FLOAT

REAL

BINARY_DOUBLE

DOUBLE

CHAR VARCHAR

STRING

STRING, TBSTRING

DOUBLE

TBNUMBER

DATE

TBDATE

TIMESTAMP

TBDateTime

BLOB CLOB

TBLOBLOCATOR

사용 예제

아래는 PARAMETERS 문법을 사용하여 PSM 함수에 파라미터를 매핑하는 예입니다.

1. C 함수를 작성합니다.

<<find_max.c>>

short find_max_short(short x, short y)
{
     if (x >= y)
         return x; 
     else
         return y;
}

2. C 함수의 파라미터를 PARAMETERS 문법을 사용하여 PSM 함수에 파라미터를 매핑합니다.

SQL> CREATE OR REPLACE FUNCTION ext_find_max_short
      (x PLS_INTEGER, y PLS_INTEGER)     ...(1)...
      RETURN PLS_INTEGER IS 
      LANGUAGE C
      LIBRARY libextproc 
      NAME "find_max_short"              ...(2)...
      PARAMETERS(x short, y short);

(1) PSM 함수인 ext_find_max_short를 호출합니다.

(2) tbEPA 프로세스는 서버로부터 전달 받은 pls_integer 타입을 short 타입으로 변환하여 사용자 공유 라이브러리 함수인 find_max_short의 파라미터로 보냅니다. 그리고 short 타입의 반환 값은 다시 PLS_INTEGER 타입으로 변환하여 서버로 전달합니다.

Callback Service

사용자는 tbCLI 등의 인터페이스를 이용하여 애플리케이션 프로그램을 개발할 수 있습니다. 또한 DBMS 서버에 접속하여 쿼리, DML 등을 수행할 수 있는 사용자 공유 라이브러리를 만들어 C External Procedure로 사용할 수 있습니다.

C External Procedure는 서버와 새로운 연결을 맺어 통신하는 일반적인 형태의 tbCLI 프로그램이 아닌 기존의 트랜잭션을 이용하는 Callback Service를 제공합니다.

본 절에서는 tbCLI를 이용하여 애플리케이션 프로그램의 개략적인 작성 방법을 살펴본 후 C External Procedure에서 제공하는 Callback Service를 설명합니다.

tbCLI를 이용한 애플리케이션 프로그램 작성 방법

일반적으로 tbCLI를 이용하여 애플리케이션 프로그램을 작성하기 위해서는 아래와 같은 순서로 수행합니다.

SQLAllocEnv 함수를 이용하여 환경 핸들(environment handle)을 생성합니다.
SQLAllocConnect 함수를 이용하여 연결 핸들(connection handle)을 생성합니다.
SQLConnect 함수를 이용하여 DBMS 서버에 접속합니다.
SQLAllocStmt 함수를 이용하여 문장 핸들(statement handle)을 생성합니다.
4번에서 할당 받은 문장 핸들에 수행할 작업을 설정한 후 SQLExecute 함수를 수행합니다.

위 순서에서 1, 2, 3번 과정은 사용자가 작성한 애플리케이션 프로그램을 서버와 연결된 상태로 만들며 4, 5번 과정을 반복하면서 사용자가 원하는 쿼리 또는 DML 등을 수행합니다.

자세한 내용은 "Tibero tbCLI 안내서"를 참고합니다.

사용 방법

“tbCLI를 이용한 애플리케이션 프로그램 작성 방법”과 같은 방식으로 사용자 공유 라이브러리를 작성하면, C External Procedure를 호출할 때 서버와의 새로운 세션을 맺고 사용자 공유 라이브러리를 실행하게 됩니다. 이때 사용자 공유 라이브러리는 기존에 C External Procedure를 호출한 트랜잭션과는 다른 별도의 트랜잭션으로 동작하게 되며, 또한 기존 트랜잭션의 정보도 볼 수 없게 됩니다.

C External Procedure에서는 SQLGetExtProcConnect 함수를 이용하여 사용자가 C External Procedure를 호출한 트랜잭션과 같은 트랜잭션 내에서 tbCLI를 이용한 작업을 동시에 수행할 수 있게 해줍니다.

아래는 SQLGetExtProcConnect 함수를 사용한 예입니다.

SQLRETURN SQL_API
SQLGetExtProcConnect(ExtProcContext *epCtx, SQLHENV *henv, SQLHDBC *hdbc, 
                     SQLSMALLINT *errHdlType, SQLHANDLE *errHdl);

*epCtx는 ExtProcContext 구조체에 대한 포인터이며, henv, hdbc는 반환받을 환경 핸들, 연결 핸들을 나타냅니다. 그리고 에러 핸들 타입(errHdlType)과 에러 핸들(errHdl)은 에러 발생에 대비하여 정의한 것 입니다.

SQLGetExtProcConnect 함수를 이용하면 “tbCLI를 이용한 애플리케이션 프로그램 작성 방법” 에서 설명한 순서 중 1번부터 3번까지의 과정을 한 번에 할 수 있고, 그 뒤의 과정은 기존의 tbCLI를 이용한 작업과 동일하게 진행하면 됩니다.

사용자 공유 라이브러리 함수 내의 DML, 쿼리 등은 현재 사용자 공유 라이브러리 함수를 호출한 트랜잭션 내에서 수행됩니다.

아래는 그 예입니다.

SQLRETURN   rc;
SQLHENV     henv;
SQLHDBC	    hdbc;
SQLHSTMT    hstmt; 
SQLSMALLINT errHdlType; 
SQLHANDLE   errHdl;

char *sql = "insert into tbl values('Tibero')"; 
SQLINTEGER cnt;

rc = SQLGetExtProcConnect(epc, &henv, &hdbc, &errHdlType, &errHdl); 
if (rc != 0) return rc;

rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); 
if (rc != 0) return rc;

rc = SQLExecDirect(hstmt, sql, SQL_NTS); 
if (rc != 0) {
    SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 
    return rc;
}

rc = SQLRowCount(hstmt, &cnt); 
if (rc != 0) {
    SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 
    return rc;
}

SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 

return rc;

위의 예제에서 보듯이 statement handle의 경우 사용자가 직접 SQLAllocHandle()을 통해 만들어야 하고 적절한 곳에서 SQLFreeHandle()을 해야 합니다. 하지만 SQLGetExtProcConnect()을 통해 자동으로 생성되는 environment handle과 connection handle은 SQLDisconnect()나 SQLFreeHandle()을 하면 안됩니다.

사용 예제

아래는 Callback Service를 이용하여 애플리케이션 프로그램을 작성한 예입니다.

int connect(ExtProcContext *epc)
{
    SQLRETURN	rc;
    SQLHENV	henv;
    SQLHDBC	hdbc;
    SQLHSTMT	hstmt; 
    SQLSMALLINT errHdlType; 
    SQLHANDLE	errHdl;
    
    char *sql = "insert into psm_test_tab_002 values('TEST')"; 
    SQLINTEGER cnt;
    
    rc = SQLGetExtProcConnect(epc, &henv, &hdbc, &errHdlType, &errHdl); 
    if (rc != 0) return rc;
    
    rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); 
    if (rc != 0) return rc;
    
    rc = SQLExecDirect(hstmt, sql, SQL_NTS); 
    if (rc != 0) {
        SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 
        return rc;
    }
    
    rc = SQLRowCount(hstmt, &cnt); 
    if (rc != 0) {
        SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 
        return rc;
   }
   
   SQLFreeHandle(SQL_HANDLE_STMT, hstmt); 
   
   if (cnt != 1) return 1;
   
   return 0;

}

PreviousC External Procedure 생성 NextC External Procedure 유틸리티

Last updated 6 months ago