You are here:

startlog()

startlog() opens an error log file. It uses the syntax CALL startlog and takes a filename or other variable as its argument. That filename, can include a path name and file extension, is a string that specifies the error log file. The variable can be a CHAR or VARCHAR datatype that includes the filename details.

All the file names you use in your 4gl development must be platform-independent.

If you use platform-dependent names (e.g., combine upper and lower case, use colons, finish names with a full stop, etc.), please remember that they might cause different problems when you move your project to another platform.

In Q4GL, startlog() has two new arguments, path and facility. The path argument defines the path in which the logfile is to be written.

The path can include $-style environment variable substitutions

If the filename begins with '!', then it will be appended to.

Also, certain other values are legal:

filename, filename - the second filename specifies an input file
stderr: - the standard error device
null: - thrown away
handle:nnn,[nnn] - a file handle (the optional,nnn specifies an input handle)

NB: facility [ default = "user" ]

This indicates what facility the log information is being set for. Current facilities include:

user
debug (don't override this if you want to use the debugger)
database - the database subsystem
(an empty string) - the default logging path
database.<database-driver> - logging information only for the specified database

Also new facilities can be defined as needed and accessed using the "systemlog" function

This is a typical sequence to implement error logging:

Call startlog( ) in the MAIN program block to open or create an error log file.
When an error is encountered, use a LET statement with ERR_GET(status) to retrieve the error text and to assign this value to a program variable.
Use errorlog( ) to make an entry into the error log file.

The last two steps are not needed if you are satisfied with the error records that are automatically produced after startlog( ) has been invoked. After startlog( ) has been invoked, a record of every subsequent error that occurs during the execution of your program is written to the error log file.

The default format of an error record consists of the date, time, source module name and line number, error number, and error message. If you invoke the startlog( ) function, the format of the error records that 4GL appends to the error log file after each subsequent error are as follows:

Date: 03/06/99 Time: 12:20:20

Program error at "stock_one.4gl", line number 89.

SQL statement error number -239.

Could not insert new row - duplicate value in a UNIQUE INDEX column.

SYSTEM error number -100

ISAM error: duplicate value for a record with unique key.

You can also write your own messages in the error log file by using the errorlog( ) function.

With other 4GL features, the startlog(), err_get(), and errorlog() functions can be used for instrumenting a program, to track how the program is used. This use is not only valuable for improving the program but also for recording work habits and detecting attempts to breach security.

Unless you specify another option, WHENEVER ERROR CONTINUE is the default error-handling action when a runtime error condition is detected. The WHENEVER ERROR CONTINUE compiler directive can prevent the first SQL error from terminating program execution.

Specifying the Error Log File

If the argument of startlog() is not the name of an existing file, the function will create a file of that name. If the file already exists, startlog() opens it and positions the file pointer so that subsequent error messages can be added to it. The following program fragment invokes startlog(), specifying the name of the error log file in a quoted string that includes a pathname and a file extension. The function definition includes a call to the built-in errorlog() function, which adds a message to the error log file.

MAIN

DEFINE x TEXT

OPEN WINDOW Error_log AT 5,5 WITH 3 ROWS, 25 COLUMNS

CALL startlog("errors.txt")

CALL errorlog ("Error 1 in my log")

CALL errorlog ("Error 2 in my log")

CALL errorlog ("Error 3 in my log")

CALL errorlog (err_get (-999))

LOCATE x IN FILE "errors.txt"

DISPLAY x

CALL fgl_getkey()

END MAIN

In this example, text written to the error log file merely shows that control of program execution has passed to the startlog() function rather than indicating that any error has been issued.

For portable programs, the file name should be a variable rather than a literal string. As in other file name specifications, any literal backslash ( \ ) that is required as a path name separator must be entered as two backslashes.