Net.Data Programming Guide

Flat File Interface

If you chose to use flat files (or plain-text files) as your data source, you can use the flat file interface (FFI) and its associated Net.Data functions to open, close, read, write, and delete files on the Web server. You must specify a path for the FFI_PATH variable in the initialization file.

What is FFI?

The file language support uses FFI functions to read from or write to files on the Web server at the Web client's request through the browser. FFI views the file as a record file, each record equivalent to a row in a Net.Data macro table variable, and each value in a record equivalent to a field value in a Net.Data macro table variable. FFI reads records from a file into rows of a Net.Data macro table, and writes rows from a table into records.

Security Considerations

You can specify which files FFI functions can access with the FFI_PATH statement in the Net.Data initialization file. FFI only searches the paths listed in the statement, so files in other directories are safe. This is an example statement:

FFI_PATH     C:\public;.\;E:\WWW;E:\guest;A:

The paths listed in FFI_PATH are searched from first to last. The first copy found is used. If the FFI_PATH is not in the initialization file, FFI attempts to find the file in the current directory or with the path, if one is given (for example, ../reports/nov96.txt). The Net.Data initialization file is shipped without FFI_PATH.

Plan ahead before setting up FFI. Consider these points:

• Choose which directories are appropriate to use for flat file operations. These directories need to be added to the FFI_PATH to limit searching to those directories.

• Use care letting people perform DTWF_REMOVE or other export operations in the macro to prevent people from removing or altering files with extensions .dll and .cmd that you might have in the current directory.

• Take appropriate steps to safeguard the files on the system by using reasonable control over what macros are added to the system.

• Do not specify a path in FFI_PATH that lets anonymous FTP users write to the path. If you do, somebody can put a Net.Data macro on the system that allows actions which were not previously allowed.

• We recommend not adding the path of the Net.Data initialization file to the FFI_PATH.

Other Considerations

General considerations

• You can import any plain-text file, but Net.Data macro syntax is interpreted by Net.Data and HTML tags that might be in the text are used to format the text by the browser.

• The FFI parameters are case sensitive only if the operating system is case sensitive.

Current directory

• The current directory for Net.Data is normally \www\cgi-bin, but depends on the configuration of your Web server. If the server's default request routing or resource mapping is changed, the current directory might be changed also.

• The suggested way to refer to the current directory in the FFI_PATH is with a dot and a slash such as .\. Adding the dot and slash in front of a file name in the FILENAME parameter indicates that the FFI looks only in the current directory. For read operations, this indicates that other paths in the FFI_PATH are not searched.

DELIMITER parameter

• The delimiter is the flag or separator that FFI uses when dividing the file into parts (such as columns of a row) according to the requested transform.

• For read operations, the delimiter separates the contents of the file into rows and columns of a table. For write operations, the delimiter is placed in the file to indicate the end of a value in a table row and column. The delimiter is passed to the FFI as a Net.Data macro string. A null character is not included at the end of the characters unless explicitly listed in the delimiter parameter. This means that to use the null character in the delimiter, the delimiter parameter should be specified with "\0" (a backslash and a zero in double quotes) instead of an empty string by using "" (two double quotes). If the ASCIITEXT transform is specified, the newline character is used for the delimiter and any requested delimiter is ignored.

• Undesirable changes to a file may occur if a different delimiter is used for write operations than was used for read operations. If a different delimiter is used for write than was used for read, the file is written with the new delimiter.

• The maximum length of a delimiter is 256 characters.

FFI_PATH

• Paths in FFI_PATH must contain valid printable characters. FFI does not allow paths that include ? (question mark) or " (double quote).

• Subdirectories of the paths listed in FFI_PATH are not searched unless explicitly specified in FFI_PATH. For example, FFI does not consider .\test (in the FFI_PATH) to be an exact match of the directory test (that might be found at the beginning of the FILENAME parameter). So to find a file called myfile.txt in the subdirectory called test, the path .\test must be in the FFI_PATH and the FILENAME parameter should be either .\test\myfile.txt or myfile.txt. This is different from requesting test\myfile.txt in the FILENAME parameter and including the current directory in FFI_PATH, which does not work.

• If the current directory is not explicitly specified in FFI_PATH, it is searched last, after all explicitly specified paths listed in FFI_PATH.

DTWF_SEARCH function

• The table returned for DTWF_SEARCH has three columns. The first two columns contain the row and the column number where the match was found; the last column contains the column value that contains the characters specified in the SearchFor parameter. For example, if the fourth row of the file contains matching characters in column three, the returned table has a row with the number "4" in the first column to indicate the row of the file that it came from; it has a number "3" in the second column to indicate which column of the file contains a match; and it has the complete column value in the third column.

• The SearchFor parameter cannot include the contents of the delimiter parameter.

STARTROW and ROWS parameters

• For DTWF_DELETE, DTWF_INSERT, DTWF_UPDATE and DTWF_WRITE, if a StartRow value larger than the last row is specified, StartRow is changed to indicate the last row and an error is returned.

• For DTWF_READ and DTWF_SEARCH, the Rows value is returned as the number of rows in the table.

TABLE parameter

• The maximum length of a row in an FFI table is 16383 characters. This limit includes a null character for each column in the Net.Data macro table.

TRANSFORM parameter

• This parameter indicates how the file is divided into parts with respect to the rows and columns of a Net.Data macro table. For example, ASCIITEXT transform means that each line of the file corresponds with a row of a Net.Data macro table and the Net.Data macro table has only one column. DELIMITED transform means that the characters in the row are examined to find the DELIMITER and after the DELIMITER is the content of the next column.

• A newline character in a file indicates the end of a row of a Net.Data macro table for ASCIITEXT and DELIMITED transforms.

• Files are not locked unless you open them with DTWF_OPEN. If a file is not locked, it can change between the time it is read and updated. This can result in the loss of the previous changes. Using DTWF_OPEN opens the file during the execution of the macro using the file system's locking mechanism.

• The current contents of a file affect the results of using DTWF_APPEND, especially the contents of the last column of the last row. If a newline follows the last column value of the last row of the file, appended data is placed in a new row. Otherwise, appended data becomes part of the last row of the file.