Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

GetFileRegions

Calculates offsets and lengths of a specified number of regions in a data file, accounting for resource locations, such that starting region offsets correspond to an active or deleted record at the time this function is called. A region is defined by a starting data file offset and the region length in bytes. (V11.8 and later)

Type

ISAM Function

NINT ctDECL GetFileRegions (pFILE_REGION_REQUEST pFileRegionRequest);

Description

  • [INOUT] pFileRegionRequest - Data structure used to pass information in and out of the function, defined below.

Description

Structure Definitions

typedef struct fileRegionRequest_t {

COUNT structVersion;

FILNO dataFileNumber;

LONG numberOfRegions;

pFILE_REGION fileRegions;

} FILE_REGION_REQUEST, *pFILE_REGION_REQUEST;

  • [IN] structVersion - Structure version (consult ctport.h for current versions).
  • [IN] dataFileNumber - c-tree data file number
  • [IN] numberOfRegions - Number of FILE_REGION structures in the array, which is the number of regions you desire.

    fileRegions must have enough memory for that number of FILE_REGION structures.

  • [OUT] fileRegions - Array of FILE_REGION structures.

    Offset and length values are set on successful output.

    Note: Your code is responsible for allocating before calling the function and deallocating afterwards.

typedef struct fileRegion_t {

ULONG8 offset;

ULONG8 length;

} FILE_REGION, *pFILE_REGION;

  • [OUT] offset - starting record offset for region in the data file
  • [OUT] length - size of this region in bytes

Region Definition

FairCom DB calculates the starting offset of each region by dividing the data file into equally sized regions corresponding to the number of regions specified by numberOfRegions in the fileRegionRequest_t structure. It aligns the offset of each region in fileRegion_t to the record offset of the first record in the region. It aligns the length to the offset of the last byte of the last record in the region.

Because the data file may contain resources, FairCom DB determines the locations of resource records in the data file. If any region offset lands on or within a resource record, FairCom DB adjusts the offset to start on the first record after the resource.

If the adjusted starting offset is no longer inside the specified region (which is only likely for small files), the offset and length of the region are returned as zero. Thus, you must ignore regions with zero length.

Example

NINT numberOfRegions = 10; /* specify number of regions */

pFILE_REGION fileRegions = NULL; /* array returned with region information */

FILNO datno; /* data file number */

/* structure used to request and receive region information */

FILE_REGION_REQUEST fileRegionRequest;

NINT i, rc;

/* Allocate memory for the array of regions that GetFileRegions() will populate */

if (!(fileRegions = (pFILE_REGION) mballc(numberOfRegions, sizeof(FILE_REGION)))) {

printf("Error: Failed to allocate memory for the region array.\n");

return -1;

}

/* Open the data file */

if ((datno = OPNRFIL(-1, "MyDataFile.dat", ctSHARED)) < 0) {

rc = isam_err;

printf("Error: failed to open file: %d\n", rc);

if (fileRegions)

mbfree(fileRegions);

return -1;

}

/* Prepare structure returning file regions */

fileRegionRequest.structVersion = FILE_REGION_REQUEST_VERS_V01;

fileRegionRequest.dataFileNumber = datno; /* The data file */

fileRegionRequest.numberOfRegions = numberOfRegions; /* Requested regions */

fileRegionRequest.fileRegions = fileRegions; /* Allocated array */

if ((rc = GetFileRegions(&fileRegionRequest))) {

printf("Error: failed to get region information: %d\n", rc);

if (fileRegions)

mbfree(fileRegions);

return -1;

}

/* Now print the region information */

printf("offset length\n");

for (i=0; i<numberOfRegions; i++) {

printf(ctLLnd(10) " " ctLLnd(10) "\n",fileRegions[i].offset,fileRegions[i].length);

}

if (fileRegions)

mbfree(fileRegions); /* Free region array */

return(0);

Limitations

  • This function is not supported for variable-length record data files.
  • This function is not supported for memory files.
  • This function is not supported for superfiles (superfile hosts or members).

Coding Considerations

  • The number of records in one region may be less than another region because the function does not take into consideration deleted records when it divides the data into regions. For this reason, it is unlikely, but possible, that a region could be occupied solely by records that were previously deleted.
  • In data files containing few records that are divided into many regions, it is possible for a region to contain no records. This will cause FILE_REGION.length and FILE_REGION.offset to be zero.
  • Multiple threads can speed data processing as long as the storage system has enough I/O bandwidth and the CPU has enough processing power. When data processing becomes I/O or CPU bound, adding more threads can slow data processing.
  • Batch record processing, such as DoBatch(), does NOT stay within the current region. Instead, batch functions stop when the end of file is reached or the batch buffer is full. This means batch functions can return records that are past the end of a region, and this can cause the same record to be processed by more than one thread. To prevent this, use the BAT_RET_REC option instead of BAT_RET_BLK to return the record offset with each record. You can write threads to stop processing records as soon as they find a record whose offset is outside of that thread’s region.
  • When adding resources to a data file while using this function, the application should first acquire a table lock. Otherwise, if a resource is added, deleted, or updated after the function has determined resource offsets, the function can return an offset that corresponds to a resource or to a location within a resource.
  • The GetFileRegions() function does not automatically provide read isolation to a region. It does not protect a region from being updated by other processes. This is because the function does not acquire locks on the records in a region. If you require read consistency for an entire region, the safest way is to lock the entire table. Alternatively, you can lock individual records in a region with the possibility that another process may lock some of them first.

Return

  • Success: NO_ERROR(0)
  • Failure: Non-zero c-tree error code:

    Programming Errors

    • 10 - SPAC_ERR - Out of space. Parameters require too much space. Check the parameters passed in to make sure they are correct.
    • 43 - FVER_ERR - Check the versions specified in the structures passed in to the function. They must match the versions in use in the data file as set at file creation or last version update. structVersion must be FILE_REGION_REQUEST_VERS_V01
    • 47 - FINT_ERR - c-tree has not been initialized. You need to call InitISAM() first.
    • 48 - FMOD_ERR - File mode error. Make sure the data file type is compatible with this function. File types such as superfile host, superfile member, memory file, or variable-length record data file are incompatible with this function.
    • 78 - TABN_ERR - Transaction has become too large. Re-try in smaller pieces.
    • 82 - UALC_ERR - User allocation error. Check the parameters, our memory allocation based on the parameters failed.
    • 540 - PNUL_ERR - Null parameter error. One or more required parameters passed to the function is null.
    • 634 - NLEN_ERR - Negative length specified. Check the lengths you passed into the function.

    Incorrect File Usage Errors

    • 22 - FNUM_ERR - filno out of range. You may be attempting to open more files than the server is configured for. Increase the file limit of the server and try again. This error may also occur if c-tree has not been initialized.
    • 26 - FACS_ERR - File number is not in use. This occurs when you specify an invalid data file number or the file has been closed.

    Handleable File Errors

    • 643 - DPND_ERR - File is being deleted.
    • 798 - FBLK_ERR - File is blocked, retry later.
    • 799 - FBLK_RDO - File block cleared: close/reopen file.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Compatibility Note: This new functionality involves changes to both the client library and the server, so, in addition to installing a new server executable, the client program must be re-linked.

TOCIndex