home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD2.img / d5xx / d516 / xl / macro.doc < prev    next >
Text File  |  1991-07-20  |  6KB  |  162 lines
  1.  
  2.       xl Macro Information
  3.       by Martin Kees
  4.       
  5.       The true power of xl is only evident when the user can
  6.       take advantage of the macro capability of xl. From
  7.       xl the user can quickly define and execute macros that
  8.       can aid in producing the output required for a particular
  9.       application. It is strongly urged that the user learn
  10.       and be familiar with this capability.
  11.       
  12.       xl uses ARexx(tm) by William S. Hawes as it's macro
  13.       language interface. ARexx is a full featured interpreted
  14.       language system that is ideal for interactive work.
  15.       In xl it easy to write short ARexx macros without
  16.       having to use an editor. These macro programs can then be
  17.       attached to a function key for easy execution. For more
  18.       involved macros, they can be composed in a text editor
  19.       and envoked by name or function key.
  20.       
  21.       The xl.doc file lists all the commands and their formats available
  22.       for macro programming. Each command may require arguments and
  23.       may return results to the macro program. For the arguments to
  24.       be passed correctly there are certain standards the user should
  25.       use in writing macros.
  26.       
  27.       NUMERIC Arguments
  28.       
  29.       xl expects integer arguments. That is if an argument is
  30.       numeric xl does not want to see a decimal point in the string
  31.       sent from the macro. This can happen if the user uses division
  32.       in the argument instead of integer division ( % is the integer
  33.       division operator in ARexx). Examples:
  34.       
  35.           blit  xposition+3 yposition/2       * possible ERROR
  36.           blit  xposition+3 yposition%2       * CORRECT
  37.           
  38.       The argument list in all xl commands uses white space as
  39.       argument separators.  If you want to use a negative number
  40.       as an argument you should ensure that it is passed correctly.
  41.       For example:
  42.           
  43.           polyscale 100 -100
  44.           
  45.       will be sent as POLYSCALE 0. ARexx interprets the minus sign as 
  46.       subtraction. Use one of these forms instead:
  47.       
  48.           polyscale 100 (-100)
  49.           or
  50.           yscale= -100;polyscale 100 yscale
  51.           or
  52.           polyscale 100 '-100'
  53.           
  54.       STRING Arguments
  55.       
  56.       Care must be taken in sending strings to xl to preseve the
  57.       case of the string and when the string contains blanks. ARexx
  58.       interprets the command statement before sending it to xl. If
  59.       a string is unquoted it will be converted to uppercase. This
  60.       may not be what the user intends. Examples:
  61.       
  62.           text  30 45 hello
  63.           
  64.       is a valid command but will produce HELLO at the x,y position.
  65.       
  66.           text  30 45 'hello'
  67.           
  68.       preserves the lowercase string.
  69.       
  70.           text  30+t 100-xx 'hello world'
  71.           
  72.       will produce an error message. ARexx strips the single quotes    
  73.       before sending to xl. xl will receive TWO strings ( hello and
  74.       world) instead of the one intended. The user must force ARexx
  75.       to send the string with quotes:
  76.       
  77.           text  30+tt 100-xx '"hello world"'
  78.           or
  79.           text  30+tt 100-xx '"' || hello world || '"'
  80.           or
  81.           text  30+tt 100-xx '22'x || hello world || '22'x
  82.           or
  83.           qt= '22'x;text  30+tt 100-xx  qt || hello world || qt
  84.  
  85.  
  86.       RESULTS from xl commands
  87.       
  88.       Many xl commands return results to the macro program. For the macro 
  89.       program to use the result the ARexx statement:
  90.       
  91.           options results
  92.           
  93.       must be encountered in the macro program before the command.
  94.       
  95.       To use the result returned it should be parsed and/or saved
  96.       in a variable. Examples:
  97.       
  98.           options results
  99.           getxy
  100.           xy= result
  101.           blit xy
  102.           
  103.           
  104.           options results
  105.           getxy
  106.           parse var result xval yval .
  107.           text xval yval 'Message'
  108.           
  109.        Note that in the first example the variable xy contains two   
  110.        numeric arguments, whereas in the second the two values 
  111.        have been parsed into different variables.
  112.        
  113.        
  114.           
  115.        SCRIPT macros
  116.        
  117.        Script macros do not use the ARexx interface. This does limit
  118.        their use since there are no control structures or variables
  119.        available in scripts. Their main advantage is speed.
  120.        
  121.        Since script commands are not interpreted their arguments must
  122.        be in 'processed' form. Ther is no evaluation of expressions and
  123.        strings must be in final quoted format. Examples:
  124.        
  125.           text 30 45 hello     
  126.           TEXT 30 45 hello     
  127.           text 30 45 "hello there"
  128.           autoaspect ON
  129.           
  130.        are correct script commands, whereas:     
  131.        
  132.           text 30+3 45 hello     
  133.           text 30 45   hello there
  134.           autoaspect on
  135.        
  136.        will produce errors. The first since no expression 
  137.        evaluation is done. The second since the string isn't quoted.
  138.        The last since the on string should be in uppercase.
  139.        
  140.        These same considerations should be used when sending
  141.        individual script commands with the @Command option.
  142.        
  143.        
  144.        FUNCTION KEY MACRO files
  145.        
  146.        xl can save and load files that control function key macro
  147.        envocations. The files are ASCII text files that may be 
  148.        edited in a text editor. Each file consists of 30 lines.
  149.        Each line contains a two character 'type' code and then the 
  150.        text of the macro if defined. The type codes are:
  151.             
  152.             **    No macro installed
  153.             AR    ARexx macros
  154.             A'    'ARexx' macros
  155.             SC    Script and @Command macros
  156.             
  157.        Note that line 10 of the file should be ** since the F-10     
  158.        key is reserved for toolbox toggle. The text of the macro
  159.        cannot contain a newline and must be on a single text line.
  160.        
  161.        
  162.