About McXtrace
Publications
Project Partners
Project People
Goal
Documentation
Manual
Commands
Wiki (GitHub)
Tutorial
6.2 Syntactical conventions
Comments follow the normal C syntax “/* ... */”. C++ style comments “// ...” may also be used.
Keywords are not case-sensitive, for example “DEFINE”, “define”, and “dEfInE” are all equivalent. However, by convention we always write keywords in uppercase to distinguish them from identifiers and C language keywords. In contrast, McXtrace identifiers (names), like C identifiers and keywords, are case sensitive, another good reason to use a consistent case convention for keywords. All McXtrace keywords are reserved, and thus should not be used as C variable names. The list of these reserved keywords is shown in table 6.1.
| Keyword | Scope | Meaning |
| ABSOLUTE | I | Indicates that the AT and ROTATED keywords are in the absolute coordinate system. |
| AT | I | Indicates the position of a component in an instrument definition. |
| COPY | I,C | copy/duplicate an instance or a component definition. |
| DECLARE | I,C | Declares C internal variables. |
| DEFINE | I,C | Starts an INSTRUMENT or COMPONENT definition. |
| DEFINITION | C | Defines component parameters that are constants (#define). |
| END | I,C | Ends the instrument or component definition. |
| SPLIT | I | Enhance incoming statistics by event repetition. |
| EXTEND | I | Extends a component TRACE section (plug-in). |
| FINALLY | I,C | Embeds C code to execute when simulation ends. |
| GROUP | I | Defines an exclusive group of components. |
| %include | I,C | Imports an instrument part, a component or a piece of C code (when within embedded C). |
| JUMP | I | Iterative (loops) and conditional jumps. |
| INITIALIZE | I,C | Embeds C code to be executed when starting. |
| ITERATE | I | Defines iteration counter for JUMP. |
| MCDISPLAY | C | Embeds C code to display component geometry. |
| NEXUS | I | Defines NeXus output type (4,5,XML,compression). |
| OUTPUT | C | Defines internal variables to be public and protected symbols (usually all global variables and functions of DECLARE). |
| PARAMETERS | C | Defines a class of component parameter (DEFINITION, SETTING,STATE). |
| PREVIOUS | C | Refers to a previous component position/orientation. |
| RELATIVE | I | Indicates that the AT and ROTATED keywords are relative to an other component. |
| ROTATED | I | Indicates the orientation of a component in an instrument definition. |
| SAVE | I,C | Embedded C code to execute when saving data. |
| SETTING | C | Defines component parameters that are variables. |
| SHARE | C | Declares global functions and variables to be shared. |
| STATE | C | Defines x-ray state coordinates. |
| TRACE | I,C | Defines the instrument as a the component sequence. |
| WHEN | I | Condition for component activation and JUMP. |
| Table 6.1.: | Reserved McXtrace keywords. Scope is ’I’ for instrument and ’C’ for component definitions. |
It is possible, and usual, to split the input instrument definition across several different files. For example, if a component is not explicitly defined in the instrument, McXtrace will search for a file containing the component definition in the standard component library (as well as in the current directory and any user-specified search directories, see section 5.2.2). It is also possible to explicitly include another file using a line of the form
%include "file"
Beware of possible confusion with the C language “#include” statement, especially when it is used in C code embedded within the McXtrace meta-language. Files referenced with “%include” are read when the instrument is translated into C by the McXtrace compiler, and must contain valid McXtrace meta-language input (and possibly C code). Files referenced with “#include” are read when the C compiler generates an executable from the generated C code, and must contain valid C.
Embedded C code is used in several instances in the McXtrace meta-language. Such code is copied by the McXtrace compiler into the generated simulation C program. Embedded C code is written by putting it between the special symbols %{ and %}, as follows:
%{
…Embedded C code …
%}
The “%{” and “%}” must appear on a line by themselves (do not add comments after). Additionally, if a “%include” statement is found within an embedded C code block, the specified file will be included from the ’share’ directory of the standard component library (or from the current directory and any user-specified search directories) as a C library, just like the usual “#include” but only once. For instance, if many components require to read data from a file, they may all ask for “%include "read_table-lib"” without duplicating the code of this library. If the file has no extension, both .h and .c files will be searched and included, otherwise, only the specified file will be imported. The McXtrace’run-time’ shared library is included by default (equivalent to “%include "mcxtrace-r"” in the DECLARE section). For an example of %include, see the optics/Lens_simple.comp component. See also section 6.4.2 for insertion of full instruments in instruments (instrument catenation).
If the instrument description compilation fails, check that the keywords syntax is correct, that no semi-colon ; sign is missing (e.g. in C blocks and after an ABSORB macro), and there are no name conflicts between instrument and component instances variables.
