Socket errors

Trapping a socket error

A TCP/IP socket error can be trapped in a Sculptor program by setting the system variable sys.ServerErrorFunction to point to an event function that is called if an error occurs. Sculptor calls the function with the following arguments:

func_id(server, errcode, dirn, maincode, subcode)

The arguments have the following meanings:


The server name. This is a text value.


The system error code.


Indicates the error type as follows:

0 = error on sending a command to the server.
1 = error on reading response from the server


The Sculptor main command code.


The Sculptor sub command code.

The dirn, maincode and subcode values are provided for diagnostic purposes. Whatever the dirn value, the command may or may not have reached the server. The best way to guard against application errors caused by socket errors is to wrap related updates between calls to the begin()and commit() functions.

The function can exit the program or return one of the following values:


Display a standard socket error message and exit the program.


Continue running the program. The command or function that was being executed when the error occurred will return with an error if possible (e.g. if it has an err = trap), otherwise with a null result. Continuing is not normally a viable option, since the program’s connection to the server has been lost, and the command or function that was being executed has failed. However, it is technically possible to re-establish a connection if the cause of the error has been corrected. Note that a program cannot issue a rollback() on a new connection. When the previous connection times out, kfserver will issue an automatic rollback().


Abort the program without displaying an error message.


     sys.ServerErrorFunction = &ServerError

!function ServerError(server, errcode, dirn, maincode, subcode) {
     error "Error " + tostr(errcode) + " on server " + server
     return 1

Recovering after a socket error

Sculptor provides functions that enable a program to recover from a socket error.

After connecting to a server, the program calls the get_client_info() function and saves the port and id values returned by the function into a local file. Before exiting, it clears these values. If, on starting, the program finds these values still set, it calls the disconnect_client() function to reconnect itself and to make sure that its previous instance is no longer running. If disconnect_client() returns a value greater than zero, the program should assume that the previous connection has already timed out.