CapeSoft.Com
Clarion Accessories
File Manager 3
Documentation
Technical Documentation
CapeSoft Logo

CapeSoft File Manager 3
Technical Documentation

Download Latest Version JumpStart FAQ History
Installed Version Latest Version

HandCoder's Reference

Introduction

This section is aimed at experienced programmers who would like to know more about the functions made available by the FM3 library. This is really only useful if you are adding FM3 features to hand-coded applications. If you are using the App Generator then the templates will take care of all of these features for you. This document is designed to be used in conjunction with the normal FM3 documentation. No effort has been made to explain the features here.

To make this document more useful than just a simple technical reference, there is also a section on implementing the specific FM3 features in hand coded applications. This includes the AutoUP and AutoNET features. The AutoBUILD feature, and hence the AutoFIX feature (which relies on it) are outside the scope of this document. Other features and utility programs shipped with File Manager 3 are not documented here.

Lastly there is a section on Adding the FM3 Library itself to your hand-coded application. This includes a copy of the function prototypes (which you can cut & paste) and the name of the LIB file you should use.

Implementing AutoUP

Implementing AutoUP, in it's simplest form, relies on a 3 step process. These are the so called 'pillars' of functionality. There are additional functions, but they are used in more specific situations and are optional. The 3 required pieces to AutoUp are as follows:

Register the file drivers
On program startup Register the File Driver's using the ds_AddDriver function.

Register the each data file
On program startup Register each of the data files using ds_UsingFile.

Replace Clarion's OPEN with ds_FileOpen
This is done automatically for you if the FM3 define switch is added to your project.

In other words make sure the installation of FM3 is completed and then add a Define to your project which reads:FM2=>1

Note: See Completing your FM3 Installation to ensure you have completed all installation tasks.
Note: FM2=>1 is the correct value for FM3 as well and FM2. Not FM3=>1.

Implementing AutoNET

Implementing AutoNet in your application is really simple as it is basically just a single function call, made before any other calls right at the beginning of your program.

The function to use is the ds_UpgradeLocalMachineEx function.

FM3 Functions Reference

ds_AddDriver
ds_UsingFile
ds_AlternateFieldName
ds_SetIfNew
ds_AlternateFileName
ds_SetUPGPath
ds_UpgradeLocalMachineEx
ds_SetFM2ININame
ds_CloseUPGFile

ds_AddDriver

ds_AddDriver(string DriverName, file ExampleFile, <*string FM3DriverFileRecord>)

Description

This adds a File Driver to the FM3 driver registry. It needs to be called once, for each driver you wish to support, near the beginning of the program. It definitely needs to be called before using the ds_UsingFile function and before any data files are opened. If you fail to register a driver, and then use a file of an unregistered driver with one of the other FM3 functions - then you will likely get a 'Driver not located - GPF likely' error. Making sure all the drivers are registered is the first 'Pillar' of using the AutoUP function in FM3.

Parameters
Parameter Description
DriverNameString - This is a 3 character name for the driver. For example, Cla, Tps or Btr.
ExampleFileFile - This is a file handle, of any file, which uses the driver that's being registered.
FM3DriverFileRecord*String (optional) - This passes the record structure of a buffer file for use in FM3, primarily important in SQL enabled applications.
Note:If you are handcoding an SQL application, then you will need to declare this file. See the FM3 template for the relevant structure for your driver.

Example
Example
Customer         File,Pre(cus),Driver('CLARION'),Create
Record             Record
CustomerNumber       Long
                   end
                 end

  code
  ds_AddDriver('Cla',Customer)
 

ds_UsingFileEx

ds_UsingFileEx(string FileLabel, file FileHandle, short Version, string Prefix, long pOptions=0)

Description
Registers a File with the FM3 registry. This needs to be done in order to be able to upgrade this version of the file in later versions of the program. Making sure this call is done is one of the 'Pillars' of using AutoUP.

Parameters
Parameter Description
FileLabel String - This is the name of the file, as it's used in the Clarion program. This is not the name of the file stored on the disk, it is the name of the file in the dictionary.
FileHandle File - This is the handle to the file. This is exactly the same as the name, but quotes are not used.
Version Short - This is the current version number of the file used in this exe. Always increment, never decrement this number.
Prefix String - This is the prefix of the file.
pOptionsbit loaded options - Add FM3equ:OldFiles to the pOptions to add an old file structure into the upg.tps file.

Example
Example
Customer         File,Pre(cus),Driver('CLARION'),Create
Record             Record
CustomerNumber       Long
                   end
                 end

  code
  ds_AddDriver('Cla',Customer)
  ds_UsingFile('Customer',Customer,1,'Cus')

ds_AlternateFieldName

ds_AlternateFieldName(string FromField, string ToField)

Description

This function alerts the upgrade library to a change in field name. Normally the library matches fields in the old file, and fields in the new file by matching their names. However in some cases it is desirable to match two fields even if they don't have the same name. In this case this function needs to be called Before any file upgrading is attempted. This means this function is usually called at the same time as the other initialisation commands.

Parameters
Parameter Description
FromField String - This is the name (including prefix) of the source field in the old file.
ToFieldString - This is the name (including prefix) of the destination field in the new file.

image spacer Example
Example
code
ds_AddDriver('Cla',Customer)
ds_UsingFile('Customer',Customer,1,'Cus')
ds_AlternateFieldName('Cus:CustNo','Cus:CustomerNumber')

ds_SetIfNew

ds_SetIfNew (string Field, string Value)

Description

This function allows you to prime new fields with a constant value. For example if you add a field, TAX, to each customer, and you want all existing customers to have this field set to 1, then you would use this function.

Parameters
Parameter Description
FieldString - The field name. This name includes the prefix for the file.
Value String - The value to prime the existing records with.

Example
Example
Customer         File,Pre(cus),Driver('CLARION'),Create
Record             Record
CustomerNumber       Long
                   end
                 end

  code
  ds_AddDriver('Cla',Customer)
  ds_UsingFile('Customer',Customer,1,'Cus')
  ds_SetIfNew('CUS:CustomerNumber','-1')

Note: This function is called SETIFNEW - i.e. "i" not "L".

ds_AlternateFileName

ds_AlternateFileName (string OldName, string NewName)

Description


This function allows you to change the disk name of a file. You may not change the Label of a file, only it's name on the disk. This is usually required when using the Topspeed driver, and changing the password.

Parameters
Parameter Description
OldName String - This is the old file name. The path is not required, but can be included if necessary.
NewName String - This is the new name for the file.

Example
Example
code
ds_AddDriver('Cla',Customer)
ds_UsingFile('Customer',Customer,1,'Cus')
ds_AlternateFileName('Customer.tps','Customers.tps')

ds_SetUPGPath

ds_SetUPGPath(<string Path>)

Description

Changes, or sets, the path where the UPG file is being stored. If this is called after any ds_UsingFile statements then those files are automatically stored in the new location as well. This can lead to the situation where 2 upg files are apparently maintained. One in the default position (typically in the application directory) and another in the new path. To avoid 2 UPG files being made the call to ds_SetUPGPath should be made before any calls to ds_UsingFile. It is also recommended that ds_SetUPGPath is called after every SetPath command. [Tip : Remember FileDialog can also act as a SetPath ]. In this way a upg file is stored with the data file. This is a good thing from a backup / restore data point of view.SetUPGPath will also open the UPG.tps file after setting the path to contain the UPG file. If the file is not found, then it will create it in the path parameter.

Parameters
Parameter Description
Path String - Optional - This is the path where the new UPG file should be stored.
Note: If omitted then the current path, as returned by the PATH () statement is used.

Example
Example
ds_SetUPGPath()        ! Sets to current directory
ds_SetUPGPath('c:\')   ! Sets it into the C root directory
ds_SetUPGPath(somepath)! Sets it to the position in the somepath var

Be careful using relative paths - rather use a complete path in the path parameter.

Note: If you are writing a Multi-DLL ABC application, then make sure you call this function in the Data DLL.

ds_UpgradeLocalMachineEx

ds_UpgradeLocalMachineEx(string Section, string INIFile),byte image spacer

Description

This function determines if the current program directory on the local machine is in sync with the program directory on the Server. The location of the directories is detailed in the INI file. The composition of the ini file is detailed in the normal FM3 documentation. If the directories are not in sync then the function will terminate the program, and spawn the AutoNET program, which will synchronise the directories. After the synchronisation is complete the original program will be restarted.

Parameters
Parameter Description
Sectionstring - The name of the section in the ini file which contains the directory information.
INFile string - This is the name of the INI file containing the directory information.

Returns

A byte. 1 if an upgrade has been started, 0 if an upgrade is not necessary. On receiving a 1 you should immediately terminate the program. (Tip : You only need to terminate the program if the directory being upgraded contains the program, or any of it's components).

Example
Example
program

code
  if ds_UpgradeLocalMachine('Directories','Program')
     halt
   end

ds_SetFM2ININame

ds_SetFM2ININame(string Name)

Description

This function sets the path and name of the FM3 Ini File used for translation of FM3 Error messages.

Parameters
Parameter Description
Namestring - The name of the Ini File.

Example
Example
program

code
  if ds_SetFM2ININame('c:\myprog\data\trn.tps')
     halt
   end

ds_CloseUPGFile

ds_CloseUPGFile()

Description

This function closes the UPG file. This is useful if you're wanting to change the datapath (for EXEs with multiple datasets) and have a UPG file for each dataset. You can use this in conjunction with ds_SetDataPath()

Parameters

None

Example
Example
program

code
  ds_CloseUPGFile()
  MyDataPath = GetNewDatapath()   !This is your function for getting the new datapath
  ds_SetUPGPath(MyDataPath)

Template Reference

FM3 Global Extension Template
Runtime File Manager Control Template
Connect to SQL Backend Controls

FM3 Global Extension Template

TabOptions Description
General TabDisable All File Manager FeaturesTick this on to completely suppress FM3 in your application. This is handy for debugging purposes if you think that FM3 is interfering with your program.
AutoUP Tabxxx DriverAllows FM3 automatic upgrading  support for files which use this driver.
Oracle: Use UserName in the filenameOld versions of Oracle require the filenames to be prefixed with the Username. Oracle Express does not support this, so you need to turn this off in order to allow FM3 to create and manage tables correctly.
Firebird: Enable embedded versionEnable firebird embedded
Sql Connect ProcedureSpecify procedure name were local ConnectToSQLBackend extension template will be added.
Let FM3 Manage my filenamesCheck this if you want FM3 to generate and use it's own variables for the FileName - otherwise it will use the global variables used in the dictionary. Only clear this if you want to use your own variables for the filenames (or the names are fixed in the dictionary).
Ignore Multi-ProjIn Multi-Proj Driver substitution feature, MProj will normally manage your filenames. If you want to force FM3 to manage your file names (typically if you're already using the FM3 variables for your filenames, and don't want MProj to replace those in the other file driver's declarations) then check this.
Force full Upgrade on Start-upCheck this if you want FM3 to upgrade all your files at startup (of your application) - instead of upgrading them as they are opened throughout your application.

If you don't want to do this on startup, you can hand-code the following into the place where you want to run the full upgrade: ds_DoFullUpgrade(1)
RuntimeFileManager()
Run full upgrade During DLL init (not construct)In a multi-dll setup (the data dll) this will do the upgrade after all the initialization. This is useful if you have a routine to setup filenames in the dll init.
Don't remove old versions of files.Old files are not deleted, just renamed.
Hide the yellow upgrade windowDuring a file upgrade, the yellow progress window will not be displayed.
Log Errors to:Specify the logfile name that you would like to use to log errors.
FM3 Callback procedureThe FM3 Callback procedure is useful to set field values during upgrade (see FAQ GQ34) or handle mismatched file structure warnings. NOTE: Your EXE will GPF if the prototype is wrong (see FAQ GQ34 for details).  
Compiler and runtime Warnings to displayBy default these are all turned on - so that if you do something that FM3 does not support it will warn you, before the problem occurs.
AutoFIX TabRuntimeFileManager procedure If you have renamed your RuntimeFileManager procedure, then enter the new name here.
Enable AutoFIXClick this on to enable AutoFIX functionality.
AutoNET TabEnable AutoNETClick this on to enable AutoNET functionality.
INI File NameContains the full name, and path, of the INI file used to hold the path settings. If no path is included then it defaults to the Windows directory, or the Logged in User's Temp Directory. Read more about AutoNET.
INI [Section]Enter the section name where the settings are stored. Do not include the square brackets. If this is left blank then the name of the App (not Exe) is used.
Options TabShow HintsGenerates extra hints, as comments, into the source code. Mostly useful for CapeSoft support staff.
No Pre-Existing DAT files.Tells FM3 not to look for old DAT files when creating new TPS files.
Program ENV fileThe name of your env file. Use Quotes or a variable.
Ignore Clarion driver field names > 12 charactersClarion driver limits field names to 12 characters. This forces FM3 to only match first 12 characters.
Suppress FM2=>1 checkWill not give warning if the define does not exist.
Open UPG onceOpens the UPG file once at the top of the file loop, and closes it at the end.
Root DLL Init NamesEnter the names of the DLL init functions here.
Declare Prototypes LocallyA hack to allow some 16 bit programs, with very large dictionaries, to compile.
Translation TabTranslation file:The name of the file to use containing text that must be translated (on the FM3 windows and the FM3 messages).
Make a blank translation file if non-existentCheck this to force FM3 to make a default translation file with the text that requires translation.
SQL TabDCT Master of Fields
DCT Master of Keys

Prime new fields zero/blank
- Ensures backend fields are dropped from backend when dropped from DCT.
- Ensures all DCT keys are created and managed by FM3 on the backend. You should normally use the Dictionary User Option than these options (Read more about SQL Field and Key Management) - but these options are available for temporary/test applications during development.
- Allows new SQL fields to default to zero or blank instead of NULL.
SQL Conversions -
Zero / Blank = NULL
- Allows FM3 to insert NULL values in TPS to SQL conversion where data value equals zero or blank. 
Create Utility Stored ProceduresAllows creation of utility stored procedures such as ds_ConvertClarionDateTime.
Miscellaneous SQL Settings
Create MySql tables as InnoDB type
By default mysql tables are created in MyISAM format, but you can override this by checking this checkbox in order to force the default to create in InnoDB type. 
Alternate Name for FM3 tableSets a different Name attribute for the FM3 SQL system tables.
No Warnings for unsupported Dimensioned fieldsBy default, FM3 will warn you at compile time if you have used dimensioned fields in your dictionary, but the backend that you are using doesn't support dimensioned fields. If you want to override the warning, do so here.

Runtime File Manager Control Template


Options Tab

Use filesYou can either select All files in Dictionary or Files used in this app, depending on what files you want displayed in the RuntimeFileManager list box.
Excluded FilesYou can specify specific tables to be omitted from the RuntimeFileManager. This means that these tables won't appear in the list box.
Include support for DET
Use File descriptions Uses the dictionary description when displaying tables instead of the dictionary table names. If there is no description, then the table name is displayed.
Allow "Fixing" of encrypted filesThis option only applies to TPS files. If you check this, then the owner string is passed to the SoftVelocity TPSFix program to allow it to decrypt and fix encrypted TPS files. Please Note: This allows a security hole, because the password is passed on the command line (allowing "sniffing" of the password) - so by default this is disabled.
Include Aliases in the file queue. 
Table Select IconYou can specify a particular icon to show that a table is selected (if you do not want to use the default).
Don't show current file-check window during full upgradeThis option will hide the progress window showing the number of files still to check, during full upgrade (if that option is turned on in the FM3 global extension template).
Force Create Tables on Startup 

Import / Export Tab

All the XML support requires that the xFiles global extension is added to the app. All the JSON support requires that the jFiles global extension is added to the app.
Allow multiple tables in the same fileIf this is on then multiple tables can be exported into a single XML or JSON file. If this is off then the user will be asked for the Directory for the files, but the file names will be based on the table name.
For backward compatibility reasons this option defaults to OFF, however for new programs where the Export and Import facilities are being used for the first time it is recommended to turn this on.
Allow Export to XML If this is on the exports to XML format are allowed.
Allow Import from XMLIf this is one then imports from an XML file are allowed.
Auto Generate xFiles objectIf this is on the the xFiles object will be generated automatically. If you wish to embed in the xFiles methods though you should turn this off, and add an xFiles extension to the procedure in the usual way.
xFiles Object NameThe name of the xFiles object, as added via the xFiles extension.
Allow Export to JSONIf this is on the exports to JSON format are allowed.
Allow Import from JSONIf this is one then imports from a JSON file are allowed.
Auto Generate jFiles ObjectIf this is on the the jFiles object will be generated automatically. If you wish to embed in the jFiles methods though you should turn this off, and add a jFiles extension to the procedure in the usual way.
jFiles Object NameThe name of the jFiles object, as added via the jFiles extension.

Connect to SQL Backend Controls

Connect TPL General screenshot  Connect TPL Settings screenshot
GeneralGlobal Owner VariableThis is the variable that is used to contain the owner variable for the tables. This variable is the same as specified in the owner attribute in your dictionary
GloVar For Backend Type field Create a global variable - and for ODBC connections, you can enter this here and FM3 will store which database you're connecting to in the variable. This is useful if you support multiple different backend types and want to perform different functions depending on the backend type.
Conditional Compile switchesThere are project defines that you need to add to your project (for drivers that you are supporting).You can leave these as is, unless you're using Multi-Proj's driver substitution (in which case you'll need to match these up with the project defines that you've used in the Multi-Proj template)
Add these project defines automaticallyBy default this is checked on, this is because most people don't use Multi-Proj (yet). To make is easier for you, FM3 can automatically set the project defines for you, based on the drivers you've selected in the Global Extension template.
Use ODBC by defaultIf the ODBC driver is activated, then you'll probably want to use it by default. This sets the option at runtime (if no value is returned from the INI stored settings).
SettingsINI file to store settingsThe name of the file to store the connect window settings for future sessions.
Alternate name for FM3 tableFM3 has a table declaration for each file structure in order to obtain info about the database structure from the backend. If this name clashes with a variable or file in your dictionary, then you can rename it here.
Set filenames with the FM3Ignore user optionYou can set FM3 to prime the field names of your SQL tables, even if they have the FM3Ignore file user option set in the dictionary.

Template Utilities

template utilities screenshot

There are basically 4 template utilities (3 of which are for ABC and legacy making it 7 in total):
After running these you'll need to tweak the options in the various templates to be able to work with your application.