Output management functions

The facilities for Output management will automatically create different kinds of output directories in different situations, such as when a Simulation report is generated or when Data collector monitors are used. It is also possible for the user to create the output directories if necessary, and to access the names of the different output directories.

The following functions can be used to access the names of the standard output directories for CPN Tools. When a function returns a path to a directory, the directory may or may not exist.

If an attempt is made to read or write a file in a directory that cannot be accessed then a NotValidDirExn exception will be raised.

Output.getModelDir()
returns the path to the directory in which the model is saved
Output.getModelName()
returns the name of the file in which the model is saved
Output.getTopOutputDir()
returns the path to the top output directory
Output.getSimOutputDir()
returns the path to the current simulation output directory
Output.getSimLogfileDir()
returns the path to the current simulation log files directory
Output.getRepOutputDir()
returns the path to the current replication output directory
Output.getRepLogfileDir()
returns the path to the current replication log files directory

The following functions can be used to create the standard output directories. If an attempt to create a directory fails, then a NotValidDirExn s exception will be raised where s is a string describing the error.

Output.initTopOutputDir()
attempts to create the top output directory if the directory does not already exist
Output.initSimOutputDir()
calls Output.initTopOutputDir, and attempts to create a simulation output directory if the directory does not already exist
Output.initSimLogfileDir()
calls Output.initSimOutputDir, and attempts to create a simulation log files directory if the directory does not already exist
Output.initRepOutputDir()
calls Output.initTopOutputDir, and attempts to create a replication output directory if the directory does not already exist
Output.initRepLogfileDir()
calls Output.initRepOutputDir, and attempts to create a replication log files directory if the directory does not already exist

The simulator will automatically invoke the functions to initialize/create the output directories in the following situations:

Examples of use

Here is an example of how the output management functions could be used in a user-defined monitor.

A number of declarations are used to define auxiliary functions and reference variables.

globref fileid = (NONE : TextIO.outstream option);

fun getfid () = 
   (* this will raise Option exception if !fileid = NONE *)
   Option.valOf(!fileid)

fun initfile () =
let
   val filename = OS.Path.concat (Output.getSimOutputDir(), 
                                  "Trans_Log_File.txt")
in  
  Output.initSimOutputDir();
  fileid := SOME (TextIO.openOut filename)
end;

The initialization, action, and stop functions for the monitor access the file using the functions that were defined in the declarations.

fun init () =
  (initfile();
  TextIO.output(getfid(), "Occurring transitions\n"))

fun action (observedval) =
  TextIO.output(getfid(), observedval)
  handle Option => (initfile();
                    TextIO.output(getfid(), observedval))

fun stop () =
  (TextIO.output(getfid(), "\n\n"^"Simulation stopped after "^
                           Int.toString(step())^" steps\n");
   TextIO.closeOut(getfid());
   fileid := NONE)

Related pages