The PC OPL translation programs =============================== The \OPL directory contains the following programs which can be used to translate standard Series 3/3a and HC OPL files into OPO files which can be run on the computer concerned: S3TRAN.EXE for translating OPL files to be run on the Series 3 S3ATRAN.EXE for translating OPL files to be run on the Series 3a HCTRAN.EXE for translating OPL files to be run on the HC Using the translation programs on Windows-based PCs --------------------------------------------------- 1. Display the DOS prompt window, or select the `Run' option on the `File' menu in the Windows Program Manager. 2. On the DOS command line, or on the `Command line' line of the `Run' dialog, type the drive and directory in which you installed RCom, then \OPL, then the name of the translation program you wish to use, then a space followed by the file specification of the OPL file that you wish to translate. For example: C:\PSRCOM\OPL\S3ATRAN.EXE C:\OPL\MYPROG.OPL Using the translation programs on DOS-based PCs ----------------------------------------------- 1. Display the DOS prompt and make sure that the current directory is the directory in which you installed RCom. 2. Type CD OPL to change to the \OPL subdirectory where the translation programs are stored. 3. Type the name of the appropriate translation program and then the path of the OPl file to translate. For example: S3ATRAN C:\OPL\MYPROG.OPL About the translation programs ------------------------------ Any existing .OPO file of the same name will be overwritten by the tranlation process. You can use wildcards in the file specification, if you wish. For example, S3ATRAN *.OPL translates all .OPL files in the current directory. If the translation fails, the translation program will report the first error it finds in each procedure. If you use the Brief programmers' editor, note that the error messages displayed are in the format required by Brief. (For more details, see your documentation for Brief.) The translation programs contain a preprocessor which allows you to use C-style comments, header files, symbol definitions and conditional translation. Comments -------- In addition to the REM statement in OPL, comments may be placed between `/*' and `*/'. Such a comment can spread over many lines - e.g.: /* this is a comment which is 2 lines long */ This may be useful for temporarily "removing" a block of code during debugging, or when writing long comments. Symbol definitions ------------------ Use #define to give meaningful names to numeric constants - for example: #define DISKFULL -37 You can then use this symbol definition instead of the number - for example RAISE DISKFULL - making your program easier to understand. Symbols are also used to define parameters which may change in different versions of a program, such as: #define SCREENWIDTH 40 You can define a symbol to save repetitive or error-prone typing: #define CHECKMSG "Checking files"+chr$(7); You can also define a symbol to control conditional compilation - see below. Conditional Compilation ----------------------- If you use, say, #define DEBUG (you don't need to define it AS anything) you might later use debugging code, like this: #ifdef DEBUG AT 1,1 :PRINT "c% is currently",c% #endif Here, the translation program translates the line(s) between #ifdef and #endif only if DEBUG has been defined as a symbol. When you want to make a final version of your program, you can remove the #define DEBUG, and debugging statements such as this one will not be translated. If you use #ifndef instead of #ifdef the subsequent code will only be translated if a symbol has NOT been defined. You can use #if to control compilation in a similar way to #ifdef/#ifndef. It evaluates some condition based on your symbol definitions - for example: #if SCREENWIDTH<40 PRINT "Not supported on this screen" #endif You can use brackets and most standard C operators in these conditions. These operators are as in OPL: > < >= <= * / - + These are different to OPL: == equals != not equals && logical AND || logical OR ! logical NOT You can use #else and #elseif with #ifdef/#ifndef/#if in the same way that you use ELSE and ELSEIF in OPL. Header files ------------ You can tell the translation program to include a different file at a given point in a program, by using #include. For example: #include "commsdef.oph" includes a file called `commsdef.oph' from the current directory. Typically you would use #include with header files (also called "include files") containing symbol definitions which you want to use in more than one OPL file. Command line options -------------------- Use the -i flag to define a path where header files may be found - e.g.: S3ATRAN *.OPL -ic:\src\h\ To include such headers, you should use angle brackets in the relevant #include, in place of quote marks - e.g: #include If your program includes filenames using quote marks in the #include, the translation program will still look for it in the current directory. Use a separate directory for header files if more than one OPL project needs to use the same OPL headers. The -d flag allows you to define up to 9 additional symbol definitions for this one translation to use. You might, for example, type this: S3ATRAN MYPROG -dDEBUG -dSCREENWIDTH=80 to produce a particular version of your program. Note the use of an `=' sign, when defining a value for a symbol. Computers supported ------------------- S3TRAN, S3ATRAN and HCTRAN can translate the full Series 3 specification of OPL; if you use an HC you should use only the commands and functions available in its version of OPL. If a translated OPL program contains an instruction specific to the Series 3, and you try to run it on a different computer, it will stop when this point is reached. None of the tranlation programs are for use with Psion Organiser II OPL programs.