Copyrights and Credits Copyright 1994 AugmenTek All Rights Reserved AugmenTek 3606 S. 180th St. C-22 SeaTac, WA 98188 USA Phone: 206-246-6077 email: augmentek@acm.org 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, ">" 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).