C Library Functions - M_framework__journal (3)

NAME

M_framework__journal(3fm) - [M_framework__journal::INTRO] write program messages to stdout and/or a log file (LICENSE:PD)

Synopsis
Description
Examples
Author
License

SYNOPSIS

use, M_framework__journal , only : journal

DESCRIPTION

For large interactive programs in particular it is useful if all messages go thru a JOURNAL(3f) call. This makes it easy to write messages to a log file as well as standard output; to toggle time prefixes on and off; to turn on and off debug-mode messages; control output paging and create replayable input journals.
The primary use of JOURNAL(3f) is to create journal files for interactive programs that
       + provide various levels of verbosity on demand, often for
         debugging purposes.
       + can be replayed even when interactive input was provided
       + and/or be used to verify program executions
Typically, you would echo what the user typed to the trail file as-is, and write output you write to stdout as comments to the trail file so that the trail file can easily be read back in (by ignoring comments).
Even though there is essentially one procedure (journal(3f) calls that are more than just a single message have an action specified as the first parameter. This action might specify to open a log file, to change the "level" required by messages for them to appear, whether output it written as a comment or not, and on what files the output should appear. So the interface can be used in a very simple manner but has more options than is evident at first glance, as detailed in the man-page for journal(3f).
to stdout is written with WHERE=’SC’ in the JOURNAL(3f) call.
    >      :
    >      :
    > call journal(’O’,’my_trail_file’)  ! open trail file
    > ! write output to stdout as-is and as comment to trail file
    > call journal(output)
    > ! echo message to trail/log file only
    > call journal(’T’,userline)
    > ! write to stdout as-is and trail as a comment.
    > ! up to twenty scalar values of any intrinsic type are allowed
    > call journal(’SC’,’i1=’,i1,’i2=’,i2,’i3=’,i3)
    > ! for more complex messages you can build them with non-advancing
    > ! I/O journal calls, or build the message with internal writes
    > ! into a string and print that.

      I=10
      R=20.3
      ! write to stdout and trail file without advancing I/O
      call journal(’+SC’,’I=’,i)
      ! write to stdout and trail file without advancing I/O
      call journal(’SC’,’AND R=’,r)
writes to the trail file(s) are ignored unless a trail file was opened, but output continues to stdout by default.
That is, destinations ’T’ and ’C’ are ignored unless a trail file has been requested, allowing journal to be used with programs that do not generate trails or journals.
Note that with no parameters, the trail file is flushed.

EXAMPLES

The man-page for journal(3f) describes all the options for the

action field WHERE.
In addition to being used to generate a journal, the routine can be used for producing optional debug messages and timing information.

Sample program for debug messages:

program demo_journal !! showing creating debug messages use M_framework__journal, only : journal implicit none !! produces no output because trail is not on call journal(’D’,’*demo* DEBUG MESSAGE 001 IGNORED’) !! turn on debug messages call journal(’>’,’debug on’) !! produces output on stdout because debug mode !! is on but no named trail file call journal(’D’,’*demo* DEBUG MESSAGE 002 ON STDOUT’) !! open trail file call journal(’O’,’mytrail.txt’) !! debug messages now go to the trail file only call journal(’D’,’*demo* DEBUG MESSAGE 003 TO TRAIL’) !! or always to stdout and trail file only if on call journal(’DS’,’*demo* DEBUG MESSAGE 003 TO TRAIL’) !! close trail file so messages go only to stdout again call journal(’O’,’’) !! debug on stdout now call journal(’D’,’*demo* DEBUG MESSAGE 004 TO STDOUT’) !! turn off debug messages call journal(’<’,’debug off’) !! back to no output from the next message call journal(’D’,’*demo* DEBUG MESSAGE 005 IGNORED’) end program demo_journal

Sample program for trail messages with optional timing information:

program testit use M_framework__journal,only : journal implicit none call journal(’a single string A -should be on S’)

! add time prefix to output call journal(’%’,’%Y-%M-%DT%h:%m:%s.%x%u:%b’) ! call journal(’a single string B -should be on S with prefix’) ! change to CPU time and number of calls prefix call journal(’%’,’CPU_TIME: %c:CALLS: %C: %b’) ! call journal(’a single string B-1 -should be on S with prefix’) call journal(’a single string B-2 -should be on S with prefix’) call journal(’a single string B-3 -should be on S with prefix’) ! Other useful time formats: ! %E -- Unix Epoch time ! %e -- integer value of Unix Epoch time ! %C -- number of times this format is used ! %c -- CPU_time(3f) output ! %S -- seconds since last use of this format ! %k -- CPU time in seconds from system_clock call journal(’%’,’’) ! turn off time prefix ! call journal(’a single string C -should be on S’) ! call journal(’O’,’aaa.out’) ! turn on trail file call journal(’a single string D -should be on SC’) call journal(’a single string E -should be on SC’) call journal(’a single string F -should be on SC’) call journal(’O’,’’) ! turn off trail file ! call journal(’a single string G -should be on S’) call journal(’a single string H -should be on S’) call journal(’a single string I -should be on S’)

! build one line of output with intrinsic scalar values added call journal(’+sc’,’APPEND:’) call journal(’+sc’,’ integer’, 1234) call journal(’+sc’,’ and real’, 1234.5678) call journal(’+sc’,’ and double’,1234567890.123456d0) call journal(’+sc’,’ and logical’, .true.) call journal(’sc’,’’) ! end program testit

AUTHOR

John S. Urban

LICENSE

Public Domain

Nemo Release 3.1

M_framework__journal (3)

February 23, 2025

Generated by manServer 1.08 from 9d069ccc-44b2-4408-af31-98cd3f2e319b using man macros.

action field WHERE.
	In addition to being used to generate a journal, the routine can be used for producing optional debug messages and timing information.