System functions

GetDir	Determining actual directory
MakeDir	Making directory
DelDir	Deleting directory
ChDir	Changing actual directory
FirstDir	Determining the first entry of the directory
NextDir	Determining the next entry of the directory
DirInfo	Getting entry of the directory
today	System date
now	System time
DelFile	Deleting file
CopyFile	Copying file
CGIExec	Executing external program
DiskFree	Determining free place in the memory partition
GetEnv	Determining environment variable

General

Please note that CGI-programs have usually only the rights of an (in the majority of cases) anonymous internet user. At least the right to execute and read CGI-programs must be granted to him and the tdbengine must be contained in corresponding directories. In case that should be conversed, the right must be granted in accordance with its accesses (readonly, read and write) to the database directory. Even if no new tables should be created, an eventual full-text indexing may require the right for creating files as well.

Notwithstanding the fact that it doesn't entirely correspond to Internet security aspects, this is common in the case of CGI-programming that all rights are granted within the CGI-directory (and in sub-directories) to the anonymous Internet user. As a matter of course the directory should be never enabled via anonymous ftp! In doing so as a CGI-programmer you accept a lot of responsibilities since the Internet user can execute all programs available here. Because of this, you must take care that:

•   no foreign programs can be stored here, and
•   your programs do not allow misuse of themselves.

In case you install the administration CGI-programs on the internet (such as our program development kit), you should place them exclusively in a (via user identification) secured directory.

Determining current directory

Function GetDir returns the current directory. If the drive number is 0, then the current directory of the current drive is returned. There are no different drives under UNIX, therefore 0 must be always specified here.

Note: The tdbengine always points to the directory, where the executable prg-file is.

The function MakeDir() creates a directory in case the user has the rights for this operation. If the directory could be created, the function returns 0, otherwise it returns the error code of the operating system.

DelDir(Dir : STRING) : REAL

The Function DelDir() deletes the specified directory in case that the user has the permission for this operation. Only empty directories can be deleted. The function returns 0, if the directory was deleted, otherwise it returns the error code of the operating system.

The function ChDir() points to the specified directory DIR. It returns 0, if the change was successful, otherwise it returns the error code of the operating system.

NextDir : STRING

The path is a directory entry, wildcards are allowed as well. Under UNIX even extended patterns of the form "*abc" are possible. The Option is evaluated under Windows only. It is a string containig a combination of the following characters:

• D searches directories
• H searches hidden files
• S searches system files

In addition to that the search is always looking for simple files.

Note:There are modifications in comparison with prior VDP and TDB versions!

The result of the function is an empty string if no (subsequent) directory entry is present, otherwise a string with following structure:

For example: Output of all files with the extension "html" in directory "/home/tdbengine/doc"

Note: By the call of the function FirstDir() the tdbengine reads all acceptable directory entries and makes them available afterwards. On the next call of the function FirstDir() (and at the end of the program) this internal buffer is emptied again. This action has the following consequences:

• none of system resources are occupied
• function NextRec is an internal function of the tdbengine-package and gives no rise to a system call
• FirstRec - NextRec - sequences couldn't be interlaced

In case only the system data (date, size, presence, etc.) of a single file shall be retrieved, then the function DirInfo() may be used instead:

The function returns the same result as the function FirstDir(Path,''), but it can be also used within a FirstDir() - NextDir() - sequence.

Today() returns the current date as days since the 1.1.1900. The call of DateStr(Today) returns the current date as string.

Now() returns the current time as number of minutes since midnight.

Note: The function Frac(now)*60 gives the seconds with a resolution of 1/1000 s.

The call of TimeStr(Now) returns the current time as string.

For example:

General file function

This function deletes the file specified by Path where no directory is involved and if the anonymous http-user has the right to do that. Under Windows an eventually existing write protection is ignored. DelFile() returns 0 if the file could be deleted, otherwise it returns the error code of the operating system.

CopyFile(p_from, p_to : STRING) : REAL

Using this function a copy of a file is created.

p_from must be:

• any path within the directory tree
• internal text file (ramtext)
• URL (only http://*, version 6.2.6 or higher)

p_to must be:

• any path within the directory tree
• internal text file (ramtext)
• "con" (for standard output)

Note: In the case of copying a file via the function CopyFile() to the standard output, the function CGICloseBuffer() must be called at first, because the function CopyFile() bypasses the cgi buffering.

CGIExec(commandline : STRING [; s_timeout : REAL]) : REAL

This function executes an external program.

The parameter s_timeout is (for the time being) evaluated only under Win9x / WinNT.

After the called program was executed completely, it passes the control back to the CGI-program. In such a case the function returns 0, and in all other cases it returns the error code of the operating system. The called program takes over the input and output channels of the CGI-program. Thats why the output buffering must be completed before executing (because the external program can't write into the buffer of the tdbengine).

Features

The program is directly started. s_timeout sets the maximum available time (in seconds) that the started program has for execution. If afterwards the program should be interrupted ahead of schedule, the function value is 1. If the value of 1 should be set for the function s_timeout, the program would be completely executed, but the output would be suppressed. This way should be preferred over the output-pipe in any case. The rights of the executed program are deduced from the rights of the internet-client.

For example:

correct: (pkzip25.exe is placed in /home/tdbengine/)

correct: (cmd.exe is placed in /home/tdbengine/)

false: (cmd.exe and pkzip25 are placed in /home/tdbengine/)

correct: (pkzip25.exe is placed in /home/tdbengine/)

CGIExec('pkzip25.exe -add backup.zip *',-1) .. creates backup.zip without output

Restriction: CGIExec() can (at least without problems) execute only true 32-bit applications.

Linux:

The command line of CGIExec() is transferred to the shell of the internet-client with all corresponding rights.

Note: Here the output-pipe is the recommended way for suppressing the output of the called program.

For example:

Notes:

You must use CGIExec() always with extreme caution. No experiments!
Disable simultaneous calls by applicable semaphores (at first by archive programs).
Consider that each CGI-process has only restricted time at its disposal (adjustable in http-server).

drive: 0 = current drive (Win32)  or memory partition, where the current directory is placed (Linux, FreeBSD)
        1 = A: (only Win32)
        2 = B: (only Win32)
        ...

Return value: Free space in drive / memory partition or -1, if drive is not available.

The function GetEnv() returns the value of the environment variable with the specified Name.

In addition a ramtext with the name "ramtext:environment" is available, which contains the environment variable as well. Thats why an environment variable can be accessed even when its content is more than 255 characters.

For example: