FairCom ISAM for C

SetFileSegments

Segmented file support configuration function.

Short Name

ctSETSEG()

Type

Low-Level function

Declaration

COUNT SetFileSegments(FILNO filno, NINT aseg, NINT tseg, pSEGMDEF pseg)

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

SetFileSegments() configures the segments for file filno. aseg specifies the number of active segments, i.e., the segments created immediately. aseg must be at least one and less than or equal to tseg. tseg specifies the total number of segments pointed to by pseg. pseg points to an array of SEGMDEF structures.

If the first segment definition pointed to by pseg has a sgname pointing to the empty string, i.e., *sgname == ‘\0’, not sgname == NULL, the sgsize member of the structure becomes the host segment size limit. Only the last segment can have a size limit of zero, which is interpreted as no limit.

Additional segments automatically become active as needed, up to the maximum set in tseg. The segments are used in the order defined by the array of SEGMDEF structures pointed to by pseg.

The file referenced by filno must be opened in ctEXCLUSIVE mode the first time SetFileSegments() is called. Note that a file which has been created and not yet closed is always in ctEXCLUSIVE mode, regardless of the file mode specified as part of the create call.

Modifying Segment Definitions

After the segment definitions have been established by the first call to SetFileSegments(), it is possible to call SetFileSegments() to modify the segment definitions even while the file is being updated. However, it is not possible to change a segment size so that the new size is smaller than the actual physical size of the segment, nor can SetFileSegments() rename a segment that is in use. A segment is in use if data beyond the segment header information has been written to the segment. An active segment is not in use just because it is on disk; data must have been written to it. Therefore, a call to SetFileSegments() can, in real time, change where segments will reside (provided the segment is not already in use) and/or how large they are (provided the new size is not smaller than the current physical size nor is the segmented already completely full).

Changing the Number of Segments

SetFileSegments() can be used to change the number of segments for a file that uses the automatic segment feature (ctSEGAUTO). Call SetFileSegments() as follows:

Set aseg to zero
Set tseg to the new maximum number of automatic segments
Set pseg to point to a single SEGMDEF structure in which the sgname field is ignored and the sgsize field specifies the size of all the segments, including the host file.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful segment configuration.
62	LERR_ERR	First call requires exclusive file lock.
70	TEXS_ERR	Call cannot be made within a transaction unless the file has just been created with ctTRANDEP or ctRSTRDEL (i.e., the creation has not been committed) and this is the first such call for this file.
446	BMOD_ERR	Illegal value for aseg.
448	DEFP_ERR	Denied permission to change file definition.
454	NSUP_ERR	File requires extended header to support segments.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

SEGMDEF segdef[2] = {

{"d:\\data\\dataseg.2",1024}, /* 1024MB = 1GB size limit */

{"e:\\data\\dataseg.3",0} /* no limit on segment size */

};

IFIL fil = {...}

/* create files */

if (CreateIFileXtd8( &fil, NULL, NULL, 0L, NULL, NULL,

&creblk)) /* pointer to array of XCREblks */

printf("Could not create %s (%d,%d)\n", fil.pfilnam, isam_err, isam_fil);

/* specify definitions for the two other segments */

if (SetFileSegments(

fil.tfilno, /* data file number */

1, /* one active segment (the host segment) */

2, /* two segment definitions to be passed */

segdef)) /* pointer to the segment definitions */

printf("Could not set file segments (%d,%d)\n", isam_err, isam_fil);

Limitations

The fxtsiz member of the XCREblk structure cannot be set higher than the size of the first (host) segment during a file create. This results in SEGM_ERR (674) signifying the need for more segments, which do not exist yet because SetFileSegments() has not yet been called.

The file referenced by filno must be opened in ctEXCLUSIVE mode the first time SetFileSegments() is called.