Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

GetCtFileInfo

Retrieve information from a file header.

Short Name

GETFIL()

Type

Low-Level function

Declaration

LONG GetCtFileInfo(FILNO filno, COUNT mode)

Description

A variety of information about a file is stored in the file header. In FairCom DB the header is accessible only by using GetCtFileInfo() to access certain items of information from the header of file filno. Use mode to specify the type of information to be returned. The following values can be used for mode:

Mode

Description

ALIGNM

Returns a value signifying the alignment of field types. If a record schema resource, or DODA, exists for the file the schema alignment is returned. If no schema exists, but the file header has a non-zero alignment setting, this value is returned; otherwise the system alignment is returned.

Note: This mode requires a call across the network for client/server systems. For efficiency, store the values in the client application after the initial call rather than calling every time the information is needed.

BEGBYT

Returns the first possible location for a data record in a data file. If filno is a member of a superfile, GetCtFileInfo() returns the position of the last record added to the file. If filno is an index, GetCtFileInfo() returns -1 and uerr_cod is set to FMOD_ERR (48). The position returned is not necessarily an active data record: it may be a resource or a deleted record.

CIPHER_ATTR (V12.5+)

Returns a file encryption attribute bitmask of encryption settings in use when the file was created.

CIPHER_LENGTH (V12.5+)

Returns the key length in bits.

CIPHER_TYPE (V12.5+)

Returns 0 for plaintext, 1 for file camoflauge, or other non-zero _CIPHER_TYPE enumeration (see ctcrsdk.h).

DEVID

Returns a 4-byte integer holding the device ID component of the system file ID. (Available post-V12)

EXTSIZ

Returns the current file extension size.

FILDEF

Returns a bit mask which specifies file related FairCom DB specifications at the time the file was created. The existing bit masks are:

  • DEF_MASK_IFIL2 - extended IFIL structures
  • DEF_MASK_SPCMGT - superfile space management
  • DEF_MASK_PSCL24 - Pascal string definition
  • DEF_MASK_XTDPRM - extended permission mask

    The same note for ALIGNM applies to client/server applications.

FILEID

Returns the c-tree sequence number of the 12-byte Unique file ID assigned to each file at creation. The ID is comprised of a server ID, a time stamp and a sequence number, each 4-bytes long.

FILMOD

Return the file mode value.

FILTYP

Return:

  • DATA_FILE (0) for a fixed-length data file,
  • INDX_FILE (1) for an index file, or
  • VDAT_FILE (2) for a variable-length data file

FLMODE2

Returns information about the file mode:

  • Forces extended (V7) header (ctFRC2HDRS)
  • ctFRC2HDRS (ctFRCXHDRS)
  • Segmented file (ctFILESEGM)
  • Transaction-dependent create/delete (ctTRANDEP)
  • HUGE file (ctFILEPOS8)
  • Do not check for disk full (ctNOSPACHK)
  • Do not create with encryption (ctNOENCRYP)
  • Auto switch to ctLOGFIL (ctTRANMODE)
  • Auto switch to ctSHADOW (ctPIMGMODE)
  • Transaction-dependent restorable delete (ctRSTRDEL)
  • Forces 128-byte (V6) header (ctNO2HDRS)
  • ctNO2HDRS (ctNO_XHDRS) - Forces V6-compatible files (V9 and newer, which default to V7 extended files, will create the older style 128-byte V6 file header)
  • Large extent size (ctLEXTSIZE)
  • First extent size (ctFEXTSIZE)
  • Maximum file-size limit (ctMAXFILEZ)
  • Space available check enabled (ctSPACEAVL)
  • Auto segment creation (ctSEGAUTO)
  • Partition host file (ctPARTHOST)
  • Auto partition naming (=> HOST) (ctPARTAUTO)
  • Deleted space is not re-used (ctADD2END)
  • 6-byte transaction support (ct6BTRAN)
  • No 6-byte transaction support (ctNO6BTRAN)
  • Temporary memory resident file (ctMEMFILE)

FLMODE3

Returns information about the file mode:

  • Create file with replication (ctREPLICATE)
  • Compressed data records (ctCompressRec)

FRSACTPRT

Returns the first active partition number for a file.

INODEID

Returns a 4-byte integer holding the low-order 4 bytes of the 8 byte inode component of the system file ID. Use ctGETHGH() to retrieve the high-order 4 bytes. (Available post-V12)

KEYDUP

Returns 0 if the index only allows unique key values, or non-zero if it permits duplicates.

KEYLEN

Return key length (valid only for key files).

KEYMEM

Returns a small integer indicating the index member number. A zero means that filno is the host index. The first additional member is number 1, and so on.

KEYPAD

Returns the byte value checked for trailing padding compression.

KEYTYP

Returns the key type.

LSTACTPRT

Returns the last active partition number for the file.

LOGSIZ

Return the logical file size in bytes. The logical file size represents the number of bytes that are taken up by actual data records, including deleted records. Not applicable to superfile members.

MAXMBRPRT

Return the defined maximum number of partitions on a partitioned file. A value of 0 means no maximum number has been defined. Possible uerr_cod errors: PHST_ERR, FMOD_ERR, NSUP_ERR

MINSCHMID

Returns the minimum record schema ID that might exist. When a compact in shared mode has completed, the MINSCHMID is set to SCHMID. indicating that all records are known to be AT LEAST at the current SCHMID at that point. In general, if MINSCHMID = SCHMID then all records are at the current schema version. If MINSCHMID < SCHMID, then there may exist records with non-current schemas.

NKYMEM

Returns the number of index members contained in filno.

NODSIZ

Returns the index node size.

NUMACTPRT

Number of active partitions.

PERMSK

Returns a file’s permission mask (Server only).

PHYSIZ

Return the physical file size in bytes. The physical size is the actual size of the file, including deleted records and file extension space not yet used. Not applicable to superfile members.

PRTKEY

Relative Partition key #

RECLEN

Return data record length (valid only for data files).

RELKEY

Returns the relative key number (zero based) for the index with respect to its associated data file.

REVMAP

Returns the data file number associated with the key filno (ISAM only).

SCHMID

Returns the current table schema ID number. This number is incremented when using ctAlterSchema() (Hot Alter Table) to modify the table schema.

SERVID

Returns the FairCom Server ID of the 12-byte Unique file ID assigned to each file at creation. The ID is comprised of a server ID, a time stamp and a sequence number, each 4-bytes long.

SUPTYP

Returns the superfile type of filno. NON_SUPER (0) is not a superfile. HST_SUPER (1) is superfile host. MBR_SUPER (2) is a superfile member. IDX_SUPER (6) is a superfile directory member.

TIMEID

Returns the c-tree time stamp of the 12-byte Unique file ID assigned to each file at creation. The ID is comprised of a server ID, a time stamp and a sequence number, each 4-bytes long.

UNQKEY

Replicated file unique key.

UPDFLG

Returns the current corrupt, or update, flag for the file, such as:

0x00 Ok

0x4C Rebuild index. Loop in leaf node links

0x52 Opened with ctOPENCRPT and file was corrupt

0x63 File compacted. Rebuild indexes

0xFF Corrupt

XFLMOD

Returns some of the extended file attributes (Xtd8). Attributes include:

  • File is mirrored (MIRRORD)
  • Force 256-byte (V7) header (ctFRC2HDRS)
  • TRNLOG swap during Dynamic Dump (ctPREIMAGE)
  • Segmented file (ctFILESEGM)
  • Transaction-dependent create/delete (ctTRANDEP)
  • File created as special temp (ctTEMPFILE)
  • HUGE file (ctFILEPOS8)
  • Do not check for disk full (ctNOSPACHK)
  • Do not create with encryption (ctNOENCRYP)
  • Auto switch to ctLOGFIL (ctTRANMODE)
  • Auto switch to ctSHADOW (ctPIMGMODE)
  • Transaction-dependent restorable delete (ctRSTRDEL)

    Refer to ctport.h for all Xtd8 file modes.

Return

The return value depends on the mode used in the function call. The value returned is based on the mode selected. A value of -1L means that uerr_cod contains an error.

Value

Symbolic Constant

Explanation

22

FNUM_ERR

filno out of range.

26

FACS_ERR

filno is not active.

116

IMOD_ERR

Invalid mode value or called for non-server system.

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

Example

FILNO datfil;

printf("\nThe record length is %ld",

GetCtFileInfo(datfil,RECLEN));

See also

GetSymbolicNames()

TOCIndex