CapeSoft File Manager 3
Technical 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

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.

ds_AddDriver
ds_UsingFile
ds_AlternateFieldName
ds_SetIfNew
ds_AlternateFileName
ds_SetUPGPath
ds_UpgradeLocalMachineEx
ds_SetFM2ININame
ds_CloseUPGFile

ds_AddDriver

ds_UsingFileEx

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

ds_AlternateFieldName

ds_AlternateFieldName(string FromField, string ToField)

ds_SetIfNew

ds_SetIfNew (string Field, string Value)

ds_AlternateFileName

ds_AlternateFileName (string OldName, string NewName)

ds_SetUPGPath

ds_SetUPGPath(<string Path>)

ds_UpgradeLocalMachineEx

ds_SetFM2ININame

ds_CloseUPGFile

ds_CloseUPGFile()

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.
	Firebird: Enable embedded version	Enable firebird embedded
	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).
	Ignore Multi-Proj	In 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-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()
	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 window	During 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 procedure	The 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 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

Options Tab

Import / Export Tab

Connect to SQL Backend Controls

 

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. This is useful if you support multiple different backend types and want to perform different functions depending on the backend type.
	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

There are basically 4 template utilities (3 of which are for ABC and legacy making it 7 in total):

• CreateFM3ConvertorApplication - is used to create a stand alone application to convert all your data once when upgrading.
• ImportFM3Connect - is used to create the SQL_Connect procedure in your application.
• ImportRuntimeFileManager - is used to create the RuntimeFileManager procedure in your application.
• SupportABC - is used when upgrading clarion to implement the necessary changes in the ABC classes to support FM3.

After running these you'll need to tweak the options in the various templates to be able to work with your application.