Keywords

Introduction

A file in accordance with the geotechnical exchange format can be divided into two parts: the header and the data block. The header describes how the registered data is organised in directly readable text. Keywords are used for this purpose. A keyword is preceded by a ‘#’ character. A ‘=’ character follows the keyword. The keyword is therefore enclosed between the ‘#’ and the ‘=’. Some examples of correct and incorrect keywords are given in Table 1.

Table 1: Examples of correct and incorrect keywords

Several conditions exist for keywords and their information. A keyword with accompanying information must always be on one line: no ‘end of line’ LF or CRLF may appear in the information. If the information following the ‘=’ characters consists of several parts, it is separated by commas. The end of the information is specified by the start of a new keyword with a hash (#).

Special characters.

A comma (,), equals sign (=) and a hash (#) are therefore special characters. If these characters appear in an information field after a keyword, it must be indicated that the literal meaning of the character is now required. The backslash is used for this purpose: \# \= or \, This also makes the backslash a special character so that if a literal backslash is required in the text, this must also be preceded by a backslash.

There are currently (October 2007) 59 keywords, but the flexibility of the geotechnical exchange format is such that new keywords can be created if required. Expansion nonetheless has consequences for the applications capable of decoding the keywords. These must be adjusted, see versions. Each keyword identifies some information. The information, i.e. text and/or numbers, must be placed after every keyword. The only exception is the keyword which indicates the end of the measurement description (#EOH=). Which information and how much depends on the keyword itself.

Several conditions must be met if the test is to be meaningful: a minimum description of how the file is organised must be known. This leads to a division of keywords into compulsory, non compulsory and conditionally compulsory keywords. The last category consists of keywords which are in fact compulsory, but for which a default value has been filled in. If the word is therefore not listed, the standard value is used. If the default value is not suitable as a result of another keyword, the word must still be given. It is therefore compulsory under certain conditions. The compulsory keywords are given in Table 2

Compulsory keywords.

Table 2: Compulsory keywords.

Table 2 forms the minimum subset of keywords. A file which complies with the geotechnical exchange format uses of all these keywords at least. If one or more of the compulsory keywords are missing then an application should stop automatically processing the data and signal the missing keyword. The test is incomplete. Optionally, the application can query the user so that the missing information can be found. The remaining keywords are given in Table 3.

Non-compulsory and conditionally compulsory keywords.

Table 3: Non compulsory and conditionally compulsory keywords.

The keywords are subdivided into four logical categories:

• File tracing

• File descriptive

• Data descriptive

• Procedure descriptive

The first and second categories ensure the direct usefulness of the file. The third and fourth category state how the numbers in the header should be interpreted, what they represent and how (via which procedures) the data in the file was obtained.

File tracing keywords allow the user to find out who created the file. It traces back to the organisation which set up the file and to the activities in the framework within which they were collected. This deals with readable data which can be interpreted without any knowledge about the type of measurement.

File descriptive keywords give information about the file itself, how the file is organised, how it should be read, and the structure of the file components. This is also concerned with readable data which can be interpreted without any knowledge about the file.

Data descriptive keywords state how the data is stored, what the numbers mean, and in which unit a quantity is listed.

Procedure descriptive keywords state which procedures have been followed, such as how the measuring, sampling, analysing, archiving and reporting activities have been carried out, which additional information was received or was required, and which calculation method was used. Interpretation of the data belonging to these keywords is only possible if the procedure used for the measurement or analysis is known.

[Non]Compulsory and conditionally compulsory

In addition to these categories, a division can also be made into compulsory and non compulsory. The compulsory keywords are given in Table 2. These keywords form the file tracing and file descriptive categories. The compulsory keywords are the minimum requirement concerning the occurrence of keywords with which a GEF file must comply. There are also non compulsory keywords or conditionally compulsory keywords.

Conditionally compulsory keywords are sometimes compulsory, depending on the occurrence of another keyword. If, for example, binary data are recorded, not only must the fact that binary data are recorded be stated, but also the size in bytes of each measurement and in which sequence the bytes are written. This information is not necessary for ASCII values.

Parts of the information following keywords which can be omitted are given between [] in the typescript. Abbreviations are used to characterise the information, as given in Table 4. E.g. 4Value represents a value of 4 bytes in size, sUnit states a string which describes the unit.

Data types.

Table 4: Types of variables and their abbreviations.

Versions.

The set of keywords is not static. Keywords may be added, keywords may become obsolete. Therefore there are versions.  Versions keep track which keywords are allowed. The version of the GEF language which is used in a file, is expressed by its GEFID. By reading the GEFID any functions processing a GEF file, can determine whether the software has sufficient capabilities to process this file. Currently there are three legitimate versions of a GEF file:

• 1, 0, 0   This is the original version. [1999].
• 1, 1, 0   This version adds two new keywords. [2000]
• 2, 0, 0   This release adds seven new keywords. Three others became obsolete. [2007]

#GEFID = 1, 1, 0

In version 1, 1, 0 the keywords Parent and Child were added. If a file mentions either Parent or Child, it must be at least GEFID 1, 1, 0. A lower version will trigger an error.

#GEFID = 2, 0, 0

In version 2, 0, 0 the keywords Qnminmax, Qntime, Qnvoid, Row, Setupcode, Setuptext and Setupvar were added. The setup keywords were introduced to provide better means to document preparations of a test. The QN keywords are introduced to provide an easier and more robust relation with the data block, unlike their Column- counterparts. The QN versions lack their dependence on the actual position of a column in the data block. The Row keyword is introduced additionally to the Column keyword: a mere description of the number of rows in the data block. When these keywords are to be used in a GEF file, its GEFID must be 2, 0, 0 or heigher. A lower version will trigger an error. 

The keywords Firstscan and Lastscan are withdrawn. In a file with #GEFID = 2, 0, 0, they are ignored. Potentionally these keywords provide danger to inadvertedly shrink the size of a file. The keyword Equipment became obsolete, since the Setup keywords provide ample opportunities for a more detailed description of the equipment used than just one keyword. In a file with #GEFID = 2, 0, 0, it is ignored. Although these three keywords are withdrawn, users may keep using them. They are still valid in files with #GEFID = 1, 1, 0 or lower.