Altair® Monarch® Server

 

Runtime Fields

Runtime fields are a special type of calculated field whose value can be easily set at runtime, thereby providing a way to parameterize a model in some fashion. When Monarch is running in interactive mode it prompts the user via a dialog box for the values of any runtime fields at the time a model is loaded. Runtime fields may also be used with Monarch in "lights-out" mode by specifying the desired values on the command line or via an automation method.

With Automator, runtime field values may be specified via script, or a manifest file when using the Web Service or API. Regardless of the source, the runtime field values are written to a special section of the job log where they are then read at the time the project is loaded.

Specifying Runtime Values via a Manifest

To specify values for runtime fields using a manifest, construct the manifest XML as usual, but add a <runtime fields> section structured as in the following example:

<manifest process="ClassicWithRuntime">

    <inputs />

        <runtime_fields>

            <runtime_field name="Interest Rate">1.75%</runtime_field>

            <runtime_field name="SelectedComposer">Mozart</runtime_field>

        </runtime_fields>

</manifest>

The name attribute of each runtime_field tag is the field name exactly as it appears in the model, and the text is the desired value. One may specify as many runtime field values as desired. The values specified in a manifest apply across all projects/models in the specified process because Automator automatically copies these values to the job logs of any and all jobs spawned by the process instance. Once a suitable manifest has been constructed it may be passed into Automator in a call to StartProcessUsingManifest, which method already exists both in Automator's .Net API and in its Web Service.

Specifying Runtime Values via Script

One may also specify runtime values in PreExport, PreProcess, or PostExport script. In the most likely scenario, one would set the desired values in the PreExport script of the project to which they apply. However, in a multiple-project-per-job scenario it might be convenient to set the values in the PreProcess script, in which case the values would apply across all projects/models in the process. In rare cases, it may even be useful to set values in PostExport script, in which case the values would apply to any projects/models that are "downstream" of that project in the same job.

The following methods are included in the JobLog class to support getting/setting of runtime field values:

Method

Description

SetRuntimeFieldValue(string strFieldName, string strFieldValue)

Sets the value of a specified runtime field, superseding the old value, if any, which may have been set for that field.

HasRuntimeFieldValue(string strFieldName)

Returns true if a value has already been set for the specified runtime field.

GetRuntimeFieldValue(string strFieldName)

Returns the value of the specified runtime field as a string. Returns an empty string if no value has yet been set for the field.

SetRuntimeFieldValues(string[] FieldNames, string[] FieldValues)

Sets the values for a whole set of runtime fields in one call. This is used internally by Automator but might also be useful to a sophisticated script programmer.

GetRuntimeFieldValues(out string[] FieldNames, out string[] FieldValues)

Gets the runtime field names and their corresponding values for all fields whose values have already been set.

To make the setting of runtime field values easily accessible, Automator includes a Set the value of a runtime field... option in the Script Editor's Insert script to... menu. If you select this option, the Set the Value of a Runtime Field dialog appears, in which you may enter the name of the field and its desired value. In addition, you may choose whether the value is set unconditionally (resulting in a simple call to SetRuntimeFieldValue) or conditionally (resulting in a call to SetRuntimeFieldValue which is contingent on a return of false from HasRuntimeFieldValue).

Note: The Set the Value of a Runtime Field dialog makes no attempt to enumerate the possible runtime fields, nor does it check that the given field name actually corresponds to a runtime field in the model(s) in question.

Runtime Fields in the Job Log

Whenever runtime field values are used in Automator, they are recorded in the job log. This serves two purposes:

  • It is the mechanism by which the values are communicated to Exporter

  • It provides documentation for what values were actually in effect during the export(s)

The runtime field values appear in the job log in a <runtime fields> section structured exactly the same as the corresponding section of a manifest (see earlier in this section). The job log's <runtime_fields> section records the last value set for each runtime field. In addition, whenever a runtime field value is set, either indirectly via a manifest or directly in script, an event is automatically added to the <events> section of the log. This event documents the field name and the value set for it at that point in the execution, thereby making it possible to accurately determine at a later time what value a particular runtime field had at the time of a particular export.