BCI NET 2/BCI NET 2.iso/archives/demos/commercial/rexxvar_demo.lzh/RexxVar_Demo/ReadMe

Text File | 1994-02-14 | 14.4 KB | 384 lines

  Copyrights and Credits

     Copyright 1994 AugmenTek
        All Rights Reserved

     AugmenTek
     3606 S. 180th St. C-22
     SeaTac, WA 98188
     USA

     Phone: [phone]
     email: [e-mail]


     AmigaGuide, AmigaGuide.info, amigaguide.library, WDisplay, WDisplay.info
     (c) Copyright 1992 Commodore-Amiga, Inc.  All Rights Reserved.
     Reproduced and distributed under license from Commodore.

     Installer and Installer project icon
     (c) Copyright 1991-93 Commodore-Amiga, Inc.  All Rights Reserved.
     Reproduced and distributed under license from Commodore.

     AMIGAGUIDE AND INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE;
     NO WARRANTIES ARE MADE.  ALL USE IS AT YOUR OWN RISK.  NO LIABILITY OR
     RESPONSIBILITY IS ASSUMED.

     ARexx is a trademark of Wishful Thinking Development Corp.

     This archive is freely redistributable only with all parts included.

  Introduction

     This is a demonstration version of the commercial RexxVar product from
     AugmenTek.

     RexxVar makes coding REXX programs easier by providing a familiar and quick
     means of exchanging variable values with  AmigaDOS commands and programs.

     This is a "crippled" demo version, limited in the amount of data that can be
     exchanged between REXX variables and commands.  In some cases, it may also be
     slower than the commercial version. In addition, the facility to extract
     meaningful error codes (the REXXVAR_RC function host) is disabled and the
     error code variable will always be "?". When a limit is exceeded, you will
     normally see the following error message in the RexxVar_Server's window:

          Not enough storage

     The full version is not limited in value lengths (except for ARexx's
     limitations), allows access to a command's meaningful error code, has
     performance comparable to ARexx's for variable creation, and provides online
     documentation via AmigaGuide.

     1.  Double-click on the "Install.RexxVar" icon to install, or type:

              Installer Install.RexxVar

     2.  After installation, there are some examples below you can run.  You can
         use your own, but you must keep in mind that variable value lengths in
         this demo are limited to 25 bytes, the maximum number of stem array
         elements are 25, and that using stem array elements may be slow.

         First, some let's define some terms.

         "Integer indices" mean that the index to a stem array ranges from 1 to n
         (by 1).  "n" is the total number of values and is also found in "stemname.0"
         (where "stemname" is the name of the stem array).

         "Arbitrary indices" mean that the index to a stem array can be any string.
         These indices are usually saved in a variable (separated from each other
         by a delimiter character), so that all elements that have values are
         remembered.

         A "variable" is any valid ARexx variable symbol that does not end with a
         period; names ending in periods are called "stemnames"

         "Redirection" is when you use ">filename" for directing command output to
         that filename, "<filename" for command input, or ">>" for appending
         command output.

  Examples

     1.  Sorting

         a.  stem array, integer indices, stemname.0 = number of values

                  line.1 = 'cat'
                  line.2 = 'bat'
                  line.3 = 'at'
                  line.0 = 3
                  Address REXXVAR "Sort REXXVAR:line. to CONSOLE:"

             Types to the window:

                  at
                  bat
                  cat

             To put the values in another sorted stem array called
             "sorted_lines.":

                  Address REXXVAR "Sort REXXVAR:line. to",
                                       "REXXVAR:sorted_lines."

             Results in:

                  sorted_lines.0 = 3
                  sorted_lines.1 = 'at'
                  sorted_lines.2 = 'bat'
                  sorted_lines.3 = 'cat'

         b.  stem array, any indices

             Please note the extra index, whose value is undefined.

                  line.AT = 'splat'
                  line.BAT = 'acrobat'
                  line.CAT = 'muskrat'
                  indices = 'AT BAT CAT MAT'
                  Address REXXVAR "Sort REXXVAR:line./nl/indices to CONSOLE:"

             yields:

                  acrobat
                  LINE.MAT
                  muskrat
                  splat

             "LINE.MAT" was created because there is no default value for all stem
             values (e.g., "line. = ''"), so the value of the stem array element
             for index "MAX" is its name, by REXX rules.

         c.  variable value

                  var = 'cat bat at'
                  Address REXXVAR "Sort REXXVAR:var to CONSOLE:"

             Types to the window:

                  at
                  bat
                  cat

             Note that input is delimited (by default) by spaces and the output is
             delimited by newline characters. The newline character is what is
             required on input by most text-based programs, so that is what each
             delimited value changes to.  If we were to write to a variable
             instead of the console:

                  var = 'cat bat at'
                  Address REXXVAR "Sort REXXVAR:var to REXXVAR:sorted_var"
                  Say sorted_var

             then the proper blank-delimited values would be seen:

                  at bat cat

             Newline characters are translated into spaces, by default.

     2.  Showing the values

         This is only useful for stem arrays, as REXX's "Say" command easily
         handles the simple/compound variable's case.

         a.  integer indices

                  line.1 = 'cat'
                  line.2 = 'bat'
                  line.3 = 'at'
                  line.0 = 3
                  Address REXXVAR "Type REXXVAR:line."

             results in the following listing:

                  cat
                  bat
                  at

         b.  arbitrary indices

             Here is a more complicated example with arbitrary indices, and only a
             subset of the possible values:

                  line.AT = 'splat'
                  line.BAT = 'acrobat'
                  line.CAT = 'muskrat'
                  indices = 'CAT AT'
                  Address REXXVAR "Type REXXVAR:line./nl/indices"

             yields:

                  muskrat
                  splat

             Note that the indices are used in left-to-right order.

         c.  sorting the arbitrary indices

             The values are in index order ("AT" before "CAT"), not value order.

                  line.AT = 'splat'
                  line.BAT = 'acrobat'
                  line.CAT = 'muskrat'
                  indices = 'CAT AT'
                  Address REXXVAR "Sort REXXVAR:indices to",
                                       "REXXVAR:sorted_indices"
                  Address REXXVAR "Type REXXVAR:line./nl/sorted_indices"

             yields:

                  splat
                  muskrat

     3.  Creating stem arrays from variable's value

         *** NOTE: Due to demo limitations, this may not work.

         Let's say you have the output from the rexxsupport.library's  SHOWLIST()
         function, and you would like these items to be placed in a stem array:

              if show('L', 'rexxsupport.library') = 0
                then do
                  if addlib('rexxsupport.library',0,-30,0) = 0
                    then Exit 20
                end
              /* Use slashes to separate since blanks may be in names */
              assigns = showlist('A',,'/')
              Address REXXVAR "Copy REXXVAR:assigns/sl to REXXVAR:assign."

         All of the assignment names, minus the delimiting slashes, would be
         placed in integer-indexed "assign." stem array elements, and "assign.0"
         would contain the number of elements.

         The reverse operation also works, creating a variable whose contents are
         the stem array element's values. But be careful -- a single ARexx
         variable can hold only about  65,000 characters: you could easily exceed
         that limit with a large number of moderately-sized stem array elements or
         a small number of large-sized elements. REXXVAR will only partially fill
         the variable value in the case where the next amount of data would exceed
         the limit.

     4.  Getting an environment variable value

         This is simple, and it should be, and is one of the reasons why RexxVar
         exists.

              Address REXXVAR "Getenv >REXXVAR:wb_version Workbench"

     5.  Editing

         *** NOTE: Due to demo limitations, this will not work beyond
                   24 lines of 24 characters apiece (maximum).

         One of the more interesting tasks that REXXVAR allows is the ability to
         use your favorite editor (e.g., MEMACS) to view and modify the contents
         of variables or stem array elements.  With this capability, you don't
         have to write special windowing code just to change a few key values, and
         you gain a familiar and full editing environment.

         For example, let's say your lines are in a stem array called "lines.",
         appropriately integer-indexed, and you use the MEMACS editor:

              Address REXXVAR "MEMACS REXXVAR:lines."

         The editor will read in your stem array values as if it were reading a
         file.  When you modify the file and save it, the editor replaces those
         "lines." values with the new ones.

     6.  Searching

         To show the stem array elements that contain a particular substring, use
         th AmigaDOS SEARCH command:

              line.AT = 'splat'
              line.BAT = 'acrobat'
              line.CAT = 'muskrat'
              indices = 'CAT BAT AT'
              Address REXXVAR "SEARCH REXXVAR:line./nl/indices bat"

         yields:

                 2 acrobat

         which means the second ("2") line passed to the Search command was where
         it found a match, then it shows the value containing the match.

         What is even more interesting is that you can select which lines you want
         to have searched -- just add indices to or remove them from the arbitrary
         indices variable.  This ability to group different portions of the same
         set of information can be invaluable in some applications.

     7.  Combining

         What if you want to combine two or more lists into one? Use JOIN:

              first_list.1 = 'c'
              first_list.2 = 'd'
              first_list.0 = 2
              second_list.1 = 'a'
              second_list.2 = 'b'
              second_list.0 = 2
              Address REXXVAR "JOIN REXXVAR:first_list. REXXVAR:second_list.",
                      "to REXXVAR:big_list."

         would yield:

              big_list.1 = 'c'
              big_list.2 = 'd'
              big_list.3 = 'a'
              big_list.4 = 'b'
              big_list.0 = 4

         You could also mix variable values with actual file contents.

         Splitting one file into pieces is another story... MultiVol (another
         product of AugmenTek) may be able to address this (this experiment has
         not been attempted, but it should, in theory, work).

     8.  Managing Files and Directories

         *** NOTE: Due to demo limitations, this may not work.

         Many times you want to do something with a group of files. The AmigaDOS
         2.0 LIST command's enhancements have helped tremendously with making an
         executable file from a special list of files, output in a special format
         (LFORMAT).  Pattern-matching helps select groups of files.

         Sometimes, however, you want more control over the processing than simply
         executing the command on each file.  But how do you get the nice
         pattern-matched output from LIST into an ARexx program?

              Address REXXVAR "List quick nohead #?.[c|h] to REXXVAR:file."

         You can also insert an LFORMAT string in there to get more information,
         such as the complete path name.  This helps a lot with the
         multiple-assign lists, which few programs support.

     9.  Get the amount of free space on a disk

         *** NOTE: Due to demo limitations, this may not work.

              name = 'DF0:'
              Address REXXVAR "info >REXXVAR:disk_info" name
              Parse var disk_info . (name) . . free_space .
              Say name 'has' free_space 'blocks of free space.'

     10. Opening a new shell

         Sometimes it is useful to open up your a shell, often executing a
         specific set of commands before opening it.  Without REXXVAR, you would
         have to create a file, probably in RAM, then pass that temporary file to
         Newshell to use.  With REXXVAR, no temporary file is needed:

              startup = 'Echo "Hi!"\CD RAM:\CD'
              Address REXXVAR "Newshell CON:10/10/640/100/MyShell/AUTO",
                              "from REXXVAR:startup/\"

     11. Passing data between ARexx programs

         You could always use clip lists, temporary files, messages, and
         environment variables to do this.  However, clip lists need to be
         interpreted to assign values, temporary files are a nuisance to code for
         reading and writing, messages are too complicated for simple uses, and
         environment variables are unwieldy and are limited in size.

         It's far easier just to use this in an ARexx program running in one
         shell/process:

              Address REXXVAR "copy rexxvar:shared_info. pipe:a"

         and in another ARexx program in another shell/process use:

              Address REXXVAR "copy pipe:a rexxvar:new_info."

         You could use different named pipes for different variables. Or you could
         pass a variable containing arbitrary indices, then pass the stem array
         values for it -- the indices may be more meaningful to the receiving
         program than numeric ones.

     It is generally not advisable to use the same stem array name or variable
     name for both input and output unless you know that the input is completely
     read before anything is output (as in an Editor).