VgwGetSchemaFnc


Use the VgwGetSchemaFnc function to return the schema for your repository. The Verity engine calls your VgwGetSchemaFnc function when a collection is opened or a document source is created.


Syntax

VdkError VgwGetSchemaFnc(
   VgwAppSession   vgwSession,
   VdkUser         vdkUser,
   VgwSchema*      pgwSchema)

Arguments

 


vgwSession

VgwAppSession   The session handle that contains session-related data, which was set in your driver’s VgwSessionNewFnc function.

vdkUser

VdkUser   A handle that identifies the user requesting access to this repository.

pgwSchema

VgwSchema*   A pointer to a VgwSchemaRec structure, which specifies the repository’s schema.


Member Descriptions

 

Table 4-1    VgwSchemaRec Members


Member

Type/Description

session

VgwAppSession   The session handle, which is passed in via the vgwSession argument.

batchLimit

VdkUint2   Internal.

columnCount

VdkUint2   The number of fields in the schema.

columnArray

VgwColumnInfo*   A pointer to an array of VgwColumnInfoRec structures that contain information about each field.

internal

VdkVoidp   For internal use by the gateway.


 

Table 4-2    VgwColumnInfoRec Members


Member

Type/Description

type

VdkFieldType   The field data type flag. Valid values are:

VdkFieldType_Invalid for unsupported field names

VdkFieldType_Text for text strings

VdkFieldType_Signed for signed integers

VdkFieldType_Unsigned for unsigned integers

VdkFieldType_Date for VdkDate type data

VdkFieldType_Float for double floats

VdkFieldType_Stream for a binary blob of data

name

VdkCString   Name of the external field.

size

VdkUint4   The data size, in bytes, or 0 for ASCIIZ (null-terminated strings).

flags

VdkInt2   Behavior flags, which are ORed together to specify how to treat this field when it is retrieved from the repository. You can set the following values:

VgwColumn_ReadOnly for field values that are not to be changed.

VgwColumn_Inline for fields that contain the actual value, not a pointer to the value.

VgwColumn_PrimaryKey for fields whose value is the primary key for the gateway; for example, the VdkVgwKey field should have this flag set

VgwColumn_RedirectFile for fields whose value is a the full pathname of a data file.

VgwColumn_Redirect_URL for fields whose value is a URL to a data file.

VgwColumn_Attachment for fields whose value is the full pathname to an attachment or subdocument.

internal

VdkVoidp   For internal use by the gateway.

precedence

VdkInt2   Internal.



Returns

This function must return one of the following error codes:

VdkSuccess for success

 

VdkError_* for a standard Verity Developer Kit API error as described in the Verity Developer’s Kit Programming Reference

 

VdkFail for a non-specific error

 


Discussion

Your VgwGetSchemaFnc function must populate a VgwSchema structure with the external fields that the specified user is allowed to access and assign the structure to pgwSchema. External fields exist in the repository but not in the collection.

A field name must be a 7-bit ASCIIZ alphanumeric string that is less than 64 bytes long. You can construct field names from the following characters:

unaccented alphabetic characters, a-z and A-Z

 

digits, 0-9

 

underscores ( _ )

 

periods ( . )

 

Field names cannot begin with an underscore and cannot end with _OF, _SZ, _IX, _MI, or _MX. Periods are only allowed for ODBC gateway fields. Field names are case insensitive; for example, vdkvgwkey, VdkVgwKey, and VDKVGWKEY all refer to the same field.

You should call VdkStructInit on your VgwSchema structure before assigning values to it; this action guarantees that optional or empty fields in the structure are set to NULL.

This schema structure is immutable after the VgwGetSchemaFnc function completes. You may create the schema in your driver’s VgwSessionNewFnc function, save it in the session handle, vgwSession, and assign the pgwSchema pointer to the schema structure inside the session handle. In this case, the schema would be available to all of your driver’s callback functions that receive the session handle.

Each schema must include an external field with the name “DOC” to identify the body of the document to the Verity engine; otherwise the Verity engine will not be able to read any documents. The “DOC” field’s field type must match the access mode for the gateway, which typically is VdkFieldType_Stream.

If execution of your VgwGetSchemaFnc function results in an error, you are responsible for freeing any resources used by the objects that you have created before returning from this function.


Example

#define FIELDCOUNT 5

#define VGWF_SECFLAG (VdkCString)"_VgwAccessType"
#define VGWF_ACLCACHE (VdkCString)"_VgwAccessValue"
#define VGWF_DOCFLD (VdkCString)"DOC"
#define VGWF_DOCKEY (VdkCString)"VgwDocKey"
#define VGWF_VWURL (VdkCString)"VgwViewURL"

static VgwColumnInfoRec reposColInfo[] = {
{VdkFieldType_Invalid, (VdkCString)"", 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Unsigned, VGWF_SECFLAG, 0,
VgwColumn_ReadOnly | VgwColumn_InLine, 0, 0},
{VdkFieldType_Text, VGWF_ACLCACHE, 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Stream, VGWF_DOCFLD, 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Text, VGWF_DOCKEY, 0,
VgwColumn_PrimaryKey | VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Text, VGWF_VWURL, 0,
VgwColumn_RedirectURL | VgwColumn_ReadOnly, 0, 0}
};

static VdkError
VDK_CALLBACK VgwGetSchema(VgwAppSession pSession,
VdkUser pUser, VgwSchema* ppSchema)
{
VdkUint2 j;
VgwSchema pVSchm = NULL;

if (!ppSchema)
return VdkError_InvalidArgs;
*ppSchema = NULL;

if (!pSession)
return VdkError_InvalidArgs;

if( !(pVSchm = (VgwSchema)malloc(sizeof(VgwSchemaRec))) )
return VdkError_OutOfMemory;

VdkStructInit(pVSchm);
pVSchm->session = pSession;
pVSchm->columnCount = FIELDCOUNT;

if( !(pVSchm->columnArray = (VgwColumnInfo*)
malloc(sizeof(VgwColumnInfo)*pVSchm->columnCount)) ){
free(pVSchm);
return VdkError_OutOfMemory;
}

for( j = 0; j < pVSchm->columnCount; j++ )

/*******************************
* use static field column info
*******************************/

pVSchm->columnArray[j] = &reposColInfo[j+1];

*ppSchema = pVSchm;
return VdkSuccess;
}