home *** CD-ROM | disk | FTP | other *** search
/ PSION CD 2 / PsionCDVol2.iso / Programs / 361 / OPLPLUS.SIS / OPLPlus.hlp (.txt) < prev    next >
Encoding:
EPOC Database  |  1998-10-04  |  52.4 KB  |  617 lines

  1. "data.app)@
  2. Courier
  3. AThe #define pre-processor directive is used to create a simple macro definition. For example the following line is added to the OPP source file:
  4.     #define MAX_ARRAY    10
  5. From this point onwards any occurrence of MAX_ARRAY in the OPP code will be replaced by 10 when the pre-processor is run.
  6. Macros may be defined from other macros, e.g.
  7.     #define WIDTH     5
  8.     #define HEIGHT 10
  9.     #define SIZE (WIDTH*HEIGHT)
  10. yAMacro functions are an extension of the simple macros described in the previous section. They are analogous to OPL procedures in that they take arguments. For example:
  11.     #define GT?(a,b) if (a<=b)                :\
  12.                     print a,
  13. failed
  14.                     endif
  15. With the above definition the following OPP code....
  16.     GT?(x%,0)
  17. ...would expand to...
  18.     if (x%<=0) :print x%,
  19. failed
  20.  :endif
  21. B## is an ANSI standard token. Again, due to the use of # by OPL, the pre-processor uses the identifiers !! instead. Consider the following macro definition:
  22.     #define M(name)    module!!name!!%:
  23. The !! characters indicate a delimiter for a macro function argument. OPP notes the delimiter and then discards the !! characters from the expansion. Thus the following...
  24.     M(a)
  25. ...would expand to...
  26.     modulea%:
  27. Without the !! OPP would not detect the presence of the name argument since neither 
  28.  nor % are normal delimiter characters.
  29. $EOPL includes the conditions if, else, elseif and endif. OPP has similar directives #if, #ifdef, #ifndef, #else, #elif and #endif which are analogous to OPL commands.
  30. Using conditional pre-processor directives provides control over the sections of OPP code which are to be translated. For example:
  31.     #define DEBUG
  32.     #ifdef DEBUG    
  33.         print 
  34. Translated with brief debug enabled
  35.         #ifdef MOREDEBUG        
  36.             print 
  37. Translated with additional debug enabled
  38.         #endif
  39.     #else    
  40.         print 
  41. Debug code not translated
  42.     #endif
  43. The #ifdef directive tests for the presence of a macro, if it exists then the remaining code up to a matching #endif or #else is passed to the OPL translator. #ifndef has the opposite affect, i.e. the condition is true if the macro does not exist.
  44. The condition 
  45. #if expression
  46.  is true if the expression evaluates to true or non-zero. Examples of valid expressions are as follows:
  47.     #if DEBUG_LEVEL > 2
  48.     #if OsVersion >= $300
  49.     #if LcdType = 11
  50.     #if (PsuType = 2) or (PsuType = 3)
  51. #elif expression
  52.  may be used as follows:
  53.     #if DEBUG_LEVEL = 1    
  54.         print 
  55. debug level 1
  56.     #elif DEBUG_LEVEL = 2    
  57.         print 
  58. debug level 2
  59.     #elif DEBUG_LEVEL = 3    
  60.         print 
  61. debug level 3
  62.     #else
  63.         print 
  64. no debug
  65.     #endif
  66. Note that the current release of OPP does not support use of 
  67. defined()
  68.  in #if or #elif expressions.
  69. GOther OPP files may be included into the file being translated using the #include directive. This takes one of two forms as shown in the following examples:
  70.     #include <os\calls>    
  71.     #include 
  72. my_procs.oph
  73. The first #include will cause the pre-processor to search for a file in the system include directory.
  74. The default system include directory is:
  75.     C:\System\Apps\OPLPlus\Include\
  76. ...this location can be altered from the OPL+ 
  77. Project->Folders
  78.  menu.
  79. If the file is found it will be included into the translation at that point. This form of include is used for system include files. These include files are generic files which are not written for any one specific OPP program.
  80. Note that by default the OPH extension is assumed for system include files, although this may be overridden by explicitly stating the extension in the include 
  81. filename.
  82. The second form of include, which uses the delimiters 
  83.  rather than <>, is for specifying include files which are specific to the program being translated. The processor will default to looking in the same directory as the program being translated and will look for a file with the same extension. A full filename which includes a path and file extension may be given to override this.
  84. Usually include files only contain pre-processor directives such as macro definitions, in which case the file extension OPH should be used rather than OPP. The OPH editor is supplied to allow include files to be listed on the system screen separate from any OPP and OPL files.
  85. Note: On EPOC32 the OPL translator supports the include keyword mainly for including OPX headers. It is important to understand that the OPL include statement will be read and handled by the OPL translator, and the #include keyword read and handled by OPP. This has two important consequences:
  86. 1. Always use the OPL include for OPX header files, failure to do so will confuse the translator.
  87. 2. Do not add any OPP extensions to an include file which is included using the OPL include keyword.
  88. AWhenever OPP translates a file it will automatically include the following file before reading any OPP code:
  89.     OPP_INIT.OPH
  90. With the EPOC32 version of OPP it will look for this file in the system include directory, e.g.
  91.     \System\Apps\OPLPlus\Include\OPP_INIT.OPH
  92. If there are any OPP directives which are used in all OPP code then the OPP_INIT.OPH file is a good place to put them without having to explicitly use a #include <opp_init>.
  93. lAUsing the #include directive it is possible to build a large OPO or APP from a number of separate OPP source code files. Splitting the code in this way makes it easier to manage.
  94. At the end of your main source file add include statements to include each additional source file, e.g.
  95.     #include "UserInterface.opp"
  96.     #include "Engine.opp"
  97.     #include "Documents.opp"
  98. BRevtran is a program which allows OPO files to be reverse translated back into OPL source code. The no_revtran pragma may be used to prevent the reverse translation of the no_revtran line. The way it works is to insert some OPL code into the translation which causes the Revtran program to fall over.
  99. Note that I cannot guarantee that the no_revtran option will stop future versions of Revtran from working, or that it will keep sufficiently determined people from reverse translating your programs. The no_revtran option has been tested against Revtran 3.3a.
  100. #pragma no_revtran
  101.  line should appear within a procedure at the top of the OPP file. Revtran will be able to reverse translate up to this line but no further.
  102. BUse 
  103. #pragma stop_on never
  104.  to instruct the pre-processor to display any pre-processor error or warning messages and to continue processing the OPP code.
  105. #pragma stop_on error
  106.  to stop whenever an error occurs but continue if there is a warning.
  107. #pragma stop_on warn
  108.  will cause the pre-processor to stop on both warnings and errors.
  109. The default mode is 
  110. error
  111. , in which case as soon as a pre-processor error is detected control will return to the OPL+ editor.
  112. never
  113.  switch could be used whenever you want to find all errors within a newly written include file in one go, rather than fixing each one individually. It may also be useful if any error occurs within an include file and you need to pinpoint exactly which line the error was on.
  114. zBWhen OPP processes OPL source it records the procedures which have been defined and those which have been called. The check_procs pragma instructs OPP to check the list of procedures called against the list of defined procedures. If OPP finds any procedures which have been called but not defined then it will list them. OPP will also list any procedures which are defined but never explicitly called. Note that in this later case OPP cannot detect procedure calls which are made using a string variable (refer to the Psion Programming Manual, Advanced Topics section). The best place for this pragma is at the end of the OPL source.
  115. #pragma to_file preproc.opl
  116.  would instruct the pre-processor to send pre-processed lines both to the translator and the file preproc.opl. This may be used to extract pre-processor directives and macros from an OPP source file. Note that the filename does not include quotes.
  117. [AThe use of this pragma statement is strongly discouraged.
  118. #pragma pack 2
  119.  will set the structure packing size to 2 bytes.
  120. The packing size controls how OPP packs fields into structures and the alignment of fields within a structure. 
  121. The default pack size is 1 which means that OPP packs structures so that there are no spaces between fields.
  122. BDOPP allows you to write one set of OPP code that can be used with both EPOC16 and EPOC32 machines.
  123. The basic problem with writing EPOC16 and EPOC32 code is that on EPOC16 pointers are 16bits wide, whereas on EPOC32 pointers should be 32bits wide.
  124. Pointers are used when allocating memory dynamically and using OPP
  125. s C style structure facility.
  126. To solve the problem OPP introduces a new pointer variable type identified with an @ character. Depending upon whether OPP is running on an EPOC16 or EPOC32 machine any variables declared with the @ symbol will be converted by OPP automatically into either 16bit or 32bit integers.
  127. The following OPP code demonstrates this:
  128.     #ifdef EPOC32
  129.         #pragma epoc32
  130.     #endif
  131.     STRUCT s
  132.         int%
  133.         ptr@
  134.     ENDS
  135.     PROC main:
  136.         local <s*>p@
  137.         p@=alloc(SIZEOF(s))
  138.         p@->int%=1
  139.         p@->ptr@=p@
  140.     ENDP
  141. With EPOC32 defined you get the following out of OPP:
  142.     PROC main:
  143.         local p&
  144.         p&=alloc(6)
  145.         pokew p&,1
  146.         pokel p&+2,p&
  147.     ENDP
  148. With EPOC32 not defined you get the following out of OPP:
  149.     PROC main:
  150.         local p%
  151.         p%=alloc(4)
  152.         pokew p%, 1
  153.         pokew uadd(p%,2),p%
  154.     ENDP
  155. FWith standard OPL only one dimensional arrays are supported, for example:
  156.     local a%(5)        /* 1-d array of integers */
  157.     local a$(5,8)    /* 1-d array of 5x8 character strings */
  158.     a%(1)=1
  159.     a%(2)=2
  160.     a$(1)=
  161. abcdefgh
  162. When using OPP multi-dimensional arrays may be used, for example:
  163.     local a%(5,3)    /* 2-d array of integers */
  164.     local a$(2,5,8)    /* 2-d array of 8 character strings */
  165.     a%(1,1)=1
  166.     a%(1,2)=2
  167.     a$(1,1)=
  168. abcdefgh
  169. OPP supports arrays with up to 20 dimensions!
  170. The memory structure for a multi-dimensional array is such that the if you add one to the last subscript then this will be located in memory adjacent to the previous array element, for example a%(2,3) is stored as:
  171.     a%(1,1) a%(1,2) a%(1,3) a%(2,1) a%(2,2) a%(2,3)
  172. Multi-dimensional arrays may be declared as local or global variables. However in the case of global variables an additional syntax is required in order to be able to access any variables which are outside the scope of the current OPL file. Suppose for example you have the following in one OPL module or source file:
  173.     global a%, b%(2,3)
  174. In a separate OPL module which may be loaded into memory using the standard LOADM OPL function you can reference the global variables from the first module:
  175.     a%=1
  176.     b%(2,1)=2
  177. In the case of the variable a% there is no problem with the above code, however in the case of the 2d array b%() OPP needs to know what the definition of the array was in order to work out where the element (2,1) is in memory. This is accomplished using an external variable definition:
  178.     extern b%(2,3)
  179. The extern declaration syntax behaves exactly like a local or global OPL definition but is used merely to declare to OPP the dimensions of global multi-dimension arrays which are outside the scope of the current file.
  180. COPP supports a special type of procedure which is designed to enable procedure source libraries to be built. A library procedure is defined using LIBPROC rather than PROC, e.g.:
  181.     LIBPROC test:    
  182.         print 
  183.     ENDP
  184. A library procedure is identical to a normal procedure with one exception. When OPP processes an OPL source file it records which procedures have been called. When OPP finds a library procedure it checks the list of procedures which have been used and only includes the procedure if it has been called.
  185. The library procedure allows a number of useful procedures to be grouped into a single OPL source file and then the file included as a whole in a number of separate programs. Only the procedures actually used within a program will be translated and included in the final OPO or OPA module.
  186. Note that OPP processes source serially so that if a LIBPROC appears in the source code but is not referenced until later in the file then it will not be included.
  187. GThe OPL pre-processor will look for the characters 
  188.  and 
  189.  within the OPP code and will convert them into something which the OPL translator will recognise. This feature is provided for greater compatibility with standard C include files.
  190.  character (entered into the OPP editor using the key combination CTRL-124) is used in C code, and is equivalent to the bit-wise OR operator in OPL, i.e. the following line...
  191.     #define FLAG (&1 | &4 | &32)
  192. ...is equivalent to...
  193.     #define FLAG (&1 OR &4 OR &32)
  194. Note that when using bit-wise operations which make use of the OPPEVAL() macro or in #if statements it is vital that the values are explicitly forced to integer values by preceding them with & or $. If this is not done then it can result in a logical OR operation rather than a bit-wise OR, consider:
  195.     OPPEVAL(1 | 2)
  196.     OPPEVAL(&1 | &2)
  197. The first will use a logical OR since 1 and 2 are treated as floating point numbers and will give a result of -1, whereas the second will use a bit-wise OR and give the result 3. Logical and bit-wise OR
  198. s are discussed at the back of the Psion Programming Manual.
  199. OPL uses the $ and & characters as prefixes for short and long hexadecimal numbers respectively. In 
  200.  0x is used as the prefix. For convenience the pre-processor will convert any 0x to $ or &, so the following line...
  201.     #define FLAGS (0x100|0x00000400)
  202. ...is equivalent to...
  203.     #define FLAGS ($100 OR &00000400)
  204. If there are more than 4 digits following the 0x characters a long hexadecimal will be generated (using the & prefix), otherwise a short will be used (using the $ prefix).A number of other C style operators which are found in normal C code are also supported by OPP:
  205. Operator    Purpose                    Example
  206. ++            set variable=variable+1        i%++
  207. -=            set variable=variable-1        i%--
  208. +=            set variable=variable+value    i%+=2
  209. -=            set variable=variable-value    i%-=2
  210. *=            set variable=variable*value    i%*=2
  211. /=            set variable=variable/value    i%/=2
  212. Courier
  213. #pragma no
  214. #pragma pa
  215. #pragma sh
  216. #undef
  217. LIBPROC
  218. Macros - b
  219. "!!" chara
  220. #define
  221. #define
  222. LIBPROC
  223. Macros - b
  224. #pragma st
  225. 'C' style 
  226. Format set
  227. Translatio
  228. Format set
  229. Translatio
  230. Format set
  231. Translatio
  232. Format set
  233. Translatio
  234. Format set
  235. Translatio
  236. Format set
  237. Translatio
  238. Format set
  239. Translatio
  240. Format set
  241. Translatio
  242. Format set
  243. Translatio
  244. Format set
  245. Translatio
  246. Working wi
  247. Project se
  248. Translatio
  249. Formating
  250. #pragma ch
  251. #pragma st
  252. Finding te
  253. Formating
  254. Building a
  255. EPOC32 & E
  256. LIBPROC
  257. #pragma sh
  258. #pragma sh
  259. #pragma sh
  260. #if, #ifde
  261. #include
  262. #pragma ch
  263. #pragma sh
  264. #pragma st
  265. #undef
  266. #pragma pa
  267. #pragma pa
  268. #pragma in
  269. #pragma no
  270. #pragma pa
  271. Multi-dime
  272. opp_init.o
  273. STRUCT
  274. 'C' style 
  275. Ansi '!' c
  276. Line conti
  277. Macro func
  278. Macros - b
  279. #pragma ch
  280. Table1
  281. ColA1
  282. ColB1
  283. ColA2
  284. ColB2
  285. ColA3
  286. ColB3
  287. Index1
  288. ColA3
  289. ColA1
  290. #pragma to
  291. #undef
  292. Ansi '!' c
  293. 4AOPL+ is shareware, if you continue to use it then please register with the author by sending 
  294. 15 or US$25 (cheque or cash) to:
  295.     A. Clarkson,
  296.     23 Worcester Avenue,
  297.     Hardwick,
  298.     Cambridgeshire. CB3 7XG.
  299.     U.K.
  300. To register on-line, and for further details, see:
  301. http://ourworld.compuserve.com/homepages/andyc/
  302. About OPL+
  303. Registrati
  304. Working wi
  305. ^DThe OPL+ editor is project based. This means you create a project and then associate a group of files with it.
  306. A single OPL application may consist of various OPL source files such as:
  307.  the main source file,
  308.  include files,
  309.  source for modules loaded into the main application.
  310. The association of source files with a project provides faster access to the files in the project. Use the buttons on the toolbars to quickly switch between the files in a project.
  311. Files can be added/removed from a project using the following menu options:
  312.  Create new file
  313.  Open file
  314.  Remove file
  315. Any type of file may be added to a project using the "Open file" menu option. Note that while the editor will open any type of file, (including binary files and files created by the standard Psion Program editor), only plain text files can be edited with the editor. 
  316. For a project, one of the files should be designated the main application source file. When selecting the "Build project" menu or toolbar option this will be the file that is translated. Use the "Project Folders" menu option to specify which source file this is.
  317. CThe OPL+ editor allows the editing of plain text OPL source files.
  318. To import existing OPL source files use the "Import OPL file" menu option or copy and paste the source from the standard Psion Program editor.
  319. Any type of file may be viewed within the editor, including binary and Psion Program editor files, but only text files may be edited.
  320. The convention is to use an .OPP file extension for source files, an .OPH file extension for include files.
  321. A project would normally consist of a main OPP  source file with a name matching the project name. The source for the application could be split over a number of OPP files to make the source easier to manage, e.g.:
  322.  MainApp.opp
  323.  UserInterface.opp
  324.  Document.opp
  325.  Engine.opp
  326. The #include statement can be used at the end of MainApp.opp to include the other source files in the application, e.g.:
  327. #include "UserInterface.opp"
  328. #include "Document.opp"
  329. #include "Engine.opp"
  330. @The "Project Folders" menu option allows two folders to be associated with the current project. These are saved with the project.
  331. OPO Output Folder:
  332. When an .OPO file is created (this does not apply to .APP files), it will be created in the given folder. If e
  333. the "Use Output Folder" option is not ticked then OPO files will be created in the same directory as the OPP file being translated.
  334. This option is useful if you are building an APP which uses the LOADM keyword to load OPO modules at runtime from the same folder as the APP file. In this case you would set the "OPO Output Folder" option to the same folder as the APP.
  335. System Includes Folder:
  336. There are three distinct keywords used to include a file:
  337.     include "filename.oxh"
  338.     #include "filename.oph"
  339.     #include <filename.oph>
  340. The first keyword is read and interpreted by the standard Psion OPL translator and is used with OPX include files or files containing CONST declarations. These files should not contain any OPP extensions since they will not be read by OPP. These include files should be in the following folder on any disk:
  341.     \System\Opl
  342. The second keyword, with a # prefix and double quotes, is read and interpreted by OPP. These include files can contain any OPP source code. The include file should exist in the same directory as the file being translated.
  343. The third keyword, with a # prefix and angle brackets, instructs OPP to include a system include file at that point. System include files are general files, e.g. containing non-project specific #defines. OPP will search for these system include files in the folder specified by the "System Includes" option.
  344. Format set
  345. Preference
  346. Translatio
  347. Working wi
  348. Project fo
  349. Project se
  350. "EThe "Project Settings" menu option has the following options:
  351. Project
  352. Main source file: The name of the main source which is translated when the "Build" menu or toolbar button is selected.
  353. OPP Display
  354. Show input: Instructs OPP to display all source lines as they are read.
  355. Show output: Instructs OPP to display all source lines output from the preprocessor.
  356. Show PROC's: Displays the name of each PROC during preprocessing.
  357. Check PROC's: OPP will report all PROC's which do not appear to have been called anywhere and those PROC's which were called but not defined.
  358. Keep .PRE file: During translation OPP will first preprocess the code, removing any OPP specific extensions. The file created will have a .PRE extension. Tick this option to keep this file after translation is complete.
  359. Preprocess only: Runs the preprocessor only on the source code, no OPO or APP file will be generated.
  360. [Generate debug info: This is for future use and is not implemented at present.]
  361. Defines
  362. Defines: Allows #defines to be set. This can be useful if you often translate code in a number of different ways, e.g. to build an APP with and without debug routines, e.g. entering the following...
  363.     DEBUG, DEBUGLEVEL=1
  364. ...is equivalent to having the following at the start of the code...
  365.     #define DEBUG
  366.     #define DEBUGLEVEL=1
  367. Arial
  368. Courier
  369. Arial
  370. Courier
  371. Courier
  372. BThe "Preferences" menu option has the following options:
  373. Syntax highlighting
  374. The OPL+ editor is capable of displaying key lines in bold or italic, e.g. PROC...ENDP lines can be displayed in bold and comments displayed in italic.
  375. Syntax highlighting is optional, and defaults to off, since it does slow down the editor slightly, especially with very large files.
  376. Show tabs
  377. Display tab characters.
  378. Show spaces
  379. Display spaces.
  380. Show page breaks
  381. Display page breaks.
  382. Sort go to proc list
  383. If this option is ticked then the "Go to proc" menu and toolbar option will sort the list of PROC's found in the current source file rather than displaying them in the order they appear in the file.
  384. BThe "Edit->Find" menu option contains the following options:
  385. Find & Find Next
  386. Find text within the current open file.
  387. Replace
  388. Replace text within the current file.
  389. Go to proc
  390. Displays a list of procedures in the current open file. Select a procedure in the list to jump to the source line. See the preference settings for an option which controls whether the list is sorted or not.
  391. Go to line
  392. Enter a line number to jump to that line.
  393. Find in files
  394. Find text within all files below a given folder. Select the found text to open the file and jump to the line.
  395. Display found
  396. Displays the text found using the "Find in files" menu option, (see above).
  397. :BThe "Edit->Format" menu option contains the following menu options:
  398. Layout
  399. Select a region of source code and then use this menu option to auto-indent the code.
  400. Indent & Unindent
  401. Select a region of source code and then use this option to shift the code to the left or right.
  402. Uppercase & Lowercase
  403. Will make the current selection UPPERCASE or lowercase.
  404. Prefix Lines
  405. Will add a given prefix, e.g. "REM ", to the start of each line in the current selection.
  406. Remove prefix
  407. Will remove a given prefix, e.g. "REM ", from the start of each line in the current selection.
  408. ,BOPP is an OPL preprocessor which also adds a number of useful extensions to the OPL language. The OPL+ editor invokes OPP when you translate code.
  409. OPP greatly enhances the capabilities of OPL, some of the facilities it provides are:
  410.  #include
  411.  #define
  412.  #ifdef, #ifndef,..., #endif
  413.  'C' style structures
  414.  Adds support for multi-dimensional arrays to OPL
  415.  LIBPROC - procedure libraries which are only included if they have been called.
  416.  Facilities to prevent reverse translation of code
  417.  C & C++ style comments
  418. See the OPP manual for full details.
  419. Table1
  420. title
  421. Arial
  422. $BOPL+ is an integrated development environment for OPL programmers. 
  423. There are two parts to the package:
  424.  OPL+ editor - a project based OPL programmers editor.
  425.  OPP back-end translator & preprocessor - supports standard Psion OPL, plus adds a number of additional extensions.
  426. Also available separately is the OPP SDK providing the following:
  427.  OPP for EPOC16 (runs on Series 3a/3c and Siena). This package includes OPPDBG, a runtime source level debugger.
  428.  OPP for MSDOS (runs on a PC allowing OPP code to be translated for EPOC16 and EPOC32).
  429. Working with projects
  430. Working with files
  431. Courier
  432. Courier
  433. Finding text
  434. qU    Formating
  435. Project settings
  436. Project folders
  437. Courier
  438. Translation
  439. There are two options for translating source code:
  440.  Translate: Translates the current open file.
  441.  Build: Builds the current project by translating the main source file, as set by the "Project Settings" menu option
  442. Format settings
  443. The "Format Settings" menu has the following options:
  444. Controls the font used by the OPL+ editor. Avoid using a bold or italic font if you use the syntax highlighting option.
  445. Indentation
  446. Controls the tab settings used throughout all source code.
  447. Preferences:
  448. About OPL+
  449. Registration
  450. #define
  451. Courier
  452. Courier
  453. Line continuation '\'
  454. The line continuation character may be used in long or multi-statement macro definitions (as above) or in normal OPL code, e.g.
  455.     dchoice 
  456. Choice
  457. Value1,    \
  458.                        Value2,    \
  459.                        Value3
  460. Courier
  461. Macro functions
  462. Courier
  463. Arial
  464. Arial
  465. Courier
  466. #undef
  467. A macro definition may be removed using the #undef directive followed by the macro name, for example:
  468.     #define DEBUG
  469.     #define MOD(a,b)    (a-(a/b)*b)
  470.     #undef DEBUG
  471.     #undef MOD
  472. Courier
  473. AThe ANSI standard defines the # character to have a special meaning within a macro definition. Due to the fact that # is used within OPL, OPP looks for the character ! rather than #. Consider:
  474.     #define ASSERT(expr)    if not (expr)                :\
  475.                                 print !expr,
  476. failed
  477.                             endif
  478. The presence of the ! character before the macro function variable instructs OPP to quote the expression when expanded. Thus the following line...
  479.     ASSERT(a%>0)
  480. ...would expand to...
  481.     if not (a%>0) :print 
  482. failed
  483.  :endif
  484. "!" charac
  485. #define
  486. "!!" chara
  487. #define
  488. COPP includes a number of pre-defined built-in macros:
  489. Macro            Purpose & Example of value
  490. __FILE__        Name of file being translated, 
  491. C:\OPP\TEST.OPP
  492. __LINE__        Line number being translated, 23
  493. __DATE__        Date of translation, 
  494. May 10 1998
  495. __TIME__        Time of translation, 
  496. 23:53:06
  497. __PROC__        Name of current procedure, 
  498. OPP            OPP version number, $19F
  499. Psion*            Indicates translating on a Psion    
  500. DOS            Indicates translating on a PC    
  501. XTran*            Set if translating for S3 on a S3a    
  502. OsVersion*        Psion OS version number, 3.18F=    $318F
  503. RomVersion*    Psion ROM version number, 3.20F=    $320F
  504. PsuType*        Power supply type 0=old MC, 1=MC, 2=Series 3, 3=Series 3a    3
  505. LcdType*        LCD type, 11=S3a, 11
  506. OPPEVAL()        Evaluate expression, OPPEVAL(SIZE+2)
  507. SIZEOF()        See section on structures, SIZEOF(my_struct)
  508. OFFSETOF()    See section on structures, OFFSETOF(my_struct,field)
  509. *These macros are only available when using the Psion EPOC16 version of OPP.
  510. Macros - built-in!
  511. "!" characterE
  512. Courier
  513. Courier
  514. Courier
  515. "!!" characters 
  516. Courier
  517. 5*#if, #ifdef, #ifndef, #else, #elif, #endif#
  518. Courier
  519. #include"
  520. opp_init.oph$
  521. Courier
  522. 5&Building a single OPO/APP from N files'
  523. Courier
  524. Courier
  525. Courier
  526. #pragma no_revtran%
  527. #pragma stop_on)
  528. #pragma show_input
  529. #pragma show_input on
  530.  (the on part is optional) to instruct the pre-processor to display lines as they are read from the program editor from that point onwards. Use #pragma show_input off to switch the display off.
  531. #pragma show_output
  532. #pragma show_output on
  533.  (the on is optional) to instruct the pre-processor to display lines as they are sent to the OPL translator, i.e. after pre-processing. Use #pragma show_output off to switch output off.
  534. #pragma show_macrosx
  535. #pragma show_macros
  536.  will instruct the pre-processor to print out all defined macros at that point in the translation.
  537. #pragma show_procs
  538. When this pragma is encountered OPP will print out the name of each procedure as it is defined. This is useful if you want to see the progress of t#
  539. he translation and which procedures have been included.
  540. #pragma check_procs(
  541. #pragma to_file*
  542. #pragma pause
  543. #pragma pause
  544.  will pause the pre-processor until a key is pressed. This could be used at the end of the OPP source file or immediately after a show_macros pragma.
  545. IThe following sample code shows how structures are declared and used:
  546. STRUCT user_data
  547.     forename$(40) 
  548.     surname$(40)
  549.     char_data#
  550.     int_data%
  551.     long_data&
  552.     float_data
  553.     string_data$(50)
  554. PROC main:
  555.     local <user_data*>p@
  556.     p@ = make@:
  557.     show(p@)
  558.     destroy:(p@)
  559. PROC make@:
  560.     local <user_data*>ptr@
  561.     ptr@=alloc(SIZEOF(user_data))
  562.     if ptr@=0
  563.         stop
  564.     endif
  565.     ptr@->id%=1
  566.     ptr@->forename$="Andy
  567.     ptr@->surname$="Clarkson
  568.     ptr@->char_data#=%a
  569.     ptr@->int_data%=1
  570.     ptr@->long_data&=123
  571.     ptr@->float_data=1.23
  572.     ptr@->string_data$="Some data
  573.     return ptr@
  574. PROC show:(<user_data*>ptr@)
  575.     print ptr@->id%
  576.     print ptr@->forename$
  577.     print ptr@->surname$
  578.     print ptr@->char_data#
  579.     print ptr@->int_data%
  580.     print ptr@->long_data&
  581.     print ptr@->float_data
  582.     print ptr@->string_data$
  583. PROC destroy%:(<user_data*>ptr@)
  584.     freealloc ptr@
  585. A structure is used to access a block of memory. The structure defines a number of fields which represent locations within the block of memory into which data may be written and from which may be read.
  586. The STRUCT line starts a structure definition and names the structure. The structure name is used later when defining pointers or variables which point to a location in memory which contains data in the given format. The structure name must be unique amongst all structure definitions.
  587. The structure and field names may contain any characters used in a normal OPL variable plus the underscore character. Unlike OPL variables the names may be of any length.
  588. The STRUCT line is followed by the names of the fields within the structure, with one line per field. These field names are used when referencing the memory within a structure. The ENDS line marks the end of the structure.
  589. SIZEOF() is a built-in macro which gives the size of a named structure. This is required when allocating memory, as shown above.
  590. OFFSETOF(struct,field) will give the offset of the field called 
  591. field
  592.  within the structure called 
  593. struct
  594. . So for example...
  595.     OFFSETOF(user_data, int_data%)
  596. ...gives 85 since the int_data% field is offset 85 bytes into the user_data structure. The OFFSETOF() macro is typically used when you need to access the memory address of a given field directly, e.g. you could write:
  597.     peekw uadd(ptr@,OFFSETOF(user_data,int_data%))
  598. ...which would be equivalent to...
  599.     ptr@->int_data%
  600. Courier
  601. Courier
  602. Courier
  603. Courier
  604. #pragma pack.
  605. EPOC32 & EPOC16 pointers/
  606. Courier
  607. Courier
  608. #pragma info, warn, error
  609. These pragma
  610. s instruct OPP to display a information, warning or error message. In the case of the warning and error messages OPP may abort the translation depending upon the stop_on pragma setting.
  611. Multi-dimensional arrays0
  612. Courier
  613. STRUCT1
  614. LIBPROC2
  615. Courier
  616. 'C' style operators5
  617.