Studio for Eclipse command-line options

The OmniMark command-line options that can be used in OmniMark Studio for Eclipse are listed below. You can enter the command line options for your program in a launch configuration.

Many command line options have short forms.

External Function Libraries on Windows

OmniMark ships with a number of external function libraries. Your OmniMark programs can call functions in these libraries. You can also write your own external function libraries or obtain them from third parties.

When you install OmniMark on Windows, the installer records in the Windows registry the location of the external function libraries supplied with OmniMark. OmniMark can find these automatically. You can prevent OmniMark from searching the directories named in the registry with the -noenvargs (or -noea) command line option. If you want a specific OmniMark programs to use a different set of external function libraries, you can specify their location using the -x command line option.

When OmniMark attempts to load an external function library, the following locations will be searched, in order:

  1. the current directory,
  2. directories that the operating system searches when attempting to load an external function library (on Windows, this is all directories in the path),
  3. paths specified on the OmniMark command line, and
  4. paths specified in the registry.

Include Files and Modules on Windows

OmniMark ships with a number of include (.xin) files, and modules .xmd. Your OmniMark programs can call the functions defined in these files. You can also write your own include files and modules, or obtain them from third parties. If you run OmniMark programs from source, OmniMark must be able to locate these files. When you install OmniMark on Windows, the installer records in the Windows registry the location of the include files. OmniMark can find these automatically. You can prevent OmniMark from searching the directories named in the registry with the -noenvargs or -noea command line option. If you want a specific OmniMark program to use a different set of include files or modules, you can specify their location using the -i command line option.

When searching for include files and modules, OmniMark searches in the following order:

  1. the current directory,
  2. paths specified on the OmniMark command line, and
  3. paths specified in the Windows registry.

External Function Libraries on UNIX

OmniMark ships with a number of external function libraries. Your OmniMark programs can call functions in these libraries. You can also write your own external function libraries or obtain them from third parties.

You must configure your system so that OmniMark can find the external function libraries you install. When you install OmniMark on a UNIX system, external function library directories are not located automatically. You must do one of the following:

  • set the OMNIMARK_XFLPATH environment variable, or
  • use the -x command line options.

When setting the OMNIMARK_XFLPATH variable under UNIX, paths should be separated by a colon. For details on setting environment variables, consult the documentation for your shell or contact your system administrator. You can prevent OmniMark from searching the directories named in the environment with the -noenvargs (or -noea) command line option. If you want a specific OmniMark program to use a different set of external function libraries, you can specify their location on the OmniMark command line using the -x command line option.

When OmniMark attempts to load an external function library, the following locations will be searched, in order:

  1. directories that the operating system searches when attempting to load an external function library (for example, on Linux, it is all directories specified by the LD_LIBRARY_PATH environment variable),
  2. paths specified on the OmniMark command line, and
  3. paths specified in the OMNIMARK_XFLPATH environment variables.
Note that in a typical Unix installation, the LD_LIBRARY_PATH environment variable (or equivalent) will include the current directory.

Include Files and Modules on UNIX

OmniMark ships with a number of include (.xin) files, and modules .xmd. Your OmniMark programs can call functions in these files. You can also write your own include files and modules, or obtain them from third parties. If you run OmniMark programs from source, OmniMark must be able to locate these files. When you install OmniMark on a UNIX system, directories containing the include files and modules are not located automatically. You must do one of the following:

  • set the OMNIMARK_INCLUDE environment variable, or
  • use the -i command-line option.

When setting the OMNIMARK_INCLUDE variable under UNIX, paths should be separated by a colon. For details on setting environment variables, consult the documentation for your shell or contact your system administrator. You can prevent OmniMark from searching the directories named in the environment using the -noenvargs (or -noea) command line option. If you want a specific OmniMark program to use a different set of include files or modules, you can specify their location on the command line using the -i command line option.

When searching for include files and modules, OmniMark searches in the following order:

  1. the current directory,
  2. paths specified on the OmniMark command line, and
  3. paths specified in environment variables.

Using arguments files

You can combine several command line options into a file called an arguments file. You then name the arguments file on the OmniMark Studio for Eclipse command line using the -f command-line option. The command-line options in the arguments file will be read as if they had been entered on the command line. Arguments files are usually given the extension .xar

When you create an arguments file, you should place command line arguments one per line, like this: 

  -d name Fred
  -c age 5
  input.txt
  -of output.txt

To specify an arguments file that is to be read as part of the command line, use one of the following:

  • -argsfile testprogram.xar
  • -f testprogram.xar

Controlling warnings

The OmniMark compiler produces warnings in several classes.

  • ambiguity: A statement is ambiguous. The compiler may not have interpreted the statement in the way you intended.
  • deprecated: The keyword you used is deprecated. You should use the modern equivalent.
  • dead-code: A section of code cannot be reached when your program is executed.
  • pattern: A pattern can match zero characters.
  • performance: A section of code can negatively impact performance.
  • redundancy: The same declaration or modifier (or equivalent) is used more than once. OmniMark will ignore the duplicates.
  • risky-code: A section of code may have an unexpected effect.
  • uninitialized-data-access: A shelf is not explicitly initialized or assigned any value anywhere, but its value is used.

By default, the OmniMark compiler will display all these classes of warnings except for uninitialized-data-access, which is ignored. You can change how each class of warning is handled using the following command line options:

  • to ignore the class of warnings, use -warning-ignore warning-class,
  • to report only a summary of the class of warnings, use -warning-summary warning-class,
  • to report the warning and continue compiling, use -warning-report warning-class, and
  • to promote the class of warnings to an error, use -warning-error warning-class.

You can also use the all warning class to quickly apply the same command-line option to all classes of warnings. For example, 

  -warning-error all -warning-ignore uninitialized-data-access
would report warnings for any warning other than uninitialized-data-access.

The -warning and -warnings command line options used in previous version of OmniMark no longer have any effect on the compiler.

Specifying the temporary directory

The -temppfx command-line option is used to specify the directory where OmniMark should create temporary files when processing referents; for instance, a typical use on a UNIX system might be 

  -temppfx /tmp/

Locating include files and modules

To specify a path to include files or modules, use 

  -i path
The -i command-line option can also be written -include.

To force OmniMark to ignore include paths specified in environment variables and Windows registry entries, use 

  -noenvargs
The -noenvargs command-line option can also be written -noea.

Locating external function libraries

The -xflpath command-line option can be used to specify a directory in which OmniMark should look for external function libraries. On Windows, a typical use might be 

  -xflpath c:\omnimark\lib\=L.dll
The -xflpath command-line option can be shortened to -x.

You must specify the file extension used for shared libraries on the platform OmniMark is running on: on Windows this means adding the trailing slash and =L.dll, while on UNIX this means adding the trailing slash =L.so. Note however that the appropriate suffix on UNIX machines is platform-dependent: consult the documentation for your system or contact your system administrator to find was suffix is appropriate for dynamic libraries on your system.

If the command line has more than one "-xflpath" option, OmniMark will search those directories in the order you've specified them.

To force OmniMark to ignore external function library paths specified in environment variables and Windows registry entries, use 

  -noenvargs
The -noenvargs command-line option can also be written -noea.

Specifying the default output destination

To specify a file to capture the data that OmniMark writes to standard output, use the -of option: 

  -of my-output.txt
To append to the output file instead of overwriting its contents, use the -aof command-line option: 
  -aof my-output.txt

Setting global variables in the OmniMark program

You can set the initial values of globals in the OmniMark program. Initial values set on the command line override those specified in the program source.

To set a switch variable to true, use 

  -activate my-switch
The -activate command-line option can also be written -a. To set a switch variable to false, use 
  -deactivate my-switch
The -deactivate command-line option can also be written -dea.

To set the value of an integer, use 

  -counter my-counter 44
The -counter command-line option can also be written -c.

To set the value of a stream or string, use one of the following: 

  -define email-addr "[email protected]"
The -define command-line option can also be written -d.

Information and logging

For a reminder of the available command-line options for your OmniMark executable, you can use the -help option.

The -log command-line option is used to specify a file to which OmniMark will write log messages generated by the OmniMark program: 

  -log testprogram.log
To append to the log file instead of overwriting its contents, use the -alog command-line option: 
  -alog testprogram.log

To add program execution statistics, including memory usage and execution times, to the log, use 

  -stats

You can find out which version of OmniMark you are using the -version command-line option.

To display the authorization key for OmniMark, or to view diagnostic information in the case of an authorization failure, use the -authkey command-line option.

Controlling markup processing

If markup errors are encountered during processing, a count is given at the end of execution. To suppress this, use the -nocount command-line option.

To suppress the error number when markup error and warning messages are reported, use the -noernum command-line option.

The number of XML/SGML error messages reported can be limited using the -limit command-line option: 

  -limit 50
The -limit can also be written -threshold.

To specify the name of a file containing OmniMark SGML/XML library declarations and comments to be used when resolving external text entities, use the -library command-line option: 

  -library my-library.xlr

To specify a directory in which OmniMark should look for files specified in the system identifier portion of an OmniMark library declaration, use the -l command-line option: for instance, a typical use on a UNIX system might be 

  -l /usr/bin/lib/
The -l command-line option can also be written -libpath. If the command line contains more than one -l option, OmniMark will search those directories in the order they are specified. Note that you must include a trailing directory name separator (/ on UNIX, \ on Windows) at the end of the specified path, as the path is prepended to the name of the file when OmniMark searches for it.

Garbage collection control

The lifetimes of record values are unpredictable, so OmniMark runtime engines contain a garbage collector to recycle the memory they use. The garbage collector can be activated manually using the collect-garbage action, or automatically when a certain threshold of memory consumption is crossed. This automatic invocation of garbage collector can be controlled using the following command-line options:

  • -gc-threshold followed by an amount of memory in bytes sets the threshold for the activation of the garbage collector. That is, the collector will spring into action as soon as OmniMark uses more memory than the specific threshold.
  • -gc-increment specifies the amount of memory in bytes that should be consumed after a collection to trigger the garbage collector again.

If these options are not specified, the collection threshold is initialized by default to an amount of memory judged appropriate for the current system (typically a tenth of the available memory) and the increment to one half of the threshold.

Specifying the option -gc-threshold 0 turns off the automatic garbage collection completely. It is then the programmer's responsibility to invoke collect-garbage manually as necessary.

Generating a license request key

To generate a licence request key, use the -reqkeygen command-line option, providing it with a serial number, an email address, and an identifying string. For example, 

  -reqkeygen "SN-Yy3X-ptdi-gpa-u[4" [email protected] "Machine Sol23"
The output goes to the log stream. It can be captured using the -log command-line option; however, in this case the -log command-line option must appear before the -reqkeygen.

Prerequisite Concepts