Copyright: © 1997-2000 TurboPower Software Company. All rights reserved.


Chapter 15: Data Conversion
Welcome to the FlashFiler Data Conversion Utilities

Due to new features in FlashFiler 2, such as support of files larger than 4 gigabytes and improved BLOB granularity, the FlashFiler table format has changed. In order to use FlashFiler 2 with existing applications, you must migrate your FlashFiler 1 tables to the new table format. There are three ways for you to convert your existing tables.

First, the FFCnvrt utility provides a graphical user interface for converting tables. If you simply need to convert your FlashFiler 1 tables so that you can start using FlashFiler 2, or if you do not have any need for automated conversions, use this tool.

Second, FFCnvrtC is a command line conversion utility. Use this tool to automate conversions or integrate conversions with your installation and patching programs.

Finally, the TffDataConverter class (in the FFConvrt unit) provides direct access to the core logic of the data conversion. FFCnvrt and FFCnvrtC are simply interfaces that wrap around TffDataConverter. If you want to develop your own conversion interface, provide new options, or perform additional maintenance during conversion, use this class directly. This class is documented in Chapter 15 of the printed documentation and in the FF.HLP help file.

This help file describes and provides examples for both FFCnvrt and FFCnvrtC. The conversion executables are located in the Bin subdirectory of your FlashFiler installation. The source code for each utility and the TffDataConverter class is located in the Convert subdirectory.

Both utilities work with all FlashFiler 1 tables and field types. The only exception is encrypted tables. The conversion utilities handle tables encrypted using the standard FlashFiler 1 server. If you customized the table encryption, you must recompile a DLL used by the conversion utilities. See "Installing New Encryption Routines" in Chapter 3 of the printed documentation for information on table encryption. See "FlashFiler 1 Dynamic Link Library" in Chapter 15 of the printed documentation or in FF.HLP for details about recompiling the conversion DLL.

Both utilities require you to specify source and destination directories. The source directory is the location of your FlashFiler 1 tables. The destination directory is the location where the converted tables are to be placed. In any one run of a conversion utility, you can convert multiple tables but they must originate from the same source directory and be converted to the same destination directory.


FFCnvrt: GUI conversion utility
Introduction to GUI Conversion

FFCnvrt provides a graphical user interface for data conversion. It provides an intuitive way to convert your tables. Use the Source list boxes to select the tables you want to convert. Use the Destination list boxes to tell FFCnvrt where to place the converted tables. Status information is displayed as the program progresses through your tables.

Specify the Source Tables

Use the Source group to specify which tables you want to convert. These fields are used in steps 1 through 3 in the FFCnvrt example. The following table defines the three fields: Drive List, Directory List, and Table List:

Field	Purpose
Drive List	Specify the drive containing the tables you wish to convert.
Directory List	Choose the directory containing the tables you wish to convert. The tables located in the selected directory will be displayed in the Table List.
Table List	Select one or more tables to convert. This list is empty until the drive and directory are specified.

Specify the Destination Tables

Use the Destination group to specify the location of the converted tables. These fields are used in steps 4 and 5 in the FFCnvrt example. The following table defines three fields: Drive List, Directory List, and Table List:

Field	Purpose
Drive List	Specify the drive in which you wish to store the converted tables.
Directory List	Choose the directory in which you wish to store the converted tables. Any tables located in the selected directory will be displayed in the Table List.
Table List	This list is empty until the drive and directory are specified. The Destination Tables List is read-only. The tables in the destination directory are listed so that you can see if you’re about to overwrite existing FlashFiler tables. There’s no problem with overwriting tables; we just want to ensure that’s what you intend. The interface confirms that you want to overwrite tables before it does so.

Watch the Conversion Status

Everything below the Source and Destination groups displays the status of the conversion. The Status section is comprised of three fields: the Status View, the Progress Bar, and the Status Bar:

Field	Purpose
Status View	A grid that displays information about each table being converted. This information includes the table name, number of records converted, original file size, converted file size, length of time to convert, and conversion status.
Progress Bar	A meter that indicates the progress of each table. The progress bar is empty until a conversion starts.
Status Bar	Located at the bottom of the screen, the status bar contains three panels. The left panel, shows which table in the Status View is being converted. The middle panel summarizes the current stage of the conversion. The right panel shows how many records in the current table have been converted.


Try an example
FFConvrt Example

This example converts FlashFiler 1 server tables, something every FlashFiler 2 user must do to use the new version. The FlashFiler Server creates several tables in its directory in order to store alias, user, and configuration information. These tables are named FFSInfo.FF2, FFSAlias.FF2, FFSUser.FF2, and FFSIndex.FF2.

Note: FlashFiler Server creates FFSIndex.FF2 only if you take advantage of User-Defined Indexes. Do not be alarmed if you do not find an FFSIndex table.

The FlashFiler Server automatically creates these tables in the directory containing the FlashFiler Server executable. In addition, applications compiled as a FlashFiler SingleEXE also write server tables to the directory containing the executable. This conversion assumes that you locate a suitable set of server tables and have FlashFiler 2 installed. Start the FFCnvrt utility using the shortcut on your FlashFiler menu. Optionally, start FFCnvrt from the Bin subdirectory of your FlashFiler installation. The FlashFiler 2 Conversion Utility dialog box will be displayed. In the following figure, the various fields and controls have been numbered for reference during the example.

Once FFCnvrt starts, perform the following steps:

1.	Select the drive containing the FlashFiler 1 tables in the Source Drive List (field [3]).

2.	Select the directory containing the FlashFiler 1 tables in the Source Directory List (field [4]). Once you select the directory, the FlashFiler 1 server tables appear in the Source Table List.

3.	Select the tables to convert from the list provided in the Source Table List (field [5]).

4.	Select the Destination drive (field [6]).

5.	Select the Destination directory (field [7]).

6.	Push the Convert button (Control [8]). The selected tables will be displayed in the Status section. As the tables are converted, the progress and status of each table are updated. During the conversion the Convert button changes to a Cancel button. When the conversion is complete, the Cancel button is labeled Convert once again.

7.	Close FFCnvrt and load your FlashFiler 2 server. FlashFiler 2 server options have changed some, so you need to verify them.

Note: NetBIOS is not supported in FlashFiler 2. When converting a FFSInfo.FF2 server table, the Network Configuration dialog box will appear if your previous server was set to use the NetBIOS protocol. You need to set at least one new protocol.


The Network Configuration dialog box.
The Network Configuration Dialog Box

The Network configuration page appears when the conversion utility attempts to convert a general configuration table (i.e., FFSINFO.FFD) that specifies NETBIOS as the primary protocol for the FlashFiler Server. FlashFiler 2 does not supports NETBIOS. The conversion utility displays the Network Configuration page so that you may reconfigure the network parameters for the converted table.The Network configuration page has three groups: Winsock TCP/IP Transport, Winsock IPX/SPX Transport, Single User Transport, and two buttons.

Winsock TCP/IP Transport Group

Field	Function
Enabled	When checked, the transport is enabled. When clear, the transport is disabled. Clear by default.
Listen for broadcasts	When checked, the server listens for, and responds to, client applications asking for a list of server names. The FlashFiler Client communications layer has a routine that retrieves all server names on a network. It performs this task by broadcasting a request across the network for all listening servers to send back a message containing the server name and net name. Under certain circumstances, you won’t want your server to respond to such a request (e.g., it is supposed to be invisible or unavailable to all network users), so you can prevent the response by clearing this box.
TCP port	Specifies the port over which the client and server, once connected, will communicate.
UDP server port	Specifies the port on which the client broadcasts a Who is there? message to all active servers.
UDP client port	Specifies the port on which the server responds to Who is there? messages.
Network interface	Specifies the installed network card used by the TCP/IP transport.

Winsock SPX/IPX Transport Group

Field	Function
Enabled	When checked, the transport is enabled. When clear, the transport is disabled. Clear by default.
Listen for broadcasts	When checked, the server listens for, and responds to, client applications asking for a list of server names. The FlashFiler Client communications layer has a routine that retrieves all server names on a network. It performs this task by broadcasting a request across the network for all listening servers to send back a message containing the server name and net name. Under certain circumstances, you won’t want your server to respond to such a request (e.g., it is supposed to be invisible or unavailable to all network users), so you can prevent the response by clearing this box.
IPX server socket	Specifies the socket on which the client broadcasts Who is there? messages.
IPX client socket	Specifies the socket on which the server responds to Who is there? messages.
SPX socket	Specified the socket over which the client and server, once connected, will communicate.

Dialog Box Buttons

Buttons	Function
OK	Saves all data in a server table, providing the Disable all server output and Disable saving configuration changes check boxes in the General Configuration dialog box are not checked. Whether or not the check boxes are checked, the changes are available immediately during the current run of the server application.
Cancel	Discards all changes.


FFCnvrtC: Command line conversion utility
Introduction to Command Line Conversion

FFCnvrtC provides the same functionality as FFCnvrt without the user interface. Use FFCnvrtC to automate conversions or to accomplish "unmanned" conversions. Unmanned conversions prevent your users from having to perform the conversions. You simply call FFCnvrtC from a batch file or application with the correct parameters. The conversion is accomplished without any interaction from your users as illustrated by the FFCnvrtC example.


Parameters
Command Line Parameters

FFCnvrtC recognizes the types of parameters as listed in the following table:

Parameters	Purpose
-s	Source directory: location of files to convert
-t	Tables to convert (no path or extension)
-d	Destination directory: location to create converted tables

There are a few things to remember about these parameters:

•	You can have multiple table parameters but only one source and destination.

•	If you don’t list any table (-t) parameters, all tables in the source directory are converted.

•	Ensure the destination doesn’t contain any tables with the same name as a source table.

FFCnvrt examples

The following lines of code illustrate some valid and invalid calls to FFCnvrtC:

Valid calls to FFCnvrtC

FFCnvrtC -sC:\FF -tFFSUser -tFFSAlias -dC:\FF2

FFCnvrtC -dD:\NewApp -sD:\OldApp -tOldData

Invalid calls to FFCnvrtC

The following example is invalid because it specifies more that one source.

FFCnvrtC -sC:\FF1 -tMyTable -sC:\FF2 -tOtherTable -dC:\NewFF

The following example is invalid because it does not provide a destination.

FFCnvrtC -sC:\FF -tFFSInfo -tFFSUser -tFFSAlias


Converting server tables
 FFConvrtC Example

The following steps result in the conversion of server tables using FFCnvrtC. The FlashFiler Server creates several tables in its directory in order to store alias, user, and configuration information. These tables are named FFSInfo.FF2, FFSAlias.FF2, FFSUser.FF2, and FFSIndex.FF2

Note: FlashFiler Server creates FFSIndex.FF2 only if you take advantage of User Defined Indexes. Do not be alarmed if you do not find an FFSIndex table.

Before beginning the conversion, decide which system tables you wish to convert, check the source directory, and decide in which directory to install the FlashFiler 2 server . Both servers are placed in the Server subdirectory by default, but may be executed from a different location.

For the following example, the FlashFiler 1 server is installed in C:\FF, the FlashFiler 2 server is installed in D:\FF2, and both servers are executed from their default location.

1.	Startup a command session. The easiest way to get to a command session is to click the Start button, click Run, type "command", and hit the Enter key.

2.	Change to the location where the FFCnvrtC executable is located. It’s installed in the Bin subdirectory of your FlashFiler installation.

3.	Type in "FFCnvrtC" at the command line. Add the source parameter with the location of the FlashFiler 1 tables. Add a table parameter for each of the server tables. Then add a destination parameter with the location of the FlashFiler 2 server. Following is an example of FFCnvrtC:

FF2Cnvrt -sC:\FF\Server -tFFSInfo -tFFSAlias -tFFSUser -tFFSIndex -dD:\FF2\Server

4.	Press the Enter key and the conversion begins. FFCnvrtC displays a message when it’s complete. If the message is "Conversion successful", start the FlashFiler 2 server and verify the settings. If you receive an error message, check the status of the conversion, adjust the command arguments, and try the conversion again.


Status
FFCnvrtC Status Messages

FFCnvrtC reports the status of the conversion in two ways: it displays a message to the screen and it sets an exit code. If the conversion utility is executed from a Delphi or C++Builder application, call the GetExitCodeProcess Win32 API to retrieve the exit code and include an error handler in the application. If the utility is called from a batch file, check the ErrorLevel value for the exit code.

The following table lists the exit codes, the associated messages, and their meanings:

Exit Code	Message	Meaning
0	Conversion successful	No problems were encountered
1	ERROR: No destination parameter	FFCnvrtC must know where to put the newly created tables
2	ERROR: No source parameter	FFCnvrtC needs to know the location of the files to convert
3	ERROR: Too many source parameters	Only one source parameter is allowed
4	ERROR: No tables to convert	No table parameters and none in the source directory
5	ERROR: <table name> doesn't exist	Table doesn’t exist in the source directory
6	ERROR: Source and destination in same location	Source and destination directories must be in different locations
7	ERROR: <table name> already in destination	A table with this name is already in your destination (See the Conversion Utilities introduction for more information.)
8	ERROR: <source path> doesn't exist	Source directory does not exist
9	ERROR: <destination path> doesn't exist	Destination directory does not exist
10	ERROR: Conversion of <table name> failed	Error while retrieving records from the table
11	ERROR: (No message)	No parameters given (A short help screen is displayed instead of an error message.)
12	ERROR: Unknown failure	Conversion not successful - unable to determine the reason