Text files are an important factor in the context of CGI-programming. E.g. templates and session information is normally stored in a text file and read from it again. Configuration files are also of importance, because they set the behavior of programs and can replace so-called system databases in many cases.
A special form of text files are the virtual texts of the tdbengine. Such texts exist only during runtime of a program in the memory. At present they are limited to 2 Gbytes. The advantage of virtual texts on the one hand is in the fast processing, on the other hand in the partial compatibility with simple strings. Thus, for example, the functions OemToAnsi() and AnsiToOem() are applicable to virtual texts as well.
Virtual texts are distinguished by the fact that its file name begins with "ramtext:". The name of this file corresponds to the rest of path.
"ramtext:name1" corresponds to the virtual text "name1".
A special virtual text has the name "ramtext". It is initialised by the CGI-functions: LoadTemplate() and CGIWriteTemplate() and builds the base of the template function: Subst().
CGI-variables with the name "text:..." create automatically virtual texts with the same name.
In a HTML-form following construction is located:
<textarea cols=60 rows=20 name="text:inhalt"></textarea>
The program, which is called by pressing a submit-button, can access the contents of the textarea via the virtual text: "ramtext:text:contents" and, for example, can be read as follows:
VAR t : INTEGER
CGIWriteLn('Contents of the text variable: <br><pre>')
WHILE NOT EOT(t)
CGIWriteLn('Error: Text variable NOT found<br>')
Opening a text file
Reset(path : STRING) : INTEGER
Reset() opens a text file for reading
Rewrite(path : STRING) : FileHandle INTEGER
Rewrite() creates a new text file and opens it for writing
TAppend(path : STRING) : INTEGER
TAppend() opens an existing text file to append more text at its end.
Important: If the function result is 0, you must not write in this file or read from it by any means!
Expert's advice: The FileHandle 0 represents the console. With its help you can directly access the channels stdin and stdout. But you should be aware that stdin is completely read by the initialization of the CGI-variable. A call of Read() or ReadLn() with the FileHandle 0 acts always in a manner that the CGI-program hangs up, because it waits for input, which will never come!
If the text file can not be opened for any reason (file is not available, right for creating a file is not granted, etc.), a runtime error is generated. This can be caught by SetPara('ec 1') (see Runtime switches):
THEN ... Error processing with TDB_LastError
... you can work with the text here
Reading from text files
Read(filehandle : INTEGER[,nchars | delchar : CHAR]) : STRING
ReadLn(filehandle : INTEGER) : STRING
Both read functions return a string up to a maximum of 255 characters. The Read() function reads all characters, the ReadLn() function reads until the carriage return (asc(10)), thereby line feed (asc(13)) is omitted. Both functions finish the reading, when the physical file end or ^Z is reached.
If none of the optional parameters is passed to Read(), exactly one character is read. If nchars (INTEGER) is given, (a maximum of) nchars characters are read. If on the contrary a delchar is given (for example, ^I=TAB), thus it is read up to this character. The character itself is not given back. In each case a maximum of 255 characters are returned.
Writing into text files
Write(filehandle : INTEGER; s : STRING) : STRING
WriteLn(filehandle : INTEGER; s : STRING) : STRING
The function WriteLn() writes a combination of carriage return and line feed after the string in the file.
Closing a file
Close(filehandle : INTEGER) : INTEGER
The result of Close() is the input/output error code of the operating system.
Obtaining the end of a file
EOT(filehandle : INTEGER) : 0|1
The typical case is shown below, when a whole text file is processed:
IF t:=Reset(pfad_zur_datei) THEN
WHILE NOT EOT(t) DO
Working with templates
A template is a text module, which is initially loaded into the RAM for carrying out replacements within this text. In most cases HTML-pages or its extracts are involved here. Thus it is possible to work with web-designers in the team.
Loading a template
LoadTemplate(Path : STRING) : INTEGER
Corresponds to the function call CopyFile(Path,"ramtext")
Output of a template
CGIWriteTemplate : INTEGER
Corresponds to the function call CopyFile("ramtext","con")
Subst(Source : STRING; DbNo : INTEGER; Field : INTEGER|STRING [; Mode : INTEGER]) : 0|1
Subst(Source,Target : STRING [; Mode : INTEGER]) : 0|1
DbNo is a database handle, which is created by OpenDB().
Field is either a field number or a field identifier as string
Target is a string. If the string begins with "external:" or "ramtext:", then a corresponding external text is signalized therewith:
external: the rest of the string represents a file name
ramtext: the rest of the string represents a Ramtext or a CGI-variable, whose name begins with "text:".
Mode is a supplement of the separate main modes0 : standard replacement without processing (default)
1 : is translated into HTML before the replacement
2 : replacement is carried out in the ANSI character set
4 : LF is replaced by LF+'<br>'
8 : ExtNote is deleted after the first replacement (only in connection with 1)
16: External text is in the ASCII character set (only in connection with external texts)
32: Only Body-part is read (only in connection with external HTML-texts)
The function result is 1, if the replacement was carried out (also in the positive case), otherwise it is 0. For replacing all occurrences for example, the following construction can be also used:
WHILE Subst(....) DO END
The tdbengine supports configuration files to a particular degree, which are built according to the following scheme:
Each entry can contain up to 255 characters.
For processing files of this kind, EASY has two functions SetIdent() and GetIdent().
||writes entry = value in configuration file
||determines the value related to the entry
Entries are inserted in the form »Group.Entry«
VARDEF ini : STRING
This small program creates the file »test.ini« with following content:
Note: Then the created file is also displayed on the screen/in the browser. The use of CGICloseBuffer() is important here for flushing out the internal buffer before the copying function.
The separate entries can be read with GetIdent().
GetIdent('test.ini','Administrator.Name) -> 'Hans Huber'
GetIdent('test.ini',Database.Addresses) -> 'database/adresses.dat'
Note: A configuration file is read into the memory of the computer on first access and then is given to the program in a tree structure. That's why the access is extremely fast.