PartitionAdmin

Partition file administration function.

Short Name

PTADMIN()

Type

Utility Function

Declaration

COUNT PartitionAdmin(FILNO datno, pVOID partdesc, LONG prawno, COUNT ptmode) 

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PartitionAdmin() manages the partitions for datno, the file number for the host data file.

• partdesc may be either a pointer to a partition member data file name, a pointer to a key value (already transformed) representative of a partition member, or NULL.
• prawno may either be a “raw” partition number or its value is ignored.
• ptmode controls how to interpret partdesc and prawno as well as what action PartitionAdmin() should perform. ptmode is formed by OR-ing together the appropriate bit values from this list defined in ctport.h:

* The ptADMINnumber, ptADMINreuse, and ptADMINmulti options have NOT been implemented.

Note: All calls to PartitionAdmin() must specify exactly one way in which the partition will be identified (ptADMINname or ptADMINkey or ptADMINraw) and exactly one operation (for example., ptADMINpurge). If the ptmode parameter is not correctly formed, PTADMIN() will return BMOD_ERR (446, Bad mode: parameter out of range).

ptADMINstatus Option

If the ptADMINstatus option is used, then PartitionAdmin() returns either an error code (such as PLOW_ERR, 712, partition number is out of range - low) or NO_ERROR. If NO_ERROR is returned, then sysiocod contains the member status code from this list:

There is a subtlety here concerning a return of pmSTATUSnone in sysiocod, and some possible error codes returned by PTADMIN(). For example, a NO_ERROR return from PTADMIN(.........,ptADMINstatus) and sysiocod of pmSTATUSnone means that the partition number is in the current valid range, but that no such partition member has been created. A PLOW_ERR (712, out of range - low) return means that the partition number is out of the current valid range (whether or not such a partition was ever created).

A partition that is not in use or a partition that has been opened by the host (that is, not explicitly by the application), and which is not in use by another user, can be archived or purged.

Base Partition Number

The record add and update functions attempt to increase the base partition number of the partitioned file to the first current active partition number if one exists, or to the partition number that will hold the newly-added or updated record if no current active partition exists.

Return

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

Limitations

• A raw partition number must be 1 or greater.
• Encryption is not supported for partitioned files.
• To support transaction processing, a partitioned file must also support transaction-dependent file creation (TRANDEP).

Perform

Evaluate FairCom Server performance.

Short Name

PERFORM()

Type

Low-Level function

Declaration

COUNT Perform(COUNT status)  

Description

Perform() collects statistics on the number of times each c-tree function is called between PERFORM_ON and PERFORM_OFF. status is used to begin and end the evaluation process and to display the information collected. The values that can be used for status are:

Return

Always returns zero (NO_ERROR).

Example

Perform(PERFORM_ON);

GetRecord(...);
ReWriteRecord(...);
NextRecord(...);

/* additional c-tree functions */

Perform(PERFORM_OFF);

Perform(PERFORM_DUMP);

PermIIndex

Permanent Incremental Index creation.

Short Name

PRMIIDX()

Type

ISAM function

Declaration

COUNT PermIIndex(pIFIL ifilptr) 

Description

In a single call to PermIIndex(), your application program will:

• Add one or more additional indexes to an existing Incremental ISAM definition.
• Automatically load the indexes from the existing data (optional).
• Reference the new indexes with the standard ISAM level calls (e.g., the next AddRecord() call updates the new indexes along with the original indexes).
• If resources are enabled, automatically update the stored file definition to include the new indexes.

Note: This command requires an exclusive open of the file (see PRMIIDX82() for a shared mode version of this function). c-tree attempts to open the file in exclusive mode while allowing other connections read access. If the file is already open, c-tree flushes updates to disk and sets the update flag to zero to indicate that the file is in a clean, consistent state. If c-tree cannot open the file in exclusive mode, this operation fails.

When the Incremental file is closed via CloseIFile(), CloseISAM(), or CloseRFile(), the new indexes are automatically closed. The next Incremental open automatically includes the new indexes if OpenFileWithResource() is used, or if you have updated your Incremental structures and use OpenIFile().

The key values from the existing records will be added automatically. The additional indexes created and loaded by PermIIndex() reside in a separate index file, distinct from the index file(s) already in existence for the data file. There is no extended form of this function because the new indexes are automatically assigned the security information assigned to the existing indexes.

To disable the automatic load feature, set the dxtdsiz parameter of ifilptr to ctNO_IDX_BUILD. This creates the new index without loading key values into it. This feature allows PermIIndex() to be followed by UpdateConditionalIndex(), limiting the keys the index loads to those that meet the specified condition. Once the condition is in place, call RebuildIIndex() to fill the index. Do not close the files between PermIIndex() and RebuildIIndex().

ifilptr points to a new IFIL structure in which:

• dfilno contains the file number of the underlying Incremental data file.
• ix points to the new index definitions.
• tfilno is -1 if you wish the index file number to be assigned, or tfilno is set to the first desired index number.
• dnumidx is the number of index files to create.

Note: The underlying data file is not determined by the pfilnam member of the new IFIL structure. dfilno specifies the data file involved.

The IFIL file name and location enhancement automatically locates index files created by PermIIndex() or TempIIndexXtd() in the same directory as the associated data file. With PermIIndex() only, it also allows the IFIL entry for the index file to have the same directory as the associated data file, even if the data file is not in its original directory. To activate this feature, the index file name in the aidxnam parameter of ifilptr should be in the form:

+index_name   

By placing a plus sign,‘+’s the first character of the index name, the new index automatically “follows” the data file, i.e., it is created in the same directory as the data file. c-tree can open files via OpenFileWithResource() in a directory different from the directory in the file’s internal IFIL resource. When this happens, OpenFileWithResource() expects any index that had the same directory as the data file to be in the new directory.

The plus sign is not part of the actual file name used to create the index. Mirrored file name components use this option independently. Only the name components beginning with the plus sign invoke this feature. For example, the following would all be “legal” for aidxnam entries:

+primary_index|+mirror_index
+primary_index|mirror_index
 primary_index|+mirror_index

Adding an Index to an Existing File

FairCom has always supported adding an additional index to an existing file if the index is placed in a new physical file. If you need to add an additional index to an existing file and want to store the new index in the same physical file, PermIIndex() is the preferred method. This support is available starting in V11.2.

Return

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

Example

pIFIL     newindex;
FILNO     filno;
VRLEN     bufsiz;

filno = OpenFileWithResource(-1,"test", (ctEXCLUSIVE | ctPERMANENT));
if (filno < 0) {
    printf("\nOpen  failed");
    exit(1);
}

bufsiz = GetIFile(filno, 0, newindex);
newindex = (pIFIL) mballc(1, bufsiz);
GetIFile(filno, bufsiz, newindex);

newindex->dfilno = filno;
newindex->tfilno = -1;
newindex->dnumidx = 1;
newindex->aidxnam = "testnew";

if (PermIIndex(newindex))
    printf("\nAdding Index failed (%d %d)",isam_err,isam_fil);

Limitations

The Incremental ISAM files must be opened ctEXCLUSIVE.

See also

TempIIndexXtd(), DropIndex(), RebuildIIndex(), UpdateConditionalIndex(), AddRecord(), CloseIFile(), CloseISAM(), CloseRFile(), OpenFileWithResource(), OpenIFile(), PRMIIDX82()

PermIIndex8

Permanent 8-byte Incremental Index creation.

Short Name

PRMIIDX8()

Type

Extended 8-byte ISAM function

Declaration

COUNT PermIIndex8(pIFIL ifilptr, pXCREblk pxcreblk)

Description

PermIIndex8() is a variation of PermIIndex() that permits the use of huge file support. This section expands on the description of PermIIndex().

pxcreblk points to an array of XCREblk structures, the extended creation block, one for each physical file in ifilptr. For more information, review Huge File Support in the c-tree Programmer’s Reference Guide.

Return

PermIIndex8() returns error codes similar to those for PermIIndex(). See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Limitations

PermIIndex8() and TempIIndexXtd8() support ctTRANDEP creates. Without ctTRANDEP creates, these routines cannot be called within a transaction. With ctTRANDEP creates, they MUST be called within a transaction.

See also

TempIIndexXtd(), RebuildIIndex(), PermIIndex(), UpdateConditionalIndex(), PRMIIDX82

PositionSet

Establish current ISAM record as current position in set.

Short Name

MIDSET()

Type

ISAM function

Declaration

COUNT PositionSet(FILNO keyno, pVOID recptr, COUNT siglen)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PositionSet extracts the key value for index keyno from the current ISAM record, and defines a set based on the first siglen bytes of this key value. This permits an application to “jump” into the middle of a set using the current ISAM record to define the set. A successful PositionSet() defines a current key value set, and subsequent calls to NextInSet() and PreviousInSet() will read the other records in the set (i.e., those records whose keys also match the first siglen bytes of keyno). If an error occurs or no key value matches the target, no key value set is defined.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;
TEXT         target[24],recbuf[320];

printf("\nEnter set value:");
scanf("%23s",target);

LockISAM(ctENABLE);

FirstInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {
    process_data();
    LockISAM(ctRESET);

    while (NextInSet(keyfil,recbuf) == DLOK_ERR) {
        LockISAM(ctSUSPEND);
        PositionSet(keyfil,recbuf,strlen(target));
        LockISAM(ctRESTORE);
    }
}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

NextInSet(), PreviousInSet(), LastInSet(), FirstInSet(), ChangeSet(), TransformKey()

PositionVSet

Establish current variable-length ISAM record as current position in set.

Short Name

MIDVSET()

Type

ISAM function

Declaration

COUNT PositionVSet(FILNO keyno, pVOID recptr, COUNT siglen, pVRLEN plen)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PositionVSet() is the same as its fixed-length counter-part, PositionSet(), except that one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PositionSet() for additional important information.

Return

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

See also

PositionSet(), NextInVSet(), PreviousInVSet(), LastInVSet(), FirstInVSet(), ChangeSet(), TransformKey()

PreviousInRange

Read the previous record in a range

Short Name

PRVRNG()

Type

ISAM function

Declaration

COUNT PreviousInRange(COUNT keyval, pVOID recptr)  

Description

Read the previous data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful PreviousInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use PreviousInVRange() to read the whole variable-length record with one function call.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInVRange()

PreviousInSet

Read the previous data record in the current key value set.

Short Name

PRVSET()

Type

ISAM function

Declaration

COUNT PreviousInSet(FILNO keyno, pVOID recptr)  

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PreviousInSet() reads the previous data record in the set of data records whose keys match the set created by an earlier set function call. If successful, this record becomes the current ISAM record for the associated data file. If an error occurs or no previous record exists in the set, the current ISAM record is not updated, and the current key value set becomes undefined.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to PreviousInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;
TEXT         target[24],recbuf[320];

printf("\nEnter set value:");
scanf("%23s",target);
LastInSet(keyfil,target,recbuf,strlen(target));
while (isam_err == NO_ERROR) {
   process_data();
   PreviousInSet(keyfil,recbuf);
}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstInSet(), NextInSet(), LastInSet(), PositionSet(), ChangeSet(), CreateIFile(), ReReadVRecord(), TransformKey()

PreviousInVRange

Read the previous record in a range

Short Name

PRVVRNG()

Type

ISAM function

Declaration

COUNT PreviousInVRange(COUNT keyval, pVOID recptr, pVRLEN plen)  

Description

Read the previous data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful PreviousInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInRange()

PreviousInVSet

Read the previous variable-length data record in the set defined by target.

Short Name

PRVVSET()

Type

ISAM function

Declaration

COUNT PreviousInVSet(FILNO filno, pVOID recptr, pVRLEN plen)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PreviousInVSet() is identical to it’s fixed-length counterpart, PreviousInSet(), except that it reads the previous variable-length data record in the set defined by target and siglen. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PreviousInSet() for additional important information.

Return

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

See also

PreviousInSet(), FirstInVSet(), NextInVSet(), TransformKey()

PreviousKey

Find the previous entry in an index file.

Short Name

PRVKEY()

Type

Low-Level index file function

Declaration

LONG PreviousKey(FILNO keyno, pVOID idxval) 

Description

PreviousKey() searches index file keyno for the previous entry in the index. If successful, it copies the index entry into the space pointed to by idxval. PreviousKey() fails if it is the first index search routine called after the index is opened, or if the entry found before PreviousKey() is the first entry in the index. Repeated PreviousKey() calls move through the index in descending key value order.

Return

PreviousKey() returns the data record position associated with the previous entry in the index file. If the index is empty or an error is detected, PreviousKey() returns zero. When PreviousKey() returns zero, check uerr_cod: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

LONG      recbyt;
TEXT      idxval[10];  /* 10 byte key, no duplicates */
FILNO     keyno;

recbyt = LastKey(keyno,idxval);
while (recbyt) {
    printf("\nIndex Entry %.10s found in record #%ld", idxval,recbyt);
    recbyt = PreviousKey(keyno,idxval);
}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo() to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

ctSETHGH(), ctGETHGH(), GetKey(), GetCtFileInfo(), FirstKey(), NextKey()

PreviousRecord

Read the preceding data record.

Short Name

PRVREC()

Type

ISAM function

Declaration

COUNT PreviousRecord(FILNO filno, pVOID recptr)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PreviousRecord() retrieves the previous data record found. If filno designates an index file, PreviousRecord() reads the previous active data record based on the key sequential order of entries in index file number filno. If filno designates a data file, PreviousRecord() reads the previous active data record, in physical sequential order. If successful, the previous record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

Note: filno cannot be a data file number, and the error FMOD_ERR (48) will be returned, if any of the following are true:

• The data file is set up for variable-length records;
• The data file is a member of a Superfile;
• The data file has Resources enabled (the default state).

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to PreviousRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If PreviousRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

PreviousRecord() can move sequentially through a data file based on one index then switch to another index. For example, moving through an inventory file in part number order before switching to part name order by changing the keyno parameter in the PreviousRecord() call.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

Example

FILNO     acct_idx, test;
TEXT      recbuf[320];

test = LastRecord(acct_idx,recbuf);
while (test == NO_ERROR) {
    post_interest(recbuf);
    test = PreviousRecord(acct_idx,recbuf);
}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstRecord(), NextRecord(), LastRecord(), CreateIFile(), ReReadVRecord().

PreviousVRecord

Read the previous variable-length data record in the data file.

Short Name

PRVVREC()

Type

ISAM function

Declaration

COUNT PreviousVRecord(FILNO filno, pVOID recptr, pVRLEN plen)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PreviousVRecord() is identical to it’s fixed-length counterpart, PreviousRecord(), except that it reads the previous variable-length data record. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PreviousRecord() for additional important information.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

See also

PreviousRecord(), NextVRecord(), TransformKey()

PRMIIDX82

Create an index with the data file open in shared mode.

Declaration

CTERR PRMIIDX82(pIFIL ifilptr, pXCREblk pxcreblk, ULONG numberOfExtendedCreateBlocks, ctINDEX_ATTRIBUTES *pIndexAttributes);

Description

Beginning with V13, a condition can be added to the index when creating the index with the data file open in shared mode. Use this function to add a permanent index to a data file. The function accepts ifilptr and pxcreblk parameters that are identical in usage to PRMIIDX8(). The two additional parameters indicate the number of extended create blocks in the pxcreblk array and provide the desired index attributes:

The ctINDEX_ATTRIBUTES structure contains a version so that it can be modified in future versions to support passing additional index attributes. Version 1 of the structure is defined as follows:

/* index attributes for PRMIIDX82 */
typedef struct ctIndexAttributes_t {
ULONG structureVersion;
ULONG numberOfExtendedKeySegments;
ULONG numberOfIndexConditions;
pctKSEGDEF *extendedKeySegments;
cpTEXT *indexConditions;
} ctINDEX_ATTRIBUTES;

To use the index attributes structure, set structureVersion to ctINDEX_ATTRIBUTES_VERS_V01, set numberOfExtendedKeySegments to the number of extended key segments in the extendedKeySegments array (specify zero and NULL if no extended key segments are supplied), and set numberOfIndexConditions to the number of index conditions in the indexConditions array (specify zero and NULL if no index conditions are specified).

• extendedKeySegments is an array of pointers to key segment definitions, one for each key segment definition (ISEG structure element) specified in the array of IIDX structures specified in the ifilptr parameter. If a given key segment has no extended key segment definition, specify NULL for that array element.
• indexConditions is an array of pointers to index conditions, one for each index definition (IIDX structure element) specified in the ifilptr parameter. If a given index has no index condition, specify NULL for that array element.

Return Values

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

putcndxmem

Frees memory from expression parser tree.

Declaration

VOID putcndxmem( pVOID objptr );

Description

The macros getcndxmem() and putcndxmem(), used to get and put memory required to process and store conditional index expressions, allow the proper memory allocation routines to be used on the client and server sides. (These substitute for the internal mballc() and mbfree() calls.)

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */
if (!ctcidxStk)  {
    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));
    if (!ctcidxStk)  {
        printf("Unable to allocate memory for run-time stack.\n");
        ctrt_exit(1);
    }
}

if (ctcidxStk)
putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

PutDODA

Store information from a record schema as a resource.

Short Name

PUTDODA()

Type

Low-Level data file resource function

Declaration

COUNT PUTDODA(FILNO datno, pDATOBJ doda, UCOUNT numfld)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PutDODA() assigns the contents of a data object definition array (DODA) to data file. The DODA is converted into a schema map and schema names as described in Record Schemas of the c-tree Programmer’s Reference Guide.

• datno is the data file number to assign the DODA to.
• doda points to the beginning of the DODA (i.e., the array of DATOBJ’s). The DATOBJ is discussed in Record Schemas of the c-tree Programmer’s Reference Guide.
• The numfld parameter indicates how many data fields (number of elements) are contained in the DODA.

Return

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

Limitations

The file must be opened in ctEXCLUSIVE mode.

Resources must be enabled for the data file.

See also

GetDODA()

PutIFile

Place an IFIL structure into a data file resource record.

Short Name

PUTIFIL()

Type

ISAM resource function

Declaration

VRLEN PutIFile(pIFIL ifilptr) 

Description

Place a new, or replace an existing file definition (consisting of IFIL, IIDX and ISEG structures) into the resource record of the data file pointed to by ifilptr.

Normally, the IFIL is placed in the file during CreateIFile(). PutIFile() allows this resource to be updated or a new IFIL structure to be placed in files created with other functions.

Return

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

Refer to the following sections for additional details regarding IFIL structures.

IFIL Structure

IIDX Structure

ISEG Structure

Example

IFIL vc_dat = {
. . . .
};   /* IFIL structure to be placed in resource record */

VRLEN ret=0;  /* function return work variable */

if (ret=PutIFile(&vc_dat))
    printf("\nError during PUTIFIL(), error = %d",ret);
else
    printf("\nSuccessful PUTIFIL()!");

Limitations

The file must be closed prior to calling this function. PutIFile() opens the file in ctEXCLUSIVE mode and closes the file upon return.

See also

OpenFileWithResource(), GetIFile(), CreateIFile(), PutIFileXtd()

PutIFileXtd

Place an IFIL structure into a data file resource record. (Extended version)

Short Name

PUTIFILX()

Type

Extended ISAM function

Declaration

COUNT PutIFileXtd(pIFIL ifilptr, cpTEXT dataextn,
                  cpTEXT indxextn, cpTEXT fileword)

Description

PutIFileXtd() is a variation of PutIFile() that permits the use of the FairCom Server’s security system. This section expands on the description of PutIFile().

fileword is an optional file password. If fileword is null then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

dataextn and indxextn are pointers to buffers specifying optional data and index file name extensions, respectively. The extensions can be 8-byte ASCIIZ (NULL terminated ASCII) strings. If they are NULL pointers, the default extension will be used: .dat for data files and .idx for index files. For files with no extension, pass a pointer to a buffer that contains only blanks terminated by a null character. Do not set both extensions to blanks, since the index and data file names must be distinct.

Return

The following error code may be seen in addition to those for PutIFile():

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

Limitations

The file must be closed prior to calling this function. PutIFile() opens the file in ctEXCLUSIVE mode and closes the file upon return.

See also

PutIFile()

PutIFileXtd8

Put an IFIL structure into a data file resource record. Extended 8-byte version.

Short Name

PUTIFILX8()

Type

Extended 8-byte ISAM Function

Declaration

COUNT PutIFileXtd8(pIFIL ifilptr, cpTEXT dataextn,
          cpTEXT indxextn, cpTEXT fileword, pXCREblk pxcreblk) 

Description

PutIFileXtd8() extends PutIFileXtd() in that it can be used on an open file. It accepts a pointer to an extended file creation block, pxcreblk, however, does not currently use that information and NULL should be passed in.

Return

The following three points will help users avoid any error when using this function:

• The file must be opened in exclusive mode.
• The tfilno member of the IFIL structure must be set to the current file number.
• The xcreblk structure must be allocated and its splval member must be set to ctFILEOPENED constant value.

See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

IFIL      vc_dat = {
. . . .
};   /* IFIL structure to be placed in resource record */

COUNT     ret=0;  /* function return work variable */
pTEXT     fileword;

getfileword(&fileword);
if (ret = PutIFileXtd8(&vc_dat, NULL, NULL, fileword, NULL))
    printf("\nError during PUTIFILX8, error = %d",ret);
else
    printf("\nSuccessful PUTIFILX8!");

See also

PutIFile(), PutIFileXtd()

PutXtdKeySegmentDef

Defines an extended key segment for a Server, an application, a data file, an index file, or a particular index segment.

Short Name

PUTKSEGDEF()

Type

ISAM Data Definition

Declaration

NINT  PutXtdKeySegmentDef(FILNO filno, NINT segno, pctKSEGDEF pkdef) 

Description

PutXtdKeySegmentDef() defines an extended key segment for a Server, an application, a data file, an index file, or a particular index segment. The pkdef parameter points to a definition to be created in a call to PutXtdKeySegmentDef(). The filno and segno parameters determine where the definition is to be stored, as follows:

Return

PutXtdKeySegmentDef() returns a handle for the definition if successful.

PutXtdKeySegmentDef() returns a negative value upon error, where the absolute value of the return value is the error code. The most common errors are shown below. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

See the API example in the chapter titled “Unicode Support”.

See also

AddRecord(), AddVRecord(), OpenIFile(), PutXtdKeySegmentDef(), GetXtdKeySegmentDef(), TransformXtdSegment()