C Library Functions - journal (3)

NAME

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

Synopsis
Description
Options
Examples
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).

EXAMPLES

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 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

   program testit
   ! this is a utility program that calls the module routines. It is typically built using ccall(1).
   use M_journal, only : journal
      character(len=:),allocatable :: time_stamp_prefix
      call journal(’s’,’--------------------------------------------------------------------------------’)
      call journal(’s’,’SIMPLE WRITES’)
      call one()
      call two()
      call journal(’sc’,’called ONE() and TWO() but did not generate a log file’)
      call journal(’s’,’--------------------------------------------------------------------------------’)
      call journal(’s’,’SIMPLE WRITES WITH LOG FILE’)
      call journal(’o’,’journal.txt’)                        ! open trail file
      call one()
      call two()
      call journal(’sc’,’called ONE() and TWO() and generated log file journal.txt’)
      call journal(’’,’journal.txt’)                         ! close trail file
      call journal(’s’,’--------------------------------------------------------------------------------’)
      call journal(’s’,’SIMPLE WRITES WITH TIMING INFORMATION’)
      time_stamp_prefix=’CPU_TIME=%c:CALLS=%C:SINCE=%S:%b’  ! change time prefix
      call journal(’%’,time_stamp_prefix) ! set a time prefix in front of messages
      call journal(’o’,’timed.txt’)                          ! open trail file
      call one()
      call two()
      call journal(’sc’,’called ONE() and TWO() and generate log file timed.txt’)
      call journal(’’,’timed.txt’)                           ! close trail file
      call journal(’%’,’’)                                   ! turn off time prefix
      call journal(’o’,’timed.txt’)                          ! open trail file
      call journal(’s’,’--------------------------------------------------------------------------------’)

   contains

      subroutine two()
         call journal(’Entered subroutine two’)
         call journal(’Exited subroutine two’)
      end subroutine two

      subroutine one()
         call journal(’Entered subroutine one’)
         sum=-HUGE(1.0)
         do i=1,10000000
           sum=sum+sqrt(real(i))
         enddo
         write(*,*)’SUM=’,sum
         call journal(’Exited subroutine one’)
      end subroutine one

   end program testit

AUTHOR

John S. Urban

LICENSE

Public Domain

Nemo Release 3.1

journal (3)

February 23, 2025

Generated by manServer 1.08 from ed744510-3d01-4f8d-9ad4-cd00ebc1c265 using man macros.