BBjConfig::releaseOnLostConnection

Description

In BBj 2.01 and higher, this method controls whether to terminate the Interpreter session immediately if the client side of a thin client connection dies unexpectedly.

Syntax

Parameters

Return Value

None.

Remarks

By default, the interpreter thread of a thin client connection is terminated if the client connection terminates unexpectedly. The application developer can choose to trap this event and do some final cleanup before terminating the interpreter thread. When releaseOnLostConnection() is set to false, the interpreter thread generates an interrupt signal if the client connection is dropped unexpectedly. This interrupt can trapped with a standard SETESC handler, which should do something like the following:

IF and(chr(tcb(19)),$08$)=$08$ THEN gosub cleanup; release

The cleanup routine must not attempt to communicate with the client session, since the client no longer exists. Any such attempt might generate a runaway error/retry situation as the program repeatedly attempts to communicate with a nonexistent client.

Example

rem 'Demonstrate how to terminate a session if a client connection is lost

rem 'The interpreter will generate a SETESC interrupt if the client is lost
SETESC escape

rem 'Set the releaseOnLostConnection setting to false. This means
rem 'that the application is responsible for cleaning up and releasing
rem 'the interpreter if a thin client connection terminates unexpectedly.
BBJAPI().getConfig().releaseOnLostConnection(0)

rem 'Create a text file and start writing to it
let log$="test.log"
ERASE log$,ERR=*NEXT
STRING log$
let log = UNT
OPEN (log)log$
LOCK (log)

rem 'Write to the file until interrupted
while 1
    PRINT DATE(0:"%Ml %D %Yl %Hz:%mz:%sz")
    WRITE (log)DATE(0:"%Ml %D %Yl %Hz:%mz:%sz")
    WAIT 1
wend

rem 'If a thin client connection is lost, TCB(19) bit $08$ will be set ON.
escape:
    if AND(CHR(TCB(19)),$08$) = $08$ then GOTO cleanup
    ESCAPE
return

rem 'Since the client no longer exists, the cleanup routine must not
rem 'attempt to communicate with the client. It should do whatever
rem 'cleanup is necessary, then release the interpreter session.
cleanup:
    if log then WRITE (log,ERR=*NEXT)"Client connection lost"
release
END

See Also

BBjAPI

BBjConfig

See the BBj Object Diagram for an illustration of the relationship between BBj Objects.