home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / MISC / REC.ZIP / CNVADV.HLP < prev    next >
Encoding:
Text File  |  1986-12-01  |  41.9 KB  |  926 lines

  1. Introduction.
  2. Patterns.
  3. Subroutine Groups.
  4. Conditional Skeletons.
  5. Iterative Skeletons.
  6. The "Same" Skeleton <=>.
  7. The (REC/.../) pattern and skeleton.
  8. Memory buffer operations.
  9. Disk system and return to CP/M functions.
  10. Arithmetic Skeletons.
  11. Character "Arithmetic".
  12. Overlays.
  13. Loading of .COM binary files.
  14. Priority Queues (Heaps).
  15. Error messages.
  16. :Introduction.
  17.  
  18. This Help file describes advanced CNVRT features as well as additions and 
  19. changes made to the compiler after CNVPRG.HLP was prepared.  Among the most
  20. noteworthy changes the following may be mentioned:
  21.  
  22.     - Full functionality for pattern definitions and the Boolean
  23.       combinations OR and AND.
  24.  
  25.     - Generalization of skeletons if, nf, while and until.
  26.  
  27.     - Generalization of pattern <[n]>.
  28.  
  29.     - Inclusion of evaluation of general arithmetic expressions whose 
  30.       operands are constants (including floating point).
  31.  
  32.     - Acceptance of any functional skeleton as a pattern.
  33.  
  34. :Patterns
  35.  
  36. References to defined patterns and the Boolean OR now perform as expected, so
  37. that programs such as the following give results consistent with the formal
  38. definition of Convert:
  39.  
  40.     ((    ((OR,[<:e:>],<(><:e:><)>,[<0>],<(><0><)>)) e
  41.     )()(0)(    
  42.         ((^Z),);
  43.         (<:e:><0>,(%t, yes)(%R)):
  44.         (,(%t, no)(%R)):
  45.     ))
  46.     [end]
  47.  
  48. This programs answers "yes" if it finds the same string inside and to the
  49. right of a nest of possibly alternated parentheses and brackets and types "no"
  50. otherwise.  For example, ([[([(ab)])]])ab produces "yes", (b)c gives "no".
  51.  
  52. Making this program work requires that pattern <:e:> "know" what follows it
  53. at the place where it is referenced; this issue has been resolved, so that if
  54. pattern <0> in the second rule fails, the next alternative in the OR is tried
  55. out.
  56. -
  57. The effect on compiled programs, of having defined patterns check the patterns
  58. that follow references to them (in the example, that "e" take into account <0>
  59. in the concatenation <:e:><0>) is an object file requiring up to about 20%
  60. more space, so that CONVERT.REC allows selection of the type of treatment
  61. desired in the compilation of defined pattern references by a flag appended
  62. to the source file name in the command line tail; if no flag appears or is /s
  63. or /S, the code produced is simpler but less general.  A slash followed by
  64. anything other than an s or S indicates full treatment should be given.  For
  65. example, if the above example is placed in a file TEST.CNV, when compiling it
  66. with the command line
  67.  
  68.         REC80 CONVERT TEST/L
  69.  
  70. the program obtained would recognize the string [([ab])][ab], whereas the line
  71.  
  72.         REC80 CONVERT TEST
  73.  
  74. would result in a program in which <:e:><0> would not match that string
  75. (although it would match some simpler strings such as [([ab])]ab).
  76.  
  77. The default is the shorter compilation because most applications to date have
  78. only used simple pattern definitions not requiring the general treatment.
  79. -
  80. The other question now resolved is that of AND.  Consider a concatenation
  81. (AND,p1,...,pn)p, in which it could happen that there is more than one way in
  82. which the concatenation of p1 and p may match the text and that it may not be
  83. necessarily the first alternative (the one that would have p1 matching the
  84. shortest possible text) that for which p2, ..., pn match the same text as p1.
  85. In this case, one requires that if pi fails (i>1), a different way to match p1
  86. and p to the text be sought.  This is necessary even if p is the null pattern,
  87. for consider the following patterns:
  88.  
  89.         (AND,<0>;,<1>ab;)
  90.  
  91.         (and,<0>;,<1>ab;)
  92.  
  93. The first one matches any text containing the substring "ab;"; the second
  94. matches only if no semicolon precedes the first occurrence of "ab;" because <0>
  95. will match the shortest substring left of a semicolon; for instance, the first
  96. pattern maches x;y;ab;z, whereas the second does not.  Notice however that
  97. (and,<1>ab;,<0>;) has the same effect as the AND shown above, illustrating the
  98. convenience of always analyzing the possibility of expressing the desired
  99. pattern in terms of (and,...) and (or,...), which produce less code and are
  100. less time-consuming.
  101.  
  102. -
  103. The length pattern <[n]> admits in place of n any skeleton.  The pattern will
  104. fail to match if the skeleton doesn't evaluate to a string of ASCII decimal
  105. digits, or if the skeleton does evaluate to such a string but there aren't
  106. that many characters in the text under scrutiny.  Some posibilities now
  107. allowed by this pattern are:
  108.  
  109.     <[128]>        A constant skeleton: its original definition.
  110.     <[<0>]>        A variable, which should be already bound to a 
  111.             string of ASCII digits.
  112.     <[(&!,<0>)]>    The length of the value of a variable.
  113.     <[(#f,2*<0>+1)]>    Twice the value of a variable, plus one 
  114.                 (the value of the variable here could be
  115.                 a string of ASCII digits or an arithmetic
  116.                 expression whose operands are integer
  117.                 constants).
  118.  
  119. Assuming <0> is bound to the two-digit string "32", the second pattern will
  120. match a 32-byte string, the third pattern will match a 2-byte string and the
  121. last pattern will match a string of 65 characters.  If the value of <0> is
  122. abc, the second and fourth patterns will fail, while the third one will match
  123. a 3-byte string.
  124.  
  125. -
  126. Any functional, conditional or iterative skeleton may appear wherever a
  127. pattern is allowed.  A skeleton such as (a,<0>:k), (%R), (if,<0>,(^Z),<1>)
  128. or (until,(%R),(^Z),<=>,(%R),), when appearing on the pattern side of a rule
  129. or within a defined pattern, will have the same effect as if a constant 
  130. pattern equal to the value of the skeleton were present in its place.  
  131. Variables used within such skeletons must have been previously bound.
  132.  
  133. :Subroutine Groups.
  134. Since CNVRT inherits REC's features as regards the grouping of subroutines,
  135. groups of defined patterns, defined skeletons and whole programs may be built.
  136.  
  137. The following example shows a defined pattern group:
  138.  
  139.     { ((IVL,0,9)) d  (<:d:>(ITR,<:d:>)) i  ((or,+,-,)<:i:>) I
  140.       ((or,<:i:>.<:i:>,.<:i:>,<:i:>.)) r
  141.       ((or,<:i:>E<:I:>,<:r:>(or,E<:I:>,))) R
  142.       (<:@:>) } K
  143.  
  144. Notice that the main routine of the group must consist only of <:@:>. In this 
  145. example, d matches a decimal digit, i a decimal integer, I an optionally
  146. signed integer, r a decimal number with explicit point and R a general real
  147. constant in the fashion of FORTRAN.  External references to these patterns
  148. are accomplished by writing <:Kd:>, <:Ki:>, <:KI:>, <:Kr:>, and <:KR:>,
  149. respectively.  A reference to the main routine by itself (e.g., <:K:>) is
  150. meaningless and therefore not to be used, and references from within the group
  151. to definitions in the same group need not have the group name, as illustrated
  152. in the example. If no external access is desired to d, i, I or r, R could be
  153. the main program (removing the last line and placing the right brace before
  154. the R); in this case the only valid external reference would be <:R:>.
  155. -
  156. The next example shows a defined skeleton group:
  157.  
  158.     { ((%V,MEM:ll,<=>)) G
  159.       ((%V,MEM:sy,<=>)) Y
  160.       ((@)) } F
  161.  
  162. The main routine of the group must consist only of a reference to the
  163. "skeleton" @.  Outside references to G and Y may take any of the following
  164. forms:  (FG,s), (FG), (FY,s) or (FY), where s is a skeleton whose value will
  165. be passed as an argument to the corresponding skeleton in group F.  (FG) and 
  166. (FY) deliver a null argument to G and Y, respectively.  As with patterns,
  167. groups may be defined in which the main program is not (@), in which case
  168. outside access would only be allowed to the main program of the group.
  169.  
  170. Finally, program groups may also be formed:
  171.  
  172.     { (()()()()) a       (()()()()) b      (()()()()) } A
  173.  
  174. In this case, subroutines a and b are not directly available from outside
  175. the braces, but can only be called mutually and recursively, from the main
  176. program (A) and from any subroutine called from within this same group.
  177.  
  178. :Conditional skeletons.
  179.  
  180. Four conditional skeletons are provided: IF, NF, if and nf.  IF and NF require
  181. a variable list to be given, if and nf do not.  Their general forms are the
  182. following:
  183.  
  184.     (IF,(v),s0{,pj,sjt,sj}[,pF,sFt])
  185.     (if,s0{,pj,sjt,sj}[,pF,sFt])
  186.     (NF,(v),s0{,pj,sjt,sj}[,pF,sFt])
  187.     (nf,s0{,pj,sjt,sj}[,pF,sFt])
  188.  
  189. where v is list of variables (zero or more integers between 0 and 30 with one
  190. space between each pair of variables), the s's are skeletons and the p's are
  191. patterns; braces indicate 0 or more instances of the enclosed list and
  192. brackets indicate 0 or 1 instances of their contents. In IF and NF, the (v)
  193. list creates new instances of the listed variables after s0 has been evaluated;
  194. these instances persist during the execution of the IF or NF and disappear
  195. upon termination.  Otherwise, IF and NF execute like if and nf, respectively.
  196.  
  197.     The next panels describe the operation of if and nf; we repeat 
  198. the form of the corresponding skeleton for ease of reference.
  199.  
  200. -
  201.     (if,s0{,pj,sjt,sj}[,pF,sFt])
  202.  
  203. Skeleton s0 is evaluated and matched to the first pattern, p1.  If they match,
  204. s1t is evaluated and its value becomes the value of the entire skeleton; if
  205. the match fails s1 is evaluated and matched to p2.  This continues until a
  206. match obtains between some sk and p(k+1), in which case the result is s(k+1)t,
  207. or there are no more comparisons to be made, in which case the last skeleton
  208. evaluated for a comparison is left as the result.  In particular, if pF and
  209. sFt appear and pF does not match the last sk, the value of if is that of sk.
  210. The conditional skeleton
  211.  
  212.     (if,(%R),(^Z),<=>(%t,End of file encountered),(%T,<=>))
  213.  
  214. reads a line from the default file; if it finds and end-of-file marker
  215. (control-Z), it leaves it but types the message "End of file encountered"
  216. (the value of %t is the null string); otherwise, it leaves the line read by 
  217. (%R) after typing it.
  218.  
  219. The use of more than one triple [,p,st,s] allows constructs of the "elseif"
  220. type within a single (if,...).
  221.  
  222.  
  223. -
  224.     (nf,s0{,pj,sjt,sj}[,pF,sFt])
  225.  
  226. NF and nf are the negative forms of IF and if, repectively; that is, if s0
  227. does NOT match p1, s1t is substituted, else if s1 does not match p2, s2t is
  228. substituted, etc.  If each sk matches p(k+1), (k=0,...,n and pF=p(n+1)), sn
  229. is left as the result (This includes the case in which pF and sFt are present.)
  230.  
  231. Alternatively, "nf" may be read as "unless":  Unless s0 matches p1, s1t is 
  232. evaluated and delivered as the result, else unless s1 matches p2, s2t is
  233. given as the result, etc.
  234.  
  235. A useful example follows:
  236.  
  237.         (nf,(%Or),Not Found,(a,(%R)))
  238.  
  239. This skeleton will call function a, with argument equal to the first line of 
  240. the default file only if it is possible to open the default file for reading.
  241. Variants of this example include giving arguments to the %Or and %R 
  242. functions.  Notice that if the value of (%Or) is "Not Found", this string
  243. will be left as the value of the nf skeleton since no skeleton follows sFt.
  244.  
  245. :Iterative skeletons.
  246.  
  247. Four iterative skeletons are provided: WHILE, UNTIL, while and until. WHILE
  248. and UNTIL require a variable list to be given, while and until do not. Their
  249. general forms are the following:
  250.  
  251.     (WHILE,(v),sI{,pk,sk,skr}[,sf])
  252.     (while,sI{,pk,sk,skr}[,sf])
  253.     (UNTIL,(v),sI{,pk,sk,skr}[,sf])
  254.     (until,sI{,pk,sk,skr}[,sf])
  255.  
  256. where v is list of variables (zero or more integers between 0 and 30 with one
  257. space between each pair of variables), each s represents a skeleton and each p
  258. represents a pattern; braces denote 0 or more instances of their contents and
  259. brackets indicate 0 or 1 instance of the enclosed item.  In WHILE and UNTIL,
  260. the list v generates new instances of the indicated variables after the initial
  261. skeleton sI is evaluated; these instances persist during the execution of the
  262. iterative skeleton and disappear upon termination. Otherwise, WHILE and UNTIL
  263. perform as while and until, respectively.  
  264.  
  265.     The next panels describe the operation of while and until; we repeat 
  266. the form of the skeleton for ease of reference.
  267. -
  268.     (while,sI{,pk,sk,skr}[,sf])
  269.  
  270. 1.    The initial skeleton sI is evaluated.
  271.  
  272. 2.    If the first pk matches the text, sk is evaluated and put aside and
  273. a new text to match with pk is given by the repetition skeleton skr.  This 
  274. step is repeated until pk no longer matches the text presented to it.  
  275.  
  276. 3.    The last text skr from step 2 (or sI if pk did not match on the very
  277. first try) is used as initial text to match with the next pattern (if any) and
  278. a similar iteration as that of step 2 occurs on the next triple pk,sk,skr.
  279.  
  280. 4.    Similar iterations are performed for each triple pk,sk,pkr; when the 
  281. last pattern pn fails to match its text, its last residue pnr is left on the 
  282. workspace, unless the optional final skeleton sf is present, in which case 
  283. it replaces the text which last failed to match.  The text produced by 
  284. "while" will thus be a concatenation of 0 or more instances of s1, s2, ...
  285. sn and either of the last of snr or sf; the number of instances of each sk
  286. will depend on how many iterations of each triple took place.
  287.  
  288. "Until" performs in a similar manner, except that iteration occurs as long as
  289. the pattern does NOT match.  Examples follow in the next panel.
  290. -
  291. The following WHILE reads the default file, leaving on the workspace its
  292. contents up to but not including the end-of-file marker.
  293.  
  294.     (WHILE,(0),(%R),(and,<[128]>,(NOT,<-->(^Z))),<=>,(%R),<<
  295.         >><=>,<0>(^Z),<0>,)
  296.  
  297. The symbol <=> is the "same" skeleton, whose value is the text used in the
  298. last matching attempt (regardless of the outcome); this skeleton is described
  299. in the next section of this file.
  300.  
  301. The first triple in the above example leaves on the workspace, one by one,
  302. all full disk sectors of the file which do not contain ^Z.  The iteration
  303. ends when either no more sectors remain in the file or a sector is read which
  304. contains a control-Z.  The last text (which is either a null string or a sector
  305. containing a ^Z) is given to the next triple, in which the pattern is <0>(^Z);
  306. if there is a ^Z, <0> will match the text in the sector up to but not including
  307. the ^Z.  A null string is given as the repeat text (the skeleton skr in the
  308. second triple), which will not match <0>(^Z), so the last action of the WHILE
  309. will be to "append" this null text to the right of the contents of the
  310. workspace.
  311.  
  312. An example of until follows.
  313. -
  314.     (until,0,13,(,(%Ow,MEM:<=>)),(#p,<=>),)
  315.  
  316. This skeleton creates 13 memory buffers, named MEM:0 through MEM:12.  After
  317. each comparison, the value of <=> is the text used in the comparison; since
  318. #p increments by one its argument if it is a number, the value of <=> will
  319. succesively be 0, 1, 2,... up to 12; when #p increments 12 to 13 the pattern
  320. matches and the iteration ends.
  321.  
  322. The skeleton which would close these buffers and release the memory associated
  323. with them would be the following:
  324.  
  325.     (until,12,-1,(%C,MEM:<=>),(#m,<=>),)
  326.  
  327. #m decrements its argument by one; notice that closing is performed in the
  328. order opposite to the one followed when opening: since memory buffers
  329. are assigned space on the pushdown list, space must be released in order
  330. opposite to that of arrival.
  331.  
  332. The final value of the skeletons in both examples is the null string.
  333.  
  334. :The "Same" Skeleton <=>.
  335.  
  336. The skeleton <=> may be used wherever a pattern match has taken place, and in
  337. skeletons appearing in the list of skeleton definitions.  It may not appear
  338. in skeletons used as patterns embedded in pattern definitions.  In particular,
  339. <=> may appear anywhere in the skeleton part of a rule and in any skeleton
  340. within a conditional or iterative skeleton.  Its value is the entirety of the
  341. text used in the latest comparison, except when appearing within a skeleton
  342. definition, in which case its value is the text passed as argument to such a
  343. skeleton.
  344.  
  345. For example, if the skeleton definition list contains the definition
  346.  
  347.             ((%W,<8>.<9>,<=>(^MJ))) W
  348.  
  349. and a skeleton (W,abc) is executed at some point, its effect will be to write
  350. five bytes (a, b, c, CR and LF) into the file whose name and extension are
  351. given by variables 8 and 9.
  352.  
  353. :The (REC/.../) pattern and skeleton.
  354.  
  355. The (REC/.../) pattern and skeleton allows REC code to be inserted directly
  356. at the point where it appears.  The inserted code is that delimited by "/";
  357. any character may be used as a delimiter as long as it is not contained in
  358. the code to be inserted.  As a pattern, it can make certain searches faster
  359. than if they are left to the normal Convert mechanisms; as a skeleton it can
  360. help to produce more compact code.
  361.  
  362. The use of this feature requires a thorough knowledge of REC and of the
  363. translation from Convert to REC.  Examples of its use may be found in
  364. RECONVERT.CNV, a Convert compiler for Convert.
  365.  
  366. :Memory buffer operations.
  367.  
  368. Open operations on MEM:-type pseudo files may have an additional argument
  369. whose value should be a string of decimal digits indicating the size in bytes
  370. of the buffer desired.  This number is effective only at the time the buffer
  371. is actually created; it is ignored if the buffer already exists.  If omitted
  372. at the time of the initial opening, 1024 is assumed.
  373.  
  374. Associated with a memory buffer pseudofile there are two pointers: a read
  375. pointer and a write pointer.  When the buffer is first created, both pointers
  376. reflect an empty buffer.  Write operations start writing into a buffer at the 
  377. location indicated by the write pointer, update the pointer to the next
  378. available location when done and remove the written argument from the
  379. workspace, however, if the argument doesn't fit in what's left of the buffer,
  380. nothing is written, the argument remains in the workspace and the write
  381. pointer remains unaltered.  Read operations will transfer to the workspace
  382. that portion of the text starting at the read pointer and matching the pattern
  383. (implicit or explicit) associated with %R.  If the pattern does not match the
  384. text between the pointers, this whole text is returned with a ^Z appended to
  385. it (which is deleted if %R contains an explicit pattern) and the read pointer
  386. moves up to the write pointer.  When there is a match, the read pointer
  387. advances to the byte following the portion of text which matched.
  388. -
  389. When a read is attempted on a MEM: pseudo file in which both read and write
  390. pointers have the same value (either because the buffer is empty or it has
  391. been read out entirely), a single ^Z or the null string is returned, depending
  392. on whether the implicit pattern or an explicit one is used, respectively.  In
  393. any case, the final text returned by %R from a memory buffer will depend on the
  394. presence or absence of the optional skeletons which %R may include.
  395.  
  396. Open operations may be performed on an open buffer, with the following effects:
  397.  
  398.     (%Or,MEM:...)    moves the read pointer to the beginning of the
  399.             buffer, thus making available all of its contents.
  400.  
  401.     (%Ow,MEM:...)    moves both pointers to the beginning of the buffer,
  402.             effectively leaving it empty.
  403.  
  404. Both open operations on a MEM: pseudofile return the address of the buffer as
  405. a four-digit ASCII hexadecimal number; this is provided for use with the %B
  406. direct BIOS call available with CP/M-86.  For most purposes, %O skeletons
  407. involving MEM: buffers should be nested inside the null function (,...) which
  408. erases its argument from the workspace.
  409.  
  410. :Disk system and return to CP/M functions.
  411.  
  412.     (%Lr)    returns a single letter (A, B, ...) corresponding to the
  413.         identifier of the currently logged-in disk.
  414.  
  415.     (%Lw,x)    logs in the disk specified by the first letter of skeleton
  416.         x; if x is omitted or is null, A is assumed.
  417.  
  418.     (%M)    returns to CP/M after closing all files.
  419.  
  420. :Arithmetic Skeletons.
  421.  
  422. Arithmetic skeletons have the form
  423.  
  424.             (#x,s)
  425.  
  426. where x may be a string of one or more of the arithmetic functions and s is
  427. the argument to which the functions given by x are applied.  In the listing
  428. of arithmetic functions which follows, the term "constant" means a string of
  429. ASCII characters representing an integer when the program is run with REC80
  430. or REC86, or an integer, long integer, single precision real or double
  431. precision real when the program is run with REC80F or REC86F. Convert inherits
  432. REC8xF's default of promoting smaller-sized arguments to the size and type of
  433. the larger argument in operations involving arguments of different sizes.
  434.  
  435.     f    evaluates a formula.  Its argument must be an arithmetic
  436.         expression in which the operands are constants.  Parentheses
  437.         are allowed (and must be balanced if present); the operators
  438.         recognized are ** or ^ for raising to a power, * for product
  439.         / for division, % for remainder, + for addition or unary 
  440.         plus and - for subtraction or unary minus.  If the argument is
  441.         not an expression it is left unchanged.
  442. -
  443.         The usual rules for operator precedence and association are 
  444.         followed: ** or ^ precede *, / and %, all of which precede + 
  445.         and -.  Unary +'s are removed and unary -'s are replaced by 
  446.         0-.   *, /, %, + and - associate from left to right and ** 
  447.         or ^ associate from right to left.  Thus, (#f,2^3^2) yields 
  448.         512, (#f,(QUO\(2^3)^2\)) yields 64, (#f,2/4*6) gives 0 and
  449.         (#f,6*2/4) gives 3.  Exponents must be of integer type; a
  450.         floating point exponent is truncated and causes the message
  451.         "Xpterr" to be displayed.
  452.         
  453.     +    Takes an argument of the form a+b, where a and b are 
  454.         constants and returns their sum.  The argument is unchanged
  455.         if it doesn't have the required form.
  456.  
  457.     -    Takes an argument of the form a-b, where a and b are 
  458.         constants and returns the indicated difference.  No change
  459.         is made in the argument if its form isn't a-b.
  460.  
  461.     *    Returns the product if the argument has the form a*b, with
  462.         a and b constant; otherwise the original argument remains.
  463.  
  464.  
  465. -
  466.     /    Returns the quotient given an argument a/b in which a and
  467.         b are constants; no change is effected if the argument
  468.         does not have the specified form.
  469.  
  470.     ^    Given an argument of the form a^b, where a is any constant 
  471.         and b is an integer, returns a raised to the power b.  The
  472.         argument is returned intact if it does not have the indicated
  473.         form.
  474.  
  475.     %    Returns the remainder of the division a/b if the argument
  476.         has the form a%b; otherwise the argument is left unchanged.
  477.         If either operand is a floating point number, the result
  478.         returned will be  a-(b*int(a/b)), where int(x) is the 
  479.         integer part of x. [e.g., int(3.5)=3; int(-4.8)=-4.]
  480.  
  481.     |    If its argument has the form a|b, where a and b are integer
  482.         constants, it returns the greatest common divisor of the
  483.         pair.  No change occurs if the argument lacks the prescribed
  484.         form and no check is made to ensure that a and b are 
  485.         integers; results are unpredictable in the latter case.
  486.         | may not be used as an operator in arithmetic expressions
  487.         to be evaluated by f.
  488. -
  489.     p    Accepts a single constant as argument and returns that
  490.         constant plus one, in a string of the same numeric type
  491.         as the original argument.  It will not alter its argument
  492.         if it isn't a constant.
  493.  
  494.     m    If its argument is a constant, it returns that constant minus
  495.         one, in a string of the same type; otherwise it leaves its
  496.         argument unchanged.
  497.  
  498.     =
  499.     >    These three skeletons take arguments in either of two
  500.     <    forms: a single number or two numbers separated by a comma.
  501.         In the case of a single number, say a, they return the 
  502.         letter t if a=0, a>0 or a<0, respectively, and the letter f
  503.         otherwise.  In the two-argument case of the form "a,b", t
  504.         is returned if a=b, a>b or a<b, respectively, and f if the
  505.         relation doesn't hold.  In this case, if a and b are two-byte
  506.         integers they are compared as unsigned operands, since 
  507.         two-byte integers are more often used in address 
  508.         calculations.  Arguments not having either of the allowed
  509.         forms are left unchanged.
  510.  
  511. -
  512.     l    Requires a single constant as argument; it converts it to
  513.         a string of the following larger numeric type.  For instance,
  514.         (#l,-1) yields 065535, (#l,010000000) yields 1.E7 and
  515.         (#l,3.14159) gives 3.14159D0.  Double precision constants and
  516.         non-numeric arguments remain unchanged, a null string as
  517.         argument returns the digit 0.
  518.  
  519.     s    Converts a single constant argument to next smaller numeric
  520.         type before rendering it back to ASCII.  Thus
  521.         (#s,3.141592653589D0) returns 3.14159265, (#s,-45.98) returns
  522.         -045, (#s,0100000) leaves 34464 (because of truncation modulo
  523.         2**16) and (#s,2000) leaves 208 (because of truncation modulo
  524.         256).  Non-numeric arguments remain unchanged; a null string
  525.         returns the digit 0.
  526.  
  527.     D    Leaves the binary form of a numeric constant in its place;
  528.         this will take the form of 2, 4, 5 or 8 bytes arranged in
  529.         Intel form (least significant byte first); the lengths
  530.         correspond to short integers, long integers, single precision
  531.         reals and double precision reals, respectively.  D is more
  532.         often used together with h to produce the ASCII hexadecimal
  533.         representation of a number.  
  534. -
  535.         No change takes place if the argument is non-numeric. 
  536.         Examples:    (#Dh,1.5)     produces     3FC0000000
  537.                 (#Dh,-1)     produces     FFFF
  538.                 (#Dh,01000000)     produces     000F4240
  539.  
  540.     H    Leaves the binary form of a string of ASCII hexadecimal 
  541.         digits (0-9, A-F).  Given a string of n bytes, it produces
  542.         a string of flr((n+1)/2) bytes, where flr(x) is the greatest
  543.         integer not exceeding x.  H is often used together with d
  544.         to convert from ASCII hexadecimal to ASCII decimal.  No
  545.         change is effected if the argument contains characters other
  546.         than hex digits.  Examples:
  547.         (#H,414243)     gives    CBA     (when interpreted as ASCII)
  548.         (#Hd,3FC0000000) gives    1.5
  549.         (#Hd,F)         gives  15
  550.  
  551.     d    Assumes its argument is the binary representation of a number
  552.         and converts it to an ASCII decimal string.  If the argument 
  553.         length is not 0, 1, 2, 4, 5 or 8 no change takes place.  
  554.         Examples: (#d,(^MJ)) yields 2573 (10*256+13, due to Intel 
  555.         ordering of bytes in binary operands being assumed); 
  556.         (#Hd,FFFE) yields 65534.
  557. -
  558.     h    Assumes its argument to be binary and converts it to a string
  559.         of ASCII hex.  An n-byte argument produces a 2n-byte result.
  560.         Examples: (#Dh,1.) produces 3F80000000;    (#h,jkl) produces 
  561.         6C6B6A (because Intel ordering of binary operands is assumed)
  562.  
  563. As mentioned near the beginning of this section, in a skeleton of the form
  564. (#x,s), x may be a string.  When x consists of more than one character, each
  565. of the represented functions is applied to the argument from left to right;
  566. thus in (#Hd,FFFF), H is applied first to FFFF and d is then applied to the
  567. result left by H (the two byte binary representation of 65535).
  568.  
  569. As mentioned in CNVRT.HLP, a program using function #f and requiring handling
  570. of floating point constnats must have the pair #. in an [Include ..] comment;
  571. furthermore, if functions #^ and #% are not invoked explicitly but operators
  572. ** or ^ and % are to appear in formulas for #f, the pairs #^ and #% must be
  573. present in the "Include".  [Include #.#^#%] would serve in a program which
  574. only uses #f explicitly but is intended for computation of formulas involving
  575. floating point numbers and exponentiation and remainder operations.
  576.  
  577. :Character "Arithmetic".
  578.  
  579. Character arithmetic skeletons have the form
  580.  
  581.             (&x,s)
  582.  
  583. where x may be a string of one or more of the character arithmetic functions
  584. and s is the argument to which the functions given by x are applied.  When
  585. x consists of two or more characters, the function represented by each 
  586. character is applied in turn from left to right, the first one to the 
  587. original argument and the rest to the result left by the preceding function
  588. For instance, (&D!,1.5) applies D to the string 1.5 and ! to the resulting
  589. string.
  590.  
  591. Functions available for character arithmetic are the following:
  592.  
  593.     D    Converts a string of one or more decimal integer ASCII
  594.         numbers optionally preceded by minus signs and separated by
  595.         commas or other nondecimal characters into binary, a pair
  596.         of bytes for each integer. Examples: (&D,2573<,>-1) yields  
  597.         4 consecutive bytes whose hex values are 0D, 0A, FF and FF;
  598.         (&D,ab) yields 6 zero bytes: a and b delimit 3 null strings.
  599. -
  600.     H    Converts a string of one or more hexadecimal ASCII numbers
  601.         into binary (modulo 2**16), a pair of bytes for each number.
  602.         For instance, (&H,F) yields two bytes whose values are, in
  603.         hex, 0F and 00; (&H,ABCDEf0123) produces 4 bytes whose
  604.         values expressed in hex are DE, BC, 23 and 01, in that order.
  605.         The inversion of high and low order bytes is due to the
  606.         Intel convention for binary data storage.  Notice also that
  607.         lowercase f is not considered a hex digit.
  608.  
  609.     d    Converts a string by pairs of bytes into ASCII decimal 
  610.         strings separated by commas; if the argument has an odd
  611.         number of bytes the rightmost byte is converted assuming
  612.         a zero high order byte.  Examples:
  613.             (#d,(^MJZ)) produces the string 2573,26
  614.             (#Hd,FFFE)  produces the string -2
  615.  
  616.     h    Converts a string by pairs of bytes into strings of 4 ASCII 
  617.         hexadecimal digits separated by commas; the rightmost byte
  618.         of a string of odd length gets converted to two hex digits.
  619.         Examples:
  620.             (#h,(^ABMJZ)) produces the string 0201,0A0D,1A
  621.             (#Dh,32767) produces the string 7FFF
  622. -
  623.     u    Shifts all lowercase letters (a-z) in its argument to
  624.         uppercase, e.g., (&u,Hello) yields HELLO.
  625.  
  626.     l    Shifts all uppercase letters (A-Z) in its argument to
  627.         lowercase, e.g., (&u,What IS it?) results in what is it?
  628.  
  629.     a    Turns off the sign bit of each byte in its argument.
  630.         For instance (&Dah,-1) results in the string 7F7F.
  631.  
  632.     s    Turns on the sign bit of each byte in its argument.
  633.         For instance (&sh,(^MJZ)) gives 8A8D,9A
  634.  
  635.     p    Substitutes a period for each byte in its argument whose
  636.         value is not a printable ASCII character (i.e., SP to ~)
  637.         Example: (&p,abc(^MJ)de) results in abc..de 
  638.  
  639.     n    Converts each byte in its argument into two ASCII hexadecimal
  640.         digits.  For example (&n,ABCDEF) produces 414243444546.
  641.  
  642.     b    Inverts the effect of n: converts pairs of ASCII hex digits
  643.         into bytes of the corresponding binary value.  Results are
  644.         unpredictable for odd-numbered arguments or non-hex digits.
  645. -
  646.     i    Converts a string of bytes into 3-digit ASCII octal numbers
  647.         (one for each byte) separated by commas; a null argument
  648.         produces 000.  Example:
  649.                 (&i,Zz) produces 132,172
  650.  
  651.     I    Converts a string of ASCII octal numbers separated by commas
  652.         to binary, a byte for each ASCII number.  For example,
  653.         (&I,116<,>117<,>77) yields the 3-byte ASCII string NO?
  654.  
  655.     8    Converts a string of bytes into 8-bit ASCII binary numbers 
  656.         (one for each byte) separated by commas; an isolated null
  657.         string produces 00000000.  Example:
  658.             (&8,Zz) produces 01011010,01111010
  659.  
  660.     B    Converts a string of ASCII binary numbers separated by commas
  661.         to binary, a byte to each ASCII number; a single null string 
  662.         produces a single zero byte.  For example,
  663.             (&Bh,01011010<,>01111010) yields 7A5A.
  664.  
  665.     =    Yields the letter f if its argument is the null string or at 
  666.         least one of its bytes is non-null; leaves the letter t if 
  667.         all of the argument's bytes are binary 0.
  668. -
  669.     >    Yields the letter f if its argument is the null string or if 
  670.         the sign bit of its rightmost byte is on; t if this byte's 
  671.         sign bit is off.
  672.  
  673.     <    Yields the letter f if its argument is the null string or if
  674.         the sign bit of the rightmost byte is off; the letter t is
  675.         returned if the rightmost byte's sign bit is on.
  676.  
  677.     !    Returns the length of its argument as an ASCII decimal 
  678.         number.  For example, (&!,What<,> me worry?) returns 15.
  679.  
  680.     #    Returns the hash function of its argument as an ASCII decimal
  681.         number, always between 0 and 12.  The hash function is 
  682.         defined here as the remainder modulo 13 of the exclusive or 
  683.         of all the bytes in the argument.
  684.  
  685.  
  686. :Overlays.
  687.  
  688. Overlays are an extremely useful feature which allow the running of programs
  689. whose overall size is much larger than REC's compilation area.  Overlays may
  690. be used when a program can be divided into three or more segments such that
  691. two or more of them are not needed simultaneously in memory.
  692.  
  693. For instance, suppose program A calls subroutines B and C, but neither B
  694. calls C nor C calls B.  Then program A could constitute a root program which
  695. loads B or C when either of them is required.  Thus B and C share the same
  696. memory area and the memory requirements for the entire program are smaller
  697. by the length of the smaller of B and C than the requirements for the
  698. non-overlaid A-B-C combination.  An overlay may load other overlays, and this
  699. way a very large program may be organized in a tree-like structure of
  700. overlays.  Since each overlay is a REC program compiled when loaded, no
  701. relocatability issue arises so that a given overlay may be loaded at different
  702. levels of an overlay tree.
  703.  
  704.     For the purpose of discussion, in what follows the root overlay
  705. will be called "driver" and the rest of the overlays will be called
  706. "segments".
  707.  
  708. -
  709. The driver is the only program which should contain the initializing code
  710. inserted by the compiler; all segments must be compiled with an [Exclude LIB]
  711. comment in their source files appearing before the first subroutine or program,
  712. preventing thus insertion of the initializing code.
  713.  
  714. Automatic inclusion of library routines at runtime requires that the root
  715. inform the compiler which routines must be included in addition to those
  716. determined automatically by the compiler during compilation of the root.  This
  717. is accomplished by an [Include ....] comment near the beginning of the root's
  718. source file, where "...." is replaced by the strings inserted by the compiler
  719. (after enclosing them in square brackets) at the end of each segment's object
  720. file (which will always happen if the source file contains [Exclude LIB]).
  721.  
  722. For example, the quantum chemistry program HAMEL is made up of 9 programs;
  723. the root is HAMELD and the segments are HAMELx, where x is X, F, G1, G2, G3,
  724. G4, G5 and M.  Due to the [Exclude LIB] in the 8 segments, the compiler
  725. produced the following strings, inserted at the end of each file HAMELx.REC:
  726. [T # #*#|#/W 64O OrOwE ], [T W 64O OrOwE ], [W t T 64O OrOw E ],
  727. [T W 64O OrOwE ], [T W 64O OrOwE ], [t T W 64O OrOwE ],
  728. [# #*#|#/T W 64O OrOwE ] and [T W 64# #*#+#-#|#/O OrOwE ]; with these strings
  729. a comment [Include T t W 64# #+#-#*#/#|O OrOwE ] was formed for insertion in
  730. the program file of the root, HAMELD.CNV.
  731. -
  732. The "Include" comment in the example was built gathering all distinct pairs of
  733. characters appearing in the eight final strings generated for the segments;
  734. notice spaces are important because the automatic inclusion mechanism examines
  735. the "Include" string by pairs of characters.
  736.  
  737. Overlays may be read from disk files or memory buffers; the latter case
  738. essentially extends the compilation area into REC's pushdown list, from 
  739. which space is procured for memory buffers.  Storing overlays in memory 
  740. buffers also has the advantage that overlay loading from them is 
  741. substantially faster than loading from a disk file.  The following skeleton 
  742. fragment shows how an overlay in a file called FSY.REC is read from disk 
  743. and written into a MEM: pseudofile whose size is computed from the length
  744. of the original file itself:
  745.  
  746.     (IF,(0),(until,(%R,FSY.REC),(^Z),<=>,(%R,FSY.REC),),<0>,<<
  747.         >>(%C,FSY.REC)(,(%Ow,MEM:sy,(&!,<0>)))(%W,MEM:sy,<0>))
  748.  
  749. Closing FSY.REC before opening MEM:sy saves memory by releasing table and
  750. buffer space associated with F77SY.REC; the length of MEM:sy is determined
  751. by the length of the contents of F77SY.REC; <0> is bound to these contents.
  752.  
  753.  
  754. -
  755. An overlay is loaded and executed by the skeleton
  756.  
  757.             (%V,name,arg)
  758.  
  759. where 'name' is the name of the disk file (whose extension is assumed to be
  760. .REC if not explicitly given) or memory buffer containing the overlay and
  761. 'arg' is a skeleton whose value is the argument received by the overlay in
  762. the workspace; 'arg' is optional and when omitted, the preceding comma may
  763. also be omitted and the overlay will receive an empty workspace.
  764.  
  765. The last overlay loaded may be reexecuted any number of times without 
  766. recompiling it (as long as no other overlay is loaded) by calling it with the
  767. skeleton ( ,arg) in which a single blank space appears between the left
  768. parenthesis and the comma, and 'arg' is the argument to be passed to the
  769. overlay; the skeleton ( ) (with a single blank) may be used if no argument is
  770. to be passed (i.e., if the null string is to be passed).
  771.  
  772. The Convert compiler may be loaded as a segment: (%V,CONVERT,arg) compiles the
  773. program contained in the disk file given by 'arg', generating the corresponding
  774. REC file.  If X.CNV, Y.CNV and Z.CNV are to be compiled, the concatenation
  775. (%V,CONVERT,X)( ,Y)( ,Z) will load CONVERT.REC once and compile the three
  776. programs.  The default extension for 'arg' in this case is .CNV.
  777.  
  778. :Loading of .COM binary files.
  779.  
  780. Three skeletons permit loading and executing machine code files:
  781.  
  782.         (%Xl,f)
  783.         (%Xx,f,c)
  784.         (%Xv,f,c)
  785.  
  786. %Xl loads the file whose name is given by the skeleton f (an extension .COM
  787. is assumed if none is given), using a file of the same name and extension .BIM
  788. (containing a bit map) to relocate the loaded file, which is assumed to be
  789. loadable without relocation at 100H.  The program contained in "f" is loaded
  790. starting at the next available address in REC's compilation area; this address
  791. is updated if the loaded program fits into the available space.  If the
  792. program does not fit or it or its bit map file do not exist, (%Xl,f) evaluates
  793. to the string 'Not Found'; otherwise its value is the null string.
  794.  
  795. %Xx executes a program previously loaded by %Xl; a program loaded by %Xl stays
  796. resident for the duration of the run, so that %Xx may be used to execute it as
  797. many times as desired.  
  798.  
  799.  
  800. -
  801. The argument c in this skeleton is a skeleton whose value is interpreted as
  802. a command line tail from which up to two file names are parsed and placed at
  803. locations 5CH and 6CH; the length of the string resulting from c (or 127,
  804. whichever is less) is stored in location 80H and the string itself (up to the
  805. first 127 characters) is placed in the data area starting at 81H.  If the 
  806. program was not loaded, %Xx returns the string 'Not Found' to the calling
  807. program; otherwise (and assuming program "f" returns to the calling program)
  808. it returns the string starting at 81H and whose length is stored at 80H, as
  809. long as it does not exceed 127 (if it does, the null string is returned).
  810.  
  811. %Xv loads and executes a file in the manner of %Xl and %Xx, but restores the
  812. compilation area pointer upon return from execution of the loaded program, so
  813. that it executes the named program as an overlay, freeing the compilation area
  814. space after execution.  It returns the string 'Not Found' if either the file
  815. given by f or its .BIM bit map cannot be found or if the program will not fit
  816. into the available space.  %Xv and %Xl must not be used on the same file f in
  817. a given Convert program, that is, a program to be loaded and executed by the
  818. %X skeletons must be either a resident program or an overlay, but not both,
  819. during a given run of a Convert program using it.
  820.  
  821.  
  822.  
  823. -
  824. The bit map is a file containing one byte for each eight bytes of the program
  825. file.  The correspondence starts at the most significant bit; the first byte
  826. of the BIM file corresponds to the first eight bytes of the COM file.  When a
  827. 1 bit is present in the bit map, it indicates that the corresponding byte in
  828. the COM file is the higher byte of an address; relocation is effected by
  829. adjusting this address.
  830.  
  831. To obtain the BIM file, the corresponding program must have been assembled or
  832. compiled with two origins differing by an integer multiple of 0100H (256); the
  833. differences between the resulting files is exploited by GENBIM (program 165.13
  834. in the SIG/M collection) to produce the bit map.
  835.  
  836. :Priority Queues (Heaps).
  837.  
  838. The following skeletons handle a MEM: pseudofile as a priority queue (or heap)
  839. of two-byte unsigned integers:
  840.  
  841.         (%Hi,m,d)        (%Hs,m)
  842.         (%Hr,m)            (%Hh,m)
  843.  
  844. In all four skeletons, m is a skeleton which must evaluate to a MEM: 
  845. pseudofile name; d in skeleton %Hi must be evaluate to a four byte ASCII 
  846. string representing a hexadecimal number (lower case a-f are not recognized).
  847.  
  848. %Hi inserts the two-byte binary representation of the ASCII hex number d 
  849. into the pseudofile m, sifting the file to maintain the heap condition.  If
  850. the pseudofile is viewed as an array P with N entries, maintaining the heap
  851. condition means requiring that P(i)>P(2*i) and P(i)>P(2*i+1) for i between
  852. 1 and floor(N/2).  After an insertion, the pseudofile read pointer is set to
  853. beginning of the buffer, so that a subsequent read from m will start from the
  854. top of the heap.  %Hi returns the null string.
  855.  
  856.  
  857.  
  858. -
  859. %Hr reads the next two-byte value from m, converting it to a four-byte ASCII
  860. string (hex).  This skeleton is essentially equivalent to (&h,(%R,m,<[2]>)),
  861. and is included for convenience.
  862.  
  863. %Hs sorts the contents of m, which are assumed to satisfy the heap condition.
  864. It returns the null string and does not affect the value of the pseudofile
  865. read and write pointers.
  866.  
  867. %Hh sorts the pseudofile m by the heapsort method assuming it to contain
  868. two-byte unsigned values.  The file need not satisfy the heap condition
  869. initially; a file suitable for sorting by %Hh may be produced by writing
  870. values with the skeleton (%W,m,(&H,h)), where h is a four-byte ASCII
  871. hexadecimal string, or with (%W,m,(&D,d)) where d is an ASCII decimal integer
  872. between 0 and 65535.
  873.  
  874. :Error messages.
  875.  
  876. CONVERT.REC displays the following messages upon detecting the corresponding
  877. errors:
  878.  
  879.     Unexpected EOF        End of file encountered in the middle of a
  880.                 compilation, for instance, if there are
  881.                 subroutines but no main program.
  882.  
  883.     Unbal {
  884.  
  885.     Excess }
  886.  
  887.     WS ovf            Workspace overflow.
  888.  
  889.     Unbal [
  890.  
  891.     Expected (, [, {    Spurious characters in the source file.
  892.  
  893.     Expected )
  894.  
  895.     Expected ","        Syntax violation in LAM, IF, WHILE, etc.
  896. -
  897.     Ill patt        Illegal pattern.
  898.  
  899.     Ill skel        Illegal skeleton.
  900.  
  901.     Ill rule        Rule lacking the comma separating pattern
  902.                 from skeleton.
  903.  
  904.     Ill sep            Colon/semicolon missing after a rule.
  905.  
  906.     Ill var            Variable number not between 0 and 30.
  907.  
  908.     Ill var list        Badly formed variable list.
  909.  
  910.     Ill <=>            Illegal use of skeleton <=>.
  911.  
  912.     Dir full        Directory full reported by the operating
  913.                 system when attempting to write.
  914.  
  915.     Disk full        Disk full reported by the operating system
  916.                 when attempting to write.
  917.  
  918.     Not Found        Nonexistent source file.
  919. -
  920.     No file given        No source file name given to the compiler.
  921.  
  922. :[CNVADV.HLP]
  923. [Gerardo Cisneros, 13.8.84]
  924. [Rev.: G. Cisneros, 28.1.86]
  925. [end]
  926.