[UP]


Manual Reference Pages  - journal (3)

NAME

journal(3f) - [M_journal] provides public message routine, no paging or graphic mode change (LICENSE:PD)

CONTENTS

Synopsis
Description
Options
Example
Author
License

SYNOPSIS

subroutine journal([where,],[VALUE(s)])

    character(len=*),intent(in) :: where
    character(len=*)|real|integer|doubleprecision|complex,optional :: g1,g2,g3,g4,g5,g6,g7,g8,g9

    WRITE MESSAGES

basic messages

      call journal(where,[VALUE(S)])
      call journal(message) # a shortcut for "call journal(’sc’,message)":

    OPEN OR CLOSE TRAIL FILE

trail file

      call journal(’O’,trailfile_name) # open trail file
      call journal(’O’,’’)             # close trail file

    SET OUTPUT TIME PREFIX

set the function display format for timestamps. See the NOW(3f) procedure for allowable timestamp macros

      call journal(’%’,time_stamp_prefix_specification)

    MODES

Turn on/off writing DEBUG messages to trail file

      call journal(’>’,’debug on’) # turn on debug mode
      call journal(’<’,’debug off’) # turn off debug mode

    ASSIGN STDOUT TO AN ALTERNATE FILE

change stdout to iunit and open filename; or close unit and go back to stdout if filename=’’

      call journal(iunit,filename)

change stdout to iunit to use a file already open

      call journal(iunit)

DESCRIPTION

If a user procedure is used for outputting messages instead of calling WRITE(3f) it is easy to provide control of when messages are printed (ie. a "verbose" mode, or "quite" mode), creating files to replay program execution, duplicating output, ...

OPTIONS

WHERE indicates where messages are written. A combination of the following characters can be used...

Usually one of these to write to the standard output files ...
S write to stdout or iounit set with journal(unit) or journal(unit,filename).
E write to stderr
And one of these to write to trail file (ignore if no trail file defined) ...
C write to trail file as a comment (if file is open) Writing output "as a comment" means it is preceded by a pound(#) character.
T write to trail file (if file is open)
Usually used by itself
D write to trail file as a comment with "DEBUG:" prefix in front of message (if file is open) if debug mode is on. Write to stdout if no trail file and debug mode is on.
Modifier for S|E|C|T|D specifiers
o subsequent files are written to with advance=’no’. Position is important. ’+sc’ does an advance=’no’ on both files, ’s+c’ only does the advance=’no’ for the trail file.
Mode changing options used by themselves:
> turn off debug messages
< turn on debug messages
O open trail file using value of "message" parameter or close trail file if no filename or a blank filename.
A Auxiliary programs that also want to write to the current log file (a2b, z2a, ...) call this routine to see if there is a trail file being generated and then add to it so that a program like ush(1f) can call the auxiliary programs and still just generate one log file, but if the auxiliary program is used as a stand-alone program no trail is generated.

VALUES(S)
  message to write to stdout, stderr, and the trail file. a numeric or character value to optionally be appended to the message. Up to nine values are allowed. The WHERE field is required if values are added.
FILENAME
  when WHERE="O" to turn the trail file on or off, the "message" field becomes the trail filename to open. If blank, writing to the trail file is turned off.
TFORMAT
  when WHERE="%" the message is treated as a time format specification as described under now(3f).

EXAMPLE

Sample program:

   program demo_journal
   use M_journal, only : journal
   !! BASIC USAGE
   call journal(’write to standard output as-is, and trail file as a comment if open’)
   ! since we have not opened a trail file yet, only stdout will display output
   call journal(’c’,’ignored, as trail file is not open’)
   ! now open trail file "trail"
   call journal(’o’,’trail’)
   call journal(’sc’,’same thing except now trail file is open’)
   ! only write to trail file if open
   call journal(’c’,’not ignored, as trail file is open. Written with # suffix’)
   call journal(’t’,’not ignored, as trail file is open. Written as-is’)
   ! turn off trail file
   call journal(’o’,’’)
   end program demo_journal

Adding intrinsic scalar values to the message:

   program test_journal
   use M_journal, only: journal
   implicit none
      call unit_check_start(’journal’)
      call journal(’S’,’This is a test with no optional value’)
      call journal(’S’,’This is a test with a logical value’,.true.)
      call journal(’S’,’This is a test with a double value’,1234567890.123456789d0)
      call journal(’S’,’This is a test with a real value’,1234567890.123456789)
      call journal(’S’,’This is a test with an integer value’,1234567890)
      call journal(’STDC’,’This is a test using STDC’,1234567890)
      call journal(’stdc’,’This is a test using stdc’,1234567890)
      call journal(’o’,’journal.txt’)                        ! open trail file
      call journal(’S’,1,12.34,56789.111111111d0,.false.,’a bunch of values’)
      ! the combinations that make sense
      call journal(’st’,’stdout and trail’)
      call journal(’s’ ,’stdout only’)
      call journal(’t’ ,’trail only’)
      call journal(’sc’,’stdout and trail_comment’)
      call journal(’c’ ,’trail_comment only ’)
      call journal(’d’ ,’debug only’)
      call journal(’e’ ,’stderr only’)
      call journal(’o’ ,’ ’) ! closing trail file
   end program test_journal

AUTHOR

John S. Urban

LICENSE

Public Domain


journal (3) October 17, 2020
Generated by manServer 1.08 from 6b994e10-9de4-4468-9d1d-15f5ab43288d using man macros.