FindFileByName

Finds a file in the file system given a name.

Declaration

NINT ctDECL FindFileByName(pTEXT infilnam,NINT opcode,pTEXT outfilnam,pVRLEN poutfillen);

Short Name

ctFILWCD()

Description

This function allows file searches using the wildcard characters ‘?’ and ‘*’. The ‘?’ identifies a single character wildcard position while a ‘*’ specifies any number of characters.

• infilnam is the wildcard filename
• opcode is one of the following:

• outfilnam is the buffer to hold the found filename
• poutfillen points to the output buffer size

Note: The wildcard logic finds all files matching the wildcard specification — there is no check that the file is a c-tree data or index file. The wildcard logic also finds memory files whose names match the specified filename.

If an error occurs during a search, the search should be closed and restarted.

Result

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

Example pseudocode

#define MAX_SIZE 1024 /* 1K buffer size */
...
int ListLength = MAX_SIZE
pText pFilelist;
pFileList = (pText) malloc (sizeOf(pText) * MAX_SIZE);

...
memset(pFileList, 0, MAX_SIZE);
if ((rc = ctFILWCD ("jrnl*.dat", ctFILWDfindfirst, pFilelist, ListLength)) != 0 ) {
printf("ctFILWCD did not execute successfully (%d).\n, rc");
}
...

Limitations

ctFILWCD() does not translate path separators between client and server and does not provide a way to re-read the name of a file if the specified buffer is too small to hold the entire filename.

FirstInRange

Read the first data record in a range

Short Name

FRSRNG()

Type

ISAM function

Declaration

COUNT FirstInRange(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

Read the first 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 FirstInRange() 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 FirstInVRange() to read the whole variable-length record with one function call.

Return

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

See also

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

FirstInSet

Read the first data record in the set defined by target.

Short Name

FRSSET()

Type

ISAM function

Declaration

COUNT FirstInSet(FILNO keyno, pVOID target, 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

FirstInSet() reads the first data record in the set of data records whose keys match the target key in the first siglen bytes. If successful, this record becomes the current ISAM record for the associated data file. A successful FirstInSet() 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 target). If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

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 FirstInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

• In a 'bound' model (either standalone or if using the server DLL in your process), the TFRMKEY() call operates on the buffer that you pass to FirstInSet(), so the target buffer must be initialized to the full length of the key to avoid memory corruption when the target is transformed to match the key.
• In client/server mode the FairCom Server will perform the TFRMKEY on the Server side using a buffer sized for the key value.

FirstInSet() can be used to perform an equality search for duplicate keys. Set target to the key value and siglen to the key length less the 4 bytes of the suffix.

You do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions contains the correspondence between the index file number and the associated data file.

Return

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

Example

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

printf("\nEnter set value:");
scanf("%23s",target);
FirstInSet(keyfil,target,recbuf,strlen(target));
while (isam_err == NO_ERROR) {
   process_data();
   NextInSet(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

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

FirstInVRange

Read the first data record in a range.

Short Name

FRSVRNG()

Type

ISAM function

Declaration

COUNT FirstInVRange(FILNO keyno, 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

Read the first 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 FirstInVRange() 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 FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

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

FirstInVSet

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

Short Name

FRSVSET()

Type

ISAM function

Declaration

COUNT FirstInVSet(FILNO keyno, pVOID target, 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

FirstInVSet() is identical to it’s fixed-length counterpart, FirstInSet(), except that it reads the first variable-length data record in the set of data records whose keys match the target key in the first siglen bytes. 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 FirstInSet() for additional important information.

Return

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

Example

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

printf("\nEnter set value:");
scanf("%23s",target);
printf("\nEnter the significant length:");
getnumber(&siglen);
FirstInVSet(keyfil,target,recbuf,siglen,strlen(target));
while (isam_err == NO_ERROR) {
   process_data();
   NextInVSet(keyfil,recbuf);
}

See also

FirstInSet(), NextInVSet(), PreviousInVSet(), LastInVSet(), PositionVSet(), ChangeSet(), TransformKey().

FirstKey

Find the first entry in an index file.

Short Name

FRSKEY()

Type

Low-Level index file function

Declaration

LONG FirstKey(FILNO keyno, pVOID idxval) 

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

FirstKey() searches index file keyno for the first entry in the index. If successful, it copies the first index entry into the space pointed to by idxval.

Return

FirstKey() returns the data record position associated with the first entry in the index file. If the index is empty or an error is detected, FirstKey() returns zero. If FirstKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

TEXT         idxval[10];
FILNO        keyno;
s
if (FirstKey(keyno,idxval))
   printf("\nFirst index entry = %.10s", idxval);
else {
   printf("\nEither index is empty or an error occurred.");
   if (uerr_cod)
      printf("\Error = %d",uerr_cod);
   else
      printf("\Index is empty.);
}

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. The Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) topic contains suggestions for manipulating the key value.

See also

GetCtFileInfo(), LastKey(), NextKey()

FirstRecord

Read the first data record.

Short Name

FRSREC()

Type

ISAM function

Declaration

COUNT FirstRecord(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

FirstRecord() retrieves the first data record found. If filno designates an index file, FirstRecord() reads the first data record based on the key sequential order of entries in index file number filno. If filno designates a data file, FirstRecord() reads the first active data record, in physical sequential order. If successful, the first 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.

If filno designates a data file that is a member of a Superfile, FirstRecord() may not reliably return the FIRST physical active data record, though it will retrieve a record.

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 FirstRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If FirstRecord() 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) contain the correspondence between the index number and the associated data file.

Return

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

Example

FILNO     keyfil, datfil;
TEXT      recbuf[320];

if (FirstRecord(keyfil,recbuf)
    printf("\nError %d retrieving first record.", isam_err);
else if (ReReadVRecord(datfil,recbuf,320))
    printf("\nError %d retrieving variable portion.", isam_err);
else
    printf("\nSuccessful FirstRecord.");

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. When reading in physical sequential order, FirstRecord() may not retrieve the first possible record position if records have been deleted and the space is currently unused.

See also

CreateIFile(), ReReadVRecord(), NextRecord(), PreviousRecord(), LastRecord()

FirstVRecord

Read the first variable-length data record.

Short Name

FRSVREC()

Type

ISAM function

Declaration

COUNT FirstVRecord(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

FirstVRecord() is identical to it’s fixed-length counterpart, FirstRecord(), except that it reads the first variable-length data record in the data file. 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 FirstRecord() for additional important information.

Return

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

See also

FirstRecord(), NextVRecord(), PreviousVRecord(), TransformKey()

FreeBatch

Free space allocated for multiple batches (groups of records).

Short Name

FREBAT()

Type

ISAM function

Declaration

  COUNT FreeBatch() 

Description

FreeBatch() should be called when it is desired to free the space allocated by AllocateBatch() for multiple, simultaneous batches.

Ordinarily, the only time it is necessary to call FreeBatch() is when you desire to increase the number of simultaneous batches from a previous optional AllocateBatch(). In this case, you call FreeBatch() to free the buffers and then AllocateBatch() with the new upper limit on batches.

CloseISAM() will free multiple batch buffers if they have not already been freed via FreeBatch().

Return

FreeBatch() should always returns NO_ERROR (0) value. Even if FreeBatch() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

if (AllocateBatch(3) == 0)
          printf("Room for 3 batches\n");
          FreeBatch();
          if (AllocateBatch(7) == 0)
               printf("Room for 7 batches\n");

See also

AllocateBatch(), CloseISAM()

FreeBatchNbr

Free space allocated for a specific batch.

Short Name

FREBATN()

Type

Low-Level function

Declaration

COUNT FreeBatchNbr(COUNT batnum)

Description

FreeBatchNbr() frees batch number batnum. This routine permits flexible use of a large number of batches within particular code segments responsible for the creation and clean up of the particular batches. Instead of freeing all batches any time one batch needs to be freed, this function frees batches one at a time.

Return

This routine returns an error code, but should return NO_ERROR (0) even if the batnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO    keyfil;
PKEYREQ  batsamp;           /* Partial Key Request structure */
TEXT     recbuf(1024), retbuf(1024);  /* buffers for records */ 

batsamp.siglen = 4;             /* first 4 bytes significant */
sprintf(batsamp.target,"DISK");         /* partial key value */ 
ChangeBatch(PRIMARY);
if (DoBatch(keyfil,&batsamp,recbuf,1024,
          BAT_GET | BAT_RET_REC | BAT_COMPLETE | BAT_LOK_WRT)) {
     printf("\nBatch error %d",isam_err);
     return;
}
printf("\n%ld entries match",batsamp.btotal);

/* find info in batch */
if ((retbuf = find_in_batch(&recbuf, 1024)) != NULL) {
    ChangeBatch(SECONDARY)
    if (DoBatch(keyfil,&batsamp,retbuf,1024,
           BAT_GET | BAT_RET_REC | BAT_COMPLETE | BAT_LOK_WRT))
    {
         printf("\nSecondary batch error %d",isam_err);
         return;
    }
    printf("\n%ld entries match",batsamp.btotal);
    DoBatch(keyfil,NULL,NULL,0L,BAT_CAN); /* close the batch */
    FreeBatchNbr(SECONDARY);
    ChangeBatch(PRIMARY);
}
DoBatch(keyfil,NULL,NULL,0L,BAT_CAN);     /* close the batch */
FreeBatch();

See also

DoBatch(), FreeBatch(), ChangeBatch()

FreeHistory

Free space allocated for multiple history buffers.

Short Name

FREHST()

Type

ISAM function

Declaration

COUNT FreeHistory() 

Description

FreeHistory() frees the space allocated for multiple, simultaneous history buffers.

Return

FreeHistory() should always return a zero NO_ERROR (0) value. Even if FreeHistory() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

  
FILNO     filno;
pVOID     target, bufptr;
LONG      recbyt;
VRLEN     bufsiz;
UCOUNT    mode;

TransactionHistory(filno,target,bufptr,recbyt,bufsiz,mode);

FreeHistory();

See also

TransactionHistory(), ChangeHistory()

FreeHistoryNbr

Free space allocated for a transaction history.

Short Name

FREHSTN()

Type

Low-Level function

Declaration

COUNT FreeHistoryNbr(COUNT hstnum) 

Description

FreeHistoryNbr() frees history number hstnum. This routine permits flexible use of a large number of histories within particular code segments responsible for the creation and clean up of the particular histories. Instead of freeing all histories any time one history needs to be freed, this function frees histories one at a time.

Return

This routine returns an error code, but should return NO_ERROR (0) even if the hstnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

ChangeHistory(0);
if ((retval = TransactionHistory(CUSTIDX, target, &bufptr, 0L,
              (VRLEN) INPBUFSIZ+40,
              ctHISTfirst | ctHISTkey | ctHISTdata)) > 0) {
    printf("\nError in first call : %d", retval);
    isam_error();                                                        
    return;
}
displayhistorybuffer(bufptr, INPBUFSIZ);
repeat("\n\nGet next match? ", choice);

while ((choice[0] == 'Y') || (choice[0] == 'y'))  {
    if ((retval = TransactionHistory(-1, (pVOID) 0, &bufptr,
                  0L, (VRLEN) INPBUFSIZ+40, ctHISTnext)) > 0) {
        if (retval == HENT_ERR) {
            printf("\nEnd of logs or bad logs.");
        } else {
            printf("\nError in subsequent call : %d", retval);
            isam_error();                         
        }
        return;
    } else {
        displayhistorybuffer(bufptr, INPBUFSIZ);
        repeat("\n\nGet more data? ", &choice);
    }
}
TransactionHistory(-1,(pVOID) 0, (pVOID) 0, -1L, (VRLEN) 0, ctHISTlog);
   /* Default terminating call */
FreeHistoryNbr(0);

See also

TransactionHistory(), FreeHistory(), ChangeHistory()

FreeRange

Reset and free allocated buffers for range operation

Short Name

FRERNG()

Type

ISAM function

Declaration

COUNT FreeRange(FILNO keyno)  

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

FreeRange() should be called when a range associated with an index is no longer needed.

Return

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

Example

if (FreeRange(1))
    printf("\nFreeRange error = %d",uerr_cod);

See also

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

FreeSet

Free space allocated for multiple sets.

Short Name

FRESET()

Type

ISAM function

Declaration

COUNT FreeSet() 

Description

FreeSet() should be called when it is desired to free the space allocated by AllocateSet() for multiple, simultaneous sets.

Ordinarily, the only time it is necessary to call FreeSet() is when you desire to increase the number of simultaneous sets from a previous optional call to AllocateSet(). In this case, you call FreeSet() to free the buffers and then AllocateSet() with the new upper limit on sets.

CloseISAM() frees all set buffers if they have not already been freed via FreeSet().

Return

FreeSet() should always returns NO_ERROR (0) value. Even if FreeSet() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

if (AllocateSet(5) == 0)
    printf("\nRoom for 5 sets\n");

FreeSet();

if (AllocateSet(10) == 0)
    printf("\nRoom for 10 sets\n");

See also

AllocateSet(), CloseISAM()

FreeSetNbr

Free space allocated for a specific set.

Short Name

FRESETN()

Type

Low-Level function

Declaration

COUNT FreeSetNbr(COUNT setnum) 

Description

FreeSetNbr() frees set number setnum. This routine permits flexible use of a large number of sets within particular code segments responsible for the creation and clean up of the particular sets. Instead of freeing all sets any time one needs to be freed, this function frees sets one at a time.

Return

This routine returns an error code, but should return NO_ERROR even if the setnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

COUNT     i;
FILNO     keyno0, keyno1;

struct DATAREC datrec0, datrec1;

if (ChangeSet(0))
    printf("\nCould not change set. Error=%d\n", isam_err);
if (FirstInSet(keyno0, &datrec0))
    printf("\nCould not get FirstInSet. Error=%d\n", isam_err);

if (ChangeSet(1))
    printf("\nCould not change set. Error=%d\n", isam_err);
if (LastInSet(keyno1, &datrec1))
    printf("\nCould not get LastInSet. Error=%d\n", isam_err);

FreeSetNbr(0);

See also

FreeSet(), FirstInSet(), ChangeSet()