Documentation for module cp_output_handling

routines to handle the output, The idea is to remove the decision of wheter to output and what to output from the code that does the output, and centralize it here.

source: cp_output_handling.F
Loading...

public Subroutines/Functions:

Adds an iteration level
adds one to the actual iteration
returns the iteration string, a string that is useful to create unique filenames (once you trim it)
returns true if the printlevel activates this printkey does not look if this iteration it should be printed
should be called after you finish working with a unit obtained with cp_print_key_unit_nr, so that the file that might have been opened can be closed.
Utility function that retuns a unit number to write the print key. Might open a file with a unique filename, generated from the print_key name and iteration info.
creates a print_key section
returns what should be done with the given proprety if btest(res,cp_p_store) then the property should be stored in memory if btest(res,cp_p_file) then the property should be print ed to a file if res==0 then nothing should be done
...
Removes an iteration level

Parameters:

INTEGER
:: add_last_no = 0
INTEGER
:: add_last_numeric = 1
INTEGER
:: add_last_symbolic = 2
INTEGER
:: cp_out_calc = ibset(0,cp_p_calc)
INTEGER
:: cp_out_default = cp_out_file_if
INTEGER
:: cp_out_file = ibset(0,cp_p_file)
INTEGER
:: cp_out_file_each = ibset(0,cp_p_file_each)
INTEGER
:: cp_out_file_if = ibset(0,cp_p_file_if)
INTEGER
:: cp_out_none = 0
INTEGER
:: cp_out_store = ibset(0,cp_p_store)
INTEGER
:: cp_out_store_each = ibset(0,cp_p_store_each)
INTEGER
:: cp_out_store_if = ibset(0,cp_p_store_if)
INTEGER
:: cp_p_calc = 7
INTEGER
:: cp_p_file = 1
INTEGER
:: cp_p_file_each = 5
INTEGER
:: cp_p_file_if = 3
INTEGER
:: cp_p_store = 2
INTEGER
:: cp_p_store_each = 6
INTEGER
:: cp_p_store_if = 4
INTEGER
:: debug_print_level = 4
INTEGER
:: high_print_level = 3
INTEGER
:: low_print_level = 1
INTEGER
:: medium_print_level = 2
INTEGER
:: silent_print_level = 0

SUBROUTINEcp_add_iter_level(iteration_info, level_name, n_rlevel_new)

Adds an iteration level

Arguments:
POINTER
:: iteration_info the iteration info to which an iteration level has to be added
CHARACTER(*),
INTENT(in)
:: level_name the name of this level, for pretty printing only, right now
INTEGER,
INTENT(out),
OPTIONAL
:: n_rlevel_new number of iteration levels after this call

SUBROUTINEcp_iterate(iteration_info, last, iter_nr, increment, iter_nr_out)

adds one to the actual iteration

Arguments:
POINTER
:: iteration_info the iteration info to update
LOGICAL,
INTENT(in),
OPTIONAL
:: last if this iteration is the last one (defaults to false)
INTEGER,
INTENT(in),
OPTIONAL
:: iter_nr ...
INTEGER,
INTENT(in),
OPTIONAL
:: increment ...
INTEGER,
INTENT(out),
OPTIONAL
:: iter_nr_out ...

FUNCTIONcp_iter_string(iter_info, print_key, for_file)

returns the iteration string, a string that is useful to create unique filenames (once you trim it)

Return Value ::
Arguments:
POINTER
:: iter_info the iteration info from where to take the iteration number
OPTIONAL, POINTER
:: print_key the print key to optionally show the last iteration symbolically
LOGICAL,
INTENT(in),
OPTIONAL
:: for_file if the string is to be used for file generation (and should consequently ignore some iteration levels depending on COMMON_ITERATION_LEVELS). Defaults to false.

FUNCTIONcp_printkey_is_on(iteration_info, print_key)

returns true if the printlevel activates this printkey does not look if this iteration it should be printed

Return Value ::
LOGICAL
Arguments:
POINTER
:: iteration_info information about the actual iteration level
POINTER
:: print_key the section values of the key to be printed

SUBROUTINEcp_print_key_finished_output(unit_nr, logger, basis_section, print_key_path, local, ignore_should_output, on_file)

should be called after you finish working with a unit obtained with cp_print_key_unit_nr, so that the file that might have been opened can be closed.

Arguments:
INTEGER,
INTENT(inout)
:: unit_nr ...
POINTER
:: logger ...
POINTER
:: basis_section ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: print_key_path ...
LOGICAL,
INTENT(in),
OPTIONAL
:: local ...
LOGICAL,
INTENT(in),
OPTIONAL
:: ignore_should_output ...
LOGICAL,
INTENT(in),
OPTIONAL
:: on_file ...

FUNCTIONcp_print_key_generate_filename(logger, print_key, middle_name, extension, my_local)

Utility function that retuns a unit number to write the print key. Might open a file with a unique filename, generated from the print_key name and iteration info.

Return Value ::
Arguments:
POINTER
:: logger the logger for the parallel environment, iteration info and filename generation
POINTER
:: print_key ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: middle_name name to be added to the generated filename, useful when print_key activates different distinct outputs, to be able to distinguish them
CHARACTER(*),
INTENT(in)
:: extension extension to be applied to the filename (including the ".")
LOGICAL,
INTENT(in)
:: my_local if the unit should be local to this task, or global to the program (defaults to false).

SUBROUTINEcp_print_key_section_create(print_key_section, name, description, print_level, each_iter_names, each_iter_values, add_last, filename, common_iter_levels, citations, unit_str)

creates a print_key section

Arguments:
POINTER
:: print_key_section the print key to create
CHARACTER(*),
INTENT(in)
:: name the name of the print key
CHARACTER(*),
INTENT(in)
:: description the description of the print key
INTEGER,
INTENT(in),
OPTIONAL
:: print_level print level starting at which the printing takes place (defaults to debug_print_level)
CHARACTER(*),
INTENT(in),
OPTIONAL
:: each_iter_names(:) ...
INTEGER,
INTENT(in),
OPTIONAL
:: each_iter_values(:) ...
INTEGER,
INTENT(in),
OPTIONAL
:: add_last ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: filename ...
INTEGER,
INTENT(in),
OPTIONAL
:: common_iter_levels ...
INTEGER,
OPTIONAL
:: citations(:) ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: unit_str specifies an unit of measure for output quantity. If not provided the control is totally left to how the output was coded (i.e. USERS have no possibility to change it)

FUNCTIONcp_print_key_should_output(iteration_info, basis_section, print_key_path, used_print_key, first_time)

returns what should be done with the given proprety if btest(res,cp_p_store) then the property should be stored in memory if btest(res,cp_p_file) then the property should be print ed to a file if res==0 then nothing should be done

Return Value ::
INTEGER
Arguments:
POINTER
:: iteration_info information about the actual iteration level
POINTER
:: basis_section section that contains the printkey
CHARACTER(*),
INTENT(in),
OPTIONAL
:: print_key_path path to the printkey- "%" between sections, and optionally a "/" and a logical flag to check). Might be empty.
OPTIONAL, POINTER
:: used_print_key here the print_key that was used is returned
LOGICAL,
INTENT(out),
OPTIONAL
:: first_time if it ist the first time that an output is written (not fully correct, but most of the time)

FUNCTIONcp_print_key_unit_nr(logger, basis_section, print_key_path, extension, middle_name, local, log_filename, ignore_should_output, file_form, file_position, file_action, file_status, do_backup, on_file, is_new_file)

...

Return Value ::
INTEGER
Arguments:
POINTER
:: logger ...
POINTER
:: basis_section ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: print_key_path ...
CHARACTER(*),
INTENT(in)
:: extension ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: middle_name ...
LOGICAL,
INTENT(in),
OPTIONAL
:: local ...
LOGICAL,
INTENT(in),
OPTIONAL
:: log_filename ...
LOGICAL,
INTENT(in),
OPTIONAL
:: ignore_should_output ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: file_form ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: file_position ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: file_action ...
CHARACTER(*),
INTENT(in),
OPTIONAL
:: file_status ...
LOGICAL,
INTENT(in),
OPTIONAL
:: do_backup ...
LOGICAL,
INTENT(in),
OPTIONAL
:: on_file ...
LOGICAL,
INTENT(out),
OPTIONAL
:: is_new_file true if this rank created a new (or rewound) file, false otherwise

SUBROUTINEcp_rm_iter_level(iteration_info, level_name, n_rlevel_att)

Removes an iteration level

Arguments:
POINTER
:: iteration_info the iteration info to which an iteration level has to be removed
CHARACTER(*),
INTENT(in)
:: level_name level_name to be destroyed (if does not match gives an error)
INTEGER,
INTENT(in),
OPTIONAL
:: n_rlevel_att iteration level before the call (to do some checks)