Number: TB0018

Availability: As of BuildPro 8.00 on all platforms

Introduction

When defining a table as either ISAM or flat file, the external files are normally created in the nominated DataPath directory. DataPath is set in your configuration file (.todayrc or wintoday.ini). The actual name of the file is determined by the BuildPro Table definition under the External tab (as shown below). The external name can also contain directory information (relative or absolute file names). Cross platform compatibility problems can occur when adding directory information to the external file names. This document proposes standards that maximize platform and database compatibility.
 

Determining External File Names

To access an external file (ISAM, Variable, Fixed) BuildPro uses the following rules:

1. If external name (as defined in table definition) begins with a slash "/" or backslash "\", BuildPro will use this name only.
    
2. In all other cases BuildPro will start with the DataPath as defined in the configuration file (.todayrc or wintoday.ini). For example: \BuildPro\data.
    
3. If there is a database name defined, BuildPro will add the external name of the database to the name string. For example if there was a database called sales with an external name of salesdata, the string would be: \BuildPro\data\salesdata
    
4. Finally BuildPro will add the name as defined in the Table definition. For a table named ledger with an external name ledger99, the string would be expanded to: \BuildPro\data\salesdata\ledger99.
    
5. Alternatively if the external name for ledger was "99\ledger" the string would be expanded to: \BuildPro\data\salesdata\99\ledger.

NOTE 1. The choice of "/" or "\" backslash added by BuildPro will be determined at runtime based on the operating platform.

NOTE 2. The value of DataPath may be changed at runtime to using the below command. Use this method to access different sets of data (fiscal year data, test/live data, company data etc):

*ENV("TDPATH") = "next data path"

Platform Compatibility

As explained above, the external name used in the table definition may contain a slash "/" or backslash "\". For cross platform compatibility it is recommended only to use forward slashes "/" as BuildPro will parse these at runtime depending on the operating system.

A test was conducted on several operating platforms. The results are shown below. The  represents ones that behaved as expected and represents ones that did not. C/S stands for Client Sever and S/A stands for Stand Alone.

The following test was performed by building ISAM files interactively from a process (i.e. not from the BuildPro Developer). The 2 lines used to create each file was:

*PASS = "-f <Table\View Name> -s -m3"
INTERNAL build_file
e.g.:
*PASS = "-f back1 -s -m3"
INTERNAL build_file

NOTE: Subfolders must be created manually for the file to be created within them (as in "\test\back3"). BuildPro must have read and write access to the directory.

As you can see backslashes "\" do not work at all on Unix but work on almost every other platform with the exception of NT in certain situations in stand alone mode. Therefore the best option to maintain portability across platforms is to use forward slashes "/" but to over come the fact that you cannot create files above the data directory in NT the files can be created dynamically using the method outlined above, in client server mode. Unix treats backslashes as a character so if you have \back1 as the external name the actual filename will be '\back1' in the data path.
For More Information on external name click here.

Database Name

The Database Name can be used to store the files within different subdirectories of the DataPath instead of having to specify the subdirectory in the External Name. Once again keep in mind that you have to create the subdirectory manually even though you specify it in database name. For example if you put the Database Name as test and Tables' External Name as back1, and the DataPath is set to C:\BuildPro\Data, then the file will reside in C:\BuildPro\Data\test\back1.
For More Information on database name click here.

Suggestions

Use the following as a guide line for external file referencing:

1. Set your default DataPath before starting BuildPro in the configuration file.
    
2. Reset the default DataPath at runtime using *ENV("TDPATH") based on the user name, selected application or other mode of operation.
    
3. If possible do not use subdirectory names in the table definition's External Filename. To allocated files into different subdirectories, use a database definition (you will appreciate this if you move to a relational database in the future).
    
4. If you need to add directory information to the External Name, only use forward slashes "/". These will work on all platforms.