/*
 * TraceOut(fmt, ...)
 *
 * outputs a formatted string a a trace file for debugging.
 * The file 'trace.txt' is opened on the first call and re-used when called again.
 * output is: "YYYY-MM-DD HH.MM.SS (format)\n".
 */
void trace_out(const char *fmt, ... ) {
// our static file handler
  static FILE *trace_file = 0L;

// create a data/time stamp "YYYY-MM-DD HH.MM.SS" into date_string
  time_t now = time(0L);
  char date_string[23];
  strftime(date_string, 256, "%Y-%m-%d %H.%M.%S", localtime(&now));

// check the file has been opened
  if (!trace_file) {
  // attempt to open the trace file
    trace_file = fopen("trace.txt", "a+");

    if (!trace_file)
      return; // hmmm, cant open the file, guess we can trace out
  }

// create a variable list for the unknown passed parameters
  va_list v;
  va_start(v, fmt);

// write out a line to the trace file {date/time} |{format_line}\n
  fprintf(trace_file, "%s |", date_string);
  vfprintf(trace_file, fmt, v);
  fputc('\n', trace_file);
  fflush(trace_file);
}