as_DBMOpenIndexScanCategory

as_DBMOpenIndexScanCategory

Description
인덱스를 이용해 특정 키값과 match되는 해당 Category의 레코드 위치로부터 레코드들을 검색하기 위한 스캔 관리자를 초기화한다.

Syntax
DBMErr as_DBMOpenIndexScanCategory(TableId tableId, CatId catId, IndexFlag indexFlag, FieldData *keyData, ScanId* scanId,);

Parameters

tableId	테이블의 ID
indexFlag	사용할 인덱스를 지정 DBM_PRIM : primary index DBM_SEC : secondary index
keyData	인덱스 검색을 위한 키 값에 대한 정보
scanId	open된 스캔 ID

Returns

value	설명
DBM_OK	성공적으로 수행된 경우
DBM_TOO_MANY_SCANS	이미 open된 스캔의 수가 NUM_SCANS인 경우
DBM_INVALID_TABLE_ID	주어진 테이블 id를 갖는 테이블이 존재하지 않는 경우
DBM_INVALID_FLAG	indexFlag가 DBM_PRIM도 DBM_SEC도 아닌 경우
DBM_SECONDARY_INDEX_NOT_EXIST	indexFlag==DBM_SEC이고 secondary index가 존재하지 않는 경우
DBM_INVALID_KEY_DATA	keyData.id라는 id를 가지는 필드가 테이블 스키마에 없는 경우, keyData.type이 스키마와 일치하지 않는 경우 keyData.type이 blob field 인 경우 keyData.len이 적절하지 않은 경우 (0 < keyData.len <= PATTERN_LEN이어야 함)
DBM_DB_NOT_INITED	데이타베이스가 초기화되어 있지 않은 경우

Comments
primary나 secondary 인덱스를 사용하여 레코드를 검색한다.
주어진 키 값과 match되는 최초의 레코드부터 검색하게 된다.

검색하려는 키 값이 숫자일 때는 exact match되는 레코드를 검색하고, 문자열일 때는 prefix match 되는 레코드를 검색한다.

매개변수에서 사용되는 keyData의 자료구조는 다음과 같다.
typedef struct {

FieldId	id;	/* 사용하지 않는다 */
FieldDataType	type;
S32	len;	/* 문자열 필드의 경우에만 사용 */
union {
S16	int2val;
S32	int4val;
P_S8	str;	/* 끝에 .'\0'이 있어야 함 */
}content;

} FieldData;

또한 인덱스 스캔은 open시에는 일단 key 데이타와 match되는 최초의 레코드를 현재 레코드로 설정하지만, 이후as_DBMGetNextRecordId나 as_DBMGetPrevRecordId 함수를 통해 스캔 open시 설정된 key 데이타와 match되지 않는 레코드의 ID도 구할 수 있다.

스캔을 open한 이후, 최초로 호출되는 as_DBMGetNextRecordId 또는 as_DBMGetPrevRecordId는 주어진 키값과 match되는 처음 레코드 ID를 반환한다(match되는 레코드가 없을 때에는 키값보다 큰 레코드 중에서 최소값을 갖는 레코드 ID 반환).

키값(keyData.content.str)이 NULL('\0')인 경우 지원. 이러한 경우 처음 결과로 나오는 레코드는 필드값이 없는 레코드가 된다.

See Also
as_DBMGetNextRecordId, as_DBMGetPrevRecordId, as_DBMOpenIndexScanTable

Example
TableId tableId; ScanId scanId;
RecId recId; DBMErr ret=DBM_OK;
S32 numFields, numExistFields; FieldDataInfo *fieldDataInfo;
FieldData keyData, fieldData;
CatId catId;

// Get tableId, catId
// assign the key data for the primary index field
keyData.id=0;
keyData.type=DBM_STRING;
keyData.content.str = Lmalloc( strlen("keyString") + 1);
strcpy(keyData.content.str, "keyString" );
ret = as_DBMOpenIndexScanCategory( tableId, catId, DBM_PRIM, keyData, &scanId);
if( ret < DBM_OK ) // error handling
ret = as_DBMGetNumFieldsInTable(tableId, &numFields);
...
/* allocate space for fieldDataInfo */
fieldDataInfo =(FieldDataInfo*)Lmalloc( sizeof(FieldDataInfo) * numFields );
while( (ret = as_DBMGetNextRecordId( scanId, &recId, &numExistFields, fieldDataInfo) >= DBM_OK ) {
   if( ret == DBM_OK_MATCH )
   // process for the matched record with key string
   if( ret == DBM_OK_UNMATCH )
   // process for the unmatched record with key string
   ...
}