Entity Command

The Entity commands lets you insert XML entity definitions in the file and use then in selected commands.

Introduction

XML entities do not have much function when building and running calculations in NairnFEAMPM or NairnFEAMPMViz. But perhaps you will use NairnFEAMPM or NairnFEAMPMViz just to create the XML input commands and then copy those files to a remote computer for running large calculations. After such calculations, you may need to modify the XML files remotely for new calculations using basic text editors or command line tools (like vi). For these situations, it is helpful have entities in your XML files. The entities will be near the beginnin of the file (and therefore easy to edit) and they can be used throughout the file to control selected options of the simulations.

Input Command

To create an XML entity to appear in automatically-formatted input commands, use the command (which is for scripted files only):

Entity (name),(value)

where

• (name) is the entity name without the leading ampersand (&) or trailing semicolon (;) (e.g, maxTime to refer to an XML entity &maxtime;).
• (value) is the setting for the entity to be inserted in the file.

All entities will appear in the DocType element at the start of the resulting XML commands. For example, the output could be:

<?xml version='1.0'?>
<!DOCTYPE JANFEAInput SYSTEM '/nairn-mpm-fea-OpenMP/NairnMPM/input/NairnMPM.dtd'
[
  <!ENTITY maxtime "7.5">
  <!ENTITY archPath "Results/MPM">
  <!ENTITY archTime "0.1">
]>

Usage

1. Once entities are defined, you can use then in selected commands. For example, the MaximumTime command will accept an entity to set the maximum time. Each command that allows an entity will be documented as accepting them. In commands that directly support entity use, you must provide the name as in the Entity command or without the leading ampersand (&) and trailing semicolon (;).¹ The commands that accept entities are all commands intended to accept numerical values.
2. You can also use entities on most commands that expect string arguments such as the Archive command or in place of any argument that can be a user-defined function. In this usage, the string you supply is simply used in place of the expected string and therefore you should always use the complete entity name including the leading ampersand (&) and trailing semicolon (;).¹ This usage works for many, but not all, commands that accept string arguments. When in doubt, you can test by providing an entity and then checking the resulting XML output to verify the entity was inserted as expected. In addition, the entity you provide is inserted without verifying you have actually defined that entity. It is your responsibility to make sure they are defined by Entity commands.
3. The XMLData command lets you insert verbatim XML code into commands files, but the verbatim text cannot include expressions. A work around is to define an entity using an Entity command with the expression and then use that entity in the verbatim XML code.

Notes

1. When using NairnFEAMPM, entities provided with the leading ampersand (&) and trailing semicolon (;) must be enclosed in quotes (e.g., "&fxn;"). They do not need to be quoted when using NairnFEAMPMViz.