home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / MAXONB32.DMS / in.adf / docs.lha / A-Converting_Programs < prev    next >
Encoding:
Text File  |  1994-10-31  |  12.7 KB  |  415 lines

  1.  
  2. Appendix A
  3. Converting Programs
  4.  
  5.  
  6.  
  7. Introduction
  8.  
  9. This Appendix is intended for use by
  10. programmers wishing to convert various forms of
  11. BASIC into MaxonBASIC. It starts with general
  12. notes about all conversions, then is sub-
  13. divided into sections for particular common
  14. BASIC implementations. It finishes with some
  15. hints and tips on writing programs that can
  16. easily be ported to the IBM PC, Macintosh and
  17. Amiga
  18.  
  19.  
  20. General Conversions
  21.  
  22. Most BASICs share a certain core of the
  23. language, no matter how different they seem to
  24. be. PRINT always does the same thing, so does
  25. INPUT and so forth. BASICs can differ by being
  26. machine specific, ANSI standard, or conforming
  27. to a certain style (Microsoft´s QuickBASIC and
  28. Borland´s Turbo Basic are notable examples).
  29. Whichever BASIC you are trying to convert a
  30. program from, you will need to get the source
  31. into ASCII. Some BASICs use ASCII for their
  32. programs anyway, but most interpreters use a
  33. tokenised form that will come out as gibberish
  34. if loaded into the editor. You should save your
  35. program from your BASIC interpreter using an
  36. ASCII option, if possible.
  37. Some things stand very little chance of being
  38. the same from one BASIC to another, in
  39. particular internal floating point
  40. representations and random-access file formats.
  41. One thing to be aware of particularly is that
  42. string length limitations found in other BASICs
  43. do not exist in MaxonBASIC. In particular the
  44. LEN function can return a long integer as a
  45. result, not just an integer as in other BASICs.
  46.  
  47.  
  48. HiSoft BASIC 1
  49.  
  50. The following is a summary of some potential
  51. incompatibilities between HiSoft BASIC 1 and
  52. MaxonBASIC; don´t panic at the size of this list
  53. as the majority of HiSoft BASIC and its baby
  54. sister, Power BASIC, programs will compile
  55. without change. We have listed these under
  56. headings of facilities used.
  57.  
  58.  
  59. LIBRARY statement
  60.  
  61. If you have used a path to the BMAP file
  62. without a colon or leading / you will need to
  63. change this; the best way is to remove the path
  64. and use the MaxonBASIC Library Path option
  65. (LIBPATH).
  66.  
  67.  
  68. REDIM/ERASE of arrays
  69.  
  70. If you dimension an array using just a number
  71. or a constant (e.g. DIM A(1000) you can´t ERASE
  72. or REDIM it in MaxonBASIC 3 unless you add
  73.  
  74.  
  75. REM $DYNAMIC
  76.  
  77.  
  78. before the DIM statement. If the DIM expression
  79. is a non-constant expression e.g.
  80.  
  81.  
  82. array_size=100
  83. DIM A(array_size)
  84.  
  85.  
  86. then there is no need for this change. As well
  87. as enabling the compiler to produce faster code
  88. for static arrays, this change also brings
  89. MaxonBASIC in line with the Microsoft
  90. QuickBASIC usage.
  91.  
  92.  
  93. ERL function
  94.  
  95. If no logical line numbers have been used, this
  96. function will now return the physical line
  97. number that caused the error. If your ONÉERROR
  98. routine is testing to see if ERL is 0 (perhaps
  99. to see if you are still in your initialisation
  100. code) then you´ll need to insert a line number
  101. at the start of your program and test for this
  102. value instead.
  103. This feature was introduced so that modern
  104. programs that need to use an ONÉERROR to ensure
  105. safe termination (freeing operating system
  106. resources for example) can give an indication
  107. of the source of the error. This facility is
  108. however not available in Microsoft BASIC on the
  109. PC.
  110.  
  111.  
  112. LOC on COM1:
  113.  
  114. The LOC statement when used on files opened
  115. with COM1: now returns the number of characters
  116. waiting rather than just a 1 if there are any
  117. characters waiting. So use something like this:
  118.  
  119.  
  120. DO
  121.  chars%=LOC(3)
  122.  IF chars% THEN
  123.      a$=INPUT$(a%,3)
  124.      PRINT a$
  125.  END IF
  126. LOOP
  127.  
  128.  
  129. rather than
  130.  
  131.  
  132. DO
  133.  IF LOC(3) THEN
  134.      a$=INPUT$(1,3)
  135.      PRINT a$
  136.  END IF
  137. LOOP
  138.  
  139.  
  140.  
  141.  
  142. New reserved words
  143.  
  144. The following are now reserved words: BEGINIO,
  145. BYVAL, CURDIR$, FORMATD$, FORMATI$, FORMATL$,
  146. FORMATS$, FREEFILE, INITHOOK, IS, LTRIM$, MAX,
  147. MIN, PEEK$, PRESERVE, RINSTR, RTRIM$, TAGLIST
  148. and so can no longer be used as names for user
  149. variables, sub-programs and labels.
  150. If you are in a hurry to compile your existing
  151. MaxonBASIC 1 program then you can include
  152. HBAm1.BH at the start of your program and then
  153. these reserved words will be disabled.
  154.  
  155.  
  156. AmigaBASIC
  157.  
  158. In the dim, distant past AmigaBASIC was
  159. supplied free with all the Amiga computers and
  160. therefore we endeavoured to make MaxonBASIC 1
  161. as compatible as we could with it. However
  162. despite all the extensions to the language,
  163. MaxonBASIC 3 will run many existing AmigaBASIC
  164. programs unchanged.
  165. Note that all references to AmigaBASIC refer to
  166. version 1.2, the final version.
  167.  
  168.  
  169. De-tokenising
  170.  
  171. Before trying to compile any program from the
  172. interpreter, the source must be converted to
  173. ASCII instead of the special tokenised form
  174. that the interpreter uses to store its files.
  175. To do this , load the interpreter, then load
  176. your program. Select the Output window then
  177. type a line such as
  178.  
  179. SAVE "filename.bas",a
  180. where "filename.bas" should be changed as
  181. required. The ,a at the end is important - it
  182. tells the interpreter to save the file as
  183. ASCII. We strongly recommend that source files
  184. follow the .bas naming convention, so you can
  185. tell them apart from compiled versions, for
  186. example. The file so created can then be used
  187. by MaxonBASIC and you can load it back into the
  188. interpreter at any time without conversion
  189. because MaxonBASIC only uses ASCII files and
  190. the interpreter can read them directly.
  191.  
  192.  
  193. Unimplemented Features
  194.  
  195. The following features of AmigaBASIC are not
  196. implemented in MaxonBASIC:
  197.  
  198. COMMON, RESUME NEXT, OBJECT.PRIORITY
  199. In addition, interpreter only statements such
  200. as LOAD, SAVE etc are not implemented as they
  201. make no sense in a compiler environment.
  202.  
  203.  
  204. Compatibility Issues
  205.  
  206. We have tried wherever possible to be
  207. compatible with the interpreter in both source
  208. syntax and run-time emulation.
  209. In terms of source syntax, MaxonBASIC accepts
  210. practically all legal AmigaBASIC syntax, except
  211. that you may be using a variable which has the
  212. same name as one of the additional reserved
  213. words, such as SYSTAB. If you are in a hurry to
  214. compile an existing AmigaBASIC program then you
  215. can include AmBas.BH at the start of your
  216. program and then these reserved words will be
  217. disabled.
  218. When trying to compile existing programs that
  219. seemed to run perfectly under the interpreter,
  220. the compiler may find errors the interpreter
  221. missed, normally in a section of code that
  222. seldom gets executed. Note that MaxonBASIC does
  223. not allow a variable to be the same name as a
  224. program label, but this is unlikely to cause
  225. problems.
  226. Some AmigaBASIC programs use LOOP as a variable
  227. name: this is not possible with MaxonBASIC as
  228. this is a reserved word used for the general
  229. loop structure.
  230. In terms of run-time emulation, we have tried
  231. to emulate the exact actions of the
  232. interpreter, where it made sense to do so. We
  233. discovered several undocumented features of the
  234. interpreter during the development of the
  235. compiler (e.g. FRE(-3)) and emulated those
  236. found.
  237. However there are bound to be circumstances
  238. that we did not try and if you rely on an
  239. undocumented feature it may not work the same
  240. under the compiler. There are some features of
  241. the run-time system we decided not to emulate,
  242. such limiting the maximum window size to non-
  243. PAL sized screens and various guru-type bugs.
  244. Under the interpreter you can use
  245. DECLAREÉLIBRARY for library sub-
  246. programs/functions before you have used the
  247. LIBRARY statement; the DECLARE statements must
  248. be after the LIBRARY statement in MaxonBASIC.
  249. Multi-dimensional arrays are stored in a
  250. different order to that used by AmigaBASIC;
  251. generally this isn´t a problem except when the
  252. graphics GET and PUT statements are used with
  253. such an array.
  254. Note that double-precision variables are stored
  255. in a different order in memory between the
  256. compiler and the interpreter, but this will
  257. only effect programs doing rather nasty things
  258. with VARPTR. In addition, single-precision
  259. numbers are stored in a completely different
  260. format (though are still 4 bytes in size) which
  261. has less range than that used by the
  262. interpreter. When reading and writing random-
  263. access files (using MKD, MKS, CVD and CVS) we
  264. are as compatible as possible with the
  265. interpreter though, except for the range limit
  266. on single-precision numbers.
  267. Also note that VARPTR returns a pointer to a
  268. string descriptor, but the string descriptors
  269. themselves are very different under the
  270. interpreter and the compiler. Programs that use
  271. VARPTR to directly adjust string descriptors
  272. will not work without modification.
  273.  
  274.  
  275.  
  276. Old-Style Microsoft BASICs
  277.  
  278. Microsoft BASIC is the closest to a world
  279. standard for the BASIC language and is the one
  280. around which we designed MaxonBASIC.
  281. For this reason most versions of Microsoft
  282. BASIC should not present problems converting to
  283. MaxonBASIC. Programs written in the old-style
  284. BASICs, such as those found in Commodore 64s
  285. and under CP/M should require little or no work
  286. to convert, as long as machine-specific PEEKs
  287. and POKEs are avoided. You can also save typing
  288. by not entering the line numbers that aren´t
  289. needed.
  290. Most BASIC interpreters from other vendors are
  291. at least in part based on the same principles
  292. as Microsoft so should also convert reasonably
  293. easily.
  294.  
  295.  
  296.  
  297. New-Style Microsoft BASICs
  298.  
  299. The new style of Microsoft BASIC is defined by
  300. QuickBASIC, Visual BASIC and the Microsoft
  301. BASIC PDS and running on IBMs and compatibles.
  302. By new-style we mean support for structured
  303. programming such as sub-programs and parameter
  304. passing, CASE, , DO etc. MaxonBASIC supports
  305. almost all the features of QuickBASIC 2 and 3
  306. and most of the features of QuickBASIC 4.0, 4.5
  307. and has some additional features from the PDS
  308. 7.1 system.
  309. The main advantages of MaxonBASIC that you can
  310. exploit when converting programs from the IBM
  311. world, are the large memory and greater graphic
  312. support. In addition, recursive programming
  313. techniques can be used.
  314. When converting QuickBASIC programs there are a
  315. few things which are not supported by
  316. MaxonBASIC by reason of operating system or
  317. hardware differences.
  318. Missing statements under this category are:
  319. COM, CVSMBF,CVSMBF,DRAW, ERDEV, ERDEV$,
  320. FILEATTR IOCTL$, IOCTL, KEY, , LOCK,
  321. MKDMBF$,MKSMBF$, ON various, PAINT, PEN, PLAY,
  322. PMAP, SETMEM, SHELL, UEVENT, UNLOCK, VARPTR$,
  323. VARSEG, VIEW, and WAIT
  324. Obviously PEEKs and POKEs are completely
  325. different, as are machine-code calling
  326. conventions. There are also slight differences
  327. in the following commands:
  328. CIRCLE, CLEAR, CLS, COLOR, FILES, LINE, LOCATE,
  329. OPEN, PCOPY, POINT, SCREEN, SEEK, SOUND, STICK,
  330. and WINDOW.
  331. MaxonBASIC does not at this time support the
  332. following Microsoft BASIC statements:
  333. COMMON , DOUBLE, INTEGER, LONG, RESUME NEXT,
  334. SINGLE, TYPEÉEND TYPE
  335. In addition to this high degree of Microsoft
  336. compatibility, MaxonBASIC also compiles many of
  337. the additional features found in Borland´s
  338. Turbo Basic compiler and Spectra Publishing´s
  339. Power BASIC for the PC.
  340.  
  341.  
  342. HiSoft BASIC on the Atari
  343.  
  344.  
  345.  
  346. The main area of incompatibility here is in
  347. graphics commands. MaxonBASIC does not
  348. support the following HiSoft BASIC Atari
  349. commands:
  350.  
  351. BAR, CLEARW, CLOSEW, ELLIPSE, ENVIRON,
  352. ENVIRON$, FILL, FULLW, GB, GEMSYS, GETCOOKIE,
  353. LINEF, OPENW, PCIRCLE, SPOKB, SPOKEW, SPOKEL,
  354. SPEEKB, SPEEKW, SPEEKL, VDISYS
  355. The following commands are implemented on both
  356. machines but differ in their action:
  357. CIRCLE, COLOR, FRE, PALETTE, SCREEN, SOUND,
  358. SYSTAB, WAVE, WINDOW.
  359. The following are reserved words in MaxonBASIC
  360. 3 Amiga but may be used as variables on the
  361. Atari; either change the variable names or use
  362. the HBST2.BH include file - this will prevent
  363. you from accessing the following BASIC Amiga
  364. commands:
  365.  
  366. AREA, AREAFILL, BEGINIO, BREAK. COLLISION,
  367. CVFFP, INITHOOK, LIBRARY, MENU, MKFFP$,
  368. OBJECT.various, ONÉ various, PAINT, PEEK$,
  369. PTAB, SAY, SCROLL, TAGLIST, TRANSLATE$
  370. In addition, we also supply HBST1.BH which also
  371. excludes the reserved words that were
  372. introduced in version 2 of MaxonBASIC for the
  373. Atari.
  374.  
  375.  
  376. Writing for compatibility
  377.  
  378. We are often asked which compiler you should
  379. purchase to make it easy to port a program that
  380. you´ve written in MaxonBASIC on the Amiga if
  381. you want to move it to another system. At the
  382. time of writing we recommend the following:
  383. For the PC, MicroSoft´s BASIC PDS 7.1 or the
  384. much cheaper, but less sophisticated,
  385. QuickBASIC 4.5 or QBASIC that is supplied with
  386. MSDOS.
  387. For the Macintosh, Microsoft QuickBASIC.
  388. For the Atari ST/TT/Falcon, MaxonBASIC of
  389. course.
  390. If you want to write your program so that it is
  391. easy to port to other systems, here are a few
  392. hints:
  393.  
  394. ·  Isolate   your  use  of  system  specific
  395.    features to a few sub-programs. If you  can,
  396.    try  porting these to other machines  before
  397.    you  use them extensively; you may find that
  398.    you  are  relying on something that is  easy
  399.    on  the  Amiga,  but  different  on  another
  400.    machine.
  401. ·  If  you are porting to a non-MAXON product
  402.    be  wary  of  limitations on  the  sizes  of
  403.    strings  and arrays. QuickBASIC 4.5  doesn´t
  404.    allow  more  than 64K of strings  total  for
  405.    example  and many BASICs won´t let you  have
  406.    more than 32767 elements in an array.
  407. ·  Use  the  forms  of  statement  that   we
  408.    recommend in the Command Reference  section.
  409.    For  example, use EXIT DO rather  than  EXIT
  410.    LOOP  and  REDIM PRESERVE rather than  REDIM
  411.    APPEND.
  412.  
  413.  
  414.  
  415.