# `opltran.exe` — Command line OPL translator

## Contents

- Purpose
- Command-line syntax

### Purpose

The `opltran` utility provides command-line OPL translation from the PC command line. It is invoked using the `opltran.bat` batch file, with up to five parameters; only one of which is mandatory.

OPL source files and include files may be in text format or native EPOC format. This allows programs developed on an EPOC machine to be transferred to and from the PC with the minimum of conversion.

### Command-line syntax

  `opltran` opl-filename [`-i` include-path] [`-o` output-path] [`-s`] [`-e`] [`-q`] [`-conv`]

#### Arguments

opl-filename | The name of the OPL source file to be translated. The name must be fully qualified (e.g. `h:\epoc32ex\opl\ophello.opl`), with the following exceptions: if the OPL source file is located in the current directory, its filename alone may be specified if unspecified, the drive letter will default to the drive on which `opltran` has been installed Wild cards may be specified in order to translate multiple OPL files within the same directory, e.g. `?` to match a single character or `*` to match a group of characters.
include-path | The directory in which to search for header files.
output-path | The target directory for the `.opo` output file.
`-i` | Set include path. Optional, but if supplied, specifies the directory in which to search for header files. Directories are searched in the following order: first, the directory containing the opl-filename source file; second, the include-path provided by this argument, if specified; third, the directory `\epoc32\winc\opl\;` and finally, the directory `\epoc32\release\wins\deb\z\system\opl\`. The header file can be in text format, or native EPOC format.
`-o` | Set output path. Optional, but if supplied, specifies the target directory for the `.opo` output file. If this parameter is not supplied, the output file is generated in the same directory as the source opl-filename. If the program is an OPL app, this parameter is ignored — the app will be generated in directory `\epoc32\release\wins\deb\z\system\apps\`appname`\`.
`-s` | Symbolic debugging information. Optional, but if supplied, causes debugging information to be incorporated in generated `.opo` or`.app` files. In a addition, a `.sym` file is created in the same directory as the `.opo` or `.app`, which provides symbolic debugging information.
`-e` | Alternate error format. Optional, but if supplied, translation errors are reported using an alternate format used by popular PC-based editors: filename(lineNum) `:` error errNum : column colNum : error msg For example, a syntax error (error 19) at line 10, column 5 of the file would be reported as:
        h:\epoc32ex\ophello.opl(10) : error 19 : column 5 : Syntax error
`-q` | Quiet mode. Optional, but if supplied, reports errors only.
`-conv` `` | Converter mode. Optional, but if supplied, converts source files from ASCII source to EPOC program file format, or visa versa. The direction of the conversion is dependent of the current source file format. When the files are converted, the first letter of the extension is also changed, e.g. in a conversion from OPL to ASCII, `opl`, `ohx` and `oph` files become `tpl`, `txh`, and `tph` respectively.

#### Notes

- A brief summary of the command-line syntax may be obtained by typing `opltran` at the command prompt.
- The include and output paths must be fully qualified (although the drive letter defaults to the letter specified in the source file opl-filename). Relative paths are not recognised.
- The search method used when including header files into the program allows `opltran` to use the native format OPL include files as supplied with the emulator in \epoc32\release\wins\deb\z\system\opl\, as well as additional generic include files stored as text or EPOC format in \epoc32\winc\opl\.
- WINC file handling prevents writing to the PC Z: drive. As opltran runs in the WINC environment, writing opo/app files to Z: drive is not permitted. If you are translating OPL source on Z:, use the -ooutput_path option to direct the output to another drive.
- When the `-conv` flag is specified, no translation is performed (e.g. the `-i`, `-s`, `-e` and `-q` flags are ignored).
- `opltran` will silently overwrite any existing files, so ensure you have a backup of your source code before using the tool.
- If an error is detected during translation, the tool stops with an exit status of 1. This can be detected with the batch errorlevel command. A descriptive error message is output in the following format:

  Error filename line Num`:` error msg

e.g. `Error LOC::h:\epoc32ex\ophello.opl 10: Syntax error`