User Exit을 사용하여 Oracle GoldenGate 기능 확장

사용자 종료는 C 프로그래밍 코드로 작성하고 Extract 또는 Replicat 처리 중 호출하는 사용자정의 루틴입니다. User Exit은 복잡성과 위험을 최소화하면서 Extract 및 Replicat 프로세스의 기능을 확장하고 사용자정의합니다. User Exit을 사용하면 데이터베이스 이벤트 발생 시 운용 프로그램을 변경하지 않고도 이에 대응할 수 있습니다.

주: CUSEREXITS를 사용하는 경우 LD_LIBRARY_PATH 환경 변수를 확장해야 합니다. 기본적으로 $OGG_HOME/lib 디렉토리는 Oracle GoldenGate 소프트웨어 홈 디렉토리의 일부입니다. Deployment 디렉토리와 설계로 구분됩니다. User Exit 함수에 대해 추가 공유 객체를 추가해야 하는 경우 $OGG_HOME/lib 디렉토리를 사용하지 않고 다른 위치를 선택하는 것이 좋습니다. CUSEREXITS의 경우 LD_LIBRARY_PATH 환경 변수를 다른 위치로 확장해야 합니다.

User Exit 구현 시기

Oracle GoldenGate 내에서 사용할 수 있는 열 변환 함수의 대안으로 또는 이와 함께 User Exit을 사용할 수 있습니다. User Exit은 데이터 추출 시 한 번, 변환 수행 시 한 번이 아니라 한 번(데이터 추출 시) 데이터만 처리하므로 내장 함수 대신 User Exit을 사용하는 것이 더 좋습니다.

다음은 User Exit을 구현할 수 있는 몇 가지 방법입니다.

• 한 테이블에서 다른 테이블로 매핑하는 동안 산술 연산, 날짜 변환 또는 테이블 조회를 수행합니다.

• 레코드 아카이브 기능을 오프라인으로 구현합니다.

• 전자 메일 메시지나 출력 값을 기반으로 페이지를 전송하는 등 사용자 정의 방식으로 비정상적인 데이터베이스 이벤트에 응답합니다.

• 총계를 누적하고 통계를 수집합니다.

• 레코드를 조작합니다.

• 부적합한 데이터를 복구합니다.

• 업데이트 전후 레코드의 순 차이를 계산합니다.

• 복합 기준에 따라 추출 또는 복제에 대한 레코드를 수락 또는 거부합니다.

• 변환 중에 데이터베이스를 정규화합니다.

Oracle GoldenGate 레코드 정보를 루틴에서 사용할 수 있도록 설정

대부분의 User Exit 처리 기준은 EXIT_CALL_PROCESS_RECORD 함수입니다. Extract의 경우 이 함수는 레코드 버퍼가 트레일로 출력되기 직전에 호출됩니다. Replicat의 경우 레코드가 대상에 적용되기 직전에 호출됩니다. 소스-대상 매핑이 매개변수 파일에 지정된 경우 매핑이 수행된 후 EXIT_CALL_PROCESS_RECORD 이벤트가 발생합니다.

EXIT_CALL_PROCESS_RECORD가 호출되면 레코드 버퍼 및 기타 레코드 정보를 콜백 루틴을 통해 사용할 수 있습니다. User Exit은 데이터 레코드를 사용하여 매핑, 변환, 정리 또는 기타 작업을 수행할 수 있습니다. 완료되면 User Exit은 Extract 또는 Replicat에서 레코드를 처리해야 하는지 아니면 무시해야 하는지를 나타내는 상태를 반환할 수 있습니다.

유저 종료 생성

다음 지침은 Windows 및 UNIX 시스템에서 User Exit을 만드는 데 도움이 됩니다. 이 지침에 설명된 매개변수 및 함수에 대한 자세한 내용은 Reference for Oracle GoldenGate for Windows and UNIX를 참조하십시오.

주: User Exit은 데이터베이스 객체 이름에 대해 대소문자를 구분합니다. 이름은 호스팅 데이터베이스에 정의된 대로 정확하게 반환됩니다. 객체 이름은 정규화되어야 합니다.

사용자 종료를 생성하려면

1. C 코드에서 공유 객체(UNIX 시스템) 또는 DLL(Windows)을 만들고 Replicat에서 호출할 루틴을 만들거나 내보냅니다. 이 루틴은 Oracle GoldenGate와 루틴 간의 통신 지점입니다. 원하는 대로 루틴 이름을 지정합니다. 루틴은 다음 Oracle GoldenGate 사용자 종료 매개변수를 받아들여야 합니다.

   • EXIT_CALL_TYPE: 처리 중 루틴이 호출되는 시기를 나타냅니다.

   • EXIT_CALL_RESULT: 루틴에 대한 응답을 제공합니다.

   • EXIT_PARAMS: 루틴에 정보를 제공합니다. 이 함수를 사용하면 TABLE 또는 MAP 문의 EXITPARAM 옵션을 사용하여 리터럴 문자열인 매개변수를 User Exit에 전달할 수 있습니다. 이는 특정 레코드를 처리하기 위한 종료 호출 중에만 유효합니다. 또한 이 함수를 사용하면 종료 호출 시작 시 CUSEREXIT 매개변수의 PARAMS 옵션으로 지정된 매개변수를 전달할 수 있습니다.

2. 소스 코드에 usrdecs.h 파일을 포함합니다. usrdecs.h 파일은 User Exit API에 대한 include 파일입니다. 유형 정의, 반환 상태 값, 콜백 함수 코드 및 기타 여러 정의를 포함합니다. usrdecs.h 파일은 Oracle GoldenGate 디렉토리 내에 설치됩니다. 이 파일은 수정하지 마십시오.

3. 해당되는 경우 User Exit에 Oracle GoldenGate 콜백 루틴을 포함합니다. 콜백 루틴은 레코드 및 응용 프로그램 컨텍스트 정보를 검색하고 데이터 레코드의 내용을 수정합니다. 콜백 루틴을 구현하려면 공유 객체에서 ERCALLBACK 함수를 사용합니다. 유저 콜백 루틴은 콜백 루틴에 전달되는 함수 코드에 따라 다르게 동작합니다.

ERCALLBACK (*function_code*, *buffer*, *result_code*);

Where:

- *function_code* is the function to be executed by the callback routine.

- *buffer* is a void pointer to a buffer containing a predefined structure associated with the specified function code.

- *result_code* is the status of the function that is executed by the callback routine. The result code that is returned by the callback routine indicates whether or not the callback function was successful.

- On Windows systems, Replicat export the `ERCALLBACK` function that is to be called from the user exit routine. The user exit must explicitly load the callback function at run-time using the appropriate Windows API calls.

1. Replicat 매개변수 파일에 CUSEREXIT 매개변수를 포함합니다. 이 매개변수는 공유 객체 또는 DLL의 이름과 Replicat에서 호출될 익스포트된 루틴의 이름을 받아들입니다. 공유 객체 또는 DLL의 전체 경로를 지정하거나 운영 체제의 표준 검색 전략이 공유 객체를 찾도록 할 수 있습니다.

CUSEREXIT {*DLL* | *shared_object*} *routine*
[, INCLUDEUPDATEBEFORES]
[, PARAMS '*startup_string*']

Where:

- *DLL* is a Windows DLL and *shared_object* is a UNIX shared object that contains the user exit function.

- `INCLUDEUPDATEBEFORES` gets before images for `UPDATE` operations.

- `PARAMS `*'startup_string'* supplies a startup string, such as a startup parameter.

예제 9-41 기본 구문 예, UNIX

CUSEREXIT eruserexit.so MyUserExit

예 9-42 기본 구문 예, Windows

CUSEREXIT eruserexit.dll MyUserExit

User Exit에서 문자 집합 변환 지원

데이터 무결성을 유지하려면 User Exit에서 Oracle GoldenGate 프로세스와 교환하는 문자 유형 데이터의 문자 집합을 이해해야 합니다. Oracle GoldenGate User Exit 논리는 다음에 대한 전역화 지원을 제공합니다.

• 카탈로그, 스키마, 테이블 및 열의 이름과 같은 문자 기반 데이터베이스 메타 데이터

• 문자열 기반 숫자, 날짜-시간 및 간격은 물론 CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2, NCLOB 등의 문자 유형 열의 값입니다.

문자 집합을 적절하게 변환하면 데이터베이스 및 Character Set의 한 유형에서 다른 유형으로 열 데이터를 비교, 조작, 변환 및 매핑할 수 있습니다. 이 처리의 대부분은 EXIT_CALL_PROCESS_RECORD 호출 유형이 호출되고 레코드 버퍼 및 기타 레코드 정보가 콜백 루틴을 통해 제공될 때 수행됩니다.

User Exit에는 고유한 세션 문자 집합이 있습니다. 이는 GET_SESSION_CHARSET 및 SET_SESSION_CHARSET 콜백 함수에 의해 정의됩니다. User Exit의 문자 집합이 프로세스의 호스팅 컨텍스트와 다른 경우 호출자 프로세스는 문자 집합 간의 변환을 제공합니다.

User Exit에서 이 지원을 사용으로 설정하려면 GET_DATABASE_METADATA 콜백 함수 코드가 있습니다. 이 기능을 사용하면 User Exit에서 호출하는 프로세스(Extract, Data Pump, Replicat)와 교환하는 문자 유형 데이터의 로케일 및 문자 집합과 같은 데이터베이스 메타 데이터를 가져올 수 있습니다. 또한 데이터베이스에서 객체 이름의 대소문자를 구분하는 방법, 따옴표로 묶인 이름과 따옴표로 묶이지 않은 이름을 처리하는 방법 및 객체 이름을 저장하는 방법을 반환합니다.

이러한 구성요소에 대한 자세한 내용은 Windows 및 UNIX용 Oracle GoldenGate 참조를 참조하십시오.

매크로를 사용하여 이름 메타 데이터 확인

User Exit API에 의해 전달되는 객체 이름은 User Exit 세션 Character Set에 인코딩된 이름과 데이터베이스에서 검색된 이름과 정확히 동일합니다. User Exit에서 객체 이름을 리터럴 문자열과 비교하는 경우 User Exit은 데이터베이스 로케일을 검색한 다음 문자열을 정규화하여 동일한 인코딩의 객체 이름과 비교해야 합니다.

Oracle GoldenGate는 데이터베이스 객체 이름의 메타데이터를 확인하기 위해 User Exit에서 호출할 수 있는 다음과 같은 매크로를 제공합니다. 예를 들어, 매크로는 따옴표로 묶인 테이블 이름이 대소문자를 구분하는지 여부와 대소문자가 혼합된 상태로 데이터베이스 서버에 저장되는지 여부를 확인하는 데 사용할 수 있습니다. 이러한 매크로는 usrdecs.h 파일에 정의되어 있습니다.

표 20 메타데이터 검사를 위한 매크로

Macro	검증 대상
supportsMixedCaseIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 따옴표로 묶이지 않은 이름을 대소문자를 구분하여 취급하고 이름을 대소문자를 혼합하여 저장할지 여부입니다.
supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )	데이터베이스가 지정된 데이터 유형의 대소문자 혼합 따옴표로 묶인 이름을 대소문자를 구분하여 처리하고 이름을 대소문자를 혼합하여 저장할지 여부입니다.
storesLowerCaseIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자가 혼합된 따옴표로 묶이지 않은 이름을 대소문자를 구분하지 않고 이름을 소문자로 저장할지 여부입니다.
storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자 혼합 따옴표로 묶인 이름을 대소문자를 구분하지 않고 이름을 소문자로 저장할지 여부입니다.
storesMixedCaseIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자가 혼합된 따옴표로 묶이지 않은 이름을 대소문자를 구분하지 않고 이름을 대소문자를 혼합하여 저장할지 여부입니다.
storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자 혼합 따옴표로 묶인 이름을 대소문자를 구분하지 않고 이름을 대소문자를 혼합하여 저장할지 여부입니다.
storesUpperCaseIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자가 혼합된 따옴표로 묶이지 않은 이름을 대소문자를 구분하지 않고 이름을 대문자로 저장할지 여부입니다.
storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )	데이터베이스가 지정된 데이터 유형의 대소문자가 혼합된 따옴표로 묶인 이름을 대소문자를 구분하지 않고 이름을 대문자로 저장할지 여부입니다.

문자 형식 설명

입력 매개변수 column_value_mode 는 처리되고 있으며 여러 함수 코드에서 사용되는 데이터의 문자 형식을 설명합니다. 다음 표에서는 데이터 유형별 EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT 및 EXIT_FN_CNVTED_SESS_FORMAT 형식 코드의 의미를 설명합니다.

표 21 column_value_mode_matrix 의미

데이터 유형	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
CHAR "abc"	2바이트 널 표시기 + 2바이트 길이 정보 + 열 값입니다. 0000 0004 61 62 63 20	"abc"는 ASCII 또는 EBCDIC로 인코딩됩니다. NULL 종료됨. 테일링 공간은 잘립니다.	User Exit 세션 문자 집합에 "abc"가 인코딩되었습니다. NOT NULL 종료됨. GLOBALS 매개변수 NOTRIMSPACES가 지정되지 않은 경우 테일링 공백은 기본적으로 잘립니다.
NCHAR 0061 0062 0063 0020	2바이트 널 표시기 + 2바이트 길이 정보 + 열 값입니다. 0000 0008 00 61 0062 0063 0020	NCHAR가 UTF-8로 처리되는지 여부에 따라 "abc"(UTF8로 인코딩됨) 또는 첫번째 바이트에서 잘림 NULL 종료됨. 후행 공백이 잘립니다.	User Exit 세션 문자 집합에 "abc"가 인코딩되었습니다. NOT NULL 종료됨. GLOBALS 매개변수 NOTRIMSPACES가 지정되지 않은 경우 테일링 공간은 기본적으로 잘립니다.
VARCHAR2 "abc"	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	"abc"는 ASCII 또는 EBCDIC로 인코딩됩니다. NULL 종료됨. 자르기 없음.	User Exit 세션 문자 집합에 "abc"가 인코딩되었습니다. NOT NULL 종료됨. 자르기 없음.
NVARCHAR2 0061 0062 0063 0020	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	NVARCHAR2가 UTF-8로 처리되는지 여부에 따라 "abc"(UTF8로 인코딩됨) 또는 첫번째 바이트에서 잘림 NULL 종료됨. 자르기 없음.	User Exit 세션 문자 집합에서 "abc"로 인코딩되었습니다. NOT NULL 종료됨. 자르기 없음.
CLOB	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	VARCHAR2과 유사하지만 최대 4K바이트까지 출력됩니다. NULL 종료됨. 자르기 없음.	VARCHAR2와 비슷하지만 사용자 종료 세션 문자 집합에서 요청된 출력 데이터만 있습니다. NOT NULL 종료됨. 자르기 없음.
NCLOB	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	NVARCHAR2과 유사하지만 최대 4K바이트까지 출력됩니다. NULL 종료됨. 자르기 없음.	NVARCHAR2와 비슷하지만 사용자 종료 세션 문자 집합에서 요청된 출력 데이터만 있습니다. NOT NULL 종료됨. 자르기 없음.
NUMBER 123.89	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	"123.89"는 ASCII 또는 EBCDIC로 인코딩되었습니다. NULL 종료됨.	"123.89"는 User Exit 세션 문자 집합으로 인코딩되었습니다. NOT NULL 종료됨.
DATE 31-May-11	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	"2011-05-31"는 ASCII 또는 EBCDIC로 인코딩됩니다. NULL 종료됨.	"2011-05-31"은 User Exit 세션 문자 집합으로 인코딩되었습니다. NOT NULL 종료됨.
TIMESTAMP 31-May-11 12.00.00 AM	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	"2011-05-31 12.00.00 AM"은 ASCII 또는 EBCDIC로 인코딩되었습니다. NULL 종료됨.	User Exit 세션 문자 세트에 "2011-05-31 12.00.00 AM"이 인코딩되었습니다. NOT NULL 종료됨.
Interval Year to Month or Interval Day to Second	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	해당 사항 없음	해당 사항 없음
RAW	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	2바이트 널 표시기 + 2바이트 길이 정보 + 열값	2바이트 널 표시기 + 2바이트 길이 정보 + 열값

User Exit 업그레이드

usrdecs.h 파일은 새 함수 또는 구조적 변경과 같은 향상된 기능이나 업그레이드가 새 Oracle GoldenGate 릴리스에 추가될 때 기존 User Exit과의 역호환성을 허용하도록 버전 지정됩니다. usrdecs.h 파일의 버전은 Replicat 또는 Extract 시작 시 보고서 파일에 인쇄됩니다.

새 User Exit 기능을 사용하려면 새 usrdecs 파일을 포함하도록 루틴을 재컴파일해야 합니다. 새 피쳐를 사용하지 않는 루틴은 다시 컴파일할 필요가 없습니다.

User Exit 함수 사용 방법 예제 보기

Oracle GoldenGate는 Oracle GoldenGate 설치 디렉토리의 UserExitExamples 디렉토리에 다음 샘플 User Exit 파일을 설치합니다.

• exitdemo.c는 User Exit을 초기화하고, 지정된 종료 지점에서 콜백을 실행하고, 데이터를 수정하는 방법을 보여줍니다. 또한 카탈로그나 컨테이너의 이름, 스키마 또는 정규화되지 않은 테이블 이름과 같은 정규화된 테이블 이름이나 특정 메타 데이터 부분을 검색하는 방법을 보여줍니다. 또한 이 데모에서는 DDL 데이터를 처리하는 방법을 보여줍니다. 데모는 특정 데이터베이스 유형에만 적용되는 것은 아닙니다.

• exitdemo_utf16.c는 User Exit과 호출자 프로세스 간에 교환되는 정보에 대해 콜백 구조에서 UTF16로 인코딩된 데이터(메타 데이터 및 열 데이터 모두)를 사용하는 방법을 보여줍니다.

• exitdemo_more_recs.c는 동일한 입력 레코드를 여러 번 사용하여 여러 대상 레코드를 생성하는 방법의 예를 보여줍니다.

• exitdemo_lob.c는 LOB 데이터에 대한 읽기 액세스 권한을 얻는 방법의 예를 보여줍니다.

• exitdemo_pk_befores.c는 기본 키 업데이트 레코드의 이전 및 이후 이미지 부분과 정기 업데이트의 이전 이미지(비키 업데이트)에 액세스하는 방법을 보여줍니다. 또한 충돌 감지를 위한 수단으로 Replicat 매개변수 파일에서 SQLEXEC를 사용하여 대상 행 값을 가져오는 방법을 보여줍니다. 대상에서 가져온 결과 값은 User Exit에 들어갈 때 대상 레코드로 매핑됩니다.

각 디렉토리에는 *.c 파일과 makefiles 및 readme.txt 파일이 포함됩니다.