1#
2# $Id$
3#
4
5Print control
6-------------
7
8All modules should use the same print control mechanism to provide
9both uniformity and flexibility.  The routine in util_print do this.
10
11A) All modules understand the print levels
12
13   none
14   low
15   medium = default
16   high
17   debug
18
19   "None" is defined to mean literally no output except for
20catastrophic errors (e.g., inconsistent data, failure to converge).
21
22B) Printing of specific quantities may be directly enabled or
23   disabled from the input.
24
25C) Modules operate independently and printing will eventually be
26   controllable via context
27
28This is how it currently works.
29
30Inside the SCF input
31
32  print low basis "final eigenvectors"
33  noprint title
34
35This sets the overall SCF printlevel to low, forces printing of the
36final eigenvectors and basis, and disables printing of the title.
37
38------------
39
40The implementation is very simple.  Each module defines one or two
41entries in the database which enable/disable printing
42
43  <module>:print ... list of names to enable print
44  <module>:noprint ... list of names to disable print
45
46The special values (none, low, ...) are recognized in the list of
47print keywords and are used to adjust the print level.
48The parsing of this list is encapsulated in the routine
49util_print_rtdb_load().  To support multiple modules a stack of print
50options is maintained ... this will eventually be combined with the
51context.
52
53The code necessary for each module is then simply
54
55  In the input routine
56
57     Upon detecting a line with the print directive
58
59     call util_print_input(rtdb, "module_name")
60
61  At the beginning of a module
62
63     call util_print_push
64     call util_print_rtdb_load(rtdb, "module_name")
65
66     Util_print_push() sets the default printlevel for a new module.
67     Util_print_rtdb_load reads in any input parameters
68
69  To control printing within a module
70
71     #include "util.fh"
72
73     if (util_print("name", level)) then
74       write out data associated with "name"
75     endif
76
77     Level is one of the prespecified print levels
78     (print_none, print_low, ...) or some module specific value
79     (see util/printlevels.fh for actual values).
80
81     If (  (the level is below the current printlevel and printing of
82            "name" has not been explicitly disabled)
83           or
84           (the printing of name has been explicitly enabled) )
85
86        util_print returns .true.
87     endif
88
89  At the end of a module
90
91     call util_print_pop
92
93  E.g.
94
95      #include "util.fh"
96
97      call util_print_push
98      call util_print_rtdb_load('scf')
99
100      if (util_print('information', print_low)) then
101         write(6,*) ...
102      endif
103
104      ...
105
106      call util_print_pop
107
108If an application wants more direct control over printing there are
109routines to explicitly control the print level and to enable/disable
110printing of named items.
111
112util.fh has been modified to define the integers
113
114    print_none     = 0 (use of this will force printing even if none
115                        is asked for!)
116    print_low      = 10
117    print_medium   = 20
118    print_high     = 30
119    print_debug    = 100
120    print_never    = 1,000,000
121    print_default  = print_medium
122
123and the routine
124
125    logical function util_print(name, level)
126    character*(*) name
127    integer level
128
129Other relevant routines are
130
131    subroutine util_print_push
132    subroutine util_print_pop
133    subroutine util_print_set_level(level)
134    subroutine util_print_input(rtdb, prefix)
135    subroutine util_print_rtdb_load(rtdb, prefix)
136
137These two routines are probably not needed by applications
138
139    subroutine util_print_enable(name)
140    subroutine util_print_disable(name)
141
142