DBMOpenIndexScanCategory

DBMOpenIndexScanCategory

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

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

Parameters

tableId	테이블의 ID
indexFlag	사용할 인덱스를 지정
	DBM_PRIM : primary index
	DBM_SEC : secondary index
keyData	인덱스 검색을 위한 키 값에 대한 정보(DBM_STRING인 키검색일 경우, 키 문자열 길이가 PATTERN_LEN 이하여야 함)
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되는 최초의 레코드를 현재 레코드로 설정하지만, 이후 DBMGetNextRecordId나 DBMGetPrevRecordId 함수를 통해 스캔 open시 설정된 key 데이타와 match되지 않는 레코드의 ID도 구할 수 있다.

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

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

See Also
DBMGetNextRecordId, DBMGetPrevRecordId, 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 = DBMOpenIndexScanCategory( tableId, catId, DBM_PRIM, keyData, &scanId);
  if( ret < DBM_OK ) // error handling
  ret = DBMGetNumFieldsInTable(tableId, &numFields);
  ...
  /* allocate space for fieldDataInfo */
  fieldDataInfo =(FieldDataInfo*)Lmalloc( sizeof(FieldDataInfo) * numFields );
  while( (ret = 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
     ...
  }