DEFINITION MODULE TransLog;

        (********************************************************)
        (*                                                      *)
        (*               Transaction logging                    *)
        (*                                                      *)
        (*  Programmer:         P. Moylan                       *)
        (*  Started:            16 March 1999                   *)
        (*  Last edited:        17 August 2025                  *)
        (*  Status:             OK                              *)
        (*                                                      *)
        (********************************************************)


TYPE TransactionLogID;          (* is private *)


PROCEDURE LogThreadID (logID: TransactionLogID);

    (* Puts a message showing our thread ID into the log, to help in    *)
    (* reading the log file.                                            *)

PROCEDURE SetProcname (name: ARRAY OF CHAR;  facility: CARDINAL);

    (* Sets process name and facility number for use in syslog messages *)
    (* and for making the pipe name if we use a pipe.  Must be called   *)
    (* before StartTransactionLogging if you plan to use syslog and/or  *)
    (* a pipe for the log messages.                                     *)

PROCEDURE SetSyslogHost (hostname: ARRAY OF CHAR);

    (* Sets syslogaddress to the IP address, in network byte order, of  *)
    (* the specified host.  If the lookup fails, leaves syslogaddress   *)
    (* unchanged.                                                       *)

PROCEDURE UpdateTopScreenLine (pos: CARDINAL; newstring: ARRAY OF CHAR);

    (* Puts newstring at position pos in our record of what should go   *)
    (* into the top screen line.  Rewrites that part of the screen if   *)
    (* the default context has the screen enabled.                      *)

PROCEDURE StartTransactionLogging
                           (LogfileName: ARRAY OF CHAR;  level: CARDINAL);

    (* Sets the transaction log file name, and enables logging.  The    *)
    (* level parameter means: 0 for none, 1 for disk, 2 for screen, 4   *)
    (* for pipe, 8 for syslog, and sums of these for multiple log       *)
    (* targets.  This can be called more than once, to change the log   *)
    (* file name or level.  On a second or later call the existing log  *)
    (* file is closed and the next log entry will cause it to be        *)
    (* reopened, possibly as a new file with a new name.  Similarly,    *)
    (* the pipe and syslog socket will be opened or closed if the       *)
    (* change in level requires this.                                   *)

PROCEDURE GetLogPrefix (LogID: TransactionLogID;  VAR (*OUT*) code: ARRAY OF CHAR);

    (* Returns the code used as a sessin ID prefix in the log. *)

PROCEDURE ReviseLogPrefix (LogID: TransactionLogID;  newchars: ARRAY OF CHAR);

    (* Modifies the first few characters of the session ID prefix. *)

PROCEDURE NILLogID (): TransactionLogID;

    (* Returns a NIL result of the correct type. *)

PROCEDURE CreateLogID (code: ARRAY OF CHAR): TransactionLogID;

    (* Creates a new logfile ID. *)

PROCEDURE DiscardLogID (VAR (*INOUT*) id: TransactionLogID);

    (* Discards a previously created logfile ID. *)

PROCEDURE LogTransaction (id: TransactionLogID;
                          VAR (*IN*) text: ARRAY OF CHAR);

    (* Puts id+text in the transaction log (if logging enabled). *)

PROCEDURE LogTransactionL (id: TransactionLogID;
                          text: ARRAY OF CHAR);

    (* Like LogTransaction, but for a literal text string. *)

END TransLog.

