JetRetrieveColumns 함수

아티클
06/12/2023

적용 대상: Windows | Windows Server

JetRetrieveColumns 함수

JetRetrieveColumns 함수는 단일 작업에서 현재 레코드에서 여러 열 값을 검색합니다. JET_RETRIEVECOLUMN 구조체의 배열은 검색할 열 값 집합을 설명하고 검색할 각 열 값에 대한 출력 버퍼를 설명하는 데 사용됩니다.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

매개 변수

sesid

이 호출에 사용할 세션입니다.

tableid

이 호출에 사용할 커서입니다.

pretrievecolumn

하나 이상의 JET_RETRIEVECOLUMN 구조체 배열에 대한 포인터입니다. 각 구조체에는 검색할 열 값과 반환된 데이터를 저장할 위치에 대한 설명이 포함됩니다.

cretrievecolumn

pretrievecolumn에서 지정된 배열의 JET_RETRIEVECOLUMN 구조체 수입니다.

반환 값

이 함수는 다음 반환 코드 중 하나를 사용하여 JET_ERR 데이터 형식을 반환합니다. 가능한 ESE 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.

반환 코드	설명
JET_errSuccess	작업이 성공적으로 완료되었습니다.
JET_errBadItagSequence	pretinfo-itagSequence>에서 잘못된 다중값 열 시퀀스 번호 값이 전달되었습니다. 다중값 열 값 시퀀스 번호의 유효한 값은 1 이상입니다. 값 0은 이 함수에 유효하지만 JetRetrieveColumn에는 유효하지 않습니다.
JET_errBadColumnId	지정된 열 ID가 열 ID의 법적 한도를 벗어났습니다.
JET_errClientRequestToStopJetService	JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다.
JET_errColumnNotFound	지정된 columnid 에서 설명하는 열이 테이블에 없습니다.
JET_errIndexTuplesCannotRetrieveFromIndex	부분 문자열로 인덱싱된 열은 일반적으로 각 인덱스 항목에 열의 작은 부분만 있기 때문에 인덱스에서 검색할 수 없습니다.
JET_errInvalidBufferSize	경우에 따라 열 값의 양을 반환하기 위해 검색 열에 지정된 버퍼의 크기를 충분히 조정해야 합니다. 예를 들어 에스크로 업데이트 가능한 열은 호출 세션의 트랜잭션 컨텍스트에 맞게 일관되도록 조정되며, 이 조정을 수행하려면 호출자가 제공하는 버퍼가 필요합니다. 버퍼 공간이 부족한 경우 JET_errInvalidBufferSize 반환되고 열 데이터가 반환되지 않습니다.
JET_errInvalidgrbit	제공된 옵션은 알 수 없거나 알려진 비트 설정의 잘못된 조합입니다.
JET_errInvalidParameter	지정된 매개 변수 중 하나 이상이 잘못되었습니다. 이는 retinfo.cbStruct가 JET_RETINFO 크기가 작은 경우에 발생할 수 있습니다.
JET_errInstanceUnavailable	세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errNoCurrentRecord	커서가 레코드에 배치되지 않습니다. 오류는 다양한 이유로 발생할 수 있습니다. 예를 들어 커서가 현재 인덱스의 마지막 레코드 뒤에 현재 위치하는 경우 이 문제가 발생합니다.
JET_errNotInitialized	세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다.
JET_errRestoreInProgress	세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다.
JET_errSessionSharingViolation	동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errTermInProgress	세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다.
JET_wrnBufferTruncated	지정된 버퍼가 열 크기보다 작기 때문에 전체 열 값을 검색할 수 없습니다.

성공하면 열 데이터와 열 크기는 JET_RETRIEVECOLUMN 구조의 배열에 설명된 제공된 버퍼에 반환됩니다. 열 데이터 대신 다중값 필드의 인스턴스 수가 필요했음을 나타내기 위해 itagSequence 를 0으로 설정한 경우 다중값 열의 인스턴스 수가 itagSequence 필드 자체에 반환됩니다. 각 JET_RETRIEVECOLUMN 구조에는 검색된 열에 대한 경고가 포함된 오류 필드가 있습니다. 열 값이 NULL 이면 오류 코드가 JET_wrnColumnNull 설정됩니다.

오류가 발생한 경우 커서 위치는 변경되지 않고 제공된 버퍼에 데이터가 복사되지 않습니다.

설명

JetRetrieveColumns 는 JetRetrieveColumn 이 지원하지 않는 하나의 기능을 지원합니다. 다중값 열의 인스턴스 수를 검색하는 기능입니다. 이 기능의 목적은 애플리케이션이 열의 모든 값을 검색할 수 있도록 하는 것입니다. 이 작업은 먼저 열에 있는 값의 수를 결정하여 수행할 수 있습니다. 다음으로, 각 값에 할당된 하나의 JET_RETRIEVECOLUMN 구조로 JetRetrieveColumns를 다시 호출하여 열 데이터의 길이를 확인하여 길이를 확인할 수 있습니다. 이 작업은 cbMax가 0인 NULLpvData 포인터를 전달하고 cbActual에서 열 길이를 검색하여 수행할 수 있습니다. 세 번째 및 마지막 호출은 열 값 데이터에 할당된 메모리를 사용하여 수행할 수 있습니다.

길이 버퍼가 부족하여 검색된 열이 잘리면 API는 JET_wrnBufferTruncated 반환합니다. 그러나 JET_wrnColumnNull 다른 오류는 JET_RETRIEVECOLUMN 오류 필드에만 반환됩니다. 그 이유는 애플리케이션이 종종 모든 데이터가 검색되었는지 확인하고 JetRetrieveColumns 에서 이 오류를 반환하면 이러한 이해를 용이하게 하기 때문입니다.

요구 사항

요구 사항	값
클라이언트	Windows Vista, Windows XP 또는 Windows 2000 Professional이 필요합니다.
서버	Windows Server 2008, Windows Server 2003 또는 Windows 2000 Server가 필요합니다.
머리글	Esent.h에 선언되었습니다.
라이브러리	ESENT.lib를 사용합니다.
DLL	ESENT.dll 필요합니다.

참고 항목

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns

JetRetrieveColumns 함수