CapeSoft.Com
Clarion Accessories
Replicate
Documentation
Technical Documentation
CapeSoft Logo

CapeSoft Replicate
Technical Documentation

Download Latest Version JumpStart FAQ History
Installed Version Latest Version

Note: The term 'a file change' is used to refer to an add, edit or delete of a record.

Can't find what you're looking for? Click here to search the entire Replicate documentation.

How to embed code into a derived Replicate method:

In your app (or LogManager), go to the module tab, dbl click on the default prog module, click the embeds button, scroll down to the Replicate tree, find the method you're after and put your code in one of the embed points there:

Embedding code in a derived method

csLog Class

Introduction

The csLog Class is Replicate's base class for all Replicate's classes. Basically the csLog class handles handles the actual logging of the records. In order to make this happen, it needs to have all the files registered and some of the site details setup (like which site am I, etc.). The csLog class definitions are located in the Replicate.inc file, and the method source code is in Replicate.clw.

Methods

MethodParameters Method Description
Init( )This method just initializes the queues that the object uses. The Global Template populates this method in the global module (before any windows are open/run).
Methods Called:
The Registration method and the Configure method.
Kill( )This method clears and disposes the object's queues, and closes the log files (if open).
Open()This method opens the logfile. Before opening, it checks if the logfile must be ended, and a new logfile created and used. 

Methods Called:
The Close method (if the file is already open), the GetNextNumber method (if a new file must be created), and the Insert method (if it needs to stamp the header site at the top of the file). StampEOF, CheckEOF, GetFileName
Open(*file pFile,
*string pData,
*string pFileName,
byte pCreateNew=0),long
This method opens a logfile (log, export, import, etc). Returns a 0 if successful, otherwise the errorcode.
Parameters:
pFile - a handle to the file structure
pData - a handle to the data string
pFileNamge - a handle to the string containing the filename.
pCreateNew - If set, then the logfile will be CREATEd (even if it exists already)
Close (byte pCloseTemp=0
,byte pStampeEOF=0)
This method closes the logfile.
Parameters: 
pCloseTemp - If set, then the TempLogFile (which is used during logout mode) is closed.
pStampEOF - if set, stamps the EOF stamp onto the end of the file.
Insert (string DataString,
<string FileLabel>)
This method is used to insert entries into the logfile (or tempfile depending on whether a file is logged out or not) - this calls the other insert method. 
Parameters:
DataString - the string that must be entered into the logfile
FileLabel - the name of the Table that had the change (used to identify files that have been loggedout).
Insert (string DataString,
<*File FileID>,
*string pData,
byte pOptions=0)
This method is used to insert entries into the logfile (or tempfile depending on whether a file is logged out or not). 
Parameters:
DataString - the string that must be entered into the logfile
FileID -  the file handle of the logfile File
pData - a handle to the DataString of the logfile
pOptions - Passed on to AddToLog method.
Register (*File FileID,
string FileLabel,
*Group RecordID,
*String GUID,
*Group RecordHist
,<*string SiteField>
,<string pSuperPre>)
This method is used to build an internal file queue of all the files whose changes must be logged.
Parameters:
FileID - the handle of the file to be registered
FileLabel - the label of the file to be registered.
RecordID - the handle of the Record group.
GUID - the handle of the GUID field.
RecordHist - the handle of the variable that contains a copy of the record when a record is read.
SiteField - the handle of the SiteField in the file.
pSuperPre - the SuperPrefix of an External DLL table (for unique identification).
RegisterArray (string pFieldLabel
,*string ArrayID
,*string ArrayHistID
,byte threaded=0
,<string pFileLabel>
,long pFieldPosition=0)
This method registers any arrays that occur in your file structures.
Parameters:
FileLabel - the label of the file which contains the array
ArrayID - the handle of the array in the Record structure
ArrayHistID - the handle of the variable that contains a copy of the array when a record is read.
Threaded - indicates that the file is opened in a new thread.
pFileLabel - the label of the file that this array belongs to (for External DLL tables)
pFieldPosition - the position of the array in the Record of the table (for External DLL tables)
GetMemo (String MemoLabel),StringReturns the value of the specified memo (code is generated into the application's default module). 
Parameters:
Memolabel - the label of the memo to be returned
GetGUID ( ),stringReturns the GUID value to be used in an insert record.
Configure( )Warns if the site details aren't setup. Template generates code into the child to set the site details up.
Methods Called:
GetNextNumber, CheckDirectory
GetNextNumber (String SiteID,
<long Number>),Long
This returns the number of the current log file that should be used for logging (for self.site), or it returns the logfile number of the last completed import (from the site specified). (code is generated into the application's default module)
Parameters:
SiteID - the label of the site whose lastnumber must be returned.
MethodsCalled:
StampEOF (if a new LogFile must be logged to, and the last one must be ended). CheckEOF
SetMemo (string MemoLabel,
*string Value)
This method is used to set the valuelabel of the Memo field specified (code is generated into the application's default module).
Parameters:
Memolabel - the label of the memo to be changed
Value - the handle of the variable containing the value for the memo
RepMessage (string MessageID,
<string ButtonText>,
<long DefaultButton>)
,long,proc
This method calls the message() function and allows for translation of the messages used in the Replicate objects.
Parameters:
MessageID - an index used to identify the messagetext.
ButtonText - a string containing the buttonstring or the button equates.
DefaultButton - identifies the default button.
CloseFile (string FileLabel,
<string pDebugString>),long
Closes the file specified.
Parameters:
FileLabel - the label of the file to be closed.
pDebugString - a string to output to the debugger
OpenFile (string FileLabel,
<string pFromWhere>,
long pMode=0),long
Opens the file specified.
Parameters:
FileLabel - the label of the file to be opened.
pFromWhere - a string to output to the debugger
pMode - indicates what mode the file must be opened in (if zero, then opened in default mode).
PrimeLog (string opCode,
 *File FileID,
<string pSiteID>,
byte pOptions=0),string
Returns a string configured for a complete log file entry when a file changes.
Parameters:
opCode - contains a label of the change type (insert/update/delete,etc)
FileID - the handle of the file which has been changed.
pSiteID - reserved for derived methods
pOptions - reserved for later use
MethodsCalled:
GetMemo, MemoChanged (checks if a memo has changed when an update occurs)
RegisterSuppressed (*File FileID,
string FileLabel,
<*? SuppressedField>,
<string FieldLabel>,
byte pOptions=0)

This method registers a field to be omitted from replication, or a file for directional replication if the fields are omitted. 
Parameters:
FileID -  a pointer to the file (containing the omitted field)
FileLabel - the dictionary label of the file
SuppressedField - a pointer to the field to be omitted
FieldLabel - the dictionary of the field to be omitted.
pOptions - b1 - Read, b0 - write.
StoreBuffer (*File FileID,<string pAction>,byte pImporting=0)Stores the record, memos and arrays into the history variables when a record is fetched (code is generated into the application's default module).
Parameters:
FileID - the handle of the file whose record is fetched.
pAction - if the LogManager is importing a change, then Action will be set to Insert, Update, UpdateFull or Delete.
pImporting - set if the StoreBuffer is called immediately prior to an imported Insert, Update, UpdateFull or Delete.

Note: be careful deriving this method as it is used to store previous file buffer states before a filechange. For file activity, set a flag and then perform the activity after Replicate has done the action. IOW, rather use the FileChange method (in the LogManager) to handle file activity after the LogManager has imported the file change that it is about to perform.
MemoChanged (string MemoLabel),ByteReturns whether the specified memo has changed(1) or not (0).
Parameters:
Memolabel - the label of the memo to check.
Commit ( )Commits the file changes occurring during a logout to the logfile.
LogToTemp (*File FileID),longOpens a TempLogFile when a Logout is issued, and stores each logged out file in a queue. Returns: 0 = file opened, 1 = file already open, 2 = error opening file.
Parameters:
FileID - the handle of the file to add to the logout queue.
StampEOF (long Number,
long DateStamp,
byte ForceStamp=0)
This method calls the generic StampEOF method.
Parameters:
Number = Number of the log file to stamp.
DateStamp = Date to stamp the EOF tag.
ForceStamp = set if stamp must be stamped, even if we should be using this logfile.
StampEOF (*file pFile,
*string pData,
long DateStamp,
byte ForceStamp=0),long
Stamps the EOF tag onto the end of the log file.
Parameters:
pFile - a handle to the file structure to stamp the EOF into.
pData - a handle to the data string.
DateStamp = Date to stamp the EOF tag.
ForceStamp = set if stamp must be stamped, even if we should be using this logfile.
Methods Called:
CheckEOF, GetFileName, Open, Close
HexFormat (long LongValue,
byte places),string
Formats a long into a HexNumber. Returns the Hex number (in a string).
Parameters:
LongValue - The long value to be converted
Places - Number of digits to return.
Registration ( )This method is an entirely generated child method, used to register each file, array and omitted field.
GetSettingWindow (<string Setting>),stringReturns a string input for a setting requested by the object. This method provides the user with a window to return a string input for a setting requested by the object.
Parameters:
Setting - the text for the window title bar describing the setting.
AddSetting (string Setting,
<long option>),string
This method is used to create a setting that has not been entered before. This is used for required settings, and directs the selection help to either the GetSettingWindow or the filedialog window. Returns the setting (or blank if not selected).
Parameters:
Setting - the label of the setting occuring in the ini file.
Option - Unused (reserved for later).
Methods Called:
UpdateSetting, GetSettingWindow
UpdateSetting (string setting,
string value)
Updates the ini file settings.
Parameters:
Setting -  the ini label of the setting
Value - the value of the variable and the setting.
GetSetting (string setting,
byte pOptions=0),string
Returns the setting specified (from the ini file, or from a window). Template generates code into the child method.
Parameters:
Setting - the label of the setting from the ini file.
pDontUpdate - b0 set don't update the setting if it is not correct. b1 set, then prime FTP with the default.
ClearSavedFields (string FileName)This method is used to clear the saved fields variables (code generated into the derived method by the template).
Parameters:
FileName - the label of the file whose variables must be cleared.
SetNextNumber (String SiteName,
Long Number,
long LastSize=0)
This method is used to record the log file number used (in the last completed import) or that must be used (for our own logging). Code is generated into the child method.
Parameters:
SiteName - the name of the site who's number must be set.
Number - the number to set the next number to. (if 0 then only the size will be updated).
LastSize - the size of the imported file received (if no EOF was received).
Methods Called:
GetGUID
CheckEOF (<string pLogFileName>,
byte OnlyEnd=0),long
This method calls the generic CheckEOF.
CheckEOF(*File pFile,
*string pData,
byte OnlyEnd=0),long
This method checks if there is an End of File stamp in the log file. If there is, it returns the date of the End Of File stamp, otherwise (if no stamp) it returns a 0 or a negative number (if and error occurred).
Parameters:
pFile - the handle of the file structure to check.
pData - the handle of the data string.
OnlyEnd = only checks the last record length of bytes.
GetFileName(<string SiteName>,
long Number,
byte NoPath=0),string
This method returns a correctly formed the logfile name.
Parameters:
SiteName - if omitted, assumes self.site.
Number - the number for the log file.
NoPath - if set, then the filename returned will not include a path.
Methods Called:
HexFormat
CheckDirectory(*? DirToCheck,
byte MakeDir=0),long
This method checks the existence of a directory and returns a 1 if it is available and 0 if not.
Parameters:
DirToCheck = a handle to a string that contains the path of the directory to check.
MakeDir = b6 Set if the directory must be created.
Methods Called:
SetPathTo
GUIDFieldToText(*group FileRecord,
long GUIDPosition,
<*long GUIDTextLen>,
<string pExtraTag>,
long pMakeUpper=0)

This method takes the passed record, separates the GUID and decodes it into a string with 4 components and separated by commas. It returns the string
Parameters:
FileRecord - the handle of the RECORD group containing the GUID.
GUIDPosition - the position of the GUID in the group.
GUIDTextLen - this value is incremented by the length of the string returned
pExtraTag - tags to place in the GUID tag (to make it a parent).
pMakeUpper - makes the GUID label upper (for CRC comparison), otherwise leaves the GUID label as is in the dct.
SetPathTo (string PathName),longThis method is used to do a SETPATH() for  short form directory names (like '.' , '..' , '.\' , etc). Returns a 0 if Path set, otherwise the errorcode() of the last SetPath.
Parameters:
PathName - the name of the directory to change to.
GetBlob (string BlobName,
*long BlobSize),STRING
This method is used to return the contents of a BLOB. The template generates a derived method.
Parameters:
BlobName - the field name of the BLOB.
BlobSize - the handle of the variable to contain the size of the BLOB.
BlobChanged (string BlobName,
*long BlobSize),long
This Method is used to test if the BLOB has changed (since the last get). Returns a 1 if it has changed. The template generates a derived method.
Parameters:
BlobName - the field name of the BLOB.
BlobSize - the handle of the variable to contain the size of the BLOB.
SetBlob (string BlobName, 
*? FieldValue)
This method is used to Set the contents of a BLOB. The template generates a derived method.
Parameters:
BlobName - the field name of the BLOB.
FieldValue - a handle to the ANY containing the BLOB contents.
ChangeBlobTouched (*File FileId,
byte SaveTouched=0)
This method is used to store the contents of the prop:touched value of the BLOBs in a file in their respective History global variables. The template generates a derived method.
Parameters:
FileID - a handle to the file containing the BLOBs.
SaveTouched - if set, will save the current PROP:Touched values, otherwise clears the saved ones.
GetBlobName (*File FileID,
long BlobNumber),STRING
This method is used to return the names of BLOBs in a file. The template generates a derived method.
Parameters:
FileID - a handle to the file containing the BLOBs.
BlobNumber - a BLOB Index number. 
SetArray (string ArrayName) This function is used (in Clarion6) if a threaded file is used to set the Array field when importing
GetArray (string ArrayName) This function is used to get the array and it's history field.
Construct ( ) This method is run every time a thread is started in Clarion6. From here the Init method is called to initialise the threaded class.
Destruct ( ) This method is run every time a thread is killed in Clarion6. From here the Kill method is called to dispose the threaded class.
GenerateTranslationFile (string pFilename) This method will generate a translation file with all the text needed to be translated (that is used in the Replicate classes).
Parameters:
pFilename - the name of the translation file to be created/appended.
GetTranslation (string pINISection,
string pINIVariable,
<string pINIValue>)
,string,proc
This method returns the translated text from the translation file. It will also place default text there if the Translation file is not found.
Parameters:
pINISection - The section of the translation file
pINIVariable - The variable.
pINIValue - the default value (if omitted the pINIVariable is assumed the default)
GenerateCRC (*file pFileID,
*string pData,
*long pFileSize,
byte pOptions=0),long
This method adds a CRC to a logfile. It is also used to check a CRC and correct (if nec). 0 = fine, -1 if the CRC exists but is incorrect, -2 if no CRC exists, and errorcode() if there is a problem opening, closing, reading or writing to the file.
Parameters:
pFileID - the handle of the file
pData - the handle of the string containing the data
pFileSize - the handle of a long containing the size of the data (set to 0 if unknown)
pOptions - bit0 is set if the CRC must just be checked.
IgnoreField (*file pFileID,
long pFieldNo,
<? pValue>,
byte pImporting=0,
<string pAction>),long

This method is called by the PrimeLog method as its writes the file changes to the logfile. Overed fields and Groups are (by default ) not written to the file, but if you need to write these, you can enter code in here to make sure the field is not ignored. Returns a 1 if Field must be ignored, a 2 if the entire record must be ignored, otherwise it will not be ignored.
Parameters:
pFileID - the handle of the table that was changed.
pFieldNo - the Number of the field in the record group.
pValue - the value of the field (for value dependent ignoring)
pImporting - set if currently importing from the logfile.
pAction - the file action that will be performed (insert, update, updatefull or delete)
ChangeFields (*file pFileID,
long pOpcode)

This method allows you to add code to change fields before the record is written to the file.
Parameters:
pFileID - the handle of the file being written to
pOpCode - a long containing the code of the instruction written to the file
DeRegister (*file pFileID) This method allows you to de-register a file on the file, if the file should no longer be logged.
Parameters:
pFileID - the handle of the file to be de-registered.
PrimeSiteField (<*file pFileID>,
<string pSiteID>,
<string pOldSiteValue>,
byte pOptions=0),long
Goes through a table (or your entire database) and replaces the OldSite value with the new SiteValue.
Parameters:
pFileID - the handle of the file to scan and replace. If omitted, will perform the replacement on all the tables in your dictionary.
pSiteID - the new SiteID to prime (generally RepGLO:Site)
pOldSiteValue - the SiteID to search for
pOptions - b0 Rep_CheckIfDone - registers when this operation occurs and prevents this from running again.
GetFileNumber
(string FileName) This method returns the number from a logfile name passed.
Parameters:
FileName - the name of the logfile to return the number of.
GetLastFileNumber 
(<string pDirectory>,
<string pSiteID>),long
This method returns the number of the last logfile used.
Parameters:
pDirectory - the directory in which the logfiles reside (logpath used if omitted)
pSiteID - the label of the site (self.site used if omitted)
HexToLong(String HexVal),longThis method returns the long value of a Hex string.
Parameters:
HexVal - the string containing the Hex number
SortFileQ (*RepDirQueue pFileQueue,
byte pOptions=0)
This method sorts the pFileQueue into Replicate logfile number order.
Parameters:
pFileQueue - the handle of the FileQueue 
pOptions - bit loaded flag. If bit1 set, then corrects the FileDate field.
GetFileDate (string pFileName,
long pFileDate),long
This method extracts the date from a logfile. This would normally be the date in the EOF stamp, but if not stamped, then it would be the date of the file.
pFileName - the name of the file
pFileDate - the default date (should the be no EOF stamp)
AddToLog (? pDataToAdd,
long pDataLen,
long pNumberOfTries=10,
byte pOptions=0,
*file pFile,
*string pData),long
This method is used to add to the logfile (or tempfile or external file). Returns an errorcode() if not successful, otherwise a 0.
Parameters:
pDataToAdd - the string of data to add to the file
pDataLen - the length of the string of data to add
pNumberOfTries - number of times to attempt writing before erroring out.
pOptions - a bit loaded flag, indicating whether to lock the file or not and whether to CheckEOF or not. Use Rep_NoFileLock and Rep_CheckEOF.
OpenTempFile (),long This method opens the Temporary file (for logout). Returns the errorcode if an error occurred, otherwise a 0.
AutoInit ( ) This method calls the Init method if the CanConstruct is set. This method is called from the Construct method.
AddExtraTag (string opCode,*File pFileID),string This method is used to return an extra string to add into a log entry.
Parameters:
opCode - the file action (Insert, Update or Delete)
pFileID - the handle of the file edited
GetLogFileHeader (),string This method is used to return the generic logfile header string.
GetLogFileFooter(),string This method is used to return the generic logfile footer string.
SetGlobalSetting (string pSetting,
? pValue)
This method locks the thread and sets the global property specified in the pSetting to pValue. You can also increment or decrement a Setting using '+' and '-' in the value.
pSetting = name of the property to set.
pValue = the value to set the property to.
GetGlobalSetting (string pSetting),? This method locks the thread and returns the global property specified in the pSetting.
PrimeString (string opCode,
*File FileID,
<string pSiteID>,
byte pOptions=0,
*long pLen),string
This method calls the PrimeLog method, but sets the length variable as well.
Parameters:
opCode - code of the function
pSiteID - if this table has a site field
pLen - the handle of a long to receive the length of the primed string.
RestoreBuffer (*File FileID) Restores the specified file's record buffer from that stored in the history.
FileID - the handle of the file to restore.
GUIDFieldToString (string pGUIDField),string This method returns a string value of the passed GUID value that will be displayed in the XML file.

Properties

The Following Properties are in the GlobalSettings class - (an unthreaded class in Clarion6). You must use the SetGlobalSetting method to set them. They were previously in the Threaded class, so if you're upgrading from a version prior to 1.69, then you will get errors wherever there is a reference to the property that was in the threaded class.
Property TypeProperty Description
LogFileName string(255)The current log file name
LogFileNumber LongThe current log file number
LogFileDate LongThe Date of the log file (when closed)
LogFileTime LongThe time of the logfile (when closed - for more than daily log files)
Configured byteA flag to indicate that the Replicate methods have been configured.
User string(255)An optional string containing the user (which if present will be written into the logfile)
Silent byteA flag indicating, progress windows (during import, etc.) must not be displayed.
Active byteA flag indicating that the logging is inactive/active (during configuring)
SuppressWarnings byteA flag indicating whether to display(0) or suppress(1) warning messages.
TranslationFile string(255)The name of the file to be used for translating where nec. (messages, etc.)
DebugMode byteA flag indicating that debug postings must be sent to the debugger.
NoLogging byteYou can set this property if you do not want your application to Log a transaction. You must clear this in order to resume logging.
CanConstructbyte(0)C6 only. This property is set in the Init method the first time it is called. From there on, all Inits from the construct method will be executed completely.
Inited byte,dim(MaxNoOfThreads)A flag to indicate that the Replicate methods have been initialized.
LogOff byte,dim(MaxNoOfThreads)A flag used to temporarily prevent loggings from occurring.
Inside byte,dim(MaxNoOfThreads)A flag to indicate that the method is inside the locally derived FileCallBackInterFace methods.
TempOpened byte,dim(MaxNoOfThreads)A flag indicating that the Temporary logging file has been opened (during logout mode).
DebugGroupA group of flags to specify what debug output to track.
AbortNowbyteSet this flag to abort out of a processing loop. Normally this is to interrupt the ProcessLogFiles and exit the program. If the program is resumed, then you must reset the AbortNow once the task required is completed (otherwise none of the processing will execute).
The following properties are in both the GlobalSettings class and in the Threaded class as well. These are set once at runtime, and each time a thread is opened, a copy is made into the threaded class from the GlobalSettings. You must not change these settings at runtime.
Property TypeProperty Description
SiteFieldID cstring(20)Contains an identifier for the site fields in the dictionary files.
LogExtension string(3)Contains the extension of all log files used by the program (log by default).
SettingsFile CSTRING(255)This property contains the ini filename where all the necessary configuration settings are kept.
LogFilePath string(255)The path where the log files will be opened
Machine string(255)An optional string containing the machine (which if present will be written into the logfile)
Sitestring(4)Contains the ID of the current site.
ParentSite string(4)Contains the parent site for this site.
These properties exist only in the Threaded class, and are thus related only to the thread that the threaded class is in existence.
Property TypeProperty Description
RecordQueueType Queue,TypeThis queue type is used to make a queue to store the information of the files in your dictionary for the Replicate objects use.
File &fileA pointer to the file
Label string(255)The file's dictionary name.
Record&GroupA pointer to the record structure
GUID &StringA pointer to the GUID field
GUIDField LongThe where value of the GUID field.
GUIDLabelstring(50)The Label of the GUID field
GUIDKey &KeyA pointer to the GUID key.
BestKey &KeyFor site related tables - the best key to handle site-related data.
LastRecord &GroupA pointer to the saved record field (a created global variable)
SiteField longThe where value of the Site field
SiteFieldID &StringA pointer to the Site field
SuperPrefixstring(20)Used for tables in external DLLs - gives a unique identifier.
end
ArraysQueueType Queue,TypeThis queue type is used to make a queue to store dimensioned field info of arrays in your dictionary.
label string(255)The label of the array.
sub &stringA pointer to the string over the array (a created global variable)
size longThe byte size of the array.
stored &stringA pointer to the saved string (a created variable).
threaded byteFor Clarion6 support - set if the File is a threaded file.
filelabelstring(FileNameSize)Stores the label of the file where this array exists (for external DLL files).
FieldPositionlongFor external DLL tables.
  end
OmitQueueType Queue,TypeThis queue type is used to make a queue to store a list of the fields (in your dictionary defined files) that must not be replicated.
File &FileA pointer to the file containing the field (to be omitted).
Filelabel string(255)The label of the file.
Field anyA pointer to the omitted field.
FieldLabel string(255)The label of the omitted field.
FieldID longThe where value of the omitted field.
WriteOnly byteIf set, writes the field to the log file, but does not read it.
end
LogoutQueueType Queue,TypeThis queue type is used to make a queue to store a list of the files that are in logout mode after a logout command.
File &FileA pointer to the file
FileLabel string(255)The label of the file
end
OmitFileQueueTypeQueue,TypeStores a list of the tables to omit (with the directional parameter).
File&FileA handle to the file
Labelstring(FileNameSize)The dictionary label of the file
ReadWritebyteRead (b1) - allows importing, Write (b0) - allows exporting. This should be XOR true (otherwise file either registered, or not register).
end
q &RecordQueueTypeThe actual file queue (as defined above).
aq &ArraysQueueTypeThe actual array queue (as defined above)
Omitq &OmitQueueTypeThe actual Omitted fields queue (as defined above)
OmitFileq &OmitFileQueueTypeThe actual Omitted file queue (as defined above)
Lq &LogoutQueueTypeThe actual Logout files queue (as defined above)
Opened byteA flag to indicate that the log file is open (1) or closed (0)
TempFileName string(255)Contains the name of the Temporary logging file during logout mode.
ExportFileName string(255)Contains the filename for the data to be exported to.
Exporting byteA flag to indicate that Replicate is in the process of exporting to dataset.
InGetNextNumber byteThis property gets incremented at the start of the GetNextNumber method (generated code) and decremented at the end). This is to prevent nested looping.
_StringHandlelongThe handle of a string that was created in the method called (where applicable). This means that the memory can be disposed at the calling procedure to prevent memory leaks.
ThisThreadlongContains the thread for the threaded class (so we don't have to use the Thread() function every time).
SiteFileString(255)Contains the label of the SiteFile.

Source Code Examples

NB - if you are handcoding calls to the Insert, PrimeString, Export and/or SearchAndReplace methods, then you must dispose the returned string using the _StringHandle property as follows:

self.FTPInDir = self.SearchAndReplace(self.GetSetting('FTPInDir',Loc:FTPDone),'\',self.FTPDirSeparator)
if self._StringHandle
     
!What we're basically doing here is disposing the string
      !that was created in the PrimeString method. ANYs don't get freed so
      !they keep chowing memory.

  Loc:SendString &= (self._StringHandle)
  dispose(Loc:SendString)
  self._StringHandle = 0
end

csLogManager Class

Introduction

This class makes use of the csLog Class as it's base object to build in some useful features. These features are described in more detail in the Replicate Documentation in the following sections:

Methods

Method ParametersMethod Description
MoveFilesIn(string FileExtension),
byte
This method imports the files that are located in the incoming directory, and then moves them to the log directory. Returns a (1) if successfully moved in, else a 0.
Parameters:
FileExtension - the file names of the log files to import (can contain wild cards).
MethodsCalled:
Import, CopyIn.
MoveFilesOut(long FromFileNumber=0,
byte pOnlyThisOne=0),long
This method is used to copy our own log files from the log path to the outgoing directory. Returns an error, or 0 if OK.
Parameters:
FromFileNumber - the number of the file to move out. If 0 , uses the LastOut property.
pOnlyThisOne - if set, then only the file specified will be moved out.
Methods called:
UpdateSetting (updates the LastCopiedOut value)
Import(string ImportFileName, byte Manual=0),longThis method imports a log file and implements all the file changes to the relevant files as specified in the log file. Returns a -1 if a complete log file was imported, a 0 if a partial log file was the last to be imported, a 1 if the ImportFile could not be opened.
Parameters:
ImportFileName - the log file to import (no path)
Manual - a bit loaded flag to indicate:
bit1 - if set then this is a manual import.
bit2 - if set then use LOGOUT/COMMIT to increase the import speed.
bit3 - if set, Append/Build is used during Manual instead of ADD.
Methods Called:
GetNextNumber, HexFormat, SetNextNumber, AddToHistory, Close, BytesDone, CloseFile, PrimeLog, Insert, Storebuffer, SetMemo, OpenFile, FileChange, TagReceived
Setup( )This method setups up the transporting of the logfiles (Incoming dirs, out going, etc)
Methods Called:
AddSetting, GetSetting, UpdateSetting
CopyIn(*string Source,
string Destination, byte pOptions=0),
LONG
This method copies the files (including extensions) from the source to the destination names.
Parameters:
Source - Directory and complete file name of the existing files.
Destination - the directory and complete file name to where the files must be copied.
pOptions - can specify whether the files must not be deleted after copy in.
CopyOut(string Source,
string Destination,
byte DeleteAfter=0),
LONG
This method copies the files (excluding extensions) from the source to the destination names. The extension used is the log extension specified in the LogExtension property.
Parameters:
Source - Directory and file name (no extension) of the existing files.
Destination - the directory and file name (no extension) to where the files must be copied.
DeleteAfter - if b7 set, then the files in the source directory are removed after a succesfull copy.
AddToHistory(string SiteID,
string LogFile1)
This method is used to add the imported Log file's details to the LogHistory file (generated into child method).
Parameters:
SiteID - the site identifier from whence the log file came.
LogFile1 - the name of the logfile to be recorded.
Export(<*File FileID>,
<string SiteLow>,
<string SiteHi>,
<string pSiteID>,
byte pOptions=0)
This method is used to export the data (or portions of the data) to a log file.
Parameters:
FileID - the data file to export (if omitted all registered data files are exported)
SiteLow - the site limiter (i.e. only export the records pertaining to this site). If omitted, all are exported.
SiteHi - the site range limiter. If present, the records pertaining to the site range SiteID to Site Hi are exported.
Methods Called:
SiteID - the Site for which this export is intended.
pOptions - bit loaded flag. Indicates if this is a Synchronization.
Open, OpenFile, Insert, PrimeLog, CloseFile.
ProcessMovedFiles(string FilesTo, 
<string SiteID>,
<string ToSiteID>, <string LastFileOut>,
<string LowSiteID>), string
This method makes subsets of the log files for distribution to children. Returns the last file name that was processed
Parameters:
FilesTo - the directory where the logfile subset will be made (cannot be the same as the outgoingdir property)
SiteID - If not omitted the records in the subset are limited to this site.
ToSiteID - if not omitted, this is the top limit of the range for the records included in the subset.
LastFileOut - if not omitted, contains the file to start processing.
LowSiteID - if not omitted, this forms the low Site limit (in place of SiteID).
CopyOut (if files must be copied directly out and not processed)
BytesDone(string SiteID,
long CurrentNumber),
long
This method is used to return the amount of bytes of the last partial log file received from a particular Site. Returns a -2 (we've missed some files), a -1 (we've done this file), a 0 (imported completely) or the LastSize. 
Parameters:
SiteID - the site name 
CurrentNumber - the number of the file to import
NewInDir(string SiteID,
byte Options=0),
string
This method creates a new out going directory for a specific site. It returns the name of the directory created.
Parameters:
SiteID - The name of the site.
Options - bit loaded flag. b0 = complete path sent (if set)
FileChange(*File FileID,
string FileName,
string FileCommand)
This method provides a callback during import when you can place some code to perform a calculation on an adjusted field.
Parameters:
FileID - the handle of the file which is receiving the change
FileName - the name of the table which is receiving the change
FileCommand - specifies whether record is being added, changed or deleted.
SendRequestedFiles(string FromFile,
string FromSite,
string SiteHi,
string Outpath,
<string ToEmail>,
byte MissingEOF=0), string
This method enables you to send requested logfiles to a relating site. It can also stamp an EOF if this has been omitted from one of the log files.
Parameters:
FromFile = The first logfile to resend
FromSite = The site (or Site low range) to send the logfiles to
SiteHi = The high range site limiter
OutPath =  Directory to place the logfiles
ToEmail = the address to send the logfiles to
MissingEOF = check for EOF and stamp if necessary.
Methods called:
ProcessMovedFiles, StampEOF 
TagReceived(string Action,
string FileLabel,
string Tag,
<string ValueStr>)
This method is used to indicate a tag (in a file) that is not a field/MEMO that is received. This allows code to be placed in the import routine if a Custom Command is used in the logfile.
Parameters:
Action - insert/update/delete/updatefull
FileLabel - the label of the file containing the tag.
Tag - the label of the command/tag/field.
ValueStr - the value associated with the Tag.
FileCrypt 
(*string FileName,
long options),long
This method loops through a logfile and en/decrypts it. Returns a 0 if file is correctly encrypted. -1 for no file found, or errorcode().
Parameters:
FileName - the name of the logfile to en/decrypt
Option - bit0 - set to decrypt and clear to encrypt.
EncryptString(*string UnEncryptedData,
long StringLen),long
This method encrypts the data passed to the method. This requires an encryptor (like CapeSoft's encryption - included in Replicate). Returns a 0 for a successful encryption.
Parameters:
UnEncryptedData - the string handle of the data to encrypt
StringLen - the bytes size of the data to encrypt
DecryptString(*string EncryptedData,
long StringLen),long
This method decrypts the data passed to the method. This requires an encryptor (like Capesoft's encryption - included in Replicate). Returns a 0 for a successful decryption.
Parameters:
EncryptedData - the string handle of the data to decrypt
StringLen - the bytes size of the data to decrypt
Requisition (string pRequest,
string pSiteID,
<string pPathName>,
<string pRequestDetails>,
<string pInform>,
byte pOptions=0),
string
This method generates a request file for (a) logfile(s) from a relating site. It returns a the file name (if successful) or errorcode or 0 if not.
Parameters:
pRequest: The request to be generated.
pSiteID: The SiteID of the requisition to be made to.
pPathname: Path to copy the MessageFile to.
pRequestDetails: include if requesting a file.
pInform: name of the tag for the request (bydefault request)
pOptions: Bit loaded flagif set the MessageFile is not removed from the logpath, Request is a Synchronization.
LoadSitesProperties (string pSiteID),long This method is used to Get the relationship record (to the pSiteID) and set any connection properties.
Parameters:
SiteID - the label of the Site's properties to load.
CheckRequestFile (string pFileName),long This method tests if a logfile is a Request file or not. Returns a 1 if true, otherwise a 0.
Parameters:
pFileName - The File to be tested.
ReceiveRequest (string pRequestFile,
byte pOptions=0),long
This method processes a request file and sends the required files to the relevant sites.
Parameters:
pRequestFile - The name of the RequestFile.
pOptions - Reserved for later use.
AutoProcessFiles (<string pSiteID>,
<string pFromFile>,
byte pOnlyThisOne=0)
This method will process loops through the SiteFile and processes the logfiles for each relating site. It is template generated.
Parameter:
pSiteID - Omit for all sites, otherwise only does the logfiles for the Site specified.
pFromFile - If not omitted, does from the specified file, otherwise takes from the latest (as in the SiteFile).
OnlyThisOne - if set, then only the one logfile is sent (and not subsequent as well).
ConnectionDetails (string pRelatingSite,
<string pRelatingOutDir>,
<string pTransport>,
long pLogFileNumber=0,
byte pDontSendFiles=0),
string
This method populates a string with all the connection details required to setup the relating site - our site communication.
Parameters:
pRelatingSite - the relating site ID.
pRelatingOutDir - the directory to place the logfiles (for direct transportation).
pTransport - 'Direct', 'Email' or 'FTP'
pLogFileNumber - the number to start receiving logfiles from.
pDontSendFiles - the new site must not send logfiles up to this site.
LoadField  (string pFieldname,
string pValue),string
Populates record in the SiteFile with the correct value. Returns the value of the field before the change was implemented.
Parameters:
pFieldName - the label of the field.
pValue - the value that the field must contain.
GetFromArchive (string pArchiveDir,
string pFileName),long
This method will be used to extract a logfile from the archive (if required).
Parameters:
pArchiveDir - the name of the directory where the archived file resides
pFileName - the name of the file to retrieve.
RestoreBackup (long pFromDate,
long pFromTime=0),string
This method is used to restore a data set from the logfiles of that site. The method returns the last logfile that is imported.
Parameters:
pFromDate - date to start restoring from
pFromTime - time to start restoring from.
SendAllOutgoing (string pOutGoingDir,
long pOptions = 0),string
This method copies the files from a relating sites Outgoing directory to the INcoming directory (for direct sites) or it formulates a (|) delimited string containing the files that must be sent.
Parameters:
pOutgoingDir - the directory containing the files
pOptions - reserved
RemoveAllFiles (string pFromDir)This method removes all files from a specified directory (pFromDir).
UpdateBasicSettings (<string pSite>,
<string pParentSite>,
<string pLogPath>,
<string pSiteHi>,
<string pSiteLow>,
<string pIncomingDirectory>),long
This method bulk updates the settings for this site that is passed to it.
ProcessLine  (*string pXMLData,
*long pDataLen,
string pSiteID,
*RepFilesOpenType pFilesOpened,
<long pFileDate>,
long pOptions=0),long,
This method will import a physical data string into the database. It will add an entry to the pFilesOpened queue passed for every file that it opens. Returns the size of the left over string, a Rtn-Complete for a completely imported string, a Rtn_EndOfFile for finding the EOF stamp, a Rtn_CRCError for a CRC error, or a Rtn_IllegalTag for an illegal tag (usually from an incomplete string that was passed).
Parameters:
pXMLData - the data string to be imported.
pDataLen - a handle to the Length indicator.
pSiteID - the ID of the SiteID from whence this came.
pFilesOpened - a handle to the Queue to track all the files opened during this import.
pFileDate - the date of the file (optional)
pOptions - a bit loaded flag:
  bit1 - if set then this is a manual import.
  bit2 - if set then use LOGOUT/COMMIT to increase the import speed.
  bit3 - if set, Append/Build is used during Manual instead of 
PutToArchive (string pArchiveDir,
string pFileName)
Puts (and compresses) a logfile to an archive.
Parameters:
pArchiveDir - the directory for the archive
pFileName - the name of the file to archive
BulkArchive (<string pArchiveDir>,
long pKeepFiles=0,
long pOptions=0),long
Archives all the files in the logpath.
Parameters:
pArchiveDir - the directory of the archive
pKeepFiles - the number of files to keep in the logpath
pOptions - b0 set to 1 then, pKeepFiles is in days.
AutoExport (string pSiteID,
<string pSiteHi>,
<String pSiteLow>,
byte pOptions=0)
This method exports a complete data set to a relating site. It creates the complete data logfile, gets the site's connection details and then sends the logfile(s) to the relating site.
Parameters:
pSiteID - ID of the Site to export to.
pSiteHi (and pSiteLow) - the Hi and Low site range
pOptions - bit loaded flag to pass onto SendAllOutgoing (and to indicate if this is Synchronizing)
Methods Called:
Export, LoadSitesProperties, CopyOut, SendAllOutgoing.
IgnoreTable (string pTable,
string pSiteID,
byte pImporting=0),long
You can return a 1 to ignore a specific table for import if you require. Normally a 0 will be returned so that a table will by default be imported.
pTable - the name of the table to import.
pSiteID - the ID of the site from whence the logfile came.
pImporting - set if importing, otherwise exporting.
Open (*file pFile,
*string pData,
*string pFileName),long
If non-existant in the path, tries to get it from the archive dir, before calling the parent.open.
MakeMissingLogFiles (long pNumber,
<string pSiteID>)
Makes a blank logfile of the number specified. The template generates code to export a complete dataset to the first missing logfile (if required), and then creates blank logfiles from there on (where missing).
Parameters:
pNumber - the number of the first logfile that is missing.
pSiteID - the ID of the site requesting the missing logfile.
SetStatusFlag (string pSiteID,
byte pStatus=0)
Sets the status of a particular site.
Parameters:
pSiteID - the site whose status must change.
pStatus - the status level to change to.
ReturnStatus  (string pSiteID,
byte pStatus=0)
Sends a MSG to a site requesting a logfile, with our status.
Parameters:
pSiteID - the ID of the Site to return the status to.
pStatus - the status of our site.
ImportFullDataSet  (string pFileIn,
string pFileOut,
byte pOptions=0)
Imports a fulldata set (a complete logfile).
Parameters:
pFileIn - The name of the file to import.
pFileOut - where to place it.
pOptions - reserved for later use.
CriticalErrorInImport(long pErrorcode),long This method is called after a critical error occurs during the import of a logfile. You can derive this method and place your own error handling to determine whether import should
continue, or should be aborted. To ignore the error and continue with the import, return 0.

The most crucial error to handle here is pErrorCode = 90. FileErrorCode will still be valid in this derived method, so you can use it to determine whether we should continue importing, or whether the import should be aborted. This will vary between backend types.
Also note that the FileErrorcode is often not a specific errorcode as we are used to, but rather a database state - in which case that state could be critical in some cases and non-critical (in terms of aborting from import) in others.
StringToFile (? p_String,long p_Len,string p_FileName) Load a file to a string using WinEvent.
FileCRC (<string pFileName>,<*File pFileID>,<string pSiteLow>,<string pSiteHi>,byte pToQueue=0) Creates a Log or Queue of the CRC of each record in a file.
Parameters:
pFileName - the name of the file to create the CRC (not valid if pToQueue is set) - if omitted, defaults to siteCRC.log in the outgoing directory.
pFileID - the handle of the file to CRC. If omitted, then all files are CRC'd
pSiteLow - the low range of the site component for record limiting
pSiteHi - the high range of the site component for record limiting
pToQueue - if set, then writes the CRC to a queue.
RestoreGUID (string pValueStr),string Returns a true GUID value (string16) from a logged GUID component value.
Parameters:
pValueStr - a string comprising of siteID & ',' & DateNumeric & ',' & TimeNumeric & ',' & RandomNumeric
AssignQueue (*file pFile,byte pFreeQ=0) Assign the internal CRCQueue handle to the correct file CRC Queue. Also creates the queue if the handle is null.
Parameters:
pFile - a handle to the file
pFreeQ - if set, frees the queue after assigning.
DisposeQueues () Disposes the created CRC queues.
CompareCRCFile (string pFileFrom,string pFileTo),long Compares an incoming CRCFile (from a relating site) - to the CRC values of the records in the database.
Parameters:
pFileFrom - the name of the compressed and\or encrypted file received.
pFileTo - where it must be copied to in order to be compared.
LoadCRCStringToQ (string pCRCString,
*string pSiteID),long
Load the CRCString received to the respective queues. Returns 0 for success, or -1 for error.
Parameters:
pCRCString - the string of the file sent
pSiteID - a handle of the SiteID string to contain the ID of the site that sent the CRC file.
LoadFileToString (string pFileName),string Loads the assigned file to a string (requires WinEvent).
Parameter:
pFileName - name of the logfile
ImportDataSet (string pFileIn,
string pFileOut,
byte pOptions=0),long
Imports a Full dataset into the database - and handles exporting if required.
Parameters:
pFileIn - the file name to import from.
pFileOut - the file name to export to.
pOptions - the options to transfer to the impot method.
ImportCRCDataSet (string pFileIn,
string pFileOut,
byte pOptions=0),long
Handles the import of a CRC dataset. Simply calls the ImportDataSet method - but allows derivation for CRC specific file.
DoCRCWithSite (string pRelatingSite,
<string pSiteLow>,
<string pSiteHi>,
byte pOptions=0)
Issues a CRC comparison between two sites.
Parameters:
pRelatingSite - the site to do the CRC comparison with.
pSiteLow, pSiteHi - the range of the site-related data.
pOptions - Passed on to SendAllOutgoing (if Rep_DontSendFiles bit is clear). 
ReceiveFiles( )This method is used to receive the log files via Email/FTP or your own transport method.
ProcessLogFiles (string pImportFiles,
byte pOptions=0)
Handles the entire processing procedure.
pImportFiles - the files to move in (normally '*.z')
pOptions - a bit loaded flag where you can set whether Send and Receive are done together (Rep_SendAndReceiveTogether), a new logfile is started after each process (Rep_UseNewLogFile) and/or a shutdown is issued on abort (Rep_CloseOnAbort)

Properties

Property TypeProperty Description
IncomingDir STRING(255)Contains the Directory of the log files (from other sites) to import into this data set.
OutGoingDirSTRING(255)Contains the directory for the log files that the current site is exporting.
LastCopiedOutlongContains the number of the file that was last copied out to the outgoing directory.
SiteHistring(4)Contains the hi site value if this site has a range of children/descendants.
SiteLowstring(4)Contains the Low site value if this site has a range of children/descendants and the LowSite is not the same as the Site.
DirectOutDirstring(255)Sets the directory to copy the files to - if the files must be copied directly (instead of emailed/FTPed/other)
LogManualbyteWhen doing a manual import, set this flag to log the changes made (like normal file changes).
ImportSuppressedFieldsbyteSet this flag if you are doing an import where the omitted fields must be imported.
SetupDonebyteThis flag is set when the setup method is run. In Clarion6 - this method can only be called once the file classes have been initialised.
LastMSGFilestring(255)The name of the last message file used.
AutoMakeIfMissingbyteContains a 1 if a logfile must be created when requested and it's missing. Otherwise we'll wait until the requesting site commands us to make the logfile.
CanReplaceSitebyteAllows a site's data to be replaced when a complete data import is received.
CRCCheckQ&CRCQueueTypeThe handle of a CRCCheckQ - assigned dynamically as each table will have it's own CRCCheckQ.

csLogConnectionManager Class


Introduction

The LogConnectionManager class builds on the Log and LogManager class. It basically enables you to build transportation methods easily into your LogManager application. It replaces the old csLogEmailManager class

Methods

Method ParametersMethod Description
SendFiles(String FileName, 
<string pSubject>,
long pOptions=0)
This method is used to send the log files via Email/FTP or your own method.
Parameters:
FileName - the Filename to send
Subject - a subject for the email.
pOptions - passed to SendFTP and SendEmail procedures
SetupEmail( )Sets up the Email setup (Pop and SMTP)
SetupFTP( )Sets up the FTP setup (sets the required properties for the FTP connection)
HandleExtraFiles(byte pOptions=0,
byte pMakeDir=0),
UpdateFTPSettings(<string pFTPDir>,
<string pFTPServer>,
<string pFTPUser>,
<string pFTPPassword>,
byte pRequired=1),long
This method is used to bulk update the FTP settings for the LogManager. Omit the settings that don't require updating.
Parameters:
FTP parameters are self-explanatory
pRequired - the site requires FTP.
UpdateEmailSettings(<string pEmailAddress>,
<string pPopServer>,
<string pPopPort>,
<string pPopUser>,
<string pPopPassword>,
<string pSMTPServer>,
<string pSMTPPort>,
byte pOptions=Rep_Required),long
This method is used to bulk update the EMail settings for the LogManager. Omit the settings that don't require updating.
Parameters:
Email settings are self-explanatory.
pOptions - set if required.
SendAllOutgoing(string pOutGoingDir,
long pOptions = 0),string
This method calls the SendFiles method if the transport method is not direct.
pOutgoingDir - the directory containing the files to move out to the site.
pOptions - passed to SendFiles

Properties

Property TypeProperty Description
OurEmailstring(255)Contains the address of our own email (i.e. the address to receive email)
FromEmailstring(255)Contains the address of the email to send the log files to.
PopServerstring(255)The server name or IP number to collect mail from
PopPortlongThe port number to collect mail from
PopUserstring(255)The mailbox/user name
PopPasswordstring(255)The password to access that mailbox.
SMTPServerstring(255)The server name to post mail to
SMTPPortlongThe port to post mail to.
FTPInDirstring(255)The FTP directory containing the files to be imported
FTPInServerstring(255)The FTP Server containing the FTPInDir
FTPInPasswordstring(255)The FTP Password for the FTP User
FTPInUserstring(255)The FTP User of the FTP Server
FTPOutDirstring(255)The FTP directory to place logfiles for the currently processed relating site.
FTPOutServerstring(255)The FTP Server containing the FTPOutDir
FTPOutUserstring(255)The FTP User of the FTP Server
FTPOutPasswordstring(255)The FTP Password for the FTP User