FairCom ISAM for C

GetXtdKeySegmentDef

Retrieves the requested extended key segment definition.

Short Name

GETKSEGDEF()

Type

ISAM data definition

Declaration

NINT GetXtdKeySegmentDef(FILNO filno, NINT segno, pctKSEGDEF pkdef)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

GetXtdKeySegmentDef() retrieves (i.e., fills in the elements of a ctKSEGDEF structure for) the requested extended key segment definition to pkdef, except that the kseg_type member of the pkdef structure should be set on input to the type of segment to be retrieved.

For example, to retrieve an ICU Unicode definition, set the kseg_type member to ctKSEG_Type_UNICODE before calling GetXtdKeySegmentDef(). If GetXtdKeySegmentDef() is called with ctKSEGhandle for the filno parameter and the handle value is passed in via the segno parameter (as shown in the third row in the table below), then the kseg_type member of the structure is ignored on input since the handle uniquely identifies the particular definition. On output, the kseg_type member will be set to the type of segment.

One of the main reasons to call GetXtdKeySegmentDef() is to be able to examine the actual locale being used for the ICU collation routines.

The filno and segno values determine which definition is returned, as follows:

filno	segno	Interpretation
ctKSEGserver	ignored	Retrieve server default definition.
ctKSEGapplic	ignored	Retrieve application default definition.
ctKSEGhandle	handle	Retrieve definition associated with handle.
datno	ignored	Retrieve data file level definition.
keyno	ctKSEGindex	Retrieve index file level definition.
keyno	0, 1, 2, ...	Retrieve particular segment definition.

Return

If successful, GetXtdKeySegmentDef() returns the handle associated with the definition. GetXtdKeySegmentDef() returns a negative value upon error, where the absolute value of the return value is the error code. The most common errors are shown below. See c-tree Error Codes in the c-tree Reference Guide for a complete listing of valid c-tree error values.

Value	Symbolic Constant	Explanation
437	DADR_ERR	NULL pkdef argument.
694	NUNC_ERR	Executable does not support ICU Unicode, but a UNCSEG modifier has been encountered.
701	CSEG_ERR	Could not process the kseg_comp options. This could occur if more than one of a set of mutually exclusive options are combined.
702	ASEG_ERR	An error occurred when attempting to process one of the special attribute options.
703	HSEG_ERR	Invalid key segment handle. The segno parameter should be set to a valid extended key segment handle.
706	NSEG_ERR	Zero bytes of binary sort key were generated. Possibly an all NULL source.
707	USEG_ERR	There is no extended key segment definition to use.
708	MBSP_ERR	Multibyte/Unicode file names are not supported.
709	MBNM_ERR	A badly formed multibyte/Unicode file name has been encountered.
710	MBFM_ERR	A multibyte/Unicode variant is not supported (e.g., UTF32)

Example

See the API example in “Unicode Support”.