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.

If the data file supports transaction logging, 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 Plus.

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 indices.
• The key length and duplicate key status of each index.
• The specification of which indices serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indices 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 indices.

Return

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus 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

• If the data file supports transaction logging but is not transaction dependent (TRANDEP), two criteria must be satisfied:
  • No transaction can be active when RenameIFile() is called.
  • The files cannot be updated after the exclusive open and before the renaming call.
• Transaction Dependent files MUST be renamed within a transaction.
• 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 indices.
  • The key length and duplicate key status of each index.
  • The specification of which indices serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indices in addition to the “base” index.

See also

RenameIFileXtd(), RenameFile()