Deutsch English
About tdbengine
First Steps
Runtime Switches
Text files
System functions
Database functions
Index functions
Full-text Indexing
Memos and BLOBs
Semaphore concept
Error codes
Hints for PHP developers
Basic Course
Function reference
Bug Reporting
Support request
Home    Overview    Search    Impressum    Contact    Members
Text files
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:

IF t:=Reset("ramtext:text:contents")
  CGIWriteLn('Contents of the text variable: <br><pre>')
  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):

SetPara('ec 1');
IF t:=Reset('text/mytext.txt')=0
THEN ... Error processing with TDB_LastError
  ... you can work with the text here
SetPara('ec 0');

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

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")

Performing replacements

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 modes

0 : 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

Configuration files

The tdbengine supports configuration files to a particular degree, which are built according to the following scheme:

[Group 1]
[Group 2]

Each entry can contain up to 255 characters.

For processing files of this kind, EASY has two functions SetIdent() and GetIdent().

SETIDENT(ConfigurationFile,Entry,Value) writes entry = value in configuration file
GETIDENT(ConfigurationFile,Entry) determines the value related to the entry

Entries are inserted in the form »Group.Entry«


   CGIWriteLn('content-type: text/html')
   SetIdent(ini,'Administrator.Name','Hans Huber')

This small program creates the file »test.ini« with following content:

Name=Hans Huber

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.

tdbengine Anwendungen im Web:

Open-Source Web CMS

Open-Source Bug-Tracking

Free wiki hosting

Open-Source Wiki-System

Kostenloses Foren-Hosting

Diät mit tdbengine 8-)

tdbengine chat

   Copyright © 2003-2004 tdb Software Service GmbH
   Alle rechte vorbehalten. / All rights reserved
   Last changed: 05.05.2004

Programmers Heaven - Where programmers go!