Chapter 3: FlashFiler Server
Welcome to FlashFiler Server

FlashFiler is a client/server database engine. Its client applications send requests for data and operations to the server application, and it is the server that performs the actual request (opening a table or getting a record) on behalf of the client. The server sends the results of the request back to the client that requested it.

The main alternative to a client/server methodology is the file manager type database engine where all the clients have direct access to the files that make up the tables in the database. The benefits of the client/server architecture over the traditional file manager type are many; the most important being the increased data integrity offered by such a scheme. A FlashFiler Server is the only application that opens and updates tables. The client applications have no direct access to the files that make up the tables. This ensures that clients cannot, through programming bugs or power outages, corrupt the data in the tables. FlashFiler allows you to increase data integrity further by giving you the option of using fail-safe transactions to maintain a journal of table updates.

For single-user applications, FlashFiler also provides the opportunity to embed a server engine directly into the client application. This functionality does not take away the client/server aspect of FlashFiler: it is still there under the hood. However, a separate server application is no longer needed since the server code is included in the client application.

For maximal data integrity, FlashFiler Server opens all its files in exclusive (non-shareable) mode. These files not only include the server’s own tables, but also the table files opened on behalf of client applications. This does not mean that clients cannot share tables and data. It means that the server application makes sure that no other process can open the files. Once a table has been opened on behalf or one of more clients, another application cannot open the physical file. This becomes a problem only during backups. When a client has a table open, the server has the physical files open for that table, and so the backup program cannot open the files to copy them to the backup device. If it were possible for a backup program to open the table’s files, it would have no way of guaranteeing that the data it backs up is coherent: the server may be in the middle of committing or rolling back a transaction.

This Help file describes the FlashFiler Server application; its configuration and operation. It also explains the FlashFiler Service, journal recovery, how to encrypt tables, and how to deploy FlashFiler Server. The FlashFiler Server executable is called FFServer.EXE and is located in FlashFiler’s Bin subdirectory. The FlashFiler service executable is called FFSrvice.EXE and is also located in the Bin subdirectory.


Configuration
Configuring FlashFiler Server

The FlashFiler Server application maintains its global configuration in standard tables, known as server-specific tables. The tables are called FFSINFO.FF2, FFSUSER.FF2, FFSALIAS.FF2, and FFSINDEX.FF2. The type of information stored is fourfold:

•	General, network, and start-up information

•	The set of user IDs for accessing FlashFiler in secure mode

•	The set of database aliases and their paths

•	The set of definitions for user-defined indexes

The Config menu on the main FlashFiler Server screen provides access to all four of these configuration types.

FlashFiler Server maintains three lists of information:

List	Available data
alias definitions	A shortcut to a FlashFiler database which points to the complete path of the database.
user-defined index description	A complete identification of a table index (by the path and name of the table and the index number), and the identification of the DLL that performs key creation and comparison for the index (by complete path and name, and the routine names).
user ID definition	Contains a user’s name and a list of their rights to access and modify FlashFiler tables. The user rights include administrative, read, update, insert, and delete rights.
FlashFiler Server can be run in secure or non-secure mode. The default, secure server encrypts these server tables with a special method to ensure that client applications cannot read and alter them. All configuration changes must go through the server. The non-secure server does not encrypt the server-specific tables; hence they can be read and altered with standard FlashFiler client applications, like the FlashFiler Explorer program. Note, however, that FlashFiler Server will always recreate these server-specific tables using information stored internally in memory when their data changes. This ensures that the data integrity remains high, but does mean that client applications cannot alter the server-specific tables and expect the data changes to be permanent.

The security mode setting is located on the General Configuration screen and is labeled Creation of encrypted tables enabled.


Operation
Operating FlashFiler Server

To start FlashFiler Server, run FFServer.EXE. The FlashFiler Server main screen is displayed. If no server-specific tables are found, the communications layer is not started (i.e., it is not listening for client applications). If the server-specific tables are found, then the server will start according to the configuration information contained in the FFSINFO.FF2 table. If the communication layer is started, it will be indicated in the state of the transports shown on the lower portion of the main screen.

The main screen of FlashFiler Server includes the following:

Menu

Toolbar

List of Servers

List of Transports attached to the selected server

Status bar


The Menu
FlashFiler Server Menu

The menu allows access to the various functions of the server (bringing the server up, setting the debug logging option, etc.), as well as accessing the configuration options of the server.

The menu provides access to server-related options, configuration options, debugging options, and help options. If FlashFiler Server is in secure mode, you must log in before performing actions such as starting the server application, bringing the server up or down, or restoring the server window from a minimized state. When you attempt to perform one of these actions, the Server Log On dialog box is displayed. Enter your user ID and password. If they are correct, the action you requested is performed.


Server-related Menu Options
Server Menu Options

Menu Option	Purpose
Name	Defines the name of the selected server. The name can be up to 15 characters. You can use the letters A-Z (both upper and lower case), numbers 0-9, and embedded spaces. This option is disabled if the server is up.
Start	Start the servers. After initializing the network drivers, the servers start listening for clients. This option is disabled after the servers are up and listening.
Stop	Stops the servers. This option is disabled if the servers are already down.
Exit	Terminates the FlashFiler Server application. If the servers are up and listening for clients, they are automatically stopped before the server application terminates.


Configuration Menu Options

Menu Option	Purpose
General configuration	Opens the FlashFiler Server General Configurations dialog box that allows you to set the start-up configuration for the selected server. This menu item is available whether the server is up or not. However, certain fields of the general configuration dialog box are disabled if the server is up.
Network configuration	Opens the FlashFiler Network Configuration dialog box that allows you to configure the default transports for the selected server.
Aliases	Opens the FlashFiler Server Aliases dialog box that allows you to add, delete, and modify the database aliases known to FlashFiler. This menu item is available whether the server is up or not. Deleting or modifying an alias while it is already open does not cause any difficulties. Clients that have the database alias open will continue to use that alias in its original form; eventually when all the clients that have the database alias open close it, the alias will no longer be available in any form. When a client opens a database by its alias, the alias is converted to a path and the path is used from then on internally to the server.
User-Defined Indexes	Opens the User Defined Indexes dialog box that allows you to add, delete, and modify user-defined indexes. See the Appendices in the printed documentation for more information on user-defined indexes. This menu item is available whether the server is up or not. However, if you alter a user-defined index definition while its table is open, the behavior is unpredictable.
User Permissions	Displays the FlashFiler Server User Permissions dialog box that allows you to add, delete, and modify the users known to FlashFiler Server. These user attributes are only used if the server is being run in secure mode (i.e. users must log on). This menu item is available whether the server is up or not.


FlashFiler Server General Configuration dialog box
Configuring General Parameters

This dialog box offers the following configuration options:

Server name

Maximum Ram

Server priority level

Enable encrypted tables

Disable server output

Force Logins

Enable debug logging

Startup options

Keep-Alive options

Server Name

You can name the server by entering a name in the Server name edit control. Server name is disabled if the server is up.

Maximum RAM (in MB)

Used for sizing the server’s internal cache. The server caches pages from the tables it opens in a special cache. This makes the server more efficient in providing records to clients because the page on which the record exists may already be in the cache and doesn’t have to be reread from disk. It also helps with transactions because the pages altered by a transaction are marked dirty and kept in the cache until the transaction is committed or rolled back. At that point the dirty pages are either written to disk (commit) or are marked empty (rollback). The server reuses the pages in the cache as it runs. To make sure that the server doesn’t keep on allocating memory infinitely, the server tries to keep the amount of pages in the cache below the Maximum RAM value. For example, if the value were set to 10 megabytes, the server would start reusing the least recently used pages once it had filled its 10 megabytes of cache. Dirty pages are never reused, and indeed, if a transaction is large enough, the server will willingly exceed the maximum limit to ensure that the whole transaction is kept in memory. As such, the Maximum RAM value is an advisory value. The default is 10.

Server Priority

Use this combo box to define the priority given to the server application. In 32- bit Windows, the foreground process runs at a higher priority than any background process, so if the server is minimized, it is possible for clients to appear sluggish, because the server does not have enough priority to fully process client requests quickly. The available options are Lowest, Below Normal, Normal, Above Normal, and Highest. You need to experiment to find the optimum setting for your system. The default is Highest.

Creation of encrypted tables enabled

Use this check box to define whether the server creates its own tables in an encrypted form. If the box is checked, the server tables created by FlashFiler Server are encrypted and can only be read by the server application itself. FlashFiler client applications will not be able to open the tables because the encryption used is different than that used for the client tables. The default is checked.

Disable all server output

A check box that defines whether the server is allowed to output any data (table updates, debug log, and configuration tables). If the box is checked, the server does not produce any output. You may want to enable this setting to ensure your data is not modified. The check box is not checked by default.

Disable saving configuration changes

Use this check box to define whether the server updates its configuration tables. The check box will be disabled if Disable all server output is enabled. If the box is checked, you can modify server options but they will not be retained after the FlashFiler Server application is closed. You may want to enable this setting while testing different settings.  The default is not checked.

Security enabled

A check box that allows you to specify secure mode for the server. Secure mode requires that all users log on to the server before using any of its functions. This log on occurs both at client applications and within the FlashFiler Server application itself (to alter the configuration of the server requires the user to log on as an administrator).

In secure mode, messages undergo additional encryption by XORing the generated code with the client’s hashed password. Since the user’s password is never passed between client and server, the client application must have the correct password in order to decrypt the code and finalize the connection. The check box is unchecked by default.

Debug logging enabled

A check box that, if checked, will cause every message received and replied to by the server to be written to a text file. The text file, FFSERVER.LOG, will be created in the same directory as the server application. The actual information written to the text file depends on the messages being received by the server. The log is a debugging tool that checks which messages are being received by the server from a client when the client performs a particular function. Enabling the debug log causes a dramatic drain on performance. We recommend that you only enable this setting while debugging. This option performs the same operation as the Debug | Log option on the main menu.  The check box is not checked by default.

Startup Options Group

There are two options in this group:

Option	Result
Bring Server up automatically	The server is brought up when the application starts.
Start minimized	The server application minimizes to a tray icon when it is run.
The default for both options is not checked.

Keep-Alive Options Group

The set of fields in the Keep-Alive Options group define what happens when there is a period of inactivity between the client and server. Because of the way that most network protocols are written, you are only notified if the connection between client and server is broken when either partner attempts to send a message across the connection. Since the server never sends a message to a client unless it is a reply to a request from that client, it is very likely that the server would not notice that a connection was broken (for example, the client had crashed, the client machine has been powered off, and so on). If the client were to crash half way through a transaction, there is no way for the server to know, and hence all other clients would be locked out from updating portions of the database. It is in this situation that the Keep-Alive options come into play.

Periodically both the client and the server will send each other a message just to say that they are alive and running. If either side does not receive a message within a certain amount of time, the connection is deemed to be broken. This connection time-out processing proceeds like this:

•	After a period of Interval from last message milliseconds from when the last standard message was sent or received, the first keep-alive message is sent.

•	Keep-Alive messages are then sent every Interval between Keep-Alives milliseconds, until a total of Keep-Alive retries messages have been sent.

•	The application, be it client or server, will assume that the partner is no longer reachable, and close the connection.

•	If a message (standard or Keep-Alive) is received anywhere within this process, the entire process is reset to the beginning.

Option	Meaning
Interval from last message	The delay, in milliseconds, between the end of one Keep-Alive process and the onset of the next. The default value is 30,000.
Interval between Keep-Alives	The delay, in milliseconds, between Keep-Alive messages. The default value is 5,000.
Keep-Alive retries	The maximum number of Keep-Alive messages sent before a connection is deemed broken. The default value is 5.


Network Configuration dialog box
Configuring Network Parameters

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.


FlashFiler Server Aliases dialog box
Configuring Aliases

When you select the Aliases option from the Config menu, the FlashFiler Server Aliases dialog box is displayed.

Field	Function
Delete Alias	This speed button on the toolbar deletes the selected alias.
Browse	This speed button on the toolbar opens a standard browse window to make it easier to select a path for an alias. The speed button is enabled only if the active cell of the grid in the Path column.
Alias	This column contains a simple identifier for a database.
Path	This column specifies the full directory path to the database. FlashFiler Server converts the path you enter to a full universal naming convention (UNC) path. A UNC path is one of the form \\MACHINE\SHARE\FOLDER. Unshared local directories are stored in the standard DRIVE:\FOLDER format. Whether the path is converted or not, it must be available from the PC on which the server application is running. The server must be able to open and update files in that folder.
	The columns in this dialog box can be resized. Move the mouse over the dividing line between the column header cells until it changes shape, click, and drag. You can sort by a particular column by clicking on its header.
OK	This button saves all data in a server table, providing the Disable all server output and Disable saving configuration changes check boxes 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	This button discards all changes.


User-defined Indexes dialog box
Configuring User-Defined Indexes

When you select the User-defined Indexes option from the Config menu, the FlashFiler Server User-defined Indexes dialog box is displayed.

Field	Function
Table Name & Path	The complete file name and path of the index for which you will supply build key and compare key routines. FlashFiler converts the path you enter to a full universal naming convention (UNC) path. A UNC path is one of the form \\MACHINE\SHARE\FOLDER\FILE. Unshared local files are stored in the standard DRIVE:\FOLDER\FILE format.
Index	The index number for which you will supply build key and compare key routines. You must enter the number associated with the index by the Table Definition dialog box in FlashFiler Explorer less one. The sequential numbers in the Table Definition dialog box are 1-based. The numbers in this column are 0-based. The number is also returned by the GetIndexFromName function in the TffDataDictionary class.
DLL Name & Path	The name of the DLL that contains the build key and compare key routines. You must enter a complete file name and path in DLL Name & Path. Your entry is converted to the full UNC path.
Build Key	Defines the name of the Build Key routine.
Compare Key	Defines the name of the Compare Key routine.
Delete	Deletes the selected index definition. The table to which it refers is not altered.
Browse…	Opens a standard search window that makes it easier to select a path for a Table Name & Path or DLL Name & Path cell. It is enabled only if the active cell is in one of those two columns.
OK	Saves all data in a server table, providing the Disable all server output and Disable saving configuration changes check boxes 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.

The columns in this dialog can be resized. Move the mouse over the dividing line between the column header cells until it changes shape, click, and drag.


Server User Permissions dialog box
Configuring User Permissions

Use this dialog box to define users and their rights. The admin user is defined by default. This user has full rights. The user’s default password is "flashfiler". Clicking on any column header in the table will sort the user list by the data in that column.

You can define additional users by entering a set of information in the table:

Column	Purpose
User ID	Specifies the User ID
Last Name	Specifies the last name of the user
First Name	Specifies the first name of the user
Admin	Provides the user the right to log on directly to FlashFiler Server and change any of the configuration options
Read	Provides the user the right to open and access databases and tables in read-only mode
Insert	Provides the user the right to create new tables and insert new records in tables
Update	Provides the user the right to rename, restructure, pack, and re-index tables and modify records in tables
Delete	Provides the user the right to delete existing tables and delete records from tables

The two speedbuttons on the toolbar and the buttons at the bottom of the dialog box provide the following functionality:

Button	Result
Delete User	Deletes the selected user. You cannot delete the admin user.
Password	Displays a standard Password dialog box so you can enter a password for the selected user. The password must be entered twice, the second time for verification purposes. If no password is supplied for a user, the user ID is displayed as a red cell that indicates that the user is unavailable.
OK	Saves all data in the Server User Permission table, providing the Disable all server output and Disable saving configuration changes check boxes are not checked.
Cancel	Discards all changes


Debug Menu Options

Selecting Debug from the Main Menu provides the following functionality:

Log

This option opens the debugging log that shows the messages FlashFiler Server received from clients and the responses it made. It also logs all exceptions generated internally by FlashFiler Server. Exceptions raised internally by the server in response to client requests are sometimes converted into BDE error codes. In the conversion, information can be lost and the log is the only way to see that information. A check mark in the menu by the Log option shows that logging is active. The log is written to the file, FFSERVER.LOG, in the directory from which the server application was started. Note that internal exceptions generated by the server application are always written to the log file, whether debug logging is active or not. The only time internal exceptions aren’t written to the log file is when the Disable all server output setting is checked on the General Configuration page.

Logging is an extremely disk-intensive process. To ensure that the log is always valid, the server opens the log file, writes a line, and closes the file for every line in the log. Consequently, the server is significantly slower if logging is on. We recommend that you only use the debug log while testing or debugging. The default is not checked.

Reset Counters

This option resets the counter and transport message-related statistics.


Help Menu Options

Menu Option	Result
About	Displays a screen of information about FlashFiler Server
Visit TurboPower's Web Site	Starts your web browser, passing the URL address of the TurboPower Software Web site


Toolbar

Directly below the menu is a toolbar. The toolbar’s speed buttons give easy access to frequently used menu options.

Button	Function
Properties	The first speed button allows you to define the properties of the server.
Server Up	The second speed button brings the server up. Is equivalent to Server | Start in the main menu.
Server Down	The third speed button takes the down. It is equivalent to Server | Stop in the menu).


Server List
Server Engines List

The body of the main screen is divided into two sections: servers and transports. The upper section is the Servers section. It lists all the servers in your FlashFiler Server application. For each server, you can see its name, state, the number of clients logged on, the number of active sessions, the number of open databases, the number of open tables, number of cursors, and how much RAM the server is currently using to cache data from the tables it has open. FlashFiler Server ships with a single server. Chapter 8: Advanced Architecture in the printed documentation includes information about adding additional servers.


Transports list

The body of the main screen is divided into two sections: servers and transports. The lower section of the screen is the Transports section. This section lists all the transports attached to the server selected in the Server section. For each server, you can see its name, address, state, the number of clients attached via this transport, the number of messages it’s processed since it was started, and the average number of messages it is processing per second (this number constantly changes as time passes). You can reset the message count and message processing statistics by using the Debug | Reset Counters menu option. Resetting these statistics allows you to get a snapshot of the network traffic. We include three transports with each server: TCP/IP, IPX/SPX, and Single User. Chapter 8, Advanced Architecture, in the printed documentation explains how to customize the included transports and how to create your own custom transports.


Status Bar

The status bar runs along the bottom of the main screen and shows a variety of icons depending on the status of the selected server:

Icon	Meaning
Circle	This icon is green when the selected server is listening for clients (in other words, the server(s) are started) and red when it is not.
Cassette tape	If this icon is displayed, debug logging is enabled. If this icon is not displayed, debug logging is disabled.
Padlock	The padlock is closed if security is enabled and open if security is disabled.
The counter shows you how long the server(s) have been up and listening for client requests. The counter, server statistics, and transport statistics are refreshed once per second.


FlashFiler Service

One limitation of FlashFiler Server is that the hosting workstation must always be logged in. For customers using Windows NT or Windows 2000, the FlashFiler Service can be used in place of the FlashFiler Server. The FlashFiler Service executable is named FFSrvice.EXE and is located in the Bin subdirectory of your FlashFiler installation.

FlashFiler Service is compatible with Windows NT and Windows 2000. It supports TCP/IP, IPX/SPX, and Single User Protocol (SUP). SUP sees requests only if the service’s Allow Service To Interact With Desktop property is enabled.

To install FlashFiler Service, invoke the following from your installation program or command prompt:

FFSrvice /i

To uninstall the service, invoke the following from your installation program or command prompt:

FFSrvice /u

You may run FlashFiler Service as a normal program (i.e., not as a service) by typing the following at the command prompt:

FFSrvice /c

Prior to starting FlashFiler Service, you must make sure that it has the appropriate configuration information. See Deploying FlashFiler Server for more information. If you must configure the service after it has been installed, perform the following steps:

1.	Stop the FlashFiler Service.

2.	Make sure the Windows Event Viewer is closed.

3.	Make sure a FlashFiler Server executable is located in the same directory as the FlashFiler Service executable.

4.	Start FlashFiler Server and make the required configuration changes.

5.	Stop FlashFiler Server.

6.	Start FlashFiler Service.

FlashFiler Service registers itself as an event message source and, if an error occurs, writes error messages to the Windows event log. This means that Windows NT/2000 will open the FlashFiler Service executable if you open the Event Viewer and the Event Viewer contains messages posted by FlashFiler Service. You will not be able to replace the FlashFiler Service executable until the Event Viewer is closed.


Transaction Journal Recovery

All updates to FlashFiler tables are performed within transactions. If a client wishes to update one or more records, a transaction is started, the updates are made, and then the transaction is either committed or rolled back. The transaction can be either explicit or implicit. When the transaction is explicit, the client makes an explicit request to the server to start a transaction. When the transaction is implicit, the server starts a transaction if it detects an update is occurring and commits afterwards. The client does have the choice of making the transaction fail-safe or leaving it as a normal transaction. Fail-safe transactions are selected by setting the FailSafe property of the TffDatabase component to True. The TffDatabase component and its properties are described in Chapter 7 of the printed documentation. The fail-safe transaction mode must be set for each database used in the application, and once set will remain so until the FailSafe property is set to False. The default is to use normal (non fail-safe) transactions.

If a client is using fail-safe transactions, updates are initially written to a transaction journal file rather than straight to the database itself. It is only when the transaction is committed, and the transaction journal file is closed and flushed to disk, that the updates are written to the database. If a crash occurs during the database update (and the tables are thereby not updated correctly), the database can be corrected the next time the FlashFiler Server is started, using the information saved in the transaction journal file.

When a fail-safe transaction is started on a database, a transaction journal file is created. An incomplete journal header is written to the transaction journal file at this time. Keep in mind that FlashFiler 2 supports multiple transactions on a database. Each transaction will have a separate journal file.

Just before a page of memory is changed in the server cache, a before image of the page is written to the transaction journal file. Then the page is marked dirty. The dirty page is known as an after image. Changes are just made to the page in memory; no disk files are updated at this time.

If the transaction is rolled back, the transaction journal file is deleted and the dirty pages in the cache are discarded. Changes were not written to the actual database files, so no further action is necessary.

If the transaction is committed, the following process occurs:

1.	The after images are written to the transaction journal file.

2.	The transaction journal file is marked complete (the incomplete journal header is overwritten with a complete journal header) and the file is closed, flushing all data to disk.

3.	All the database pages marked as dirty in the server cache are written to the disk.

4.	The transaction journal file is deleted.

Fail-safe transactions become important if the server application crashes during the third step. In this case, the user believes that the (committed) fail-safe transactions have been fully written to the database, when, in actuality, they have only been saved to the transaction journal file.

Each time FlashFiler Server is started, it performs transaction journal recovery before it becomes available as a database server. For each database defined as an alias, it searches for all transaction journal files. If it finds a transaction journal file that is marked incomplete, it cannot be processed (indeed the database is valid since nothing was written to it), so the journal file is simply deleted. This is akin to rolling back an incomplete transaction.

If, however, it finds a transaction journal file marked as complete, a dialog is displayed for the FlashFiler Server administrator. The dialog displays the database alias and file names, notes that a complete transaction journal was found, and asks whether to commit or rollback the changes. If the administrator chooses to rollback the changes, the before images in the journal are written to the database files and the transaction journal file is deleted. If the administrator chooses to commit the changes, the after images are written to the database files and the transaction journal file is deleted. After all of the transaction journal files are processed, the server starts its network protocol, and becomes available to act as a database server.

Note that should a FlashFiler client application crash in the middle of a transaction, the server will eventually notice that the client has disappeared (see the discussion on Keep- Alives) and will roll back all transactions for that client.


Server Scripting

The server has the ability to read its initial configuration from a script file. The script file is read and the commands processed when the server first starts. Since the script is acted upon after the server has read configuration data from its own tables, you can:

•	Use a script instead of server tables to store the server’s configuration.

•	Use a script to set up the server part of a SingleEXE application.

•	Reduce the number of support files you must ship with FlashFiler Server (indeed, your installation program can create the script file when your product is installed).

The configuration items supported by the server-scripting engine are most of the general configuration items (excluding the port/socket numbers and the debug logging option) and alias definitions. User-defined indexes and user IDs are not supported with this scripting facility. The script is a simple ASCII file, structured as a series of lines of the form KEY=VALUE. Both KEY and VALUE strings are case-insensitive.

If you distribute a FlashFiler Server or SingleEXE application containing multiple server engines, you may include two or more sets of configuration items within the same script. Each set of configuration items must be prefixed with a line having the following format:

[<server component name>]

where <server component name> is the value of the server engine's Name property. If the first items encountered in a script are not tied to a specific server engine then the items are treated as though they apply to all server engines.

The following table shows the scripting keys corresponding to the FlashFiler Server General Configuration screen, including a brief description and possible values:

Key	Description	Possible Values
SERVERNAME	The server name	String up to 15 characters with the letters A-Z (both upper and lower case), numbers 0-9, or embedded spaces
MAXRAM	The recommended maximum amount of RAM (in megabytes) the server will use to cache FlashFiler tables	Number from 0 up to available RAM
USELOGIN	Whether the server requires users to log on	TRUE, FALSE, YES, or NO
AUTOUPSERVER	Whether the server starts automatically	TRUE, FALSE, YES, or NO
AUTOMINIMIZE	Whether the server minimizes automatically	TRUE, FALSE, YES, or NO
ALLOWENCRYPT	Whether the server will create encrypted tables	TRUE, FALSE, YES, or NO
READONLY	Whether to prevent output from the server	TRUE, FALSE, YES, or NO
LASTMSGINTVAL	How many milliseconds to wait before sending the first Keep-alive message	Any number from 1,000 to 86,400,000
ALIVEINTERVAL	How many milliseconds to wait between Keep-alive messages	Any number from 1,000 to 86,400,000
ALIVERETRIES	How many total Keep-alive messages to send	Any number from 1 to 100
PRIORITY	Priority given to the server application	LOWEST, BELOWNORMAL, NORMAL, ABOVENORMAL, or HIGHEST
DELETESCRIPT	Whether the script file is deleted after processing has occurred	TRUE, FALSE, YES, OR NO
NOAUTOSAVECFG	Whether the configuration tables cam be updated from the server	TRUE, FALSE, YES, OR NO

The following table shows the keys corresponding to the FlashFiler Server Network Configuration screen:

Key	Description	Possible Values
IPXSPXLFB	Whether the Winsock IPS/SPX Transport should listen for broadcasts	TRUE, FALSE, YES, or NO
TCPIPLFB	Whether the Winsock TCP/IP Transport should listen for broadcasts	TRUE, FALSE, YES, or NO
TCPINTERFACE	Which network interface(s) to bind the FlashFiler Server to	-1 to (total interfaces minus 1)
USEIPXSPX	Whether to enable the Winsock IPX/SPX Transport	TRUE, FALSE, YES, or NO
USESINGLEUSER	Enable the Single User Transport	TRUE, FALSE, YES, or NO
USETCPIP	Whether to enable the Winsock TCP/IP Transport	TRUE, FALSE, YES, or NO

Any other KEY value is assumed to be an alias name and the VALUE part is assumed to be the path. That means that you cannot create an alias named as one of the above identifiers.

Once a script has been created, you get the server to read it by passing the script file name as the first parameter on the server command line. For example, you could set up an icon on your desktop that executed the following command:

D:\FF2\SERVER\FFServer C:\DATABASE\FFSERVER.SCR

When you double click on this icon, the FlashFiler Server would start and read and process the C:\DATABASE\FFSERVER.SCR script. The same thing applies to SingleEXE applications: the first parameter to your application’s command line would be the script file.

It must be emphasized that a script file is read after the current configuration of the server is read. This means that items in a script file override the values in the normal server configuration tables.


Installing New Encryption Routines

In your \FF\EXAMPLES\DELPHI folder is an example FFTBCRYP.PAS file that replaces the one we ship pre-compiled into the FlashFiler Server. You can change the encryption algorithm implemented in this unit and then recompile the server application. This will enable you to have encrypted tables that only you can read.

The FFTBCRYP unit provides four routines that you will have to replace: FFCodeBlock, FFDecodeBlock, FFCodeBlockServer, and FFDecodeBlockServer.

The first two routines encrypt and decrypt a block of table data. Recall that a FlashFiler table is a file (or set of files) of many blocks, each of which is the same size: 4, 8, 16, 32, or 64 KB. FFCodeBlock is called just prior to writing one of these blocks to disk and so is responsible for encrypting the data. FFDecodeBlock is called just after reading a block from disk and so is responsible for decrypting the encoded data.

The second two routines do exactly the same as the first two, except the table is one of the server-specific tables, and must be encrypted in a different fashion. This is to avoid a situation where a user maps an alias to the server directory and reads the server- specific tables directly. If the server tables are encrypted in a different fashion they will be unintelligible and only usable by the internal code in the server.

The parameters to the routines are the same in all four cases. aBlock is a pointer to the block to be encrypted/decrypted. aBlockLen is the length of this block. aRandomizer is a special value that is different for different blocks (actually, it's the block number). This will introduce a random element into the encryption/decryption process, so that each block can be encrypted in a slightly different way if you so wish (if you don't, just ignore the parameter).

Tables are encrypted in two situations: first, when they are created with the encryption option set, and second, if they are server-specific tables. (Note that, for either of these two cases to apply, the SecureServer compiler define must be active in FFDEFINE.INC.) The header record for FlashFiler tables (the first block in each table file) is not encrypted. This allows non-secure servers to read the header and determine that the table is encrypted. The routines you write in this unit will not be called for header blocks.

FlashFiler, by default, does not use passwords to encrypt and decrypt table data. Consequently, you could try to fashion a password as key for your encryption routine from the aRandomizer parameter.

You can replace the encryption algorithm with any encryption routine you have at hand, a good source for such routines (with printed code in C) is Advanced Cryptography by Bruce Schneier (Wiley). The encryption routine used in the example unit is the LockBox Stream Cipher from TurboPower's LockBox library. Simpler alternatives could be XORing a key (possibly a random key) over and over into a block: the longer the key the better. Be aware, however, that simpler encryption algorithms are usually more easily broken.


Deploying FlashFiler Server

Deploying FlashFiler Server is quite simple since you are free to distribute the FlashFiler Server application and service along with your own applications. The only precaution is ensuring your application has the configuration data it needs, especially FFSINFO.FF2 and the required database aliases.

Since you may not know where a user will install your product, you probably don’t want to ship your application with pre-defined aliases. You have two choices:

•	During installation, create a script file containing the required aliases. Run the FlashFiler Server. Specify the script file as the first parameter on its command line.

•	Modify your program to create aliases on the fly. You can create aliases using the TffSession.AddAlias method, as shown in the following example:

     MySession.AddAlias('MyApp', 'D:\MyFF2App');

If you are deploying a FlashFiler service, you must install a pre-defined FFSINFO.FF2 file or manually define the information through FlashFiler Server. You must create the aliases manually through the FlashFiler Server or programmatically in code. The FlashFiler service does not accept or process a script file. You must place the server tables in the directory containing the service executable (i.e., FFSrvice.EXE).

If you are upgrading an existing FlashFiler site with a new version of FlashFiler Service, your installation program will not be able to replace the service executable until a) the service is stopped and b) the Event Viewer is closed. If the Event Viewer is open and it contains messages from FlashFiler Service, the Event Viewer keeps the FlashFiler Service executable open.

If your application is a SingleEXE application, you don’t need to deploy the FlashFiler Server application but you still need to ensure the embedded server has the configuration information it needs. As with the FlashFiler Server application, it’s probably best to create your aliases using information gathered during the installation process.