Single Processing Engine

About Single Processing Engine

OmniMark Single Processing Engine runs programs written in the OmniMark programming language.

To run OmniMark programs from source in OmniMark Single Processing Engine:

  1. Write your program in OmniMark Studio for Eclipse or in your favorite editor. You can use OmniMark Studio for Eclipse to debug your program.
  2. In OmniMark Single Processing Engine, run the file using the -s command line option.

To run compiled OmniMark programs in OmniMark Single Processing Engine:

  1. Using the OmniMark Development Toolkit, create a Virtual Machine Code file (.xvc file) from your project.
  2. In OmniMark Single Processing Engine, run the file using the -load command line option.

You can write and compile OmniMark programs using OmniMark Studio for Eclipse, or use OmniMark Desktop Compiler or OmniMark Batch Compiler to compile. Compiled OmniMark programs have the extension .xvc. .xvc files are platform-independent: that is, they can be run by OmniMark Single Processing Engine on all supported platforms.

Installing and Configuring OmniMark on Windows

On a Windows machine, you install OmniMark by running the OmniMark installer. You will be guided through the installation and licensing process.

You configure your copy of OmniMark by choosing from the options in the installation program. To change your configuration, re-run the installation program at any later time: you will be presented with the option of modifying your installation.

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.

Installing and Configuring OmniMark on UNIX

On a UNIX machine, you install OmniMark by untarring the files into a suitable directory. Once OmniMark is installed, you must license it. To license your copy of OmniMark you must request an authorization key from Stilo.

Licensing OmniMark Single Processing Engine on UNIX

To receive and install your license key, begin by running OmniMark Single Processing Engine with the -reqkeygen command-line option with the following arguments:

  1. the serial number you received when you purchased OmniMark,
  2. the email address you want the license key sent to,
  3. a string of your choice that will let you identify the license key you will receive; this is useful if you are licensing several copies of OmniMark at once, and
  4. the number of the port you select for Single Processing Engine to use; we recommend a number not less than 32000.

Capture the output in a file. For example, suppose that your serial number is SN-Yy3X-ptdi-gpa-u[4, the selected port number is 40999 and you want to save the request key in the file req.txt: 

  omspe -log req.txt -reqkeygen "SN-Yy3X-ptdi-gpa-u[4" [email protected] "Machine Sol23" 40999

OmniMark Single Processing Engine will generate a request key and write it to the specified file. Email the contents of req.txt in the body of a plain text email to [email protected]. You will receive an authorization key by return email.

Create an environment variable called OMNIMARK_INFO and give it the value AUTH: followed by your authorization key. If you already have an OMNIMARK_INFO environment variable, you can add your new key to the end of the existing key using a semi-colon as a separator. For details on setting environment variables, consult the documentation for your shell or contact your system administrator.

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.

Running OmniMark Single Processing Engine

To run an OmniMark program on Windows start a Command Prompt window by selecting Command Prompt from the Start Menu; on UNIX, bring up a shell prompt.

To run OmniMark programs from source,

  1. write and debug your program, and
  2. run the program using the -s command line option.

To run compiled OmniMark programs,

  1. use the OmniMark Development Toolkit to create a virtual machine code file (.xvc file) from your project, and
  2. run the file using the -load command line option.

Command line options preceded by a single hyphen ("-") character are interpreted by OmniMark Single Processing Engine. Other command-line options (including those preceded by two or more hyphen characters) are passed to the OmniMark program and are made available on the #args shelf.

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 Single Processing Engine 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. The following command line loads program.xvc and reads command line options from the file arguments.xar. 

  omspe -load program.xvc -f arguments.xar

If you place the -load argument into an arguments file, you can start OmniMark Single Processing Engine using an arguments file alone. The following command line causes OmniMark Single Processing Engine to read options, including the -load option, from the arguments file program.xar. 

  omspe -f program.xar

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

  #!/usr/bin/omspe -f
  -load program.xvc
  -d name Fred
  -c age 5
  input.txt
  -of output.txt

You can include the #! directive in an arguments file. It will be interpreted appropriately on a UNIX system and will generally be ignored on a Windows system. If used, the #! line must contain the -f command-line option, which causes OmniMark Single Processing Engine to read the arguments file.

You may include command line arguments meant for the OmniMark program as well as OmniMark Single Processing Engine arguments in an arguments file. Additionally, you can load one arguments file from inside another arguments file.

Command-line options

The command-line options for OmniMark Single Processing Engine are listed below. Many command-line options have short forms.

Loading compiled OmniMark programs

A compiled OmniMark program can be loaded and executed using 

  -load myprog.xvc

Running OmniMark programs from source

To run an OmniMark program from source, use 

  -s sourcefile.xom
The -s command-line option can also be written -source or -src.

Specifying arguments files

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

  -f testprogram.xar
The -f command-line option can also be written -argsfile.

Controlling license locking

The -licto command-line option is used to specify a maximum time, in seconds, that OmniMark should continue to try to obtain authorization.

The -licri command-line option is used to specify a time, in seconds, that OmniMark should wait between attempts to obtain authorization.

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 (port locking)

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

  -reqkeygen "SN-Yy3X-ptdi-gpa-u[4" [email protected] "Machine Sol23" 40999
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