C Library Functions - journal (3)
NAME
journal(3f) - [M_framework__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 class(*),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 Mode changing options used by themselves:
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.
> 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_framework__journal, only : journal !! BASIC USAGE call journal(& & ’write to standard output as-is, and trail file as a comment if open’) ! since trail file is not yet open, 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_journalAdding intrinsic scalar values to the message:
program test_journal use M_framework__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_journalprogram testit ! this is a utility program that calls the module routines. It is ! typically built using ccall(1). use M_framework__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’) ! change time prefix time_stamp_prefix=’CPU_TIME=%c:CALLS=%C:SINCE=%S:%b’ call journal(’%’,time_stamp_prefix) ! set a message time prefix 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) | July 22, 2023 |
