Manual Reference Pages - M_journal (3)

NAME

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

Synopsis
Description
Examples
Author
License

SYNOPSIS

use, M_journal , only : journal

DESCRIPTION

For interactive programs in particular it is useful if all messages go thru the JOURNAL(3f) routine. 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 can be replayed 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). So usually things that are read from user input are using output with WHERE=’T’ and output that usually goes to stdout is written with WHERE=’SC’ in the JOURNAL(3f) call.
    >      :
    >      :
    > character(len=256) userline, output
    > call journal(’O’,’my_trail_file’)  ! open trail file
    >      :
    >      :
    > do
    >    read(*,’(a)’,iostat=ios) userline  ! read user input
    >    if(ios.ne.0)exit
    >    ! echo user input to trail file
    >    call journal(’T’,userline)
    >    ! assume user input causes values i1, i2, and i3 to be calculated
    >    write(output,’(i0,1x,i0,1x)’)i1,i2,i3 ! build an output line
    >    ! write output to stdout and as comment to trail file
    >    call journal(output)
    >    !or you can specify the WHERE parameter and up to ten scalar values
    >    call journal(’SC’,’i1=’,i1,’i2=’,i2,’i3=’,i3)
    > enddo
In this example an output line was built with an internal write; but calls to journal(3f) with numeric values with and without advancing I/O turned on are often used for simpler output:
      I=10
      R=20.3
      ! write to stdout and trail file without advancing I/O
      call journal(’+SC’,’I=’,i)
      call journal(’SC’,’AND R=’,r)
writes to the trail file are ignored unless a trail file was opened with
      CALL JOURNAL(’O’,filename)
So that routines that do their output via JOURNAL(3f) can be used with and without programs generating trail files. That is, destinations ’T’ and ’C’ are ignored unless a trail file has been requested.
With no parameters, the trail file is flushed.

EXAMPLES

The man(1) page for journal(3f) describes all the options for the WHERE field. 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_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 call journal(’D’,’*demo* DEBUG MESSAGE 003 TO TRAIL’) !! close trail file so messages go to stdout again call journal(’O’,’’) !! debug on stdout now call journal(’D’,’*demo* DEBUG MESSAGE 004 TO STDOUT’) 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_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’) call journal(’%’,’CPU_TIME: %c:CALLS: %C: %b’) ! change time prefix 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

M_journal (3)

March 11, 2021

Generated by manServer 1.08 from 615a9376-acc6-423c-9340-c1f60ff661ac using man macros.

[UP]