ARexx: Configure Two Directory Opus Gadgets to Help Make and Show ANIMs by Merrill Callaway Last month we looked at a couple of handy utilities for showing IFF24 files from Directory Opus. I didn't have room to discuss another handy utility that I developed along the same lines, so this month we will look at an ARexx utility (MkANIM.dopus) to help you when you are making or showing ANIM files from images rendered in many different programs. My collection of ANIM capable programs includes CellPro and FractalPro (by MegageM); Scenery Animator (by Natural Graphics); VistaPro (by Virtual Reality Laboratories); DeluxePaintIV (by Electronic Arts); and DCTV (by Digital Creations), but this ARexx MkANIM.dopus routine should work with any appropriate set of IFF files. In your Directory Opus window, you simply "drag select" the image files you want to make into an ANIMation, click on the gadget, and Opus, ARexx, and some Freely Distributable software do the rest. MkANIM.dopus automatically creates an ANIM file from your series of pictures. The files should all have the same palette and resolution, and be in the order you want them to play. Different resolutions will not work, but different palettes will work the first time through, but the colors will become polluted during subsequent animation play loops. Your application program (such as CellPro) should have generated numbered pictures for you or you may rename a set of files until they are in the alpha-numeric order you want in the window. The routine works using ARexx and "Makeanim" and "Showanim", freely distributable programs that I got with Scenery Animator and CellPro, but which are probably included with other programs; or you may download them from a BBS such as BIX; or find them on a Fred Fish disk. At any rate, I made my utility to both make and show ANIMs by simply selecting a set of files in Directory Opus, and clicking on a gadget. As with last month's programs, they're not complicated, just great time savers, and a good way for beginners to get into ARexx. First Steps The first thing we need to do, after we ask for OPTIONS RESULTS from function calls, is load the libraries that we need. Since we will need to delete a file, we will load the rexxsupport.library which is one way to extend the ARexx command set to include AmigaDOS functionality transparently. When you ADDLIB() an ARexx shared library, think of it as including an additional list of ARexx functions, not ordinarily available. Notice that we need a name, a priority (0), and an "offset" (where to find the library). As with all functions, we CALL this one when we don't need to use the RESULT. Next, we OPEN the output file. You may name your file anything you want; just change the name here. Can you think of how to make ARexx ask for a path and file name at this point? We OPEN() the output as a 'W' or Write file. This will be the input file for MakeANIM later. Now change the address to "dopus_rexx" a case sensitive name for the ARexx port of Directory Opus. Only ports, logical names and libraries are case sensitive in ARexx. Commands The next series of lines are what we call ARexx "commands". They have meaning only at the "current address" or "dopus_rexx" which we have just set. This is one of the confusing things about ARexx for beginners: commands are sent to the current address and if they have meaning, fine; but if not, the RETURN code and/or the RESULT variable will not be what you expect. Commands are valid to ARexx, but have no meaning to the ARexx interpreter itself! This is the heart of the matter; how ARexx can control other programs remotely through its "command interface", as this capability is called. (See chapter 7 of The ARexx Cookbook). We let ARexx issue the command to Directory Opus STATUS 3 which means to "get the active window" or the one we have just "drag selected" our files in. Notice how, since we have asked for RESULTS in the OPTIONS instruction, that we must always "read" or "assign" the answer or reply from the command into some variable or other, or else our effort is wasted. We set the variable "window" equal to RESULT, the reply coming back from the command STATUS 3. This is where some developers are unclear on the concept of how to implement an ARexx interface. All too frequently, they forget to let the user "get" information about the program; and only let them "set" something. Now you can see how we get the path name to the active window. We do a little routine to get rid of the annoying tendency of Directory Opus to call "RAM:" as "RAM Disk:". The space plays havoc in some cases, so we must use the little routine to remove the space and change the name back to "RAM:", by checking to see if the LEFT most 8 characters spell "Ram Disk" and if so, we PARSE VAR, or parse the variable "path" on a pattern ":" and then concatenate to the file name (with the operator "||") our preferred spelling of "RAM:". Get Selected Files Still using Directory Opus commands, we "getselectedfiles", which puts all selected files into a long sentence-like string, filenames separated by spaces. We assign a variable called "file" to the RESULT. Next, we deselect all files with a NONE command. An Array Now we get tricky. We need an array to keep track of all these names. We use a counter called "n" to keep track; and set n=0 to start. We make a DO WHILE loop to count while our variable file is NOT equal to the "null string" (something is still in the string). We parse the variable "file" into a "compound symbol" or array called "fname.n" each time through, when n is a different number. All the different n's make different array variable names (a.k.a. compound symbols--the period tells us it's a compound symbol or an array element variable). Notice how we both increment "n" each time and also how we assign the rest of the string to "file" itself! This self-referential aspect of ARexx makes it very powerful for string manipulation. The parse instruction will assign the first "word" of any string (delimited by one or more spaces) to the first variable, and the rest of the string to the second variable (if there are only two variables in the "template"). The "template" tells ARexx how to assign the VARiable file to variables called "targets". In plain English the parse line says, "Nibble off the first word of the sentence, and assign it to a variable called `fname.n' where n is the current count. Then assign the rest of the sentence, (without the first word) to the variable `file'." So our little routine separates every file name out of the original string of selected files and gives each one a unique name: fname.1, fname.2, etc. up to how many file names were in the string. The next series of commmands puts up a REQUESTER in Directory Opus to ask, "Do you want to add first and second frames to the end?", which makes some animations run smoother. The RESULT comes back as the number 1 if you say OK, (and 0 if not), so that we can use RESULT directly in an IF statement. Two incrementations of n complete this section. Make a List of Files Next, a loop lets us WRITELN() each path and file name to our output file in a list, one file per line. We need this list because we are going to use MakeANIM to make the animation, and it needs an ASCII list of file names including the path names. Finally, we close the output, because we need to use it later, and we shouldn't leave it open for writing. More Parsing The program needs a "base file name" for the ANIMation. We let the program choose the name from the first file in the series: fname.0 and it then looks for a non-alphabetic delimiter in the name as well, which we will use later. Most programs that generate a series of images which may be made into an ANIM file, put some sort of delimiter on the file name and then a number. For example, image.001, image.002 or pic-001, pic-002, etc. We need to find the base name such as "image" or "pic" and then count up the numbers as well. Study the way we "nibble" off one character at a time and test it with DATATYPE() for NOT alphanumeric. This is a little more complex than the first example of the DO WHILE construct using a self-referential parse, but you should be able to figure it out. The reason, we assigned the variable "delim" is that we use it next in a "parse on a variable pattern" instruction. Notice how enclosing the (variable) in parentheses lets the parse instruction know that our template contains a reference to the pattern variable and not to a target. (See Chapter 3 of The ARexx Cookbook for a complete treatment of parsing). Expressions and Defaults Now we construct a variable called "filestring" using an expression as its assigned value. This technique is powerful and elegant. ARexx evaluates all string tokens (literals `in quotes'), symbol tokens (variables), and any operators (|| or concatenation), and assigns the finished value to the symbol token "filestring", all in one step. "Filestring" represents the file in which we store our finished ANIM file; that's why we put ".anim" as an extension. A "getstring" Opus command tells us that clicking on "Okay" will accept our constructed default string. Of course, you may use this opportunity to enter another file name for the finished animation. IF we click on "Okay" in the requester, then RC=0 and RESULT is set equal to what we enter in the string gadget. Otherwise "Cancel" sets RC=1 and RESULT=[the command string itself]. We use this construct to allow us to put in a default ANIM file name and path -- the line with "Data:CellPro..." in it. (You may change this to YOUR default file name.) Finally, if RC still is not equal to 0 then we SIGNAL STOP which branches the program to the label called "stop:" and thus ends it. At the end of each IF test is the "default". IF RESULT='' ARexx sets the RESULT to the default we specified. This is an example of how to save typing into string gadgets when you wish to use several default strings. ADDRESS COMMAND The ADDRESS COMMAND line executes a single DOS program (the expression following) without changing the current host address (`dopus_rexx'). Any single command sent to a particular address can be launched this way, on one line. Here we use the freely distributable program MakeANIM with its two arguments, the input file with our pictures all listed (the one we wrote to with our ARexx program); and the output file of the finished ANIM file. MakeANIM does the rest! The last requester asks if we want to show the ANIM we made. The comments in the listing show the options we may use in ShowANIM. In case you want to use another set of options, just change the ADDRESS COMMAND ShowANIM ... line to use your preferred options. Finally, we close it all down after the label "STOP:" referred to by a previous instruction. RESCAN rescans our window to show new files, and the single function that uses the rexxsupport.library, DELETE(), we use it to erase the temporary RAM file. EXIT 0 shows our WShell that the program executed all right. Configuration The pictures show how to configure your Directory Opus gadgets to run this ARexx routine and on the "alternate" gadget -- the one accessed by the Right Mouse Button we show the configuration for the ShowANIM program as a stand alone gadget in Directory Opus. I hope that these utilities help you to learn ARexx as well as how to configure Directory Opus to perform chores automatically.