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

ISEG inv_seg = {

2,25,2

};

IIDX inv_idx = {

25, /* key length /

0, / key type /

0, / dup off /

0, / null off /

32, / empty char /

1, / number of key segments*/

&inv_seg, /* pointer to segment array*/

"Itemidx", /* pointer to symbolic index name (r-tree)/

"invent.idx" / optional index name (if this field is omitted the

default index name will be used. The default is the

name supplied in the IFIL pfilnam with an extension

of "idx".)*/

};

IFIL inv_dat = {

"invent", /* data file name ("dat" is always assumed)/

INVENTDAT, / data file number /

sizeof(invent), / data record length /

4096, / data extension size /

1, / data file mode /

1, / number of indices /

4096, / index extension size /

1, / index file mode /

&inv_idx, / pointer to index array*/

"Delflag", /* pointer to first field name (r-tree)/

"Buffer" / pointer to last field name (r-tree)*/

};

#ifdef PROTOTYPE

VOID RenameTable(void)

#else

VOID RenameIFile1()

#endif

{

if (CloseIFile(&inv_dat)) /* Close file - file must be opened in exclusive mode */

printf("\nCloseIFile error %d",isam_err);

inv_dat.dfilmod = 0; /* set data file mode to exclusive for RenameIFile /

inv_dat.ifilmod = 0; / set index file mode to exclusive for RenameIFile */

if (OpenIFile(&inv_dat)) /* Open file now that the data file AND the index are set to exclusive */

printf("\nOpenIFile error %d",isam_err);

cpybuf(inv_dat.pfilnam,"invent2",sizeof("invent2")); /* copy in the new file name for the data file /

cpybuf(inv_idx.aidxnam,"invent2",sizeof("invent2")); / copy in the new file name for the index file */

if (RenameIFile(&inv_dat))

printf("\nRenameIFile error %d",isam_err);

}

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.