Version Beta www.capesoft.com

Complete Documentation

Search the Docs
	Search Docs: Powered by Google.

Contents
	Recommended Reading   General Information   Introduction   Installation New Users   Jump Start   Examples The RULES!!!    [NB: Very Important!]   Adding FM3 to your application   Errors (Compile Warnings and asserts , Program GPFs or Hangs) FAQ Debugging & Support   Purchasing FM3   Distribution       In Depth   AutoUP   AutoBUILD   AutoFIX   AutoNET       Technical Reference Guides SQL Documentation (essential reading when converting from TPS to SQL) Technical Reference       Other Information   Helpful Utilities Hot Tips   Miscellaneous Topics   To Do List   Version History Licence, Copyright, and Disclaimer       Can't find what you're looking for?   Click here to Search the FM3 Docs

Introduction

• Btrieve (Pervasive - but not SQL - i.e. Scalable is not supported)
• Clarion (dat files)
• TopSpeed (tps files)
• MSSQL (SQL Server)
• Oracle
• SQLAnywhere
• ODBC: (currently limited to MSSQL, ORACLE, MySQL (2 and 3), Firebird, PostgreSQL*)
• SoftVelocity's IP Driver (IPD)

* PostgreSQL is limited to Clarion6 and up.

FM3 also endevours to support SoftVelocity's Dynamic File Driver (DFD). This driver is still reasonably new (as of the writing of these docs), and therefore has gone through a few changes between versions, often resulting in FM3 needing to find a new way to support them. Support for the In-Memory Database Driver (IMDD) is superfluous to FM3.

As per CapeSoft's standard policy, File Manager 3 supports 3 versions of Clarion, currently Clarion 5, Clarion 5.5, and Clarion 6. File Manager 3 only supports 32bit applications.

FM3 consists of a Template and a DLL.

Please note: FM3 is currently in beta, and may not support all features across all drivers at this stage! See Version History for updates on features.

Main Features include:

AutoUP:

AutoBUILD:

AutoNET:

AutoFIX:

C-Scan:

UPGView:

BDE:

Limitations:

Installation

It is vital that you follow the complete instructions for installing FM3. As per CapeSoft standard, File Manager 3 adheres to the standards specified by the C3PA (Clarion 3rd Party Association).

Run the supplied setup program. (Download the Latest Version!)

In earlier versions of FM3, you were required to run the following Template Utility. If you're running version 3.26 or earlier, complete the installation as follows:

Running the Template Utility

Open the Clarion IDE.
Open any application.
Choose Application > Template Utility from the menu.
Select the Support ABC Template Utility from the FM3 Class.
Enter the name of your Clarion directory. For example: C:\Clarion5.
Click on OK.

Note: We highly recommend upgrading!!

Notes on the Template Utility:
It is strongly recommended that you do run this Template Utility, even if you're not using ABC.
You only need to run it once. You do not need to run it for each application, or when you upgrade FM3.
You will need to re-run this after upgrading Clarion in anyway (patches, ClarioNet, etc).
If you own FM2 also, you need to run both template utilities.
You will need to run it for each version of Clarion you're installed on your machine, if you're using them.

New Users

Before You Start

Getting Started

Where to from here?

New to SQL?

Examples

Examples
		Name	Description	Drivers
		FM3Demo:	Main example demonstrating AutoUP, AutoBUILD, & AutoFIX.	TopSpeed, Clarion.
		SinglABC:	Single exe ABC app.	TopSpeed.
		SinglEXE:	Single exe Clarion / Legacy app.
		MultiABC:	Multi dll ABC apps.
		MultiDLL:	Multi dll Clarion / Legacy apps.
		MultiDET:	Multi dll with DET support.
		MultiDEF:	Multi dll with DEF support.
		MSSQL:	MSSQL example demonstrating conversion from TPS to SQL.	TopSpeed, Mssql.
		ORACLE:	Oracle example demonstrating conversion from TPS to SQL.	TopSpeed, Oracle.
		ODBC:	ODBC examples demonstrating conversion from TPS to SQL.	TopSpeed, ODBC.
		MABCMSS:	Multi dll ABC MSSQL example.	Mssql.
		MLEGMSS:	Multi dll Clarion / Legacy MSSQL example.	Mssql.

Keen to get started? Then this section is just for you - the basics on how to get FM3 into your application as quickly and simply as possible.

Adding FM3 to your application

Adding the Global Extension

Open your app.
Click on the Global Button.
Click on Extensions.
Click on Insert.
Select the Activate FM3 Extension from the list (check out the Template Reference: FM3 global extension template for more details).
Click OK.

Adding the Project Define (Clarion5 users)

If you're using a SQL backend - adding the SQL_Connect window

If you're using AutoBUILD/AutoFIX, then add the RuntimeFileManager procedure

Run the Template utility: ImportRuntimeFileManagerABC/Legacy.
In the FM3 Global Extension template (on the AutoFIX tab) you must set the RuntimeFileManager to the newly created RuntimeFileManager procedure. Goto Template Reference: FM3 global extension template for more details. 

In your Global properties (on the File Control tab), make sure that you've checked the 'Generate all file declarations' checkbox.

The Alternative - creating a separate application to handle file conversions.

What to do in your Dictionary

You will need to add a Version item to each file's user options list and set it to 1. You can do this easily with CapeSoft's Bulk Dictionary Editor (BDE). You will need to increment the version number every time you make a change to the file properties or file structure.

If you are using SQL - then each table's owner must be set to use the owner variable that is use in the SQL_Connect window.

For other file options check out the section on How to make basic file structure changes

That's basically all you need to add to your application. To find out more detail on the different aspects of FM3, read the following documentation sections: AutoUP, AutoBUILD, AutoFIX and AutoNET. Oops - before getting too excited, don't forget to read The Rules.

To find out what you need to do the first time you deploy your FM3 application, check out the UPGFile section.

The RULES!!!

AutoUP

AutoUP Contents
		Who Should Implement AutoUP?
		Description
		Implementation
		How to make basic File Structure changes
		Overrides (also check the Dictionary User Options Quick Reference and Dictionary User Options)
		The UPG File (upg.tps)
		Miscellaneous
		SQL

Who should implement AutoUP?

Description

Currently UnSupported Structures

Implementation

Adding AutoUP to your Single exe ABC Application

Adding AutoUP to your Multi-DLL ABC Application

Adding AutoUP to your Single exe Legacy Application

Adding AutoUP to your Multi-DLL Legacy Application

Adding AutoUP to your IP Driven Application

Some additional cases:

Case 1:
Note: If you would like FM3 to manage local client-side files, then leave FM3 in your data dll or exe, and check the IPDriver check box on the Global extension.

Case 2:
If you have applications that use the TPS files on the IPserver as local TPS files, then these applications will need to use the upg.tps file that exists in the IPServer database. These applications can be treated as normal TPS applications (where adding FM3 is concerned). If you have Multi-Proj, then you can use the Driver Substitution feature to make 2 exes from the same application - one that is IPDriver enabled and one that is TPS enabled. Otherwise you will need 2 apps - one for IPDriver and one for TPS.

Case 3:
Your data does not exist in the root directory of the IPServer. Insert the following code into your Data DLL (in the 'FM3: Before initialization' global embed point):

ds_SetUPGPath()

Known issue: Once adding FM3 to the IP_Server Dll, a Memory Block free'd twice error occurs on unloading of the dll. We are not certain of the cause, but this will only occur when you close the IP_Server Dll. The message will remain for about 20 seconds, and then disappear harmlessly. Not recommended: Further to this, you can set your IPREQ service to not allow interaction with the desktop. This will ensure the error is not visible - although be careful, because if you have any errors, they will not be displayed, so Possible file upgrading without changing the version number errors will cause your DLL to freeze on the IP Server.

AutoUP and the Dynamic File Driver (DFD)

Because the majority of DFD usage is using handcoded data structures, you will need to handcode the FM3 functionality

• You will need to make a call to the ds_AddDriver function - if you have no other files using that file driver in your dictionary (IOW this function should be called once for each driver that your application's files use, and that FM3 is required to upgrade).
• After creating the DFD data structure, make a call to the ds_UsingFile function. You will need to manually increment the version number in this call each time you make a file structure change.

The alternative - Creating a Separate Upgrading Application

Many times it's a good idea to have a separate application to upgrade your datatables. This means that the upgrading of the tables is done once at a scheduled time. Normally you would run this application at the end of the installation routine. You can do this very easily as follows:

• Create a blank application based on your dictionary.
• From the Application | Template Utility menu, select the CreateFM3ConvertorApplicationxxx utility.
• If you're wanting to include a SQL_Connect procedure in this application, then check the Include a Connect Procedure checkbox, otherwise leave it blank.
• You will see the RuntimeFileManager and SQL_Connect (if selected) procedure(s) added to this application. 
• You will need to setup the FM3 global extension template as you have in your application (for settings pertaining to AutoUP).
• You will also need to create the necessary project defines in your project to include the supported drivers.
• You will also need to modify the ConnectToSQLBackendControls control template prompts (on the SQL_Connect window) to match those in your application.

Where to from here...Assess your scenario:

How to make basic file structure changes

Changing a File Structure
		How to add / change the version number(NB: Must be done for every file structure change!)
		How to change a file name
		How to change a field name
		How to change the file prefix
		How to prime new fields
		How to add / change a file password
		Other Dictionary User Options Available

 How to add / change the file version number

In some cases, there may be a little more to be done, but for the most part, this is all you need to do:

Make the necessary change in the dictionary.
Then, for each file you have changed, go to the file Properties, Options tab. Either add or increment the following:
Clarion 5:

How to change a file name

How to change a field name

Note: You must include the file prefix!
Note: No quotes should be used!

You can have up to 14 old field names listed.

How to change the file prefix

How to prime new fields

Note: This variable will be set ONCE before each file conversion, so the same value will be populated into the new field for each record changed. If you are wanting to populate each variable with a unique value, then you need to create a process to run through the file and populate the new field with a variable after the file conversion.

Tip: To prime a field with an existing field in the same table's data, use the oldname user option of that existing field.

NOTE: For SQL files, using this will move the data from the one SQL field to the other (in accordance with the renaming field feature) - unless the oldfield still exists in the dct. If the old field exists (in the dct) then the data will be copied from the one filed to the new field, otherwise the oldfield will be renamed to the newfield (and not exist on the backend).

To prime a GUID field

AutoUP will automatically prime each empty GUID field it finds during upgrade. The field must be named GUID, or PRE:GUID and must be a STRING(16).

To prime a field with a value from a function

AutoUP can automatically prime fields using a function (or variable). Note that you need to prime variables for this function before FM3 initializes:

Note: This function will only be called ONCE before each file conversion, so the same value will be populated into the new field for each record changed. If you are wanting to populate each variable with a unique value, then you need to create a process to run through the file and populate the new field with a variable.

How to add / change a file password (Owner)

AutoUpLimitations

See also the SQL Reference for SQL specific limitations.

General:

• You can't dimensioned groups in an FM3 managed table.
• You cannot change a DATE or TIME to a LONG (or visa-versa) - as FM3 moves the data byte for byte without interpretting the bytes. This means that the data will be invalid because these datatypes store data differently.

BTrieve Specific:

• You cannot have the Memo=single attribute on BTrieve files.

Dictionary User Options

Introduction

Right click on your file, and select properties.


Go to the options tab, right click on the list box, and select insert.


Ensure that the String radio is selected, and then type the name of your user option.


Finally, click in the right hand column of the list box, and set it's value.

Dictionary User Options Quick Reference

Dictionary User Options In Detail

Version

OldName(File Level)

When changing the physical name of a file, the OldName user option should be added to the FILE level options. It should be of STRING type. The label should be OldName, and the value should be the name of the previous file.

If this is a constant, then your OldName user option should like this:

(Note the lack of quotation marks in the value)

If the name of the old file must be a variable, then you can enter this in the value as follows:

(Note: You must prime the variable before FM3 initializes.

OldName (Field Level)

OldOwner

SetIfNew

UnRealField (SQL)

RealField (SQL)

AutoNumber (SQL)

For other backends, only the increment portion is relevant, so you need just enter (1) for an increment value.

Note: You can only create an Identity field. You cannot convert an existing data field into an auto-numbered field.

 Take a look at Server side Auto-incrementing for details on implementing the full solution.

TableSpace (SQL)

IndexSpace (SQL)

ZeroNull(SQL)

OldPrefix

IgnoreDriver

FM3IGNORE

DctMasterFields (SQL)

DctMasterKeys (SQL)

DctMasterRelations (SQL)

DctMasterField (SQL)

DctMasterKey (SQL)

DctMasterRelation (SQL)

ForceSQLDataType (SQL)

DisableUniqueKeyNameCheck

This is a Dictionary User Option that is used to suppress the assert warning that is generated by the template is a key has the same name (external name) as another key.

Some Examples:

Overrides

Ignoring Pre-existing DAT files

To set this option for all files:

To set this option for a specific file:

Ignoring a particular file

To set this option for a specific file:

Downgrading files

The UPG file (Upg.tps)

When do I distribute the UPG file?

	Case 1:	You've got a new app that you are distributing to new clients. You are using any file driver.
	What you do:	You DO NOT distribute the UPG file. It is created, and managed for you, at the client's site, automatically.

	Case 2:	You've got an existing app you want to upgrade. The app currently uses Clarion DAT files (maybe it was written in CPD or CDD). You may or may not be converting the data to the Topspeed / Btrieve file formats.
	What you do:	You DO NOT distribute the UPG file. It is created, and managed for you, at the client's site, automatically.

	Case 3:	You have an existing app using Topspeed or Btrieve files. You are thinking of doing an upgrade, but you haven't changed any file structures yet.
	What you do:	Before changing the file structures, add FM3 to your app, re-compile and distribute. You DO NOT distribute the UPG file. It is created, and managed for you, at the client's site, automatically.

	Case 4:	You have an existing app using Topspeed or Btrieve files. You have already changed some file structures in the dictionary since you distributed the program to your clients.
	What you do:	If you can revert to Step 3 then do so.
	Alternative 1:	Add FM3 in the normal way. Upgrade the existing clients to the new version using one of the older methods (i.e. using the CW IDE or Conversion programs). From then on later versions will upgrade automatically. If you were using the DC Data Convertor templates, then this is probably the route you'd take. Make your last data convertor conversion application. You can either include this in the installer - and only run it when the installer does not find the upg.tps file, or handle the clients on a case -by-case basis (i.e. manually). You will then need to ship the upg.tps file in your installer (with version 1 records in it) - and only install it if the upg.tps file does not exist already.
	Alternative 2:	Add FM3 in the normal way. Compile a version of your app using the OLD dictionary structure. Compile and run the EXE. Distribute the generate UPG.TPS file to the existing clients with the next upgrade. You do not need to ship it to new clients, or to clients who have already received it once. Make sure that in your install, you set the installer to only install the UPG.tps file if it is non-existent on the clients machine.

Forcing the position of the UPG file?

1. Option 1 is to have a common directory that all the users can access (although this isn't always possible with an SQL backend).
2. Option 2 (if your user's exes don't all have access to a common directory) is to assign an "always install from this machine" that keeps a local copy of the upg.tps file that it references - and then run the conversion application from the installer.
3. Option 3 (if you don't have the ability to restrict which pc the user installs on) - if every installed copy of the app runs every version - so even if each install maintains their own copy of the application, it doesn't matter who installs from where, because they all will have an up-to-date upg.tps file (albeit multiple copies of the upg.tps file).
4. Option 4 (if there's a possibility that they will run the update from a machine that did not install the last update - and has not run the exe since the last update) then you will need to ship a default upg.tps file with all the possible versions in - although this is definitely the worst possible option.

Some more details regarding the UPG.tps file For those that care:

Miscellaneous

Support for Multiple data sets

Very Large Dictionary Support

To add the VLDS:FM3 Init Code Template:

Screenshot:

How to handle a pre-existing Error 47

Option 1 - Undo the changes you made in the dictionary.

If you have a backup of the program in non-error 47 state, restore that version, and add FM3 to the program there. Alternatively, if you are aware of the changes you have made to the dictionary to cause the error 47, and it is easily undone, then do so. If you are unsure of the structure of the current TPS file on disk, use TopScan to view the file structure. E.g.: TopScan File > File Layout.

Option 2 - Manually create a conversion program.

Using the before and after file structures, you can manually create a conversion program in Clarion.

SQL (for FM3 users)

Adding the Connect procedure

AutoBUILD

Who should implement AutoBUILD?

Description

Runtime File Management functions described

Some additional guidelines:

Implementation

Adding AutoBUILD to your application

Adding AutoBUILD to your Multi-DLL application

Distribution

AutoFIX

Who should implement AutoFIX?

Description

Implementation

Adding AutoFIX to your application

Recommendations

Distribution

AutoNET

• Who should implement AutoNET?
• Description
• Implementation
• Distribution
• Troubleshooting and Debugging
• AutoNET.log
• Translation for AutoNet

Having problems getting AutoNET to work? Check out the AutoNET TroubleShooting Section of these docs.

AutoNet and Vista: Because AutoNet is copying program files (like EXEs and DLLs) from a source directory to (generally) the Program Files directory, it requires administrative privileges to perform this task. If your users cannot run as administrators, then you will not be able to use AutoNet as an automatic program updater.

Who should implement AutoNET?

Description

Implementation

*Definition: "The logged in user's temporary directory"

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

Notes

Note: When using AutoNet in a Terminal Services environment, you need to use with caution. The AutoNet.log file is created in a created user Windows directory. The windows directory (used by Terminal Services) is a sub-directory within the Terminal Server User's directory (C:\Documents and Settings\<LoggedInUser>\Windows). You need to resolve the AutoNet.log file that is located in that directory. Note: If the autonet section in the original INI file gets changed, than you will need to delete the ini file from the User's Terminal Services directory so that a new one can be copied from the master directory.

Distribution

AutoNet makes use of the included AutoNET.exe program found in your Clarion\3rdparty\bin directory.

This must be installed into your application directory when you install your application.

Note: The source of AutoNet exe is shipped as a project file with FM3. This means that you can edit the manifest file to reflect your company in the trusted chain of applications (rather than CapeSoft). To do this, you can edit the autonet.exe.manifest file, and recompile the alu.prj project and distribute the resultant autonet.exe file rather than the one included in the FM3 install.

Troubleshooting and Debugging

If your application is not being updated, then check:

1. that the AutoNET.exe utility is in the same directory as your exe on that machine.
2. that the machine has read/access rights to the directory that it is trying to copy from. Open your AutoNET.log file, and a DOS command prompt. Use the COPY command to attempt a DOS copy from the NetPath to the LocalPath. If the files are not copied, then you need to set the access rights of that machine.
3.  If you are running Vista  or above, check that your user is able to elevate to Administrative privileges (see AutoNet and Vista for details).

If you are unable to solve the problem you're experiencing, send this log file to CapeSoft Support. Please read the Support and Debugging section for details.

AutoNET.log

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

Translation for AutoNet

Currently AutoNet uses the FM2.ini file inside the directory where the AutoNet exe resides to translate the window text that it displays. The following code is used to get the translation text:

mess1 = getini('AutoNet','M1','Upgrading program files from the network...','.\fm2.ini')
mess2 = getini('AutoNet','M2','Please be patient....','.\fm2.ini')
mess3 = getini('AutoNet','M3','Initializing :','.\fm2.ini')
mess4 = getini('AutoNet','M4','Copying :','.\fm2.ini')

So adding translation simply means creating an ini file that will contain the text above in the following INI file type format:

[AutoNet]
M1=Upgrading program files from the network...
M2=Please be patient....
M3=Initializing :
M4=Copying :

Hot Tips

Using BLOB's in FM3 enabled applications in Clarion5
Use BDE to help convert your dictionary to SQL
Use Multi-Proj's Driver Substitution features to build multi-driver support into your app.

Using BLOB's in FM3 enabled applications in Clarion 5

Note: Clarion5.5 and up - BLOBs are supported (but not yet in converting from TPS to SQL).

Code Example
		MyParentFile file,driver('TopSpeed'),pre(MPF) PK_MyParentFile key(IDCol),primary,nocase FK_MyBlobFile key(MyBlobID),nocase! Relates to MyBlobFile record record IDCol long EmailAddress string(30) MyBlobID long   end   end     MyBlobFile file,driver('TopSpeed'),pre(MBF)! FM3IGNORE User Option PK_MyBlobFile key(IDCol),primary,nocase BlobField blob record record IDCol long   end   end

I've got a BLOB in my table, but want to move over to the correct method of handling BLOBs (only for Clarion 5 users)

Use BDE to help convert your dictionary to SQL

Use Multi-Proj's Driver Substitution features to build multi-driver support into your app.

Helpful Utilities

CScan

Description

Screenshot:

Note: If you're getting an Error 47 when attempting to browse a file, then it probably means that your file declaration does not match that of the UPG.tps file. This is normally due to either a restored backup (without the UPG.tps file being restored as well) - or a data file that has been converted by the dictionary convertor instead of ensuring that conversion is only handled by FM3.

Formatting

Note: Because CScan saves the format of your layout as you set it up, this can cause problems in the future - particularly if you hide columns or alter column orders. If the file browse gets completely out of hand, you can modify the c-scan.ini file in the windows directory manually to tweak the fields displayed, and the order in which they are displayed.

Security

Searching (and Replacing)

Distribution

Btrieve

UPGView

Description

ScreenShot:

Print File Layout

Analyse File Changes

ScreenShot:

Distribution

Bulk Dictionary Editor (BDE)

Errors - Runtime, Compiler, Program GPFs or Hangs

 Compiler Errors

C7 specific compile errors

• Assertion failed on line: 303 in file abfile.clw. Message: You are calling CLOSE(thefile) instead of FileManager.close(). Shall I GPF?
• Compile Error: Link Error: Too many segdef in file Error(6): cif$fileclose The handle is invalid.
• Duplicate Identifier: &Workfile
• Duplicate symbol: CloseODBCPerfData and others.
• Duplicate symbol: $GLO:<FileName>_Name for all my files.
• FM3 warning: '<FieldName>' has a non-unique external name. Invalid in '<FileName>' of driver: <FileDriver>.
• FM3 warning: '<FieldName>' of type '<FieldType>' is invalid in '<FileName>' of driver: <FileDriver>.
• FM3 warning: You have more than one key in your dictionary with the same external name: <KeyName>. Files: <File1>, <File2> Driver: <FileDriver>
• Error Occurred: 37000 [Microsoft][ODBC SQL Server Driver][SQL Server]Zeile 1: Failed Syntax in the File
• Link Error: DS_FILEOPEN is unresolved in file c:\Clarion5\xxxxxxxxx.OBJ (Repeated for a number of functions)
• Link Error: Duplicate symbol: SQLxxxxxxxxxx, file FM2.OBJ (Repeated for a number of functions)
• Parameter type label ambiguous
• Syntax error: Unknown identifier: GLO:<FileName>_NAME
• Syntax error: Unknown Identifier: WorkFile and\or WorkFileName in my SQLConnect or RuntimeFileManager windows.
• Unknown Procedure Label error on the line that calls the RuntimeFileManager
• Unknown variable '%NoFm2'
• Unknown variable errors in the RuntimeFileManager window
• Unresolved External ds_FILEOPEN in xxxxxx.obj
• Unresolved External, ds_SomeFunction
• You have 2 files which will be named the same (<filename>.tps): <table1> and <table2>

Program GPFs or Hangs

General FM3 Errors

• M1: Possible file change without changing File Version number. File involved : <filename>
• M2: Unable to Open UPG file : cause <error>
• M3: Unable to upgrade file which doesn't have a prefix : <filename>
• M4: Unable to Upgrade - Not "Using" File <file prefix>
• M5: Unable to upgrade file - no file name available
• M6: Unable to upgrade file - Error creating destination file <error>
• M7: Unable to upgrade file - Error reading source file <error>
• M8: Error Writing destination file <error>
• M10: Warning - Driver not located - GPF likelyCapeSoft ...
• M11: Unable to open file. Errorcode 90 received. Are you sure your Connection details are correct?
• M13: Memo file missing
• M14: Internal File Format Too Large. File : <FileName>
• M15: Unable to upgrade. Access to the existing file has been denied
• M16: File has no prefix
• M17: Data file is invalid
• M19: File Corrupt. Restart program to invoke AutoFIX. Name : <FileName>
• Can't fix Encrypted files

SQL Specific FM3 Errors

• M20: Error: No connection string found for this file: <FileName>
• M21: Error: File not in Manageable Zone!
• M22: Error Creating / Opening FM3 System File: <FileName>
• M23: Error getting IncomingVersionQ:
• M24: Error occurred inserting/updating FM3 System file:
• M26: Error occurred executing SQL Statement: <SQLStatement>
• M27: Unrecognised Datatype: <DatatType>
• M28: WARNING: This table already contains an IDENTITY FIELD : <TableName>
  Ensure there is a maximum of 1 per file.
• M29: Could not create Oracle TableSpace! <FileError>
  Press Ignore to create the table in the default tablespace.
• M30: FM3 encountered errors during file structure upgrade.
  Please review the "Debugging" and "Support" sections in the FM3 Documentation,
  or contact your application vendor for technical support!
• M32: SQL WARNING ABOVE - take note!
• M33: FM3 File error on final open:<filename> : <driver> <error>
  Please ensure you have the FireBird Client DLL installed on your workstation: gds32.dll.
• M34: Unable to interpret SQL structure: [columns] Error: <FileError>
• M35: Could not configure your SQL Server as a Linked Server! FM3 cannot manage this file! Error: <error>
• M36: Could not configure SQL Server for DATA ACCESS! FM3 cannot manage this file! Error: <error>
• M38: Could not locate key field: <FieldName>
• M39: Could not reconnect ASA: <Reason>
• M43: Attempted using an Invalid field type for creating a unique index/constraint <IndexName>
• M44: Attempted creating an index/constraint greater than the permitted size <IndexName>
• M48: Attempting to create a key with a reserved keyname: <KeyName>
• M49: Attempting an illegal field type conversion. Field: <FieldName>

SQL Related Errors

• WARNING: FM3 detects this application contains older file structures than the current backend version. Please upgrade your Program. FM3 suggests implementing AutoNET for automatic program file upgrades across networks! Ending Program!
• Error locating the Database name for this file: <FileName>
  Owner string searched: <FileOwner>
• File Manager 3 does not currently support this Database through ODBC: <DataBase> Alternatively, please check that you entered the database backend correctly on the ConnectToSQLBackend Extension Template. Ending Program!
• FM3 could not find the specified database (<DataBaseName>) in the backend!
• Unable to open FM3 System table: <gSQLFileName> Error posted: <Error>.
• FM3 has detected a SREAL datatype in your Clarion Dictionary. Oracle does NOT support this datatype.
  Please update your dictionary definition to datatype REAL. FM3 cannot manage this file!
• FM3 has detected an INVALID datatype in your Clarion Dictionary.
  FM3 does not support this datatype: <DataType>
  Please update your dicitonary definition. FM3 cannot manage this file!
• S1000: Connection is busy with results for another hstmt, t: M26, l: 0
• Driver Error (1): (10) ODBC.DLL Could Not Be Loaded

Runtime Errors Related to FM3

• Untrappable runtime error - program crashes at startup (during FM2/3 launching)
• I've added FM3 to my IPDriven application, and now I get a Memory Block free'd twice error?
• My program starts with the "Unable to open MDI window (No application active) message"
• File could not be opened. Error: Invalid Filename (45). Press OK to end this application.

Translating FM3 Error Messages

Compiler Errors
	Error:	Assertion failed on line: 303 in file abfile.clw. Message: You are calling CLOSE(thefile) instead of FileManager.close(). Shall I GPF?
	Cause:	ABC is doing a rather over-enthusiastic check of the CLOSE() statement, initially useful when converting your Clarion / Legacy code to ABC.
	Reason:	FM3 does not use ABC code, so the ABC File Manager is complaining.
	Solution:	You can safely click on No, then there are 2 ways to eliminate these errors: Go to your Project Properties and turn off debugging by "Building Release System", or setting Debug mode to "Off". Edit the ABFILE.clw. (Comment out the assert on that particular line in the abfile.clw - which is found in your Clarionx\libsrc directory). If you want GPFReporter and FM3 to co-exist, then you need to do this.

	Error:	Compile Error: Link Error: Too many segdef in file Error(6): cif$fileclose The handle is invalid.
	Cause:	The main program module is too big for the compiler.
	Reason:	You're possibly using FM3 on a very large dictionary with lots of aliases and FM3 user options. This causes FM3 to generate a lot of initialisation code.
	Solution:	Use the Very Large Dictionary Support Code template to split the FM3 initialisation code between multiple modules. ...to be continued...

	Error:	Error Occurred: 37000 [Microsoft][ODBC SQL Server Driver][SQL Server]Zeile 1: Failed Syntax in the File
	Cause:	The Compiler is trying to use a file driver that is not compiled in.
	Reason:	There is no project define including the file driver into your application.
	Solution:	Add the MSSDRV (or other depending on which compile flag you're using) to the Project defines.

	Error:	FM3 warning: '<FieldName>' has a non-unique external name. Invalid in '<FileName>' of driver: <FileDriver>.
	Cause:	You have more than 1 field in a file with the same External Name.
	Reason:	SQL requires a unique field name for each field in a table. If you have not uniquely assigned an external label for each field, this will cause a GPF in the conversion of the table.
	Solution:	Go to the dictionary, and ensure all fields have unique External Names across the file.

	Error:	FM3 warning: '<FieldName>' of type '<FieldType>' is invalid in '<FileName>' of driver: <FileDriver>.
	Cause:	You file declaration is using a datatype that is not allowed with the specified driver.
	Reason:	Usually when changing the file driver in the dictionary, the IDE will warn you to change any invalid datatypes, but if you used BDE, there may be a MEMO left behind which is not SQL compatible.
	Solution:	If you are manually editing your dictionary then you should never see this message, however if you have used a 3rdparty tool to convert your dictionary to a different driver, then you may have some field types that are invalid for the new file driver. The compiler simply warns you of an invalid data type for the new file driver. If you continue compiling you will probably get an Error 47 when FM3 tries to convert the file. If the type is blank, then you probably had MEMOs which BDE was unable to convert to CSTRINGs (for SQL) and are now of type blank in the dictionary. You need to set each MEMO to a CSTRING in the dictionary.

	Error:	FM3 warning: Group 'PRE:MyGroup' has an external name. Invalid in 'MyFile' of driver: MyFileDriver
		External group names were always overlooked by the compiler until recently. If you have a external group name, this will now cause a GPF in the file conversion process (in FM3). If you have a really good reason for an external group name, then ignore this assert - however you will probably experience a GPF in the file-conversion process.

	Error:	Link Error: DS_FILEOPEN is unresolved in file c:\Clarion5\xxxxxxxxx.OBJ (Repeated for a number of functions)
	Cause:	The FM3 lib is not being linked into the project
	Reason:	You're probably compiling in 16 bit mode - or else you have removed the FM3 template from the application.
	Solution:	Change your project to 32 bit mode. FM3 only supports 32 bit applications. OR (if you have removed FM3 from the application) remove the FM2=>1 from the project defines in the project.

	Error:	Link Error: Duplicate symbol: SQLxxxxxxxxxx, file FM2.OBJ (Repeated for a number of functions)
	Cause:	Two products are declaring the same procedure
	Reason:	You're using an old version of Fomin Report Builder.
	Solution:	Download the latest version of Fomin Report Builder from their website - and include the 'Compatibility with MAV and other ODBC templates' global template in your application.

	Error:	Syntax error: Unknown identifier: GLO:<FileName>_NAME
	Cause:	FM3 uses a variable name for each filename. This filename is set for each table when you upgrade your dictionary using BDE. Either you have not used BDE to do the conversion to SQL (in which case the filename is not set to use the variable) - or else you have the 'Generate File Declarations in Modules'  checkbox (in the Global Properties - file tab) checked
	Solution:	Make sure that the 'Generate File Declarations in Modules'  checkbox (in the Global Properties - file tab) is unchecked. You need to check the 'Generate all file declarations' checkbox on the FileControl tab of your application's Global Properties. If you're using Multi-Proj's Driver Substitution feature? If so, you need to make sure that the Conditional Compile Switch in the SQL_Connect procedure matches what you've set it in the Multi-Proj driver substitution settings. For example (using ODBC driver): 1. In the Connect to SQL Backend Controls control template in the SQL_Connect window, set the ODBC Driver Conditional Compile Switch to UseMySQL. 2. In your MultiProj extension (the one with Enable Driver Substitution checked) - in your Override Driver Possibilities button list (immediately below the Enable Driver Substitution checkbox on the Resources tab), make sure that your Conditional Define of the Topspeed to ODBC is set to UseMySQL. 3. On your Versions tab of the same Multi-Proj Extension instance, you should have a version to create a project for the ODBC version of your program, lets call it ODBCPrj. In there (on the defines tab) you should have an entry: UseMySQL=>1, and on the FileDrivers tab you should have at least the ODBC and the ASCII file drivers listed (you'll need any others as well if you've used the file drivers that won't be substituted in the other project.

	Error:	Unresolved External ds_FILEOPEN in xxxxxx.obj
	Cause:	FM3 has been removed from the application, but the project define is still set to 1.
	Solution:	Remove the FM2=>1 from the project defines in your application's project.

	Error:	Unresolved External, ds_SomeFunction
	Cause:	You have an old copy of the lib file on your hard drive.
	Solution:	Check the project to see which FM3 lib is being linked into your program, and then search your drive for that lib.

	Error:	Parameter type label ambiguous
		In Clarion 4 and above, the old File Manager procedure has to be renamed to RuntimeFileManager.

	Error:	Syntax Error: Unknown Procedure Label error on the line that calls the RuntimeFileManager
		Go to the Properties for the RuntimeFileManager Procedure, and make sure the Declare Globally option is on.

	Error:	Duplicate Identifier: &Workfile
		Go to the Global Data Button, and delete the variable &WorkFile from there.

	Error:	Unknown variable '%NoFm2'
		If you have converted your application from FM2 to FM3, you may not have changed the Runtime File Manager control template from FM2 to FM3. Open the Runtime File Manager window, delete one of the controls to delete the control template, and then add the FM3 File Manager Controls.

	Error:	Unknown variable errors in the RuntimeFileManager window
		If you have set your RuntimeFileManager to use all files in your dictionary, but you have not checked the 'Generate All Files' checkbox in the Global Properties (File tab).

	Error:	Unknown Identifier: WorkFile and\or WorkFileName in my SQLConnect or RuntimeFileManager windows.
		You've handcoded code using these two variables which changed in 3.78. Change the code to use the LocFMx:WorkFile and LocFMx:WorkFileName.

	Error:	'FM3 warning: You have more than one key in your dictionary with the same external name: <KeyName>. Files: <File1>, <File2> Driver: <FileDriver>
		Some SQL backends require that unique constraints have database-wide unique external names. FM3 will be therefore unable to add non-unique constraints to the SQL backend if there are duplicates in the dictionary, thus FM3 checks the dictionary for you to find non-unique external names. If you don't want FM3 to check the unique external key names, then you can add the following Dictionary user option: DisableUniqueKeyNameCheck (1)

	Error:	Duplicate symbol: CloseODBCPerfData and others.
		You have at least one other template that is trying to include the ODBC function library into your application. To prevent FM3 from linking this LIB file in, go to the SQL tab of your FM3 Global Extension template, and uncheck the 'Link in ODBC.LIB' checkbox. This will ensure that the ODBC LIB only gets included once into the template.

	Error:	Duplicate symbol:$GLO:<FileName>_Name for all my files.
		You need to uncheck the 'This is the Data-DLL' switch in the DLLs that are not the data-DLL (for DLL applications). If this is the EXE application of a Multi-DLL application, then you need to check the 'This is part of a Multi-DLL project'. This is only applicable to legacy applications - for Multi-DLL ABC applications, you only need to add the extension to the data DLL.

	Error:	You have 2 files which will be named the same (<filename>.tps): <table1> and <table2>
	Cause:	If you don't specify a filename for your tables, clarion will use (up to) the first 8 letters to name the file on disk (for TPS/flat files). If you have 2 files in your dct with the same first 8 letters - you'll get both tables using the same file. The second table to open the file will get an error 47 - because the structure is different. FM3 is warning you about this so you don't get to this place - and wonder why you're getting error 47.
	Solution:	Either specify a filename in the dct or you can add the NoAutoNameCheck file user option to one (or both) of the tables.

C7 specific compile errors

Clarion 7 has converted your c6 application erroneously. This is normally fairly easy to solve.

1. Close your application and the C7 IDE.
2. Open the folder wherein your application resides (using Windows Explorer).
3. Make a backup of the files in the folder.
4. Remove the <applicationname>.app, the <applicationname>.sln and the <applicationname>.cwproj.
5. Rename the <applicationname>.6app to <applicationname>.app.
6. Re-run the conversion.

Program GPFs or Hangs

• I've added FM3 to my program, and now it GPF's on close of the program?
• I've added FM3 to my program, and now I get a GPF on program startup, or when I access a file?
• FM3 connects to the SQL backend, but when it tries to upgrade datatables, it hangs - or it hangs while trying to connect to the backend
• My program hangs as it upgrades a table.
• My program hangs at the Connect window after I click the connect button.
• I am installing my FM3 enabled app on a Tablet 2005, and my app is hanging, or getting an error: unable to open upg.tps.
• I'm using Clarion 6, ABC multi-dll, and my application hangs on exit with the CPU running at 90%.

		I've added FM3 to my program, and now it GPF's on close of the program?
		You are upgrading / converting files on the main thread. This is causes a problem with the Clarion Threading issues. Ensure you are only opening FM3 managed files on new threads.

		I've added FM3 to my program, and now I get a GPF on program startup, or when I access a file?
		You have probably used a CString for the Owner or Full Path Name attributes in your Dictionary. Change these to Strings.

		FM3 connects to the SQL backend, but when it tries to upgrade datatables, it hangs - or it hangs while trying to connect to the backend
		Check that you have correctly named your server (that FM3 is connecting to the correct server). Sometimes the connection is a bit more forgiving than the upgrading, so if your server is MyServer\MyDB, and you enter it as \MyServer\MyDB it will connect, but will have problems upgrading the tables. If you're not sure, then run the application with the command parameter: /ShowConnectErrors and the error will be displayed. A logon window will also be displayed. Note: For MSSQL: If you are using SQL Authentication - then make sure that your server is setup for mixed-mode Authentication. If you are connecting from a remote machine, you may need to enable the Guest account. Also, make sure that your firewall/router is allowing/forwarding requests from the port that the connection is using. Note: For MSSQL on Vista (where the client is running on Vista): You need to tweak some of the connection settings from the command line prompt (at the client PC): netsh interface tcp set global rss=disabled netsh interface tcp set global autotuninglevel=disabled

		My program hangs as it upgrades a table.
		There's a couple of reasons that this could be occurring: 1. You are using Superfiles, and you are attempting a table upgrade (that's in the superfile) while another table in the same superfile is already open. FM3 requires exclusive (locked) read/write access to the file during conversion. The most simple work around is to convert all the tables on application startup - otherwise, you need to open and close each file (in case of upgrade) - before starting your procedures. 2. Due to an apparent known issue with the MDI Sync Templates, FM3 hangs during upgrade. To workaround this, you can switch off this template on the local procedure you're using to upgrade the file. ie, go to the procedure extensions, and check the Disable MDI Synchronisation. Alternatively, add AutoBUILD - FM3's RuntimeFileManager Control Template, and this should convert your files without a problem.

		My program hangs at the Connect window after I click the connect button.
		There's a couple of reasons that this could be occurring: 1. You could have omitted to ensure that the Project Define was set for the driver(s) that you've selected in the AutoUp tab. Example: MSS_DRV=>1 Also checkout the following faq: FM3 connects to the SQL backend, but when it tries to upgrade datatables, it hangs - or it hangs while trying to connect to the backend

		I am installing my FM3 enabled app on a Tablet 2005, and my app is hanging, or getting an error: unable to open upg.tps.
		Some people have reported problems running new FM3 enabled apps on Tablet 2005 PC's. The workaround is to ship your development upg.tps.

		I'm using Clarion 6, ABC multi-dll, and my application hangs on exit with the CPU running at 90%.
		Due to a possible bug in Clarion 6, you need to add the FM3 Global Extension to your exe app as well as your data dll app. Make you sure you check on all the necessary driver support, but leave the Connect Procedure blank in the exe extension.

		My program GPFed - and now it GPFs on startup. If I rename the exe, it works for sometime but then starts GPFing like the first one.
		You are probably using TPS files - and one of the files has reached the 2Gigabyte limit. AutoFix is registering it as a corrupt file - and when the application runs, it goes to the RuntimeFileManager for you to "fix" the file, and GPFs on file open. You need to restore a backup of the file (from before it reached the 2G limit), and truncate the file - either by reducing the number and/or size of fields, or splitting the table into 2 - the new table being a child of the existing one.

General FM3 Errors
	Error:	Unable to identify driver - use ds_AddDriver driver to register drivers.
	Cause:	FM3 cannot identify the driver specified for the file it's attempting to manage.
	Reason:	The driver has not been registered in FM3 by a call to ds_AddDriver().
	Solution:	2 options: Go the Global Extension and ensure that all file drivers in your dictionary(past and present) are checked on. If handcoding, use the ds_AddDriver() function to register the driver in FM3. See the Technical Reference for details. ...to be continued...

	Error:	Unable to Upgrade - Not "Using" File <file prefix>
	Cause:	The file has not been registered with FM3.
	Reason:	Possibly a wrong implementation of FM3 for your application (Multi-DLL).
	Solution:	Check the implementation for your setup in the AutoUP section.

	Error:	Possible file change without changing File Version number. File involved : <filename>
	Cause:	FM3 has detected a difference between the file structure being used, and the file structure stored by FM3 for that version number.
	Reason:	You've made changes in the dictionary, and forgotten to increment the version number for the file.
	Solution:	FM3 can upgrade the file if necessary, but you will not be able to upgrade again unless you fix the error by performing the following step without changing the structure. Go the dictionary, and increment the version number for this file. Then recompile. If you still get this error, then probably the best thing is to use UPGViewer to check the version numbers for that table inside the UPG.tps file. That will show you what the last version number for that (those) files is inside the UPG.tps file. You need to set the version number to the last version number +1 (in the dct). For more info, see How to make basic file structure changes.

	Error:	Unable to Open UPG file : cause <error>
	Cause:	FM3 is unable to open it's own data file (upg.tps).
		If the errorcode is 3, then the most likely reason is that the path specified for the upg.tps file does not exist. If you specified the upg.tps path using ds_SetUPGPath(), then check that the path is valid and accessible.
		If the errorcode is 5 (Access denied) then there's 2 things I'd check _very_ carefully. a) open a dos prompt. c: cd "\Program Files\iCollecttrains"  be _very_ careful that you spell it _exactly_ as the error describes it. I know, I know. the folder is there. I've lost count of the folks who've assured me the folder is there, but the above test fails. hmm dang client has decided to move something - or something is misspelled or whatever. b) assuming that test is ok, and the folder does exist. now type notepad test.txt notepad (should) open - in the file write hello, and save and exit notepad. type notepad test.txt file still there? contains the word hello? This is the second most common reason for access denied. Some sort of access restriction by the server that prevents files being opened in create / write mode. Oh, and remember to do this test _on the machine that triggers the error_...
		If the errorcode is 90, then it probably means that the file is corrupt. Your options are (in recommended order) a) restore a file from backup b) copy a upg.tps from your machine, or the machine of another client. c) rename upg.tps to upg.old (on their machine). If one TPS file is corrupt then chances are other may be too, so inspect your data carefully after the program starts running. At the very least go to your Runtime File Manager window, do a Tag-All, then "Info".

	Error:	Unable to upgrade file which doesn't have a prefix : <filename>
	Cause:	No File Prefix specified.
	Reason:	You have not specified a file prefix for this file in the dictionary. FM3 needs a file prefix for each file. Alternatively you may have handcoded a file into your application. FM3 replaces the Clarion open function with the FM3 - so all file opens proceed through it. If you have a table without a prefix, then FM3 is unable to determine whether the file is in the "Used File" list or not.
	Solution:	Go to the Dictionary and add a file prefix for the file (or add a pre(<Prefix>) if you're handcoding the file definition in your application/project).

	Error:	Unable to upgrade file - no file name available
	Cause:	FM3 cannot copy your data to a temporary file.
	Reason1:	FM3 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.. they already exist) you will get this error.
	Reason2:	Your data is on a different network machine, but the machine that you are running your application from does not have sufficient create/delete/read/write access rights/permissions.
	Solution1:	You probably have the "Don't remove old versions" check box checked on in the Global Extension. 2 steps: Uncheck the "Don't Remove old versions" checkbox on the Global Extension. Go to your data directory and delete, or move all the DSTMPxxx files.
	Solution2:	Check the permissions settings on the machine that houses the data for the user that accesses the data. Make sure that that user has file create, remove, read and write access all allowed.

	Error:	Unable to upgrade file - Error creating destination file <error>
	Cause:	The <error> above describes the cause.
	Reason:	FM3 could not create and open the destination data file.
	Solution:	The solution would depend on the <error>.

	Error:	Unable to upgrade file - Error opening destination file <error>
	Cause:	The <error> above describes the cause.
	Reason:	FM3 could not open the destination data file.
	Solution:	The solution would depend on the <error>.

	Error:	Unable to upgrade file - Error reading source file <error>
	Cause:	The <error> above describes the cause.
	Reason:	FM3 could not read the source data file.
	Solution:	The solution would depend on the <error>.

	Error:	Error Writing destination file <error>
	Cause:	The <error> above describes the cause.
	Reason:	FM3 experienced an error while writing the data out to the destination file.
	Solution:	The solution would depend on the <error>.

	Error:	Warning - Driver not located - GPF likely
	Cause:	FM3 is attempting to use a driver that has not been registered in FM3.
	Reason:	A structure exists in the upg.tps file which uses a driver that is not switched on in your app.
	Solution:	Go to the AutoUP tab on the Global Extension. Check on all drivers used in the app, both in the past and present. If you are using the Dynamic File Driver, then you will need to add the replacement driver as well (like 'MEMORY')

	Error:	WARNING: Possible downgrade...
	Cause:	FM3 has detected a possible Downgrade about to take place.
	Reason:	Either, you've used the /downgrade command line switch, or an AutoDowngrade on Clarion DAT files. See Downgrading Files for info. ...to be continued...
	Solution:	Click Ignore to continue with downgrade. Click Abort to abort the program immediately without downgrading.

Error: "File has no Prefix"

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. These variables must be primed before the file is opened. To be completely safe, prime them in the Program Setup embed priority < 3000.

Error: "The data file is Invalid"

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. These variables must be primed before the file is opened. To be completely safe, prime them in the Program Setup embed priority < 3000.

	Error:	File Corrupt. Restart program to invoke AutoFIX. Name : <FileName>
	Cause:	FM3 has detected a possible TPS File corruption.
	Reason:	<FileName> is corrupt. FM3 will call TPSFix when the program is restarted and attempt to fix the file.
	Solution:	Restart the program.

	Error:	Errorcode received on open: <error>
	Cause:	FM3 cannot open the file.
	Reason:	FM3 does not know how to automatically handle this error <error>.
	Solution:	You are highly unlikely to receive this error, as FM3 automatically handles most of the common File Open errorcodes. If you cannot fix the problem based on <error>: Send the details together with a debuglog to CapeSoft Support.

	Error:	Unable to Open MDI window.
	Cause:	The program is trying to open an MDI window before the frame exists, or when no frame exists.
	Reason:	FM3 initialises the RuntimeFileManager window before the frame opens when it has detected a possible file corruption.
	Solution:	Remove the MDI attribute from the RuntimeFileManager window.

	Error:	M13: Memo file missing
	Reason:	Some flatfile systems have a separate physical file for the memo contents. If this memofile is missing, then you will get this message.
	Solution:	Locate the missing memo file (restore from backup)

	Error:	M14: Internal File Format Too Large. File : <FileName>
	Reason:	FM3 interprets the file header memory space in order to glean information about file structures (that Clarion uses or requires). The memory required is larger than the maximum specification - this normally means that the file is corrupt.
	Solution:	Restore the file from backup.

	Error:	FM3: Unable to upgrade.  Access to the existing file has been denied
	Cause:	FM3 requires exclusive access to data files in order to upgrade them.
	Reason:	Another program has access to the data files (either another instance of your application)
	Solution:	Ensure that all users have quit the program before upgrading. You could make use of NetTalk's AutoCloseApps control template to do this.

	Error:	This record was changed by another station. Those changes will now be displayed. Use the Ditto Button or Ctrl+H to recall your changes
	Cause:	1. You're using MSSQL and are accessing the database from multiple instances of the application (or threads in the same application) 2. You are using PostgreSQL and upgraded from TPS.
	Solution:	1. Use the /MultipleActiveResultSets=true driver switch that you can add to the FM3 connect table (you need to do this in your FM3 global extension template). 2. See the Turning_off_the_CR/LF_conversion_(to_LF_only) section of the FM3SQL documentation.

Can't fix Encrypted files

Fixing encrypted files means that your encryption code is passed to TPSFix via a command line parameter. This means that your encryption code can be detected (and is therefore not secure). You can allow fixing of encrypted files (check the "Allow fixing of encrypted files" checkbox in the RunTimeFileManager control template) - but be aware that this will be exposing your encryption code.

Back to the top of the errors section

SQL Specific FM3 Errors 

M11: Unable to open file. Errorcode 90 received. Are you sure your Connection details are correct?

If you're getting a Errorcode 90 on a SQL file, then checkout the Connection Issues section of the SQL documentation.

If you get Errorcode 90 on a TPS file, then it means that either the file is encrypted (and the encryption code has changed - so FM3 can't read the file) - or the file is corrupted. In order to get the file error, run your application to output debug information and the fileerror and fileerrorcode will be output to a DebugViewer (see the Debugging & Support section for more information).

M21: Error: File not in Manageable Zone!

FM3 can only manage one database at a time. If the database name for a specific file does not match the current database, then FM3 will not be able to convert that database. You need to either:

1. Move the offending table to the database that will be managed.
2. Use the FM3IGNORE function to tell FM3 not to manage that file.

M22: Error Creating / Opening FM3 System File: <FileName>

FM3 could not create or open the FM3 system file that it requires in the database. Checkout the Connection Issues section of the SQL documentation.

M23: Error getting IncomingVersionQ:

FM3 is attempting to upgrade a file that has not been registered (using the ds_UsingFileEx function). This normally occurs if you've handcoded calls to the FM3 functions, but have omitted the call to the ds_UsingFileEx for one specific table.

M24: Error occurred inserting/updating FM3 System file:

FM3 uses a file it creates on the backend to keep track of changes that it has made to the database. This error will occur if FM3 attempts to insert (or modify) a record into the table. Depending on what the file error is, will depend on why the insert failed.

M26: Error occurred executing SQL Statement: <SQLStatement>

FM3 uses SQL syntax to modify data structures on the backend. This syntax is compiled at runtime in order to re-structure the backend. We have endeavored to cater for as many exceptions as possible, but all the supported backends have different limitations and unique quirks. Occasionally, FM3 will therefore compile a statement based on changes to the dictionary, which cannot be performed on the backend (and which it does not detect as illegal). Let us know about these exceptions and we will build in a check for that specific condition before the SQL statement is compiled.

M27: Unrecognised Datatype: <DatatType>

FM3's query to the SQL backend has returned a datatype for a field that it does not know about. Please inform: support at capesoft dot com , and we will endeavour to support that field type (so long as it can be matched to a Clarion datatype).

M32: SQL WARNING ABOVE - take note!

A non-fatal error occurred when FM3 performed some file structure changes on the backend. This will be displayed in the logfile.

M38: Could not locate key field: <FieldName>

A component of the index\constraint could not be located in the list of fields from the database. The database is corrupt and needs to be repaired.

M39: Could not reconnect ASA: <Reason>

Clarion sometimes loses the connection to the Sybase database, and needs to be re-established (when maintaining files). Sometimes this connection cannot be re-established again.

M43: Attempted using an Invalid field type for creating a unique index/constraint.

A field in the key is being converted to a datatype on the backend that cannot be used in an index\constraint. You need to either:

1. Force the datatype to a datatype that the backend will support as a component of keys (use ForceSQLDataType for this).
2. Remove that particular field from the key's components.
3. Shorten the field (in some cases (like MySQL) - a maximum CSTRING size is 256, so anything greater than this will be converted to a text datatype, which is not legal in a constraint)

M44: Attempted creating an index/constraint greater than the permitted size <IndexName>

Some backends do not permit the fields used in an index to have more than a certain amount of characters (particularly large strings). If you get this message, then you need to either:

1. remove the key from the dictionary,
2. remove certain fields from the key's components,
3. remove the attribute that is forcing the key to be populated on the backend (either the DCTMasterOfKeys or Unique key).
4. Use a different backend (MySQL < 5 is particularly prone to large keys).

M48: Attempting to create a key with a reserved keyname: <KeyName>

You have used a label for your key that is not permitted on the SQL backend that you are using. The best is to change the External name of the key in the dictionary. Generally a good idea is to use: file-prefix underscore and keyname in the external key name.

M49: Attempting an illegal field type conversion. Field: <FieldName> <FromType> - <ToType>

FM3 is trying to convert a datatype on the backend, and this field cannot be converted to the type that it needs to convert it to. This normally occurs when there is a pre-existing database - and now you've added FM3 to your application to manage the database. If the field is correctly typed in the database, then you need to use the ForceSQLDataType feature to force the field to the unconventional datatype. Otherwise, you need to delete the field from the database.

An Example:

You have imported your tables into your dictionary from an SQL Server. You have a variable type of text in the SQL Server. After importing, the variable type used is a BLOB. FM3 will try and convert this field to an image (which is the variable type normally used for a BLOB) which is an illegal type conversion in SQL Server. To prevent FM3 from attempting to convert this field you can either:

1. Use the ForceSQLDataType feature to force FM3 to use a text type character

2. Redefine the variable type in the dictionary as a string or cstring of > 8000 (which will make FM3 use a text type variable on the backend). You will need to ensure that the string/cstring has sufficient characters to handle the data handling in Clarion, as this will be the size of the buffer allocated to the variable in Clarion (even although there SQL data is virtually unlimited on the Server side).

SQL Related FM3 Errors
	Error:	(M20) FM3 cannot detect any connection properties for this file: <FileName>
	Cause:	FM3 cannot connect to the database for <FileName>. Checkout the Connection Issues section of the SQL documentation.

	Error:	WARNING: FM3 detects this application contains older file structures than the current backend version. Please upgrade your Program. FM3 suggests implementing AutoNET for automatic program file upgrades across networks! Ending Program!
	Cause:	The application's file definitions are out of date or old - or you've imported the structures from your db to your dct.
	Reason:	Possibly another site has a newer version of the exe which has already updated the SQL Backend, but this exe has older file definition versions.
	Solution:	Use AutoNET to implement automatic program file updates across networks. Alternatively, manually ensure your exe is up to date. If you're still not coming right, delete the gMSSQLFile (or gODBCFile if using ODBC) from the backend. This will be re-created by FM3 again.

	Error:	Error locating the Database name for this file: <FileName> Owner string searched: <FileOwner>
	Cause:	FM3 cannot locate a Database to connect to for <FileName>. Checkout the Connection Issues section of the SQL documentation.

	Error:	File Manager 3 does not currently support this Database through ODBC: <DataBase> Alternatively, please check that you entered the database backend correctly on the ConnectToSQLBackend Extension Template. Ending Program!
	Cause:	FM3 does not recognise this backend <DataBase>.
	Reason:	Either you have misspelled <DataBase> or it is currently not supported by FM3.
	Solution:	Ensure you have typed it correctly as shown in the ConnectToSQLBackend Extension Template Notes. Alternativly, if this database is indeed not supported, disable FM3.

	Error:	FM3 could not find the specified database (<DataBaseName>) in the backend!
	Cause:	FM3 cannot connect to the Database specified in <DataBaseName>. Checkout the Connection Issues section of the SQL documentation.

	Error:	Unable to open FM3 System table: <gSQLFileName> Error posted: <Error>.
	Cause:	FM3 cannot open the required FM3 system table: <gSQLFileName>.
	Reason:	An error occurred: <Error>.
	Solution:	If you cannot solve the problem based on the error, send a Debuglog to CapeSoft Support. See the Debugging section.

	Error:	Unable to interpret SQL structure: [columns] Error: <FileError>
	Cause:	An error occurred when FM3 attempted to retrieve the current SQL file structure.
	Reason:	<FileError> should give you the reason.
	Solution:	Check User Access Rights. Check that the SQL Server is online. If you are unable to determine the problem, send a Debuglog to CapeSoft Support. See the Debugging section.

	Error:	Could not create Oracle TableSpace! <FileError> Press Ignore to create the table in the default tablespace.
	Cause:	An error occurred during creation of a the specified Oracle TableSpace.
	Reason:	<FileError> should give you the reason.
	Solution:	If you would like FM3 to continue and create the table in the default TableSpace: Click Ignore. If you would like to fix the error, and not continue to create the table at this point: Click Abort. Make the relevent changes to eliminate the error. If you are unable to determine the problem, send a Debuglog to CapeSoft Support. See the Debugging section.

	Error:	WARNING: This table already contains an IDENTITY FIELD : <TableName> Ensure there is a maximum of 1 per file.
	Cause:	FM3 cannot create the identity field.
	Reason:	FM3 detects more than 1 identity field specified for this table: <TableName>.
	Solution:	Go to the dictionary and ensure that you have only specified 1 field in the file as an Identity Column.

	Error:	FM3 has detected a SREAL datatype in your Clarion Dictionary. Oracle does NOT support this datatype. Please update your dictionary definition to datatype REAL. FM3 cannot manage this file!
	Cause:	FM3 warns you of un-manageable datatype.
	Reason:	You have declared a field of SREAL datatype in an Oracle driven table.
	Solution:	Go to the dictionary and change it to a REAL, or some other supported datatype for this driver.

	Error:	FM3 has detected an INVALID datatype in your Clarion Dictionary. FM3 does not support this datatype: <DataType> Please update your dictionary definition. FM3 cannot manage this file!
	Cause:	FM3 warns you of un-manageable datatype.
	Reason:	Not all Clarion datatypes are supported by the various SQL drivers. FM3 supports what the driver can handle, and in some cases more!
	Solution:	Go to the dictionary and change <DataType> to a supported datatype for this driver.

	Error:	FM3 encountered errors during file structure upgrade. Please review the "Debugging" and "Support" sections in the FM3 Documentation, or contact your application vendor for technical support!
	Cause:	1 or more errors occurred during FM3's upgrade process.
	Reason:	The reason would depend on the errors.
	Solution:	Run a Debuglog of the behaviour. See the Debugging section. Analyse the errors yourself, and fix the problem if possible. If you are unable to determine the problem, send the Debuglog to CapeSoft Support.

	Error:	Could not configure your SQL Server as a Linked Server! FM3 cannot manage this file! Error: <error>
	Cause:	Executing Microsoft Stored Procedure (sp_addlinkedserver) returned an error.
	Reason:	Most likely related to user permissions. <error> should give you more details.
	Solution:	Ensure the user has the required permissions and roles for FM3 to function properly (Check the FM3SQL docs - The SQL Database for details) Read the Microsft SQL Server Books Online for information on the stated <error>. Ask your Microsoft SQL Server DBA to configure your server to be a linked server, and set DATA ACCESS to true. If you are running SQL Server Express, then your server name needs to include the computer name that the Server is running on: Computer_Name\Instance instead of just Instance or localhost\Instance.

	Error:	Could not configure SQL Server for DATA ACCESS! FM3 cannot manage this file! Error: <error>
	Cause:	Executing Microsoft Stored Procedure (sp_serveroption) returned an error.
	Reason:	Most likely related to user permissions. <error> should give you more details.
	Solution:	Ensure the user has the required permissions and roles for FM3 to function properly (Check the FM3SQL docs - The SQL Database for details) Read the Microsft SQL Server Books Online for information on the stated <error>. Ask your Microsoft SQL Server DBA to configure your server to be a linked server, and set DATA ACCESS to true.

	Error:	FM3 File error on final open:<filename> : <driver> <error> Please ensure you have the FireBird Client DLL installed on your workstation: gds32.dll.
	Cause:	Trying to open an FireBird table.
	Reason:	Most likely your workstation does not have the FireBird Client DLL installed: gds32.dll or <error> describes the problem.
	Solution:	Obtain the gds32.dll. (This is installed when you installed IBExpert www.ibexpert.com or copy from FireBird Server. Take action according to <error> described.

	Error:	S1000: Connection is busy with results for another hstmt, t: M26, l: 0
	Cause:	Multiple connections to SQL Server on the same thread.
	Solution:	Prop:BusyHandling = 2 Must be set on the file before any SQL file is opened - indeed this should be done before the connection to the backend is made. A good place to put this would be in the Program Setup before FM3 initializes (there's a place you can add this to the driver option string of the FM3 table used to connect to the backend in the fm3 template). You can also try using the MultipleActiveResultSets=TRUE option in the same place. Older versions of Clarion appear to have been more prone to this error, upgrade your Clarion (if you're not running the latest version).

	Error:	Driver Error (1): (10) ODBC.DLL Could Not Be Loaded
	Cause:	The ODBC driver is trying to load a specified database client driver that is not installed on this client machine.
	Solution:	Make sure that you've installed the correct ODBC driver on the client that FM3 requires. If you're installing PostgreSQL, check out the driver that you need in the Hot Tips section of the FM3 SQL Document Older versions of Clarion appear to have been more prone to this error, upgrade your Clarion (if you're not running the latest version).

	Error:	01000: OLE DB provider "SQLNCLI" for linked server "KB-SERVER\LTC" returned message "Login timeout expired"
	Cause:	The connection to the linked server is timing out.
	Solution:	Take a look at http://sqlserver2000.databases.aspfaq.com/how-do-i-prevent-linked-server-errors.html for possible solutions. Alternatively, google "Login timeout expired" SQL and see the results.

Runtime Errors Related to FM3...
	Error:	Untrappable runtime error - program crashes at startup (during FM2/3 launching)
	Cause:	Possible corrupt UPG.TPS file
	Reason:	UPG.tps is a tps file - and is also vulnerable to the weakness of the TPS driver. This means that very occasionally the UPG.tps gets corrupted (which I think is what happened to you).
	Solution:	You can minimise the damage by having a separate EXE to upgrade your tables - and run this on upgrade, rather than each instance of the application upgrading some tables as and when it uses them (although you may still want to leave FM2 installed in those apps in case someone runs it before the upgrade program kicks in - or without upgrading). The less applications writing to the UPG file at any given point in time the better.

	Error:	My program starts with the "Unable to open MDI window (No application active) message"
	Cause:	You have a corrupt data file and the application is trying to launch the RuntimFileManager window in MDI mode
	Solution:	You have 2 options (the first is preferable but may not be possible for an immediate solution): Make the RuntimeFileManager window not an MDI child. If you have a menu item for it then make sure the menu item is set to NOT call it on it's own thread. (i.e. you do not want to start a new thread when running the RuntimeFileManager window.) A temporary fix, assuming for some reason you can't recompile, is to edit the Win.Ini and remove the BadFile setting. This is an entry in the win.ini file that tells FM3 to run the RuntimeFilemanager and fix that file.

	Error:	I've added FM3 to my IPDriven application, and now I get a Memory Block free'd twice error?
		This is a known issue. Once adding FM3 to the IP_Server Dll, a Memory Block free'd twice error occurs on unloading of the dll. We are not certain of the cause, but this will only occur when you close the IP_Server Dll. The message will remain for about 20 seconds, and then disappear harmlessly. Further to this, you can set your IPREQ service to not allow interaction with the desktop. This will ensure the error is not visible.

	Error:	File   could not be opened. Error: Invalid Filename (45). Press OK to end this application.
		Normally this occurs because you are relying on FM3 to set the filename (in SQL applications) - but you've added the FM3Ignore property to that file. The best option is to set this in the dct, but you can also get FM3 to setup your filenames (for the FM3Ignored files) in the Connect window, by checking the 'Set filenames with the FM3Ignore user option' checkbox on the control template prompts.

Translating FM3 Error Messages

Also implement translation into the AutoNet windows: Translation for AutoNet

FAQ (Frequently Asked Questions)

If you're getting errors when converting to Clarion7, please check out the C7FAQs page on our website

Check out the Errors section for all queries on compile errors, runtime errors, GPFs and program hangs.

AutoNET Questions

• AutoNET does not seem to work?
• AutoNET give me an error saying the AutoNET.exe and File Manager are out of Sync?
• AutoNET isn't working in my Multi-DLL application - I have VLDS added as well.

Upgrading Questions

Please take note of the AutoUpLimitations section of this doc.

• I'm using AutoUp and still getting Error 47
• When is it a good idea to delete the upg.tps file?
• When is it ok to decrease the file version numbers in the dictionary?
• Does FM3 support programs that use Multiple Data Sets?
• Does FM3 support programs using different dictionaries, but sharing the same UPG file?
• I added FM3 to my application, but now it takes a long time to load?
• I ran CScan, but it prompts for a password. I tried the password you emailed me, but it does not work?
• I am having a problem with upgrading using an Alias file?
• I changed a field from decimal(13,3) to decimal(13,4). FM3 upgraded the file, but now the data values for that field have been divided by 10?
• FM3 upgrades my files perfectly, but I cannot see the name of the file displayed on the upgrade window?
• Is there any way to exclude a file from the AutoUP?
• Is there a variable I can check inside the trigger statements to make sure the triggers don't fire on an FM3 upgrade?
• How do I upgrade all my tables at startup?
• What do I do when adding FM3 to an IPDriver application?
• FM3 upgrades my tables, but my data is getting corrupted.
• How do I hide the upgrade window? Answer: Check the 'Hide the yellow upgrade window' checkbox on the FM3 global extension template.
• I was using Data Convertor templates, but want to move over to FM3. How do I handle existing clients? See the upgfile section of this document - particularly case 4.
• I'm changing a long to a decimal, but my data is all wrong after conversion.

SQL Specific FM3

• I'm getting FM3 SQL errors about a syntax error near the Keyword ... ?
• Only my Primary Key is being created on the SQL backend. Why aren't my other keys being created?
• I'm using DCTMasterKeys/DCTMasterFields but FM3 is not creating / dropping Keys off the SQL Backend?
• I am converting TPS to SQL. No error messages pop up, but my data is NOT converted to the new files?
• Does FM3 support the creation and maintenance of File Relationships on a SQL backend?
• If FM3 supports ODBC, why can't I use FM3 against any ODBC driven backend?
• Every time I run my app, FM3 "upgrades" my files even though no changes have been made. (ie, I see the little yellow progress bar window flashing up for 1 or more files.)
• The Connect window opens initially the app, if I select an item from my menu, the Connect window re-opens.
• I have a Decimal(18,0) (in my dictionary) that FM3 converts to a Decimal(19,0). Why is this?
• Why is it necessary for FM3 to create a linked Server on my SQL Server?
• Why can I not use the  /TURBOSQL property for my MSSQL tables in FM3?
• I cannot connect to my MSSQL database with the SQL Server name, but I can via the IP Address.
• Where should the upg.tps be located in the case of a SQL file server installation?
• FM3 does not create any of the tables on the backend except the gMSSQLFile.
• I'm converting my TPS data to Oracle (or Oracle Express) - but my unique indexes are not being added
• My application takes a long time to connect to the SQL Server (or doesn't connect).
• How do I enable /MultipleActiveResultSets or /BusyHandling (or other driver strings) when using FM3?
• Where should I put the upg.tps file when I have multiple users using my SQL exe?
• My AutoNumbered key is not AutoNumbering correctly.
• How do I use a different ForceSQLDataType for different backends that I'm supporting
• I get "Invalid character value for cast specification" when running my application.
• Do I have to change the Exclude Empty Key attribute on all the unique keys even if there are not the primary key?
• I have problems connecting to the database. What should I look for?
• I am using FM3 and Multi-Proj driver substitution. The SQL_Connect window pops up in my TPS app. Why?
• I'm using PostgreSQL, and when FM3 tries to upgrade a large table I get and "Out of memory while reading tuples.." message

Other Questions

• Where can I buy FM3?
• I bought FM2/3 some time ago, but want to upgrade. How much does it cost?
• How do I translate the FM3 windows and Error messages?
• What must I do to support Windows Vista?
• I don't use SQL - why should I upgrade from  FM2 to FM3?

AutoNET Questions

	GQ5:	AutoNET does not seem to work?
		This is probably because you have the ini file, containing the settings, in the wrong location. The default location is either the Windows directory, or the current users temp directory. See the AutoNET docs for details. Particularly the TroubleShooting and Debugging section.

	GQ10:	AutoNET give me an error saying the AutoNET.exe and File Manager are out of Sync?
		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.

	GQ27:	AutoNET isn't working in my Multi-DLL application - I have VLDS added as well.
		You need to setup AutoNet in your data DLL application as well as your main EXE for AutoNet to work in conjunction with VLDS.

Upgrading Questions

	GQ1:	I still get Error 47!?
		Check through the following list to determine the reason (If you have recently upgraded Clarion, or even ClarioNET, you will need to repeat step 2 of the following list.). FM3 Error 47 Check list: You have the CREATE file attribute turned on. You have definitely run the Support ABC Template Utility. You have definitely added the FM2 define to my Project Property Defines. You have not deleted or moved the upg.tps file. You added FM3, compiled and ran your program before making file structure changes. Check that you're not calling a procedure which accesses a file before FM3 initializes. To do this, run FM3 in debugmode, and see if your errorcode happens before any of the debug appears in the DebugView. Check that the old structure is matched in the upg.tps file. To do this: 1. Open your existing data file in C-Scan. If it does not open, then there is no matching file structure in the UPG.tps file. This means that the upg.tps file was either moved or deleted at some stage. You can open UPGView to see the various historical structures of that file contained in the UPG.tps file for that table. Basically, FM3 needs to find one of those structures that matches the one in the existing table in the UPG.tps file - otherwise it will not be able to open the file. Note: UPGViewer does not provide an exhaustive display of all the properties of the file header, so it appear to display exactly the same information as the file structure expected, but there may be slight nuances between the file header structure (as in the existing file) and that saved in the UPG file, which are not displayed in the UPGViewer. 2. If it does open successfully in C-Scan, then wizard an app with just that offending table, add FM3 to that application and see if the table converts successfully. 3. If that's successful, then there's something wrong in your program - either the datapath is incorrect, or it's using a different UPG.tps file (check for instances of the ds_SetUPGPath and ds_SetDataPath calls in your program). If you have changed the FilePrefix - check the rules for changing a FilePrefix. Occasionally calling a procedure in the OpenWindow event of a procedure may induce this behavior (the calling window is in modal mode during this event). You'll find that moving this code to the init method will resolve this. (MSSQL) If you are using a uniqueidentifier, then you need to use an external name when using the '| READONLY' attribute. Unfortunately, there's no way to rename the column after it is already added - so you will need to use the column name in the external name. (SQL) You are not making changes to the Primary key. Additional components, or altering the sort order, or any other change to the primary key is not permitted. If you are using hyperthreading and/or multi-cpus and you get the Error47 intermittently, then you should try binding your exe to a single cpu (google for assistance) If you are certain you have obeyed "The RULES", and the above check list, please send your app, dct, upg.tps, builtins.clw, and a Debuglog to CapeSoft Support detailing the steps taken.

	GQ2:	When is it a good idea to delete the upg.tps file?
		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?

	GQ3:	When is it ok to decrease the file version numbers in the dictionary?
		Never. Never. Never. Except if..... no, that's right, never....

	GQ8:	Does FM3 support programs that use Multiple Data Sets?
		For flatfile, yes, but for SQL databases, it can only manage one contiguous database connection. See Support for Multiple Data Sets

	GQ9:	Does FM3 support programs using different dictionaries, but sharing the same UPG file?
		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.

	GQ11:	I added FM3 to my application, but now it takes a long time to load?
		You may have made a call to ds_SetUPGPath after FM3 has initialised itself - in which case FM3 is loading twice. In order to eliminate the second load up make your call to ds_SetUPGPathbefore FM3 initializes. There is a Global embed point, called "FM3 : start of initialisation section", where you can do the call.

	GQ12:	I ran CScan, but it prompts for a password. I tried the password you emailed me, but it does not work?
		The password to C-Scan is SCAN. The password you were emailed is to extract the FM3 install file from the saf file using SafeReader, downloaded from our website.

	GQ13:	I am having a problem with upgrading using an Alias file?
		This can be a real funky problem, especially if the Alias was introduced well into the development cycle. From FM3'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.

	GQ15:	I changed a field from decimal(13,3) to decimal(13,4). FM3 upgraded the file, but now the data values for that field have been divided by 10?
		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. Go back to the dictionary. Set the decimal back to 13,3 BUT INCREMENT the file version number. Compile and run the application. Back to the Dict again. Change the decimal correctly this time. i.e. to 14,4. INCREMENT the file version number again. Compile and run the application.

	GQ23:	FM3 upgrades my files perfectly, but I cannot see the name of the file displayed on the upgrade window?
		Are you using Prop:LazyDisplay? This is be known to cause a problem with the name being displayed on the upgrade window.

	GQ25:	Is there any way to exclude a file from AutoUP?
		Yes, see the Ignoring a particular file section.

	GQ28:	Is there a variable I can check inside the trigger statements to make sure the triggers don't fire on an FM3 upgrade?
		What you need to do is create a pointer to a byte (in your global data) and then before FM3Initializes:       MyPointerToFM3Upgrading &= (ds_PassHandleForUpgrading())   Then you can use MyPointerToFM3Upgrading to detect whether FM3 is upgrading or not. In the trigger, it would be worth checking whether the pointer is null or not before using it.

	GQ29:	FM3 hangs when it tries to convert a superfile in my application.
		This is an oddity in the Clarion environment. You probably have a file (that's in the file) that is open already in another window. You can either: 1. Upgrade all the files at the startup of the application. 2. Run the application with the /silentupgrading command line parameter when running your program. The FM3 progress screens will not be displayed, but the conversion will occur without hanging the application.

	GQ30:	How do I upgrade all my tables at startup?
		On the Global Extension template, check the Force full upgrade on Startup checkbox. (Note: You must have added the RuntimeFileManager procedure to your application, and checked the Enable Auto Fix on the AutoFix tab of the FM3 Global Extension template in order to be able to do this). If you would like to place a condition around the full upgrade, then the place to do that is in the Global Embeds, using code around the 'FM3 - Do Fullupgrade on Startup. Place condition around this embed' embed point: If you need to do additional functionality (other than just upgrade the files - like build or pack) - then: on the RuntimeFileManager window, Goto the Info button, and find the End of Fullupgrade embed point. Make a source entry point immediately above that and enter: if ds_DoFullUpgrade()   post(event:accepted,?Build) end omit('****')  And after the End of FullUpgrade embed, enter the following: !****   In your embed point of the build button (after the FM - Handle Build button embed), enter: if ds_DoFullUpgrade(0)   post(event:accepted,?Done) end

	Q	FM3 upgrades my tables, but my data is getting corrupted.
		Check the following: 1. You don't have a dimensioned group in the file structure. FM3 does not support dimensioned groups. 2. That you're not changing a datatype which will invalidate data (for example a string based data type to a value based datatype). FM3 simply reads the data in binary and puts it straight into the new variable space. For example: You cannot convert a LONG (containing dates) to a DATE type. These are stored differently within the file. If you do this, your DATEs will contain invalid date data. 3. If you have OEM collation checked, then FM3 does not support changing file drivers with OEM collation turned on. Clarion uses different OEM algorithms to interpret the actual bytes returned from the files, so the same byte returned from  two files with different drivers will be interpreted as 2 different characters. 4. Clarion5 users: You don't have a BLOB in your TPS file structure. FM3 does not support BLOBs in flatfiles (in Clarion 5). 5. If you have triggers in your dictionary, these can affect the data migration to the upgraded tables. You need to turn the triggers off for the upgrade (you can use the ds_FM3Upgrading flag to determine if a upgrade is in process).

	Q	I'm changing a long to a decimal, but my data is all wrong after conversion.
		You must change the size of the variable storing the decimal - so you cannot convert to a Decimal 7,x or 6,x.

SQL Specific FAQ

	SQ3:	I'm getting FM3 SQL errors about a syntax error near the Keyword ... ?
		You have named a file, field, or key with a SQL Reserved Keyword. For more information, see your SQL documentation. BDE can bulk allocate all external names to include the file prefix (e.g.: PRE_Keyword).

	SQ4:	Only my Primary Key is being created on the SQL backend. Why aren't my other keys being created?
		Read the FM3 SQL Key Management section.

	SQ5:	I'm using DCTMasterKeys/DCTMasterFields but FM3 is not creating / dropping Keys off the SQL Backend?
		Read the FM3 SQL Key Management section.

	SQ6:	I am converting TPS to SQL. No error messages pop up, but my data is NOT converted to the new files?
		Check: 1. You have added the OldName property to your File User Options in the dictionary. If only some files are converted correctly, then this is most often the cause (that you may have omitted this on some of the tables). 2. FM3 is creating the tables in the SQL backend. FM3 must create the tables in order to transfer the data. If the tables exist already, then your data will not be transfered. 3. There is no error when upgrading (in this case check the FAQs for the error that you are experiencing) 4. You do not have the create attribute checked for that/those table(s) in the dictionary property. You must check the 'Enable Table Creation' checkbox checked. 5. Make sure that you've set the oldname to the correct attribute. If your data is not being ported across, it means that FM3 is not finding the old file - or else the table already exists on the backend. Make sure that you're setting your filenames immediately prior to FM3 init (and not after FM3 has initialised). Also, you need to have added FM3 to your application before doing the conversion. If not, you need to go back to your previous app and dct (before doing the conversion) - add FM3, compile and run your old application. For more info, see the Converting your app to SQL section. 6. Check that your SQL application is using the UPG.tps file that your tps application was using. If FM3 cannot find the file structure in the UPG.tps file that it needs to open the TPS files, then it will not convert these. If only some files are converted correctly, then this is most often the cause.

	SQ7:	Does FM3 support the creation and maintenance of File Relationships on a SQL backend?
		No. Not at this stage.

	SQ8:	If FM3 supports ODBC, why can't I use FM3 against any ODBC driven backend?
		Unfortunately, there is no SQL language standard. Each SQL Backend uses a slightly different dialect of SQL. Therefore, FM3 needs to be told exactly how to interpret structure of different backends, and execute the upgrade scripts. We have chosen at this stage not to rely on 3rdparty ODBC dlls, but we may well implement a generic ODBC engine at a later stage. Generally we implement support for new backends based on demand. The higher the demand, the sooner it will be added. Feel free to make your request - or use our prioritisation of features policy ( www.capesoft.com\support\policy.htm#Level2) to bump the implementation of your priority up the list.

	SQ13:	Every time I run my app, FM3 "upgrades" my files even though no changes have been made. (ie, I see the little yellow progress bar window flashing up for 1 or more files.)
		There could be a number of reasons for this: Are you running your program with the /goindeep commandline switch? If so, remove it. Have you turned on the "Full FM3 comparison" switch on the Connect Window? If so, uncheck it. It could be that for some reason, FM3 is unable to mark this file as managed, or update it's version in the FM3 SQL System table. Run a debuglog, and see if you can solve the problem, or send it to CapeSoft Support for analysis. If you have made a change in your dictionary that FM3 is unable to perform (because the change is not permitted by the SQL Server) - then FM3 will attempt to perform this change every time the file opens. Common errors: Making a change to your primary key (like adding a component column or changing a column's sort order in the key), changing an image based data type to a text based data type (or visa-versa) - changing a ROWGUID column's name.

	SQ15:	The Connect window opens initially the app, if I select an item from my menu, the Connect window re-opens.
		Checkout the Connection Issues section of the SQL documentation.

	SQ16:	I have a Decimal(18,0) (in my dictionary) that FM3 converts to a Decimal(19,0). Why is this?
		Clarion stores the Decimal size in odd number multiples. It thus sees a Decimal(18,0) (on the backend and dictionary) as a Decimal(19,0). FM3 will change a Decimal(18,0) to a Decimal(19,0) - even though the dictionary says it's Decimal(18,0). The runtime file properties that Clarion returns show it as a Decimal(19,0), therefore FM3 will detect this as a field type mismatch and perform the conversion.

	SQ17:	Why is it necessary for FM3 to create a linked Server on my SQL Server?
		FM3 requires a linked server to extract information about the existing table structures from the system tables of the database. In order to created a linked server, the user must have administration rights, otherwise FM3 will be unable to create a linked server and therefore be unable to read the system tables containing the table structure information.

	SQ18:	Why can I not use the /TURBOSQL property for my MSSQL tables in FM3?
		Normally (without /TURBOSQL=TRUE set) when opening a table in SQL, all the field properties of the table are returned. FM3 needs this information to verify that the file structure is correct.

	SQ19:	I cannot connect to my MSSQL database with the name, but I can via the IP Address.
		Checkout the Connection Issues section of the SQL documentation.

	SQ20:	Where should the upg.tps be located in the case of a SQL file server installation?
		Seeing that there is no common data directory - I'd go with putting in the appdata directory (for Vista compliancy). What is quite a common tack is to run a conversion application on installing (which would probably be done on a central location - fileserver or the like) - this upgrades all the datafiles on installation, so that at runtime, each user is able to run their application without any upgrades required. The UPG file then becomes superfluous to each individual instance of the application.

	SQ21:	FM3 does not create any of the tables on the backend except the gMSSQLFile.
		This is indicative that your owner string for your dct tables is set incorrectly. A couple of things that would cause this: 1. Duplicate variable declaration of the owner string (GLO:dbOwner defined in your application and your dct). 2. A different variable used in the owner property in the dct (or your Multi-Proj template if you're using Driver Substitution) to that set in the SQL_Connect window. 3. The SQL_Connect window called too late (this should not happen if you're using the template to call the window - but if you're calling it manually in code, then it needs to be called before FM3 initializes).

	SQ22:	I'm converting my TPS data to Oracle (or Oracle Express) - but my unique indexes are not being added.
		The most likely reason for this is that your Oracle server has been pre-configured to accept upper case names. If your external names use mixed case, then Oracle will not match the mixed case names to the upper case names in the database. If this is the case, then change your external names to uppercase (or if this is a Multi-Proj Driver Substitution application, then you can check this option in the File Driver options).

	SQ23:	My application takes a long time to connect to the SQL Server (or doesn't connect).
		There are a couple of possible for this: 1. If you have a SQL View(MS-SQL) declared and that does not have an Owner Name. Enter a owner. 2. If using Windows server software without Active Directory Services, you may need to add a static host record for your server manually (google this for help on your particular server and environment). 3. If you are connecting to a server that is not on the same PC as you application: Cehck that the server is allowing remote connections, also that the firewall is allowing access through the port that the SQL server is listening on.

	SQ24:	How do I enable /MultipleActiveResultSets or /BusyHandling (or other driver strings) when using FM3?
		MARS (and BusyHandling and some other driver options) - must be established at connect time. In other words, they must be set on the table that is used to make the connection to the db. If you are using FM3, then you can't set this in your dct (because any table that you are opening will already have an established connection to the db by that stage), you need to set it in the FM3 Global Extension template (on the AutoUp tab, there's a driver string entry field that you can enter what you want in the driver string). FM3 makes it's own table that it uses to connect to the database, which is why you need to add the driverstrings required for the _connection_ to the FM3 table in the Global Extension template.

	SQ25:	My AutoNumbered key is not AutoNumbering correctly.
		In SQL, AutoNumber is created on the field level, not the key level (like the Clarion dct). Take a look at Server side Auto-incrementing for details.

	SQ26:	How do I use a different ForceSQLDataType for different backends that I'm supporting?
		1. In your connect window extension template, equate the db that you're connecting to to a global variable (create a GLO:ThisODBCdb) in the 'GloVar For BackendType' prompt. 2. In your global embeds find the following embeds (see attached pic) for the field you need to change. 3. In the ForceSQLDataType - Before embed:       case GLO:ThisODBCdb     of  'MSSQL'          !One in the dct is set for MSSQL   4. In the ForceSQLDataType - Just After embed:         of 'ORACLE'       orof 'ORACLE EXPRESS'           ds_ForceSQLDataType('CON:MemoField','imageblob')       of 'MYODBC 2'       orof 'MYODBC 3'       orof 'MYODBC 5'       orof 'FIREBIRD'       orof 'POSTGRES'       orof 'ASA'           ds_ForceSQLDataType('CON:MemoField','text')              else        !Unknown ODBC type - don't force the datatype     end

	SQ27:	I get "Invalid character value for cast specification" when running my application.
		You are probably using the incorrect ODBC file driver for the backend that you are connecting to. For instance, in SQL Server 2008, you must use the SQL Server 2008 driver (not the generic SQL Server driver) if you are using dates and times.

	SQ28:	I have problems connecting to the database. What should I look for?
		If you have errorcode 90, on a straight connection, but  can connect using dsn, then it could very well be that you an instance of Zone Alarm has been installed, and is interfering with the connection.

	SQ29:	I am using FM3 and Multi-Proj driver substitution. The SQL_Connect window pops up in my TPS app. Why?
		You need to uncheck all the SQL driver checkboxes in the AutoUp tab of the FM3 global extension template.

	SQ30:	I'm using PostgreSQL, and when FM3 tries to upgrade a large table I get and "Out of memory while reading tuples.." message
		You need to add the following driver options to the table that connects to the backend (in this case the FM3 connect table): DeclareFetch=on You can do this in the AutoUp tab of the FM3 global extension template.

Other FAQ Contents

	OQ1:	Where can I buy FM3?
		Read the Purchasing section in this documentation.

	OQ2:	I bought FM2/3 some time ago, but want to upgrade. How much does it cost?
		Upgrades are currently FREE for FM3 users ...even across Clarion versions. Read more info in the Purchasing section. If you are still using FM2, you will need to purchase an upgrade from FM2 to FM3 (see the Purchasing section for details).

	OQ4:	What must I do to support Windows Vista?
		The best is to store your application data in the CommonAppData directory. Ideally you need WinEvent to return this so that you can set it correctly in your application on startup, otherwise you can use the windows API calls to return this location. In the "FM3 start of initialization" embed, you need to set your application data path: GLO:CommonAppData = LONGPATH( CLIP( ds_GetFolderPath( WE::CSIDL_COMMON_APPDATA ))) & '\<Company>\<Product>'   !You'll need WinEvent for this functionality ds_SetUPGPath( CLIP( GLO:CommonAppData ))  !Tell FM3 where to find our upgradable files SYSTEM{PROP:DataPath} = CLIP( GLO:CommonAppData )  !Set the datapath for all our common files

	OQ5:	I don't use SQL - why should I upgrade from FM2 to FM3?
		We are no longer implementing changes to FM2 - so any features added to FM3 will not be included in FM2. For example, TPS BLOBs are now supported in FM3, we've improved the renaming of temp files (so you hardly ever get the 'data disappearing' that occurred after a failed upgrade), FM3 does upgrading in multiple transactions - reducing memory usage, and other changes.

Debugging & Support

Support Request Check List

Debugging FM3

Example of using DebugView to monitor FM3 applications

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

	Run the DebugView program.
	Run your FM3 enabled program with 1 of the following command line parameters: /debugfmgpf- reports functions executed, useful for tracking down a GPF. /debugfm3- standard debug switch, reports functions executed and errors. (Recommended for your use) /debugfmall- reports everything. These files can be quite big. Use this when sending the DebugLog to CapeSoft Support. Syntax example: C:\AppDir><YourApp> /debugfmall
	You will see the DebugView logging as your program runs. Once complete, go File > Save As ... to save the log file.

DebugView Tips

	If you are unable to determine the cause for the error, and resolve it yourself, email the DebugLog to CapeSoft Support.
	You can set color highlights in DebugView to help make it easier to find specific entries. Edit > Filter/Highlight Filter 1 is red. Type in "Error" as in the example: You can set many other colors highlight conditions.
	You can set DebugView to Include or Exclude specific entries too. For example, there may be other applications outputting debug logging in between your FM3 log. You can get DebugView to only read FM3 logging by changing the "*" in the Include box to "[FM3]" as all FM3 logging is prepended with"[FM3]". This is recommended when sending large DebugLogs to FM3 Support. Please remember to reset it after you've completed your FM3 logging, as it will not log any other Debug output in this mode.
	If you are unable to start your program from the commandline (eg: C:\AppDir>), then use the SetCommand() function in your program. This must however be placed before any FM3 Init code. E.g.: FM3:Start Of Initialisation priority 1 <g>. Some example options: A check box on your Connect procedure: This is my personal favourite, but only really helpful if you are a SQL user. An Ini setting: An option, but you still control how this is set and maintained. You could use a compile switch: This is not the nicest option, as it is obviously set at compile time. Not recommended. Syntax example: SetCommand(command() & ' /debugfmall')

Creating an example application

Some important rules for submitting example apps:

Submitting Your Support Request

Files to accompany your support request

Describe in detail the steps you took to produce the problem

Purchasing FM3

If you are currently an FM2 user, you will need to purchase an upgrade to FM3. You can do this at ClarionShop: http://www.clarionshop.com/pdetail.cfm?id=461

CapeSoft Sales
	Web	www.capesoft.com
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, South Africa

Buy Online
	Web	www.clarionshop.com

Distribution

FM3 Distribution DLLs
		Clarion Version	DLLs required
		Clarion 5.5	c55fm3x.dll, c55dosx.dll, c55tpsx.dll
		Clarion 6	c6fm3x.dll, c60dosx.dll, c70tpsx.dll
		Clarion 7	c70fm3.dll, c70dos.dll, c70tps.dll

Miscellaneous Topics

Converting your FM2 apps to FM3
Converting your CW2 apps to Clarion 4 or above
International Language Support

Converting your FM2 apps to FM3

FM2 and FM3 can NOT co-exist in the same app, but an app can easily be converted to FM3.

Here are the recommended steps for converting your FM2 app to FM3:

• Add the FM3 Global Extension to your application.
• Remove the FM2 Global Extension.
• Delete the RuntimeFileManager procedure and run the FM3 Template Utility (in the IDE - Application | Template Utility - select the ImportRuntimeFileManager template utility).
• Go to Project DEFINES and make sure you have FM2=>1 set. Note: This is FM2=>1, not FM3=>1.
• If you used AutoNET in FM2, you need to sure you tick the Enable AutoNET in FM3 as well
• If you used AutoFIX in FM2, you need to sure you tick the Enable AutoFix in FM3 as well
• Compile, run, and test your application.

Converting your CW2 apps to Clarion 4 or above

International Language Support

You'll probably want to add locale for different sorting of your data. The best place is to put it in the DataDLL (If your application is a Multi-DLL application) in the 'FM: Start of Initialisation Section'.

To Do List

 Version History

If you're getting compile errors after upgrading, then check the Compile Errors section of the FAQ.

Licence, Copyright, & Disclaimer

Copyright

Licence

Disclaimer

CapeSoft Software (Pty) Ltd, 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 product is used entirely at your own risk.
Use of this package constitutes agreement with the above licence.