Apollo VCL Components > Apollo VCL Component Reference > TApolloTable > TApolloTable Methods

Declaration

procedure Replace( sFieldName: String;

iDataType: Integer;

vpData: Pointer );

Description

Replaces the named field's contents in the record buffer with the given data value.

$image\tip.gif$ The standard TDataSet.FieldByName('???').As??? syntax can be used in place of this method, and is also somewhat easier to use in most cases. See the Delphi/C++Builder help for more information on the FieldByName method.

Note that pointers to BLOBs must be written with PutBlob.

Parameters

sFieldName: The name of the field.

iDataType: The type of data represented by vpData. It must be one of the following defined constants:

R_INTEGER Short Integer

R_LONG Long Integer

R_DOUBLE Doubles or Floats

R_JULIAN Julian Dates (*)

R_LOGICAL Boolean (T/F)

R_CHAR Character (0-255 bytes long)

R_CHAREX Long Character (255+ bytes long)

R_DATESTR Date String

R_MEMO Memo text

R_BITMAP Bitmap image

R_BLOBFILE Binary Disk File

(*) Only JULIAN dates equal or greater than January 1, 1000 are supported.

vpData: vpData must be of the data type indicated by iDataType.

Note that logical fields are replaced by numeric values (0 for False and non-zero for True). The RDE takes care of translating these into "T" or "F" in the case of DBF files.

Replacement values of type R_DATESTR must be formatted according to the setting of SetDateFormat and SetCentury.

Replaced data is not immediately written to disk (except in the case of memos). In a multi user environment it is good practice to physically commit the record changes to disk by calling Commit.

Replacement data of types R_CHAR or R_CHAREX must be a PChar type. This can be insured by either explicitly declaring the variable as a PChar in your var section or by casting a literal string parameter value as a PChar. A pointer to an Array of Char can also be used (See the example below).

Short Binary Values

To store short binary values in memo fields, use the PutBinary method.

Bitmaps and BLOBs

Binary large objects (BLOBs) may be stored in memo fields. The maximum size of a binary large object that may be stored with Replace is 16 megabytes.

Bitmaps

A bitmap (i.e., picture) is a type of BLOB; we make the distinction because a BLOB that is explicitly defined as a bitmap may be moved to the Windows clipboard with TApolloTable methods.

The vpData parameter for R_BITMAP types is passed as a file name (including path) to a standard Windows .BMP or .RLE file. The file is stored in a special format in Apollo FPT, SMT, and DBT memo files. If RLE files are stored, they must be run length encoded compressed variants of BMPs in either 4 or 8 bit per pixel format. FieldType returns type "P" for stored bitmaps.

BLOBs

Apollo memo fields may store any type of binary data. R_BLOBFILE types refer to any binary large object that is stored in a file. If the type is R_BLOBFILE, the binary object is retrieved from the named file.

Apollo may also store binary large objects created by the applications program (e.g., numeric arrays). In this case, use PutBlob to write the BLOB to the memo file.

BLOBS may be retrieved with the GetBlob method. Because a BLOB may store any type of information, it is entirely up to the applications programmer as to what is done with the BLOB after retrieval.

See the "Using Memo/BLOB Fields" section for important information on BLOB usage with Apollo.

FieldType returns type "B" for stored BLOBS.

Delphi Example

procedure TForm1.Button1Click(Sender: TObject);

var

sLast, sNotes, sDate : String;

cpLast : Array[0..30] of Char;

cpNotes : Array[0..100] of Char;

iVal : Integer;

lVal : LongInt;

bVal : WordBool;

begin

with ApTbl do

begin

try

begin

Edit;

// Set up values to be stored

sLast := 'Simpson';

StrPCopy( cpLast, sLast );

sNotes := 'Husband of Marge. Father of Lisa, Bart, and Maggie.';

StrPCopy( cpNotes, sNotes );

sDate := '12/31/85' + #0; {Remember to null-terminate}

iVal := 39;

lVal := 42000;

bVal := True;

// Store them (Remember to use pointers to the values)

Replace( 'FIRST', R_CHAR, PChar( 'Homer' ));

Replace( 'LAST', R_CHAR, @cpLast );

Replace( 'NOTES', R_MEMO, @cpNotes );

Replace( 'HIREDATE', R_DATESTR, @sDate[1] );

Replace( 'AGE', R_INTEGER, @iVal );

Replace( 'SALARY', R_LONG, @lVal );

Replace( 'MARRIED', R_LOGICAL, @bVal );

Post;

end;

except

ShowMessage( 'Record already in use!' );

end;

C++Builder Example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

String sLast;

String sNotes;

char cpLast[31];

char cpNotes[101];

char cpDate[9];

int iVal;

long lVal;

bool bVal;

try

{

ApTbl->Edit();

// Set up values to be stored

sLast = "Simpson";

StrPCopy( cpLast, sLast );

sNotes = "Husband of Marge. Father of Lisa, Bart, and Maggie.";

StrPCopy( cpNotes, sNotes );

StrPCopy( cpDate, "12/31/85" );

iVal = 39;

lVal = 42000;

bVal = true;

// Store them (Remember to use pointers to the values)

ApTbl->Replace( "FIRST", R_CHAR, PChar( "Homer" ));

ApTbl->Replace( "LAST", R_CHAR, cpLast );

ApTbl->Replace( "NOTES", R_MEMO, cpNotes );

ApTbl->Replace( "HIREDATE", R_DATESTR, cpDate );

ApTbl->Replace( "AGE", R_INTEGER, &iVal );

ApTbl->Replace( "SALARY", R_LONG, &lVal );

ApTbl->Replace( "MARRIED", R_LOGICAL, &bVal );

ApTbl->Post();

}

catch (...)

{

ShowMessage( "Record already in use!" );

}