home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PSION / COMMS / RCOM114 / OPL / README.TXT < prev    next >
Encoding:
Text File  |  1994-10-13  |  6.2 KB  |  186 lines
  1.                 The PC OPL translation programs
  2.                 ===============================
  3.  
  4. The \OPL directory contains the following programs which can be used
  5. to translate standard Series 3/3a and HC OPL files into OPO files
  6. which can be run on the computer concerned:
  7.  
  8.  S3TRAN.EXE    for translating OPL files to be run on the Series 3
  9.  S3ATRAN.EXE   for translating OPL files to be run on the Series 3a
  10.  HCTRAN.EXE    for translating OPL files to be run on the HC
  11.  
  12. Using the translation programs on Windows-based PCs
  13. ---------------------------------------------------
  14.  
  15. 1. Display the DOS prompt window, or select the `Run' option on the
  16. `File' menu in the Windows Program Manager.
  17.  
  18. 2. On the DOS command line, or on the `Command line' line of the
  19. `Run' dialog, type the drive and directory in which you installed
  20. RCom, then \OPL, then the name of the translation program you wish to
  21. use, then a space followed by the file specification of the OPL file
  22. that you wish to translate. For example:
  23.  
  24. C:\PSRCOM\OPL\S3ATRAN.EXE C:\OPL\MYPROG.OPL
  25.  
  26. Using the translation programs on DOS-based PCs
  27. -----------------------------------------------
  28.  
  29. 1. Display the DOS prompt and make sure that the current directory is
  30. the directory in which you installed RCom.
  31.  
  32. 2. Type CD OPL to change to the \OPL subdirectory where the
  33. translation programs are stored.
  34.  
  35. 3. Type the name of the appropriate translation program and then the
  36. path of the OPl file to translate. For example:
  37.  
  38. S3ATRAN C:\OPL\MYPROG.OPL
  39.  
  40. About the translation programs
  41. ------------------------------
  42.  
  43. Any existing .OPO file of the same name will be overwritten by the
  44. tranlation process.
  45.  
  46. You can use wildcards in the file specification, if you wish. For
  47. example, S3ATRAN *.OPL  translates all .OPL files in the current
  48. directory.
  49.  
  50. If the translation fails, the translation program will report the
  51. first error it finds in each procedure. If you use the Brief
  52. programmers' editor, note that the error messages displayed are in
  53. the format required by Brief. (For more details, see your
  54. documentation for Brief.)
  55.  
  56. The translation programs contain a preprocessor which allows you to
  57. use C-style comments, header files, symbol definitions and
  58. conditional translation.
  59.  
  60. Comments
  61. --------
  62. In addition to the REM statement in OPL, comments may be placed
  63. between `/*' and `*/'. Such a comment can spread over many lines -
  64. e.g.:
  65.  
  66.     /* this is a comment which
  67.     is 2 lines long */
  68.  
  69. This may be useful for temporarily "removing" a block of code during
  70. debugging, or when writing long comments.
  71.  
  72. Symbol definitions
  73. ------------------
  74. Use  #define  to give meaningful names to numeric constants - for
  75. example:
  76.  
  77.     #define DISKFULL -37
  78.  
  79. You can then use this symbol definition instead of the number - for
  80. example  RAISE DISKFULL  - making your program easier to understand.
  81.  
  82. Symbols are also used to define parameters which may change in
  83. different versions of a program, such as:
  84.  
  85.     #define SCREENWIDTH 40
  86.  
  87. You can define a symbol to save repetitive or error-prone typing:
  88.  
  89.     #define CHECKMSG "Checking files"+chr$(7);
  90.  
  91. You can also define a symbol to control conditional compilation - see
  92. below.
  93.  
  94. Conditional Compilation
  95. -----------------------
  96. If you use, say,  #define DEBUG  (you don't need to define it AS
  97. anything) you might later use debugging code, like this:
  98.  
  99.     #ifdef DEBUG
  100.       AT 1,1 :PRINT "c% is currently",c%
  101.     #endif
  102.  
  103. Here, the translation program translates the line(s) between  #ifdef 
  104. and  #endif  only if DEBUG has been defined as a symbol. When you
  105. want to make a final version of your program, you can remove the 
  106. #define DEBUG, and debugging statements such as this one will not be
  107. translated.
  108.  
  109. If you use  #ifndef  instead of  #ifdef  the subsequent code will
  110. only be translated if a symbol has NOT been defined.
  111.  
  112. You can use  #if  to control compilation in a similar way to 
  113. #ifdef/#ifndef. It evaluates some condition based on your symbol
  114. definitions - for example:
  115.  
  116.     #if SCREENWIDTH<40
  117.       PRINT "Not supported on this screen"
  118.     #endif
  119.  
  120. You can use brackets and most standard C operators in these
  121. conditions. These operators are as in OPL:
  122.     >  <  >=  <=  *  /  -  +
  123. These are different to OPL:
  124.     ==  equals
  125.     !=  not equals
  126.     &&  logical AND
  127.     ||  logical OR
  128.     !   logical NOT
  129.  
  130. You can use  #else  and  #elseif  with  #ifdef/#ifndef/#if  in the
  131. same way that you use ELSE and ELSEIF in OPL.
  132.  
  133. Header files
  134. ------------
  135. You can tell the translation program to include a different file at
  136. a given point in a program, by using #include. For example:
  137.  
  138.    #include "commsdef.oph"
  139.  
  140. includes a file called `commsdef.oph' from the current directory.
  141.  
  142. Typically you would use  #include  with header files (also called
  143. "include files") containing symbol definitions which you want to use
  144. in more than one OPL file.
  145.  
  146. Command line options
  147. --------------------
  148. Use the  -i  flag to define a path where header files may be found -
  149. e.g.:
  150.  
  151.     S3ATRAN *.OPL -ic:\src\h\
  152.  
  153. To include such headers, you should use angle brackets in the 
  154. relevant  #include, in place of quote marks - e.g:
  155.  
  156.     #include <general.oph>
  157.  
  158. If your program includes filenames using quote marks in the #include,
  159. the translation program will still look for it in the current
  160. directory.
  161.  
  162. Use a separate directory for header files if more than one OPL
  163. project needs to use the same OPL headers.
  164.  
  165. The  -d  flag allows you to define up to 9 additional symbol
  166. definitions for this one translation to use. You might, for example,
  167. type this:
  168.  
  169.     S3ATRAN MYPROG -dDEBUG -dSCREENWIDTH=80
  170.  
  171. to produce a particular version of your program. Note the use of an
  172. `=' sign, when defining a value for a symbol.
  173.  
  174. Computers supported
  175. -------------------
  176. S3TRAN, S3ATRAN and HCTRAN can translate the full Series 3
  177. specification of OPL; if you use an HC you should use only the
  178. commands and functions available in its version of OPL. If a
  179. translated OPL program contains an instruction specific to the
  180. Series 3, and you try to run it on a different computer, it will
  181. stop when this point is reached.
  182.  
  183. None of the tranlation programs are for use with Psion Organiser II
  184. OPL programs.
  185.  
  186.