.. _output-commands:

********************************
General Output Database Commands
********************************

A number of commands that control the format of the output database are available in several types of output (results, restart, history, and/or heartbeat). These commands are described in detail below.

.. code-block:: sierrainput

   DATABASE NAME = <string>results_file_name
   DATABASE TYPE = <string>database_type(exodusII)
   OVERWRITE = <string>OFF|ON|TRUE|FALSE|YES|NO
     (ON|TRUE|YES)
   TITLE <string>user_title
   PROPERTY = <string>propName = <string>propValue

The first two command lines (``DATABASE NAME``, ``DATABASE TYPE``) give pertinent information about the database file. The command line

.. code-block:: sierrainput

   DATABASE NAME = <string>results_file_name

gives the name of the results file with the string ``results_file_name``. If the file is to appear in the current directory and is named ``job.e``, this command line would appear as:

.. code-block:: sierrainput

   DATABASE NAME = job.e

If the file is to be created in some other directory, the command line must include the path to that directory. If the directory does not exist, all necessary directories will be created automatically.

Two special, shorthand meta-characters may be used in the results file name specification in the input deck: ``%P`` represents the number of processors in use for the analysis, while ``%B`` represents the base name of the analysis input file. If the ``%P`` character is used, for example, a specified database name of ``results-%P/job.e`` for a job running on :math:`N` processors would be expanded to ``results-N/job.e``, and the actual results files would be of the form ``results-N/job.e.N.i``, where :math:`i = \{0000, 0001, \ldots, 1023\}`. If the ``%B`` character is used, for example, a results database name specified as ``%B.e`` in an input file named ``my_analysis_run.i`` and the , would yield a results output file named ``my_analysis_run.e``. If no results database file name is given, the default file name is ``%B.e``, the base name of the input file with the extension ``.e``.

If the results file does not use the Exodus II format [:footcite:`int:ref:scho`], the format for the results file must be specified using the command line:

.. code-block:: sierrainput

   DATABASE TYPE = <string>database_type(exodusII)

The Exodus II database is supported in Presto and Adagio. Exodus II is currently the only supported format, but other options may be added in the future.

The ``OVERWRITE`` command line can be used to prevent the overwriting of existing results files.

.. code-block:: sierrainput

   OVERWRITE = <string>OFF|ON|TRUE|FALSE|YES|NO (ON|TRUE|YES)

The ``OVERWRITE`` command line allows only a single value. The options ``FALSE``, ``NO``, or ``OFF`` will cause the code to terminate before existing results files can be overwritten, while ``TRUE``, ``YES``, or ``ON`` will cause existing results files to be overwritten by new files (the default status). Suppose, for example, that an existing results is named file named ``job21.e``, and suppose that an input file with a ``RESULTS OUTPUT`` command block containing

.. code-block:: sierrainput

   OVERWRITE = ON
   DATABASE NAME = job21.e

is run. In this case the existing file ``job21.e`` will be overwritten.

Whether or not files are overwritten is also impacted by the use of the automatic read and write option for restart files described in :numref:`output-restart-options-automatic`. If using the automatic read and write option for restart files, the results files, like the restart files, are automatically managed. The automatic read and write option in restart adds extensions to file names and prevents the overwriting of any existing restart or results files. For the case of a user-controlled read and write of restart files (:numref:`output-restart-options-control`) or of no restart, however, the ``OVERWRITE`` command line is useful for preventing the overwriting of results files.

A title may be added to the results file with the ``TITLE`` command line. The specified ``user_title`` will be written to the "title" field of the results file. Some of the programs that process the results file (such as various SEACAS programs [:footcite:`int:ref:sja`]) can read and display this information.

The ``PROPERTY`` command can change some of the fundamental properties of the output database. For example, maximum variable name length, which, in Exodus II format, has a limit of 100 characters. Note, changing this properties is not recommended unless by direction of the development team.

.. raw::
   html

   <hr>

.. footbibliography::
