


	Version Beta www.capesoft.com

Technical Documentation and Reference

Contents

	<< Back to Complete Documentation

	In Depth
		HandCoder's Reference
		DLL Functions Reference
		Template Reference

	Can't find what you're looking for?
		Click here to Search the FM3 Docs

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 andAutoNETfeatures. 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(string DriverName, file ExampleFile, <*string FM3DriverFileRecord>)

Purpose

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

DriverName - String - This is a 3 character name for the driver. For example, Cla, Tps or Btr.

ExampleFile - File - 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

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

code
ds_AddDriver('Cla',Customer)

ds_UsingFile(string FileLabel, file FileHandle, short Version, string Prefix)

Purpose

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

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.

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(string FromField, string ToField)

Purpose

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

FromField - String - This is the name (including prefix) of the source field in the old file.

ToField - String - This is the name (including prefix) of the destination field in the new file.

Example

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

ds_SetIfNew(string Field, string Value)

Purpose

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

Field - String - The field name. This name includes the prefix for the file.

Value - String - The value to prime the existing records with.

Example

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

ds_AlternateFileName(string OldName, string NewName)

Purpose

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

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

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

ds_SetUPGPath(<string Path>)

Purpose

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

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

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(string Section, string INIFile),byte

Purpose

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

Section - string - 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

program

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

ds_SetFM2ININame(string Name)

Purpose

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

Parameters

Name - string - The name of the Ini File.

Example

program

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

ds_CloseUPGFile()

Purpose

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

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

Tab	Options	Description

General Tab	Disable All File Manager Features	Tick 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 Tab	xxx Driver	Allows FM3 automatic upgrading support for files which use this driver.
	Oracle: Use UserName in the filename	Old 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.
	Sql Connect Procedure	Specify procedure name were local ConnectToSQLBackend extension template will be added.
	Let FM3 Manage my filenames	Check 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).
	Force full Upgrade on Start-up	Check 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()
	Don't remove old versions of files.	Old files are not deleted, just renamed.
	Compiler and runtime Warnings to display	By 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 Tab	RuntimeFileManager procedure	If you have renamed your RuntimeFileManager procedure, then enter the new name here.
	Enable AutoFIX	Click this on to enable AutoFIX functionality.
AutoNET Tab	Enable AutoNET	Click this on to enable AutoNET functionality.
	INI File Name	Contains 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 Tab	Show Hints	Generates 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 file	The name of your env file. Use Quotes or a variable.
	Ignore Clarion driver field names > 12 characters	Clarion driver limits field names to 12 characters. This forces FM3 to only match first 12 characters.
	Suppress FM2=>1 check	Will not give warning if the define does not exist.
	Open UPG once	Opens the UPG file once at the top of the file loop, and closes it at the end.
	Root DLL Init Names	Enter the names of the DLL init functions here.
	Declare Prototypes Locally	A hack to allow some 16 bit programs, with very large dictionaries, to compile.
Translation Tab	Translation 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-existent	Check this to force FM3 to make a default translation file with the text that requires translation.
SQL Tab	DCT 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 Procedures	Allows 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 table	Sets a different Name attribute for the FM3 SQL system tables.
	No Warnings for unsupported Dimensioned fields	By 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

runtime file manager control template screenshot

	Use files	You 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 Files	You 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 files	This 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.
	Table Select Icon	You 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 upgrade	This 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).

Connect to SQL Backend Controls

Connect TPL General screenshot Connect TPL Settings screenshot

General	Global Owner Variable	This 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.
	Conditional Compile switches	There 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 automatically	By 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 default	If 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).
Settings	INI file to store settings	The name of the file to store the connect window settings for future sessions.
	Alternate name for FM3 table	FM3 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 option	You 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):

HandCoder's Reference

Introduction

Implementing AutoUP

Register the file drivers

Register the each data file

Replace Clarion's OPEN with ds_FileOpen

Implementing AutoNET

FM3 Functions Reference

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

ds_UsingFile(string FileLabel, file FileHandle, short Version, string Prefix)

ds_AlternateFieldName(string FromField, string ToField)

ds_SetIfNew(string Field, string Value)

ds_AlternateFileName(string OldName, string NewName)

ds_SetUPGPath(<string Path>)

ds_UpgradeLocalMachineEx(string Section, string INIFile),byte

ds_SetFM2ININame(string Name)

ds_CloseUPGFile()

Template Reference

FM3 Global Extension Template

Tab

Options

Description

Runtime File Manager Control Template

Connect to SQL Backend Controls

Template Utilities