FairCom ISAM for C

Migrating Data Between Platforms and Operational Models

FairCom created FairCom DB with the intent to provide cross-platform support with a standardized database, no matter which operational model is used or what mix of platforms are involved. In some cases, this capability is invisible to the developer, in others careful consideration is required to allow various applications to work together.

This section provides an overview of topics covered in more detail in later sections. It is intended to provide background information to help you choose the appropriate operational model for your present and future implementations.

The considerations are broken down by operational model: Single-user standalone, Standalone Multi-user, and client/server. Applications from different models should not share files concurrently, though files can be exchanged as described in File Migration.

In This Section Single-User Standalone Multi-User Standalone Client/Server File Migration

Single-User Standalone

Single-user applications should not share FairCom DB files simultaneously. There is no mechanism in the single-user library to prevent multi-user interference. However, files can be exchanged between different instances of an application for sequential, not simultaneous, use. See File Migration for details.

Multi-User Standalone

The multi-user standalone model has the same issues with exchanging files described in File Migration in the FairCom DB Programmers Reference Guide.

However, sharing files between platforms simultaneously introduces additional complications with byte order and alignment, and adds the issue of record locking.

• Byte order is critical. Applications expecting different byte orders cannot seamlessly share files in this model.

  Note: The FairCom Server does allow seamless file sharing!

  However, the UNIFRMAT define allows HIGH_LOW applications to store and retrieve data in LOW_HIGH format instead of HIGH_LOW. This allows the files to be shared. If a record schema is present in the form of a DODA, data records will be adjusted automatically. See the FairCom DB Features chapter for more information on UNIFRMAT. Record Schemas in the FairCom DB Programmers Reference Guide describes the DODA.

• All applications sharing FairCom DB files must use the same alignment settings. If not, the application developer is responsible for ensuring record layouts are consistent.
• Locking between cross-platform applications introduces the complications of different locking standards and network file sharing mechanisms.
  • In multi-user standalone mode, FairCom DB uses three different locking systems to deal with the different locking standards used by various operating systems. Any combination of systems sharing files must use the same locking method with the same settings or they will not properly identify each other’s locks. See Multi-User Concepts in the FairCom DB Programmers Reference Guide for information on locking methods and their implementation.
  • Different network file sharing systems handle locks in different ways. Sometimes, this leads to incompatible locking systems between applications. When mixing applications from different environments, verify that locks are working. A simple test is to use a sample application, such as ctixmg, a FairCom DB example program. In one instance of the application, enable locking and add a record (which locks that record automatically). On the other platform, open ctixmg, enable locking and attempt to read the record added by the other application. If ctixmg returns an error DLOK_ERR (42), locking is functioning properly. Otherwise, there is a locking issue requiring troubleshooting.
  • Note, the FairCom Server relieves the programmer of many of the issues regarding heterogeneous networking and data integrity as described in the following sections.

Client/Server

The client/server model must also deal with byte order, but the FairCom Server handles this automatically when a record schema, in the form of a DODA, is present in the data file. Clients manipulate the data in their native format, and the FairCom Server manipulates the data in its native format. Translation takes place automatically during communication between the clients and the server.

This automatic translation allows a variety of clients using a variety of standards to cooperate with minimal effort on the part of the developer. For example, FairCom Servers running on Mac, Windows, and Unix systems can communicate simultaneously with any combination of clients on Mac, Windows, and Unix systems. This allows the customer flexibility in their selection of client and server systems, and allows clients in a mixed environment to share data.

See Record Schemas in the FairCom DB Programmers Reference Guide for more information about the DODA.

The client/server models also require the extended initialization functions, such as InitISAMXtd(), which pass logon information and trigger automatic target key transformation. See TransformKey in the FairCom DB Programmers Reference Guide for more information.

File Migration

Applications of any model can exchange files, sharing them sequentially but not simultaneously. Ensure the applications involved do not have the files open when they are copied or moved. If the application in question is the FairCom Server, this is especially important. See Copying Server Controlled Files in the FairCom DB Programmers Reference Guide for additional information.

Issues that affect file exchanging include byte ordering of numeric values and alignment of data structures. FairCom DB uses the same default for byte order as the hardware CPU and the default structure alignment dictated by the compiler.

• Byte Ordering is a processor-related issue. Intel-based processors store numeric values least-significant byte first (LOW_HIGH), while other processors store numeric values most-significant byte first (HIGH_LOW). So a four-byte integer containing the value “16” stored on an LOW_HIGH system as the hexadecimal value 10 00 00 00 would be stored on a HIGH_LOW system as the hexadecimal value 00 00 00 10. The order of the bits is consistent within the bytes, but the order of the bytes in the numeric value is reversed. By default, FairCom DB files are stored in the native format to the operating system, so files created on a HIGH_LOW machine cannot be exchanged directly with applications on a LOW_HIGH machine. See Portable Data Through UNIFRMAT Support, in the FairCom DB Programmers Reference Guide, which allows HIGH_LOW systems to work with LOW_HIGH files.
• Different compilers align data structures in different ways, but most have compile-time options allowing the alignment to be adjusted. Some compilers default to 1-byte alignment, which means structures are not adjusted in any way. With 2-byte or higher alignment, variables are aligned to the boundary matching the alignment or the variable’s size, whichever is smaller. There is a potential for the compiler to add dead space within a data structure. See Buffer Regions in the FairCom DB Programmers Reference Guide for more information on alignment.

Some of the common problems caused by alignment differences are:

1. Record lengths when different applications use different amounts of padding;
2. Indexing when padding shifts key segments to different locations than specified in the ISEG structure;
3. Data corruption when applications align the record buffer differently.

Use the FairCom DB ctunf1 reformat utility to adjust the alignment and byte ordering for a given file before exchanging it with another platform. See CTUNF1 - File Reformatting Utility in the FairCom DB Programmers Reference Guide for more information on this utility.