


	Version www.capesoft.com Updated April 6, 2006

Technical Reference

Implementing AutoUP

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

a.	On program startup Register the File Driver's using the ds_AddDriver function.
b.	On program startup Register each of the data files using ds_UsingFile.
c.	Replace the OPEN(File) command in Clarion with ds_OpenFile. In Clarion 4 this is done automatically for you if the FM2 define switch is added to your project. In other words make sure the installation of FM2 is completed (by running the installation wizard at least once) and then add a Define to your project which reads: FM2=>1

When a file structure is changed in the code, then the call to ds_UsingFile for that file must be updated by incrementing the Version parameter.

In addition the following functions are useful for implementing additional specific AutoUP functionality; ds_AlternateFileName, ds_AlternateFieldName, ds_SetIfNew. The ds_SetUPGPath function is also worth having a look at.

Implementing AutoNET

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

The function to use is the ds_UpgradeLocalMachineEx function.

ds_AddDriver(string DriverName ,file ExampleFile)

Purpose

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

Parameters

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

ExampleFile - File - This is a file handle, of any file, which uses the driver that's being registered.

Example

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

code
ds_AddDriver('Cla',Customer)

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

Purpose

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

Parameters

FileLabel - String - This is the name of the file, as it's used in the Clarion program. This is not the name of the file stored on the disk, it is the name of the file in the dictionary.

FileHandle -File - This is the handle to the file. This is exactly the same as the name, but quotes are not used.

Version - Short - This is the current version number of the file used in this exe. Always increment, never decrement this number.

Prefix - String - This is the prefix of the file.

Example

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

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

ds_AlternateFieldName(string FromField,string ToField)

Purpose

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

Parameters

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

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

Example

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

s_SetIfNew(string Field,string Value)

Purpose

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

Parameters

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

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

Example

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

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

ds_AlternateFileName(string OldName,string NewName)

Purpose

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

Parameters

OldName - String - This is the old file name. The path is not required, but can be included if necessary.

NewName - String - This is the new name for the file.

Example

ds_SetUPGPath(<string Path>)

Purpose

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

Parameters

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

Example

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

ds_UpgradeLocalMachineEx(string Section,string INIFile)

Purpose

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

Parameters

Section - string - The name of the section in the ini file which contains the directory information.

INFile - string - This is the name of the INI file containing the directory information.

Returns

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

Example

program

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

[End of document]

meatloaf@capesoft.com