Quick Tips
	Are you looking for support?	You will find most of your questions answered in the FAQ section of this documentation

BEFORE EMAILING FOR SUPPORT, READ THE FAQ !!

Introduction

File Manager 2 builds basic file management directly into your application. It consists of 5 main features.

AutoUP and AutoBUILD support the Topspeed, Btrieve and Clarion file drivers. C-Scan supports the Clarion and Topspeed drivers. AutoFIX supports the Topspeed file driver via the TPSFix utility. AutoNET supports all files including EXE's and DLL's.

AutoUP and C-Scan do not currently support BLOBS in Topspeed files, or Group Arrays. Note that normal arrays are supported.

Copyright, License and Distribution

This product, and all the files contained therein, are copyrighted © 2011 by CapeSoft Software.

You are licensed to distribute any the DLL's contained in this package with your applications. You are also allowed to distribute the C-Scan program (CS.EXE), UPGView program (UpgView.Exe) and AutoNET program (AUTONET.EXE) along with any application that uses File Manager 2.

You are not allowed to copy any of the other files, including but not limited to, Template (TPL) files, Library (LIB) files, Resource (RSC) files and documentation files.

Each developer needs his own license to use File Manager 2.

CapeSoft Software, employees of CapeSoft Software, and Dealers of CapeSoft Software products, explicitly accept no liability for any loss or damages which occur from using this package.  This package is used entirely at your own risk.  Use of this package constitutes agreement with this license.

When you distribute your FM2 enabled application for the first time, if it's compiled in "Stand-Alone" mode (i.e. it requires the use of  DLLs) then you will need to ship the following DLLs with your application:

Support

Installation Instructions

Installing FM2, with ABC support, is a 2 step process:

What Not to Do

1. Sooner or later you will be tempted to reduce the version numbers in your dictionary. DO NOT DO IT.
2. You may think that deleting the upg file will help you. It won't. DON'T DELETE IT.
3. Do NOT change the prefix of a file. Once FM3 is applied, it uses the prefix of a file to identify the file.

Adding FM2 to your application

If you include any of the built-in features of FM2 in your application then you'll need to add the FM2 global extension to your app. To do this...

If you are using an ABC application then you need to add a Define to your project. Do this...

For more information on the individual FM2 features, read on below...

AutoUP

Contents

Introduction
To Use AutoUP in your Application
Steps to take when changing the dictionary
What's this UPG file and when do I distribute it?
Forcing the position of the UPG.TPS file
Support for Multiple Data Sets 
Setting the Password for a File  
Changing a Password
Changing a File Name
Changing a File Prefix
Changing a Field Name  
Priming Fields
Overrides
Very Large Dictionary Support

Introduction

AutoUP allows your program to automatically upgrade it's own data files when they need to be upgraded. This means that all you have to do is change the dictionary, re-compile and distribute.. AutoUP will do the rest. AutoUP supports the Topspeed, Clarion and Btrieve file drivers. All file structures are supported except dimensioned groups and blobs.

When you change your dictionary you can change anything. The file driver, the password, add fields, remove fields, change keys, make arrays bigger or smaller etc. You can also change field types, including memos and strings etc.

Tip: Our recommendation (and indeed a good practise anyway) is to separate the BLOBS out from the data, and put it in it's own table. With a single linking key field. This file obviously never gets upgraded. The "parent" file is then free to upgrade as often as it likes. There are a number of advantages to this approach, quite apart from the upgrading. For example when doing support you can leave the blob bit "behind".

To use AutoUP in your application

Adding and using AutoUP is really easy. However different types of applications have different ways to use AutoUP. After adding AutoUP to your application read on to discover how you go about changing your dictionary. Also if you are adding AutoUP to an existing application, i.e. one that has already been distributed, then you need to read the section on using AutoUP in existing applications.

If you have an existing CW, CPD or CDD application that uses Clarion DAT files (i.e. the Clarion Driver) then AutoUP will automatically upgrade from existing DAT files, to your current file. This means that if you have existing projects, which use only the Clarion driver, then you can treat your project as a "new" app.

Notes

• DET is the Dictionary Enhancement Template set from The Moseley Group. Support for DET is now automatic - i.e. proceed as for normal Legacy apps. See also the MultiDET Example.
• DEF is the Dictionary Enhancement Foundations from the Moseley Group. Support for DEF is automatic - i.e. proceed as for normal ABC apps. See also the MultiDef Example.
• Legacy templates are also known as the Clarion templates - in other words, the non-abc templates. These are the only templates that are shipped with Clarion 2. Later versions of Clarion ship with the Legacy and ABC templates.

To use AutoUP in your single exe ABC application (SinglAbc Example)

To use AutoUp in your multi-dll ABC application (MultiAbc Example)

To use AutoUP in your single exe Legacy, application (SinglExe Example)

To use AutoUP in your multi-dll Legacy, application (MultiDll Example)

Steps to take when changing the dictionary

 What's this UPG file and when do I distribute it?

The UPG.TPS file allows FM2 to work it's magic. It is created and maintained by the FM2 dll. To avoid any confusion about the use of this file please read the following;

Forcing the position of the UPG.TPS file

By default the UPG file is placed in the application directory, in the same place as the calling program. In certain circumstances you may need to override this. If for example you access the data from a number of EXE's, stored in different locations, or if you don't have write access to the application directory, then it makes sense to store the UPG file in the data directory.

There is a strong case for getting the UPG file to appear in the data directory. This has the following advantages;

You can also set the location of the UPG file in your program using the ds_SetUPGPath() function. This should be used in the Global Embed Point called FM2 : Start of initialisation. 

For example in the embed point put;
ds_SetUPGPath()    ! forces upg file to 'current' directory
or
ds_SetUPGPath(datapath)   ! datapath is a variable of yours containing the correct path.

Note : If you are writing a Multi-DLL application, Using C5b (or later) and ABC templates,  then make sure you call this function in the Data DLL, in the same Embed AS WELL.

Support for Multiple Data Sets

FM2 supports programs that have multiple data sets. This is inherently built-in and you do not need to take any extra steps.  However if you would like the UPG file to be duplicated for each data set

If you have an application, that supports multiple data sets, then simply add a call to ds_SetUPGPath() straight after any data directory changes. This is highly recommended because it means that if the data sets are backed up separately then the UPG file will be backed up with the set as well. This can make life MUCH easier later if the individual set is restored.

You would normally make a data directory change by calling either the SetPath command, or by using the FileDialog command. If you go this route then you should add a call to ds_SetUPGPath() after EVERY occurrence where you change the directory. This will cause the UPG file to be duplicated in the new data directories as necessary.

Setting the Password for a File

Clarion allows you to encrypt a file using a password set in the dictionary. For security reasons it's better to specify a variable in the dictionary, and set the variable in the program. If you use a variable password then the password must be set in the Global Embed Point called FM2 : Start of Initialization. If you fail to do this then FM2 will be unable to upgrade the file.

Note : If you are writing a Multi-DLL application, Using C5b (or later) and ABC templates,  then make sure you set the password in the Data DLL, in the same Embed AS WELL.

Changing a Password

One of the limitations of the Topspeed Driver system is that the file inside a superfile must have the same password as the superfile itself. Therefore to change the password for a file, you need to create a new TPS file to put the new file into. See the next section on Changing a File Name for information on how to do this. 

Changing a File Name

If you want to change the name of a file (not the label, but the actual name of the file on the disk) then you can use the following feature. Note that this step is necessary if you are changing the password of a Topspeed file. To change a file name do these steps;

OldName(oldfilename)

Note the lack of 'quotes'. Also to put multiple options together you put them on the same line, separated by a comma. For example

Version(3),OldName(oldfilename)

Changing a File Prefix

Previously this was not supported in FM3, as the Prefix is used to identify files. We have now added support for changing the prefix of a file. To do this, add a File level String User Option to the file in the dictionary.

1)	Go to the dictionary, to the Properties of the file you want to change.
2)	Change the Prefix to be the new prefix of the file.
3)	Go to the Options Tab increment the version number and add the following to the User Options

OldPrefix(OldFilePrefix)

Please note the lack of quotes.

Changing a field name

Sometimes you want to change the name of a field in a file, but you want the data to be moved from the old field to the new field. You can do this using FM2 by following these steps;

OldName(cus:Car)

The cus:car bit is the old field name INCLUDING the prefix! Notice there are no quotes.

Priming Fields

Sometimes when you add a field you want this field to be primed to a value for all records in existing files. You can do this in FM2 using the following steps;

SetIfNew(44)

The 44 bit is the value you want to set the field to. To set a string field you enter the text WITHOUT quotes. e.g.

SetIfNew(Hello World)

There is a special setting you can use for Auto-Number fields. If the value in the SetIfNew field is set to AUTONUMBER then the Dll will automatically give each record a unique number - starting from 1.  This enables you to add AutoNumber fields and keys to your files.  Note that this setting has no effect on existing fields - i.e. you cannot use this feature to turn an *existing* field into an auto-number field. Example :

SetIfNew(AUTONUMBER)

TIP : You can also prime a new field with the value of an existing field. To do this use the OldName feature. i.e. if the new field is PostalAddress, and you want it to default to being the same as the existing Address field then you can use;

OldName(fil:Address)

Overrides

You may want to override some of the default FM2 behavior. This section discusses some of those options, and cases when you would use them.

Ignoring pre-existing DAT files

If your application does not have pre-existing DAT files then you can disable the search that FM2 does for them. This is NECESSARY when you have DAT files of the same name as your new TPS files, and they are in the same directory. e.g.; App 1 uses file Customer.Dat
App 2 uses file Customer.Tps
but the two "Customer" files are unrelated.

You can set it for all files in your application by clicking on the "No pre-existing Clarion files" on the "Advanced Options" tab on the FM2 global extension.

To set it for just one file then add the following user option to the User options for that file, in the dictionary;

IgnoreDriver(1)

Note that when adding multiple user options to the file properties they are separated by a comma, e.g.

Version(3),IgnoreDriver(1)

Ignoring a particular data file

If you wish to ignore a particular file, for whatever reason, then you can do this by using the FM2IGNORE switch. This is added to the User Options for that particular file.

Note that if you ignore a file then it is removed from FM2's sight, as if it didn't exist in the dictionary. This includes the ability for C-Scan to scan the file, if it is a TPS or Btrieve file. If all you want to do is make it be ignored by the File Manager template then use the Exclude button on the window properties of the File Manager procedure.

Downgrading Files

By default FM2 prevents your Topspeed and Btrieve files from being accidentally downgraded. By default it allows downgrading of Clarion files, this is a side effect of the support for pre-existing Clarion files.

You can disable the automatic downgrading of DAT files by using the IgnoreDriver attribute discussed above.

If you want to downgrade a Topspeed or Btrieve file for any reason then you can attempt it by placing /Downgrade on the command line when running the program. If you have disabled the reading of pre-existing Clarion files then this switch will also be able to downgrade Clarion files.

Example :

Very Large Dictionary Support

Are you getting this compile error: Link Error: Too many segdef in file Error(6): cif$fileclose The handle is invalid.

The first thing to try here would be to empty your obj, obj32 directories, possibly restart your machine, and retry a compile. If this does not work, ensure you're compiling in 32bit mode, unless you're deliberately in 16bit mode. If the error persists, it is possible that your program module is just too big for the compiler. If you're using FM2/3, then this is possible when using a large dictionary, especially if you've declared a lot of Alias files, as FM2/3's init code can be quite large. If this is the case, then there is a solution!

The VLDS: FM2 Init Code template generates FM2's init code in another specified procedure. It's probably easiest to add a new source procedure named FMxInitProc (or something similar). Open the embed editor and insert the FM2 code template: VLDS: FM2 Init Code Template. This prompts for a Start and an End, and a File Loop Only? Screen shot below. Start is the alphabetic character of file names to start generating from (typically "A"), and End is the Last alphabetic character of file names to generate init code for. It may well be that you'll need to split the init code into more than one procedure. If this is the case, then you would break the init code by specifying smaller alphabetic ranges for each init procedure. Eg: FM2InitProc1 might be "A" to "M", and FM2InitProc2 would follow on from "N" to "Z". There is also a "File Loop Only" check box. This is to specify whether to generate all init code, or just the file loop. For the first init code template, you would leave this box unchecked, but for any further init code procedures you declare, you'll need to check this box on, to ensure you're not calling other FM2 init code more than once. When you're done adding your init procedures, you need to go the Global Extension Advanced Tab, and specify the init procedures to call.

Example screenshot:

AutoNET

AutoNET is designed to allow you to easily upgrade program files and DLL's (and other files) over a network. This makes upgrading your application much easier on a network as only the server has to be upgraded. All the workstations will automatically upgrade themselves from the server.

This means that application files can be stored locally on each workstation without the normal maintenance overhead this implies. This is important as it reduces network traffic and speeds load times on the workstations.

AutoNET works by keeping the directory on the server and the directory on the workstation in sync. Each time your application runs it checks the files in the local directory against the files in the server's directory. If any files in the servers directory have been upgraded, or if new ones have been added, then they will automatically be copied to the workstation and the application will be restarted.

AutoNET requires that the two paths, the path to the application on the server, and the path to the application on the workstation, be stored in an INI file using the two settings NetPath and LocalPath respectively. You can specify the INI file, or you can let it default to AutoNET.log in your operating systems user temporary directory. Previously it defaulted to the win.ini, but this was not writable to users in Win2K and WinXP enviroments. You can also specify the Section name or let it default to the name of your application. You will need to set these settings during your program's installation routine.

Tip: You can use variables for the section name, and ini file name. Simply put a ! in front of the variable name on the template.

After you have installed your program once on each workstation then you will only have to upgrade the server - the workstations will upgrade themselves.

To use AutoNET in your application

1. If you haven't already done so, add the File Manager 2 Global Extension to your application. (More info)

2. In the File Manager 2 global extension click the Enable AutoNET switch on. When you turn this switch on you will be prompted for the name of an INI file and a Section name. If you leave it blank the INI file will default to AutoNET.log in your operating systems user temporary directory. If you don't enter a path then it will default to the Windows directory, not the application directory. If you leave the section name blank then it will default to the name of your application.

If you have a multi-dll application then switch should only be clicked on in the main EXE. If it is clicked on inside the Dlls then it doesn't matter, but AutoNET will not be used there.

3. When you install your application on the workstation you will need to set the NetPath and LocalPath settings in the Ini file. This can be done by your installation program.

Distribution

AutoNET makes use of the included AutoNet.Exe program. This must be installed into your application directory when you install your application. The AutoNet.Exe program can be located in your \Clarion\3rdparty\bin directory.

Trouble Shooting

If you have any problems with AutoNet then check the Workstation Windows subdirectory for a file called AutoNet.Log. Email this to "support at capesoft dot com" as it contains valuable information.

Synchronising more than 1 Directory

Occasionally a programmer will write a program which needs 2 (or more) directories to be synchronised. The templates only support a single directory being synchronised.  While it would be possible to have the templates support more than 1 directory, it seems that the method used by each developer to identify the directories changes a lot. 

Therefore, in order to give you maximum flexibility, an Embed point has been created. It's a global point called FM2 - Manually Sync More Directories. In this embed point you can identify directories that need to be sync'ed using the ds_SyncDirEx function. For example;

If ds_SyncDirEx('q:\mydir1','c:\mydir1')
  halt
End
If ds_SyncDirEx('q:\mydir2','c:\mydir2')
  halt
End

Obviously you are then free to identify the directories in the way that suits you best.

Note: I added an optional third parameter to this function in version 3.22: ds_SyncDirEx(NetPath, LocalPath, Logfile), where LogFile is the AutoNET.log file, or whatever file you have specified for AutoNET logging.

AutoNet.Log

A useful addition to the AutoNET functionality is the AutoNet.Log file. This is created in the Windows directory on the workstation. This file is especially useful if you're not sure as to why AutnNet is doing the things that it's doing. You should not change the values in AutoNet.Log unless they are marked as changeable.

 

TIP:

If you are using AutoNet then there are 3 distinct directories that you need to keep in mind.

a) the shared data directory on the server. This should not be the same as
(b)
b) the shared program directory on the server.
c) the local program directory.

AutoNet's job is to sync the server program directory with the local program directory. Since you don't want data files flying around, you should
definitely not have any data files in the server program directory.

Many people simply place the data files in a sub-directory on the server.

AutoBUILD

AutoBUILD adds basic Database File Management routines to your application. It presents you with a list of your data files and then allows you to do basic file maintenance on files you select. This maintenance includes rebuilding key files (Build), removing deleted records from the files (Pack), unlocking held files and records (Release), examining the number of records in a file (Info) and calling TPSFix to fix corrupted TPS files (Fix).

NEW : In version 2.7 a new button, Freshen, has been added. This function creates a new file and copies all the old records out the old file and puts them in the new file. This effectively removes all duplicate entries (which might be causing the Build to fail) and also can act as an effective fixing of possibly corrupted files.

NEW : In version 2.7 the Runtime File Manager Procedure template has been replaced by the Runtime File Manager Control template. The procedure template is still included (so that your program compiles) but it should be considered obsolete. At this point you should delete your Runtime File Manager procedure and re-add it again using the instructions below.

This is a very useful procedure to have in your application when doing support. It allows your user to effectively, and easily, do their own database management when required. AutoBUILD is also required if you're going to make use of the AutoFIX feature.

To use AutoBUILD in your application

1. If you haven't already done so, add the File Manager 2 Global Extension to your application.

2. Add a menu option to your main menu. Call it File Manager. Set it to call a procedure called RuntimeFileManager.

3. Create a procedure in your app called RuntimeFileManager. Use the Window Template (NOT the FM2 Runtime File Manager Procedure) as the procedure template. Populate the Runtime File Manager Control template into the window.

Using AutoBUILD in Multi-DLL applications

1. Create the RuntimeFileManager procedure in the Data Dll ( i.e. the DLL where all the files are declared.)

2. Go to the extensions for that procedure, and set the extension to "Use all files in Dict".

3. Export the procedure from the DLL in the normal way.

Distribution

You will need to ship the TPSFix.Exe utility with your application if you use Topspeed Driver data files. You do not need to ship TPE files with your application. AutoBUILD will create example files (TPE files) as and when required. TPSFix.Exe can be found in your \clarion5\3rdparty\\bin directory.

As TPSFix is supplied by Topspeed we recommend you read the instructions regarding it's use. CapeSoft can not accept responsibility for the actions performed by the TPSFix program.

DET Compatibility

DET users note : For maximum compatibility with DET you will need to make a slight modification to the FM2.TPL file. This change will be required if you are using DET's variable file name feature. The FM2.TPL file is located in your \clarion5\3rdparty\template directory and contains instructions at the top of the file on the change required.

AutoFIX

If you have a corrupt TPS file then this will most likely evidence itself when the file is opened. By using FM2's AutoFIX feature you can automatically trap when this occurs, and automatically invoke TPSFix when your application is next run.

AutoFIX works by noting which file is being opened when a fatal crash occurs. Unfortunately there is nothing we can do about the crash, but the next time the program is run a message will appear noting that the file caused an error, and offering to run TPSFix for you. If you decide yes then a TPE file will be created and TPSFix will be invoked in automatic mode. No other input from the user is required. After TPSFix has finished the user can attempt to run the program again to see if any progress has been made.

At this stage AutoFIX only supports the Topspeed File Driver.

To use AutoFIX in your application

1. If you haven't already done so, add the File Manager 2 Global Extension to your application.

2. In the File Manager 2 global extension click the Enable AutoFIX switch on.

3. You must enable the AutoBUILD feature in your application in order for AutoFIX to work. To add AutoBUILD to your application follow the directions above.

Distribution

You will need to ship the TPSFix.Exe utility with your application if you use Topspeed Driver data files. You do not need to ship TPE files with your application. AutoFIX will create example files (TPE files) as and when required. TPSFix.Exe can be found in your \clarion\bin directory.

As TPSFix is supplied by Topspeed we recommend you read the instructions regarding it's use. CapeSoft can not accept responsibility for the actions performed by the TPSFix program.

C-Scan

C-Scan is a program for scanning and editing data files. Similar to the "Browse Database" feature in the CW IDE, and similar to the old Clarion Professional Developer CSCN utility.



Formatting

To change the formatting of a column, after opening a file, point to that column and press Ctrl-F, or Ctrl-P. You can enter any standard Clarion picture.

To change the contents of a field simply type the new contents over the existing contents.

Security

To prevent unwanted scanning by your end user, C-Scan is protected using a simple password. The password is "SCAN". This is not meant as a security device, but to stop users accidentally scanning, and possibly editing files. To turn off this feature go to Preferences in the Help menu.

If you want to give your users access to C-Scan, but you don't want to give them the SCAN password, then there is a dynamic alternative. C-Scan has a "password of the day" feature. This password is calculated as follows;

C-Scan asks for the file's "Owner" name, if one exists, every time that file is scanned. If you want to protect your files from scanning by a sophisticated user, or another Clarion user, then use the Owner feature to encrypt your data files.

Searching (and Replacing)

C-Scan includes the ability to search a column for a matching entry. In addition to this you can also do Partial and Anywhere searches. A Partial search will find a match, even if the search string is only part of an actual field. In other words a partial search of the word Cape will return a match in the string CapeSoft. An Anywhere search allows you to search all the fields for the required value. If this is switched off then only the highlighted column will be searched. Choose the Search menu option after opening a file to search the file. Search and Replace is also supported.

Distribution

You are free to install CS.Exe on any computer, provided that an FM2 enabled application is running on that computer. This means that you can install C-Scan on your clients computer which can assist you with debugging, and supporting your program. C-Scan is compiled in local mode, and doesn't require any DLL's.

Btrieve

The current release of C-Scan does not support Btrieve. However an old version of C-Scan is available from our web site (https://www.capesoft.com/accessories/downloads.htm#fm2). The older C-Scan requires also that you install some btrieve DLL's. These DLL's are included in the cs.zip file.

UpgView

UpgView is a utility for viewing the Upg.Tps file.  This is a useful debugging tool to see why a particular file won't upgrade. It is not intended as an End-User tool, but rather as a tool to assist developers.



Print File Layout

To print a copy of the file layout, for any particular version of the file, simply highlight the file and choose Print from the File menu.

Analyse File Changes

To view an analysis of the changes to a file structure, highlight the file label and choose Analyse from the File menu. This lists all the versions of the file, and the differences between the versions.


 

Distribution

You are free to install UpgView.Exe on any computer, provided that an FM2 enabled application is running on that computer. This means that you can install UpgView on your clients computer which can assist you with debugging, and supporting your program. UpgView is compiled in 32 bit, Local mode, and does not require any DLL's. 

FM2 Template Options

The options on the FM2 global template are detailed here.

International Language Support

FM2 allows you to translate all the error messages into your local language. This is done through the use of a simple INI file (called FM2.INI). Sample versions of this file are shipped with FM2. To translate the messages into your language of choice simply edit the INI file. Remember to ship the modified INI file with your application.

FM2 currently ships with examples of this file, in several languages. These files are installed into your \Clarion5\3rdparty\LibSrc directory as Fm2Ini.???.  Rename the one you prefer to fm2.ini and ship with your application.  We rely on users to supply us with these files, so please feel free to send us translations of the file in your language.

Tip : By default the INI file must be located in the same directory as the EXE.

ABC Template Support

Basically using FM2 in ABC apps is exactly the same as using it in a Clarion app except for the following 2 items.

Converting your CW 2 apps to Clarion 4/5

When converting your apps from Clarion for Windows 2, to Clarion 4 or 5 (or converting from FM2 ver. 2 to FM2 ver. 2.9 in Clarion 4) you'll need to remember to do the following...

Error Messages

Unable to identify driver - use ds_AddDriver driver to register drivers.

Go back to your app and make sure that you have, in the FM2 extension, clicked on support for all the drivers in your app (past and present).

Unable to Upgrade - Not "Using" File <file prefix>

If you are trying to upgrade this file, and you get this error, then this means that the file has not been registered with the FM2 Dll. If this occurs in your Multi-DLL app then it points to either a wrong implementation on your side (see the AutoUp section for the right implementation) - or possibly a bug in the template.  If after checking the implementation you don't come right then contact Technical support at support@capesoft.com .

Possible file change without changing File Version number. File involved : <filename>

The program has detected a difference in the file structure being used, and the file structure that FM2 has stored against that version number. This occurs when you change the dictionary, but forget to change the Version number.

FM2 will upgrade the data file, if necessary, but you will not be able to upgrade FROM this structure, unless you fix the error WITHOUT changing the structure again.

To fix the error, go to your dictionary, increment the version number for this file, and recompile (and redistribute if necessary) your EXE.

Unable to Open UPG file : cause <error>

FM2 uses a data file called UPG.TPS. If it is unable to open this file then you will get this error. If the errorcode is 3 then the most likely cause of the error is that the path specified in FM2.INI does not exist.

Unable to upgrade file which doesn't have a prefix : <filename>

All the files in your dictionary must have a prefix. You will get this error if FM2 encounters a file that does not have a prefix.

Unable to upgrade file - no file name available

You are very unlikely to get this error. FM2 renames your data file to another name before upgrading. this name is DSTMPxxx. Where xxx is a number from 000 to 999. If none of these filenames are available (i.e. if they exist already) then you will get this error.

Unable to upgrade file - Error creating destination file <error>

FM2 could not create and open the data file, for the reason mentioned in the message.

Unable to upgrade file - Error reading source file <error>

There was an error during the upgrade, while reading the source file.

Error Writing destination file <error>

An error occurred while writing the data out to the destination file.

Warning - Driver not located - GPF likely

A structure exists in the UPG file, which uses a driver that is not switched on in your app. On the FM2 global extension switch on all drivers that your app uses, or has used.

Debugging FM2

Important: FM2 has been changed to only produce Debug Information using the free SysInternals' DebugView application available from www.microsoft.com.

The DebugView application can also be used to create actual file as well.

Disclaimer:
This is not a CapeSoft product and while we recommend it (and we use it ourselves), we can not take responsibility for what this application may or may not do to your computer system.

To turn on the logging you will need to do the following:

1) Run the DebugView Application.
2) Run your application with one of the following command line parameters:

/debugfmgpf - reports functions executed, useful for finding position of GPF.
/debugfm2 - standard debug switch, reports functions executed and errors. (recommended)
/debugfmall - reports everything. NB - use this one when sending log files to CapeSoft. Please note, you will not necessarily be able to draw your own conclusions from this debug log - send the file to CapeSoft for analyising.

Important: If you send CapeSoft support a log file (you can get DebugView to produce a .log file), please make sure it is generated using the /debugfmall option.
e.g. <YourApp> /debugfmall

TIP: You can use Clarion's SetCommand() function to run your program with debugging without manually using the commandline! Alternatively, you can create a windows shortcut to the EXE and add these arguments to the "Target" field in the shortcut's properties box.

3) Once you've run your app and can see the results in DebugView, you can go to File > Save As to save the log file.

Frequently Asked Questions (FAQ)

---

Question 1: When is it a good idea to delete the upg.tps file?

Answer : Never. To get some idea of this question, ask yourself, when is it a good time to delete your customers / invoices / products / whatever file. The answer is never right? well that goes double for the upg.tps.  Never. Never. Never. Get it?

---

Question 2: when is it ok to decrement the file version numbers in the dictionary?

Answer : Never. Never. Never. Except if..... no, that's right, never....

---

Question 3 : I still get Error 47. 

Answer : You probably haven't completed the installation by running the SupportABC utility template.

---

Question 4 : After conversion I get an Assert window. It says "Assertion Failed on line 303 in Abfile.clw".

Answer : This is caused by ABC doing a rather over-enthusiastic check of the CLOSE statement. you can safely just click No and continue. To make the error go away compile with debugging turned off, or remove the offending Assert statement from ABFILE.CLW

---

Question 5 : Suddenly Error 47 has returned. 

Answer : You have probably upgraded your Clarion, maybe with just a patch, and you haven't re-done the  the installation by running the SupportABC utility template.

---

Question 6 : AutoNET doesn't seem to work.

Answer : This is probably because you have the ini file, containing the settings, in the wrong location. The default location is the Windows directory. 

---

Question 7 : I want to reduce the version numbers in the dictionary. Can I do this?

Answer : No. If you do this you will break the upgrading. It will not work. There is no benefit to doing this, so give up this idea ok?

---

Question 8 : File Manager 2's AutoUP feature has been working very well. But suddenly it's stopped working, and I get an Error 47.

Answer : Have you just updated your copy of Clarion? Or installed ClarioNET? If so you need to re-run the SupportABC utility template. See Installation Instructions for more info. (Ok this question is repeated in the FAQ, but hey - it gets asked an awful lot!)

---

Question 9 : Does FM2 support programs that use Multiple Data Sets ?

Answer : Yes. See Support for Multiple Data Sets

---

Question 10 : Does FM2 support programs using different dictionaries, but sharing the same UPG file ?

Answer : Yes. Absolutely no problem here. One consideration though - If you have files of the same name ( ie Customer File) in the different directories, then the file structures, Including File Version Number, must be the same in both Dictionaries.

---

Question 11 : AutoNet gives me an error saying the AutoNet.Exe and File Manager are out of Sync.

Answer : Check and make sure the values in the designated INI file, for NetPath and LocalPath, use the Short form of the name. In earlier versions of Clarion Long File Names were not supported. The AutoNet.Exe is compiled in Clarion 5 so it _does_ support Long File Names, but if you use it with a Clarion 2 program, and you use the longer version of the path name, then you might get this error.

---

Question 12 : I added AutoFix to my application or moved my Clarion 2 application into Clarion 4 or 5. Now I get lots of compile errors "Parameter type label ambiguous".

Answer : In Clarion 4 and 5 the old File Manager procedure has to be renamed to RuntimeFileManager

---

Question 13 : I've got a RuntimeFileManager procedure, but when my app compiles I get a Unknown Procedure Label on the line that calls the RuntimeFileManager.

Answer : Go to the Properties for the Runtime File Manager procedure. Make sure the Declare Globally option is ticked on.

---

Question 14 : I've been using FM2 for a while, and I've upgraded, and now I get a warning "Duplicate Identifier : &WorkFile"

Answer : Go to the Global Data Button and delete the variable &WorkFile from there.

---

Question 15 : I added File Manager 2 to my application, but now it takes a long time to load.

Answer : You've made a call to ds_SetUPGPath after FM2 has initialised itself. For the quickest load time make your call to ds_SetUPGPath before Fm2 initializes. There is a Global embed point, called "FM2 : start of initialisation section", where you can do the call.

---

Question 16 : I ran C-Scan, but it wants a password. I tried the password you emailed me, but it doesn't work.

Answer : The password to C-Scan is SCAN. The password you were emailed is to unzip the update files from the web site - www.capesoft.com

---

Question 17 : I bought File Manager 2 some time ago - for Clarion 2 (or 4 or 5) - but I now need the version for Clarion 4 (or 2 or 5). How much does it cost, and where can I get it?

Answer : Updates are free, and can be downloaded from the web site - www.capesoft.com - the password is issued to you when you register. If your password is outdated then send an email to and we'll update you.

---

Question 18 : So how do I register?

Answer : Send us your contact details, via email () or via fax (+27 21 715 2535). Include the dealer you bought it from and the order number.

---

Question 19 : I'm getting a link error, Unresolved External, ds_SomeFunction.

Answer : You have an old copy of the lib file on your hard drive. Check the project to see which FM2 lib is being linked into your program, and then search your drive for that lib. 

---

Question 20 : I'm getting a problem upgrading the file. I'm using an Alias here.

Answer : This can be a real funky problem, especially if the Alias was introduced well into the development cycle. From FM2's point of view an alias behaves very similarly to a file. However if the file structure being converted pre-dates the introduction of the Alias then you may get an effect where the file is converted, but all the fields are cleared.

In a situation like this try and make sure that the genuine FILE is used in the app before the ALIAS.

---

Question 21 : I'm getting some really strange errors.  Like it's telling me that files have no prefix (and they do). Or that the data file is invalid. What's going on?

Answer : Are you using encryption for these files? If so read up on using AutoUp with encrypted files here, as you probably aren't setting the variable passwords soon enough.

---

Question 22 : I Changed a field from decimal(13,3)  to decimal(13,4).  This was the only change in the file (at that time).  Now in the program (on screen and on reports) the values in the field in question has been divided by 10?

Answer : The problem here is that you haven't fundamentally changed the file, but rather you've changed the interpretation that the program applies to the decimal field.  It's natural to think of the decimal declaration as (digits-left-of-decimal-point , digits-right-of-decimal-point).  But this is not the way they are actually defined.  The clarion definition of a decimal is (total-number-of-digits , number-right-of-decimal-place).

Thus when you changed 13,3 to 13,4 you effectively decreased the size of the number that can be stored.  In order to simply add an extra decimal place you should have converted to 14,4 .

It is possible to correct the problem, but you must be careful to do it right, or your data will remain in a "divided by 10" state.

A) Go back to the dict. Set the decimal back to 13,3 BUT INCREMENT the file version number.
B) Compile and run the application.
C) Back to the Dict again. Change the decimal correctly this time. ie to 14,3. INCREMENT the file version number again.
D) Compile and run the application.

 

Version History Download  here

Version 3.92 Beta (Released January 6, 2010)

• Some Clarion7.1 support.
• MaxKeys (for each file) increased to 120.

Version 3.91 Beta (Released April 20, 2009)

• C7 workaround. Build requires the files to be closed - so flat file's keys were not being built after upgrading - because in older version s of Clarion, the build could be applied when a file is opened in exclusive access mode.

Version 3.90 Beta (Released February 3, 2009)

• C7 fix - SupportABC template utility modifies the builtins.clw file correctly (was looking in the incorrect place).
• C7 work-around - Don't error after build() attempt. Build in C7 always returns an error if the file is open (even in 12h mode).

Version 3.89 Beta (Released November 26 2008)

• Clarion 7 support template tweaks - includes correct lib files and generates code (for C6 and up).

Version 3.88 Beta (Released November 10 2008)

• Clarion 7 compatible install.

Version 3.87 Beta (Released November 22 2007)

• FM2 DLL includes the improvements made to the FM3 DLL (for tps functionality) up to FM3 version 4.25.
• Clarion7 support DLL built

Version 3.86 Beta (Released July 16 2007)

• FM2 uses it's own txas to import the RuntimeFileManager windows.
• Also merged the templates into one TPL file.

Version 3.85 Beta (Released July 16 2007)

• FM2 removed from the dependency of FM3 (uses it's own tpw file).

Version 3.84 Beta (Released June 13 2006)

Note: For FM3 users: You need to upgrade FM3 as well in this FM2 release!!

• RuntimeFileManager (by default) takes the status of the 'Generate all file declarations in this App' checkbox for the UseFiles template prompt (previously was defaulting to 'Files used in this App') (New fmcommon.tpw)

Version 3.72 Beta (Released May 12 2006)

Note: For FM3 users: You need to upgrade FM3 as well in this FM2 release!!

• Template Fix: Alert if a BLOB is inserted into a FM2 table. BLOBs are not supported at this stage. If you need to use BLOBs, they should be placed in a separate table.

Version 3.71 Beta (Released April 6 2006)

• Template Fix: Regression introduced in 3.70 - was trying to link FM3 libs into the application instead of FM2 libs.

Version 3.70 Beta (Released April 4 2006)

• Template Fix: Merged more common FM2 functionality and FM3 functionality into the FMCommon.tpw.
• Template: New Template utility to import the RuntimeFileManager window into your application.

Version 3.69 (Released March 27 2006)

• Fixed regression introduced in 3.67 - inability to populate the RuntimeFileManager control template.

Version 3.68 (Released February 22 2006)

•  Version compatibility release with FM3.

Version 3.67 (Released January 27 2006)

•  Template: Split template into 2, moving common code between fm2.tpl and fm3.tpl to fmcommon.tpw.

Version 3.64 (Released December 15 2005)

•  Template: Fixed Multi-DLL VLDS Support.

Version 3.63 (Released December 12 2005)

•  DLL: Fixed creation of a "0" file in the application directory.
•  DLL: Added support for Clarion 6.2 9047 internal data structures.
•  Template: Fixed VLDS AutoFIX placement.

Version 3.60 (Released June 2 2005)

•  DLL: Fixed FM_Upgrading switch to be turned on during a Freshen.
•  DLL: Added workaround for Access Denied Error occurring on SuperFiles during upgrade if 1 or more subtables were open on another thread.
•  DLL: Tweaked Downgrade messages.
•  Template: Tweaks to the RuntimeFileManager.
•  AutoNET: Fixed Error handling for running AutoNET.exe.
  

Version 3.55 (Released February 7 2005)

•  DLL: Fixed Changing file names when fullpath is set in the OldName user option.
•  Template: Fixed "Driver not located" error when using IPDriver files in an FM2 enabled app. Please note: FM2 does not support upgrading IPDriver files.
•  AutoNET: New version available!

Version 3.45 (Released October 27 2004)

•  DLL: Now handles DateTime Group Over String structures in TPS.
•  DLL / Template: Now handles upgrades for files containing triggers (C6).
•  Template: Now conforms to the new CapeSoft Template Standards.

Version 3.43 (Released September 03 2004)

•  DLL: Huge optimizations on file conversions.
•  DLL: Other minor optimizations and fixes.
•  Template: Minor changes and improvements.
•  AutoNET: New version of AutoNET - now allows your program to start with up to 6 command line parameters.

Version 3.28 (Released December 11 2003)

•  DLL: Fixed Clarion 5 compile errors.
•  DLL: Added support for Replicate to know when FM2 is upgrading.

Version 3.27 (Released November 14 2003)

•  FIX: fmXXcwrt.dll errors on IDE Loading Template Registry.

Version 3.26 (Released November 13 2003)

•  Template: Fixed %OldPrefix Template error in Legacy applications.
•  Template: Fixed automatic running of Support ABC Template Utility which copied builtins.clw into the app source directory.

Version 3.25 (Released November 03 2003)

•  Template: Now automatically adds the FM2=>1 Project Define for C55 and above. NB: C5 users still need to do this manually!
•  Template: Now automatically runs the Support ABC Template Utility. NB: If you get an error 47, run this manually and retry before contacting Support.
•  Template: Added support for changing your file prefix. New File Level String User Option: OldPrefix

Version 3.24 (Released September 10 2003)

•  Template: Fixed GPF in AutoNET when calling ds_SyncDirEx.
•  Docs: Minor fixes and updates to docs.

Version 3.23 (Released September 05 2003)

•  Template: Improved Very Large Dictionary Support (VLDS:FM3 Init Code).
•  Template: Changed AutoFIX to use Long Path Names in Clarion 6 (TPSFix v6.0).
•  DLL: Fixed Multi-table TPS file conversion.
•  Runtime File Manager: Fixed Freshen emptying files.
•  Runtime File Manager: Added Build Error checks.

Version 3.22 (Released August 06 2003)

•  DLL: Fixed the upgrading of Btrieve(DAT) files containing MEMOs where the FM2/3 "Keep old versions of files" switch is ON.
•  UpgView: Fixed displaying of non Topspeed data file structures.
•  Docs: Updated and changed the Debugging section. NB: Please refer to this section before requesting support!

Version 2.99 (Released July 22 2003)

•  Template: Added "/A" switch to TPSFIX.exe command line so that it runs visibly, but silently.
•  DLL: AutoNET default ini file has changed to AutoNET.log in the operating systems user temporary directory.
•  CSCAN: Fixed.
•  Docs: Fixes and adjustments to documentation.

Version 2.98 

+	Fixed data corruption in files containing OVERed fields.

Version 2.97 

+	Fixed some outstanding bugs in C-Scan
+	Clarion 6 build released
+	Clarion 4, and 16 bit support, dropped.

Version 2.96

Version 2.95e

Drops leading zeros from decimal/decimal and string/decimal conversions.

Version 2.95d

Warning : this contains a subtle, yet major bug which can cause some invalid data to appear in the file. Please do not use this version, use 2.95e instead.

Version 2.95c

The UPGView utility in 2.95b was completely broken. Fixed in this release.

Version 2.95b

This is something of an interim release. There are still some bugs in C-Scan and UpgView (which are being worked on) but many others have been fixed. Plus AutoNet has been tweaked, as has the Upgrading, so on balance we've decided to release now. Chances are there'll be another release fairly soon after this one...

Version 2.95a

Version 2.95

Version 2.9

Version 2.8


Version 2.7