glo 클래스는 CUBRID의 CALL METHOD 문으로 호출하여 사용한다. glo 클래스에서는 클래스 메소드와 인스턴스 메소드가 운영된다.
glo 클래스에 정의된 두 메소드는 클래스의 인스턴스보다는 클래스 객체를 운영하는 데에 사용된다.
glo 인스턴스 메소드는 glo 데이터를 조작하기 위한 접근, 갱신 기능을 제공한다. 메소드의 인수(데이터 버퍼 등)는 CSQL 프로세서에서 명시할 수 없기 때문에 대부분의 인스턴스 메소드는 Java나 C와 같은 프로그래밍 언어 인터페이스에서 사용한다.
이 메소드는 glo 인스턴스의 FBO (File Based Object) 타입을 생성한다. 메소드의 인수 값은 단일 문자열의 파일 경로이다. new_fbo( ) 메소드가 성공적으로 수행되면, 요청한 클래스의 새로운 인스턴스가 반환된다. FBO를 생성하기 위한 new_fbo( ) 메소드의 문법은 다음과 같다.
CALL new_fbo(:pathname)
ON CLASS glo INTO :write_object;
new_fbo( ) 클래스 메소드의 파일 경로명으로 환경 변수를 사용할 수도 있다. 따라서 서로 다른 파일 시스템을 사용하는 클라이언트가 동일한 FBO에 접속하는 것도 가능하다.
예를 들어, 다음과 같이 FBO 파일 경로를 주고, 어떤 사용자는 FBO_ROOT의 값을 ”/usr/local”로 설정하고 다른 사용자는 ”/net/edsel/usr/local”로 설정할 수 있다.
csql>CALL new_fbo(’$FBO_ROOT/test/fbo1.txt’)
ON CLASS glo INTO :fbo;
파일 경로는 CUBRID 환경 변수인 CUBRID_FBO_PREFIX를 수정하여 사용할 수도 있다. CUBRID_FBO_PREFIX 변수에 값을 설정하면 파일에 접근할 때 모든 FBO 파일 경로명 앞에 붙는다. 이미 파일 경로명에 환경 변수 참조가 포함되어 있으면, 변수의 값이 앞에 붙지 않는다.
예를 들어, 다음의 경우 FBO 파일에 접근하는 경로명은 "h:/remote1/usr/local/test/fbo1.txt"이다.
%setenv CUBRID_FBO_PREFIX ”h:/remote1”
csql>CALL new_fbo(’/usr/local/test/fbo1.txt’)
ON CLASS glo INTO :fbo;
NFS가 루트 파일 시스템이나 특정 서브 디렉토리에 마운트되고, 파일 경로명이 같다면, UNIX와 PC 클라이언트 모두 FBO의 내용에 접근할 수 있다. 위의 예에서, UNIX 시스템에서는 CUBRID_FBO_PREFIX 변수에 값이 없고, PC에서는 변수에 NFS 볼륨 식별자 ”h:/remote1”를 명시해야 한다.
이 메소드는 glo 인스턴스의 LO (Large Object)를 생성한다. 함수 인수는 없다. new_lo( ) 메소드는 원하는 클래스에 새로운 인스턴스를 반환한다.
csql>CALL new_lo()ON CLASS glo INTO :labeled_object;
이 메소드는 새로운 LO 인스턴스를 생성하거나 외부 파일로부터 그 내용을 초기화한다. 메소드 인수가 NULL이면 비어있는 LO를 생성하고, 메소드 인수가 파일명을 포함하는 문자열이면 새로운 인스턴스 생성 후 해당 파일의 내용을 복사하게 된다.
csql>CALL new_lo_import(’./import_data.txt’)
ON CLASS glo INTO :labeled_object;
이 메소드는 glo 클래스의 새로운 인스턴스를 생성할 때마다 new_lo( ) / new_fbo( ) 클래스 메소드에 의해 자동으로 호출된다. glo 클래스에서 기본 값으로 속성을 설정한다. glo 클래스로부터 상속받은 클래스는 다른 기본 속성을 설정하거나, 다른 연산을 수행하도록 initialize_data( ) 메소드를 재정의할 수 있다. 이 메소드는 일반적으로 사용자에 의해 호출되지 않으므로 인수가 없으면 무시된다.
이 메소드는 glo 인스턴스 메소드에 의해 사용되는 glo 데이터 구역의 시작 위치를 반환한다. 다음은 glo 인스턴스로부터 현재 위치를 반환한다.
csql>CALL data_pos() ON :labeled_object INTO :location;
이 메소드는 첫 번째 인수 값을 현재 위치로 설정한다. data_seek( ) 메소드가 성공적으로 수행되면 새로운 위치가 반환된다. 다음은 data_seek( ) 메소드를 사용하여 glo 데이터 구역에서 현재 위치를 42로 설정하는 예이다.
csql>CALL data_seek(42) ON :labeled_object;
이 메소드는 glo로부터 사용자 데이터 버퍼로 데이터를 전송한다. 데이터는 glo 데이터 내의 현재 위치부터 시작하여 읽게 된다. read_data( ) 메소드의 인수는 두 개이다. 첫 번째 인수는 상수로 glo로부터 읽어 들일 유닛의 개수를 명시하고, 두 번째 인수는 문자열로 데이터를 저장할 버퍼를 나타낸다. 메소드가 성공적으로 실행되면, 읽어 들인 실제 유닛의 개수와 glo로부터 읽어 들인 데이터를 반환한다. 현재 위치는 자동적으로 갱신된다. 다음은 read_data( ) 메소드를 사용한 C API 예이다. glo 데이터의 현재 위치로부터 1024개의 유닛을 읽어 들이고, 문자 배열 버퍼에 데이터를 전송한다.
...
DB_INT32 rc, length = 1024;
DB_OBJECT *read_object;
char buffer[1024];
DB_VALUE val1, val2, val3;
...
DB_MAKE_INTEGER(&val1, length);
DB_MAKE_VARCHAR(&val2, DB_MAX_VARCHAR_PRECISION, buffer, length);
rc = db_send(read_object, GLO_METHOD_READ, &val3, &val1, &val2);
...
참고 read_data( ) 메소드는 리턴 값이 반드시 문자 버퍼에 저장되어야 하기 때문에 CSQL에서 사용되는 것이 지원되지 않는다. 따라서 JDBC나 C API를 통해서만 사용이 가능하다.
이 메소드는 사용자 데이터 버퍼로부터 glo로 데이터를 전송한다. 쓰기는 데이터가 존재하는 경우 glo 데이터의 현재 위치로부터 덮어쓰기를 한다. write_data( ) 메소드의 인수는 두 개이다. 첫 번째 인수는 glo에 저장할 유닛의 수(정수)이고 두 번째 인수는 저장될 데이터를 포함하고 있는 버퍼(문자열)이다. 실제 저장된 유닛의 개수를 반환하고, glo 데이터 내의 현재 위치는 자동으로 갱신된다. 다음은 write_data( ) 메소드를 이용한 예이다. LO를 만들고 데이터를 저장한다.
csql>CALL new_lo() ON CLASS glo INTO :wr_lo
csql>CALL write_data(8,’raw data’) TO :wr_lo;
이 메소드는 사용자 데이터 버퍼로부터 glo 내로 데이터를 삽입한다. 데이터는 현재 위치에 의해 정의된 위치를 시작으로 하여 삽입된다. insert_data( ) 메소드의 인수는 두 개이다. 첫 번째 인수는 glo로 삽입될 데이터의 유닛에 상응하는 정수이고, 두 번째 인수는 삽입될 데이터를 포함하고 있는 버퍼이다.현재 위치는 자동으로 갱신되며, 다음 연산이 시작될 위치를 나타내게 된다. insert_data( )가 성공적으로 수행되면 glo로 입력된 데이터의 양이 반환된다.
csql>CALL insert_data(3,’end’) ON :wr_lo;
이 메소드는 현재 위치에서 시작하는 glo 데이터를 삭제한다. 메소드는 첫 번째 인수에 명시된 수만큼의 유닛을 제거한다. 삭제가 성공하면 제거된 유닛의 수가 반환된다. 삭제할 유닛의 수가 glo 데이터의 끝부분을 넘어가면 시스템은 절단(truncate)을 수행하고, 실제로 제거된 유닛의 수를 반환한다. 데이터가 삭제될 때 현제 위치는 변하지 않는다. data_size( ) 호출 후에 delete_data( )를 호출하면 할당된 바이트 수가 출력된다. 다수의 삭제와 삽입 후에는 glo의 조각 모으기를 위해 compress_data( ) 메소드를 호출해야 한다.
csql>CALL delete_data(3) ON :wr_lo;
이 메소드는 현재 위치에서부터 glo 데이터의 끝까지 모든 데이터를 제거한다. truncate_data( ) 메소드는 인수가 없다. 성공적으로 절단이 수행되면 삭제된 유닛의 수가 반환된다.
csql> call truncate_data() on :wr_lo into :num_deleted
이 메소드는 glo 데이터의 끝 부분에 데이터를 추가한다. 메소드의 인수는 두 개이다. 첫 번째 인수는 추가할 유닛의 수를 명시한다. 두 번째 인수는 추가될 데이터를 가지고 있는 버퍼이다. 추가 연산이 성공적으로 수행되면 추가된 유닛의 수가 반환된다. 현재 위치는 추가된 glo 데이터의 끝으로 자동 갱신된다.
csql>call append_data( 14, 'appended_data' ) on :wr_lo
이 메소드는 glo가 가지고 있는 모든 유닛의 개수를 반환한다. 갱신 메소드를 이용하여 glo에 데이터를 추가하거나 삭제할 수 있기 때문에 데이터의 크기는 변할 수 있다. 메소드의 사용 예는 다음과 같으며, 유닛의 총 개수는 total_units 변수에 저장되어 반환된다
csql>call data_size () on :wr_lo
이 메소드는 좀 더 효과적인 공간 사용을 위해 LO 데이터를 재구성한다. compress_data( ) 메소드는 다수의 delete( ) 또는 insert( ) 메소드 수행 후에 호출할 것을 권장한다. 메소드가 성공적으로 수행되면 0이 반환되고, 실패하면 0보다 작은 값이 반환된다.
csql>CALL compress_data() ON :wr_lo;
다수의 삭제와 삽입 후에는 compress_data( ) 를 수행하여 glo 조각 모으기를 해야 한다.
이 메소드는 glo 데이터를 제거한다. 메소드는 size 속성, 현재 위치, header_size 속성을 모두 0으로 설정한 후 완료된다. 메소드가 성공적으로 수행되면 0을 반환하고, 그렇지 않으면 -1을 반환한다.
csql>CALL destroy_data() ON :wr_lo;
이 메소드는 데이터 원본(파일 또는 다른 glo 인스턴스)에서 glo 내로 데이터를 복사한다. copy_from( ) 메소드의 인수로는 파일 경로명을 가지는 문자열이나, 다른 glo 인스턴스가 사용될 수 있다. 메소드가 성공적으로 수행되면 기존의 glo 인스턴스에 덮어쓰기를 하고, 새로운 glo의 크기를 반환한다.
csql>CALL new_lo() ON CLASS glo INTO :lob;
csql>CALL copy_from(‘test.txt’)
ON :lob INTO :size;
참고 glo를 더 작은 데이터를 포함하는 새로운 파일로 덮어쓸 때, glo의 마지막에 원치 않는 데이터를 삭제하기 위해 truncate_data( )를 호출하지 않는다면, 그 결과로 glo 객체는 원래 크기를 계속 유지하게 된다.
이 메소드는 glo 데이터로부터 파일이나 다른 glo로 데이터를 복사한다. copy_to( ) 메소드는 파일 경로명을 나타내는 문자열이나, 다른 glo 인스턴스를 인수로 갖는다. 메소드가 성공적으로 수행되면 복사된 데이터의 크기가 반환된다.
csql>CALL copy_to(‘extract.txt’) ON :lob INTO :size_value;
이 메소드는 glo 인스턴스가 FBO일 경우에 경로명을 반환한다. glo 인스턴스가 LO이면 NULL을 반환한다. 이 메소드는 인수를 갖지 않는다. 다음 예에서 glo가 FBO이면 파일 경로명을, LO이면 NULL을 file_name 변수에 저장하여 반환한다.
csql> CALL glo_pathname() ON :fbo INTO :file_name;
에러 발생시 에러 원인에 따른 값을 반환한다. 다음은 get_error( )가 반환하는 에러 값이다.
INVALID_STRING_INPUT_ARGUMENT -2 /* bad input argument */
INVALID_INTEGER_INPUT_ARGUMENT -3 /* bad input argument */
INVALID_STRING_OR_OBJ_ARGUMENT -4 /* bad input argument */
INVALID_OBJECT_INPUT_ARGUMENT -5 /* bad input argument */
UNABLE_TO_FIND_GLO_STRUCTURE -6 /* internal error */
COULD_NOT_ACQUIRE_WRITE_LOCK -7 /* object already locked*/
ERROR_DURING_TRUNCATION -8 /* truncation error */
ERROR_DURING_DELETE -9 /* delete error */
ERROR_DURING_INSERT -10 /* insert error */
ERROR_DURING_WRITE -11 /* write error */
ERROR_DURING_READ -12 /* read error */
ERROR_DURING_SEEK -13 /* seek error */
ERROR_DURING_APPEND -14 /* append error */
ERROR_DURING_MIGRATE -15 /* migrate error */
COPY_TO_ERROR -16 /* copy to error */
COPY_FROM_ERROR -17 /* copy from error */
COULD_NOT_ALLOCATE_SEARCH_BUFFERS -18 /* search error */
COULD_NOT_COMPILE_REGULAR_EXPRESSION -19 /* reg exp error */
COULD_NOT_RESET_WORKING_BUFFER -20 /* search error */
get_error( ) 메소드의 예는 다음과 같다.
csql>CALL get_error() ON :fbo INTO :error_value;
사용자에 의해 glo 클래스 계층이 확장된 경우 set_error( ) 메소드를 이용하여 get_error( ) 메소드에서 반환하는 에러 값을 추가할 수 있다.
csql> CALL set_error(:user_method_error) ON :fbo;