Schema  > Products  > SRTransport  > Documentation  > Modules  > File
 

The File Module

The Flat-File transport module allows you to read records from and write records to data files. The files'  format must first be specified by entering field lengths and/or field terminators, a record terminator, and data start and end markers.

When writing records to a file, the file is truncated at the start of each transport operation.

In a Transport window, you can specify that either the source or the destination is a data file. Select Choose Source or Choose Destination from the 'Transport' menu, or double click on an empty icon well. In the dialog that follows, choose File. You will be asked to 'Open' a source file or 'Save' a destination file. Once you've selected a file you will return to the 'Transport' window. Double click in the icon well a second time and the File Transport Module window will appear.

You must define the file format before you read or write the file. The format can be defined in three ways:

• Specify the column format manually
• Default the format from the other side of the transport
• Import the column format from a BCP .ftm file.

Creating and Editing Fields

You can create, paste, copy and cut fields using the following menus and buttons.

Fields have the following attributes.

Name

For sources the name is the variable name that will appear in the 'expressions'. For destinations the name is for reference only.

Terminator and Length

Each field is specified with a fixed length or with a terminating character sequence [usually a single character like '|' (pipe), '\t' (tab) or ','(comma) ]. If a field has both a length and a terminator, then whichever results in the smaller field length is used.

If a field length of 0 is specified, the field length is unlimited, and it therefore must have a terminator.
Note: The 'string' type has a maximum length of 1000 characters.

You can use special characters in the terminator field. The following escapes are provided:

• \b space 
• \n line feed 
• \r carriage return 
• \t tab 
• \\ back slash 

Position

When field lengths are used this is the byte offset for the field (starts at position 1).

Type

The type of data in a file is always ASCII. However, as fields are read from the file, they are converted to 4gl variables of a particular data type. The supported types are:

 

string	A string with maximum length 1000 bytes.
integer	A 4-byte integer.
double	An 8-byte double.
hex	Unlimited length. Hexidecimal is read from the file, and can be either upper or lower case, and can optionally start with 0x (or 0X).
text	Unlimited length. Bytes are read from the file.
binary	Same as text.

The 4gl variables are used in the expressions in the Transport window. Data conversion can be done explicitly in those expressions, but it's most convenient to speicfy the datatype as it's parsed from the file.

The data type is not used when the file is the data destination.

Notice that the last field doesn't have a field terminator. The record terminator serves, in this case. For further information, see End of Record, below.

Options Pop-Up Menu

• Default Format
  SRTransport reads the 'other side' of the transport and creates a comma seperated file format to match.
• CSV Format Comma Seperated Values.
  When you manually add a field, the terminator used depends on how the field was added. Choosing 'CSV Format' will change all but the last terminator to commas, leaving the last empty.
• From BCP file
  You can import a file format from a Sybase BCP .fmt file. Binary file formats are not supported at this time.
• Field Terminator
  Allows you to quickly change the field terminator for all fields.
• Open in Workspace
  Asks the operating system to open the file. The application used depends on the file's extension.
• Open in Editor
  Opens the file in systems' default text editor.

End of Record - EOR

The End of Record terminator indicates the end of a record. The EOR terminator is recognized at any point as the record is parsed, even if not all fields have been read.

If the record terminator is encountered before all fields have been read, the unread fields are set to be NULL.

This feature is specially valuable when processing data exported by a spreadsheet, which often writes records with differing numbers of fields.

A terminator on the last field will behave similarly to that same terminator in the EOR field, with one notable difference. The EOR terminator is recognized ANYWHERE within the record; the field terminator is recognized only when all fields before it have been read.

In general, it's better to use an EOR terminator than a terminator on the last field, because SRTransport can better recover from a corrupt record in the datafile.

Beginning of Data - BOD

The Beginning of Data marker indicates the start of records in the data file. It is not necessary to have a BOD marker if records start immediately at the top of the file.

End of Data - EOD

The End of Data marker indicates the end of records in the data file. It is not necessary to have an EOD marker if there is no text after the data records.