FairCom ISAM for C

RenameIFile

Atomically rename some or all of the files associated with the IFIL structure.

Short Name

RENIFIL()

Type

ISAM function

Declaration

COUNT RenameIFile(pIFIL ifilptr)

Description

RenameIFile() atomically renames some or all of the files associated with the IFIL structure ifilptr, and updates the internal IFIL resource. ifilptr must point to a complete IFIL structure corresponding to an exclusively opened IFIL, with the names replaced by the new names. If the “new” name is the same as the original name, no renaming takes place for that file. The tfilno member of ifilptr must contain the file number of the data file associated with the IFIL. The dataextn and indxextn parameters can be used to modify the file name suffixes of the data and/or index files.

The data file’s IFIL resource will be updated under the following conditions:

Resources have been enabled.
The ctDISABLERES bit of the dfilmod member of ifilptr is not on.

When the IFIL resource is updated, then the following protocol is used:

If an existing IFIL resource is found, then only the name fields are updated to reflect the renaming operations.
If no existing IFIL resource is found, then the IFIL information passed into RenameIFile() is used in its entirety.

The IFIL structure passed into RenameIFile() must agree with both the physical files and the existing IFIL resource (if any) on the following points:

The number of indexes.
The key length and duplicate key status of each index.
The specification of which indexes serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indexes in addition to the “base” index.

If any of these characteristics do not match, RenameIFile() returns IAIX_ERR (608).

The first index in the IFIL may derive its name either from the data file name, or through a non-NULL aidxnam parameter. The new IFIL may change whether or not the aidxnam parameter is used for the first index. It cannot change whether aidxnam is used for any of the other indexes.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful rename of file.
14	FCRP_ERR	File updated since ctEXCLUSIVE open.
70	TEXS_ERR	Transaction in progress.
608	IAIX_ERR	IFIL resources too different.

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

Example

extern IFIL myfile;

COUNT retval;

if (retval = InitISAM(6,7,4))

printf("\nCould not initialize. Error %d.", retval);

else {

if (OpenRFile(-1, "MyFile.dat", ctEXCLUSIVE))

printf("\nCould not open files.");

else {

if (RenameIFile(&myfile))

printf("Could not rename IFIL, error %d.", isam_err);

}

if (CloseISAM())

printf("\nCould not close ISAM.");

}

Limitations

Transaction Logging

If the data file supports transaction logging and it does NOT have the ctTRANDEP or ctRSTRDEL extended file attributes, two criteria must be satisfied:

No transaction can be active when RenameIFile() is called.
The files cannot be updated between the exclusive open and the renaming call.

If either of the criteria is violated, RenameIFile() returns TEXS_ERR (70) or FCRP_ERR (14), respectively.

The renaming and optional updating of the IFIL resource are performed atomically under the control of a transaction automatically managed by c-tree.

Note: Transaction dependent files that have the ctTRANDEP or ctRSTRDEL extended file attributes MUST be within an active transaction to be renamed (the exact opposite of those that do not have these attributes).

Other Limitations

The IFIL structure passed into RenameIFile() must agree with both the physical files and the existing IFIL resource (if any) on the following points:

The number of indexes.
The key length and duplicate key status of each index.
The specification of which indexes serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indexes in addition to the “base” index.