Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/545a.lha/PowerVisor_v1.0/docs.LZH/docs/Scripts

Text File | 1991-09-01 | 11.2 KB | 292 lines

*-----------------*
* Tutor : Scripts * Sun Sep  1 15:00:47 1991
*-----------------*

===================== Commands used in this tutorial =========================

   assign      Assign to a variable for use in ARexx
   attach      Attach a command to a key
   awin        Open/close 'Rexx' logical window
   cleanup     Free all memory allocated with 'alloc'
   front       Bring PowerVisor to the front
   go          Jump to memory
   hide        Hide output from ARexx script
   list        List a list
   load        Load a file in memory
   pvcall      Call PowerVisor internal variable
   remattach   Remove a keyattachement
   remvar      Remove a variable
   rx          Start an ARexx script
   script      Start a script
   sync        Synchronize ARexx with PowerVisor
   unhide      Unhide output from ARexx script
   unsync      Undo synchronization of ARexx with PowerVisor
   vars        Show all variables
   void        Evaluate expressions

===================== Functions used in this tutorial ========================

   alloc       Allocate memory
   eval        Evaluate string
   free        Free memory
   if          Conditional evaluation

============================== Introduction ==================================

This tutor file explains everything (or almost everything at least) that
there is to know about ³scripts for PowerVisor. This is already quiet a lot.
²ARexx scripts, ²PowerVisor scripts and ²machinelanguage scripts are all
explained here.

=========================== PowerVisor scripts ===============================

²²PowerVisor scripts are the simplest. A PowerVisor script is simply a bunch
of PowerVisor commands put after each other. You can't do special things
in scripts. There are a few things that must be noted though :

   - You can put ¹comments in your script files by putting a ';' in front
     of the line (you may put spaces in front of the ';')
   - The 'quit' command works different in scripts. The 'quit' command
     stops the script. (PowerVisor will not quit)
   - The 'script' command does not work in scripts. You can't recursively
     execute scripts

You can start a script with the 'script' command.

The recommended place for scripts is the ¹s:pv subdirectory but PowerVisor
will first try the ²current directory. When a script is located in the
current directory or in the s:pv directory you need not specify the full
pathname.

There is one exception. The ¹Startup-PowerVisor script always resides
in the s: directory.

There are some commands in functions present in PowerVisor that can
be used from the PowerVisor commandline but are more useful in scripts.
Two of these functions are 'if' and 'eval'. They are explained more fully
in the 'Expressions' tutorial file.

Of course, commands like 'print' and 'locate' are also more useful in
scripts.

For a fully documented script example, look at ¹s:pv/mkeys.explained.
This script installs a memory viewer. Don't be alarmed at the apparent
complexity of this script (well, you may alarm yourselves a bit, because
it is a complex example :-), once you got the feeling you will find it
rather easy to use scripts in general.

If you use ¹variables in your script it is recomended that you put
an ¹underscore ('_') in front of your variable. That way you minimize
the chances for variable collision with user variables. If you are
ready with the variable use 'remvar' to remove it.

============================== ARexx scripts =================================

For more complex scripts you can use ¹¹ARexx. With ARexx you can interface
PowerVisor to all other programs that use ARexx. If you want you could even
write an ARexx script to debug programs from within your favorite editor,
or edit files from within PowerVisor :-)

The ³PowerVisor ARexx port is called ¹'REXX_POWERVISOR'. This port is
the default ARexx port if your script is started from PowerVisor. But
if you want to make global scripts (scripts that can be started from
anywhere, like the Shell or an editor) you must use :

ARexx< address rexx_powervisor

before you issue any PowerVisor command.

You can of course also use :

ARexx< address rexx_powervisor 'some powervisor command'

(Note that an ARexx script always starts with a comment /* ... */)


Almost all PowerVisor commands can be used from within an ARexx script.
There are some differences compared with the commandline :

   - You can't use ¹abbreviations for commands, you must always type the
     full commandname
   - You can't use ¹prefixes like '-' and '~' before a command. ('~' is
     not useful). If you want to ²hide output ('-'), you must use 'hide'
   - The 'quit' command is ignored
   - You get some new commands ('assign', 'hide', 'unhide', 'sync',
     'async' and 'front') (explained below)
   - ¹Functions are called the same way as commands. The result is put
     in the ²'result' variable (if you use ²'options results' in
     the ARexx script)

You can use the 'rx' command to start an ARexx script. This command
starts the script ¹asynchronous. This means that while the script is
running you can still use PowerVisor commands. If you want to disable
this feature you can use the 'sync' command from within the ARexx
script. This command ²synchronizes PowerVisor with the ARexx script.
You will not be able to use the PowerVisor commandline. When the
ARexx script is ready, it should call 'async'. If the ARexx script
forgets the 'async' command, you will not be able to use PowerVisor
anymore. You can solve this by sending the command 'async' from
the Shell (with the 'rx' shell command).

Note that the ³default file extension for PowerVisor ARexx scripts
is ¹'.pv'. You do not need to type this extension when you use the
'rx' command.

When you execute a PowerVisor command or function from within ARexx
and there is an error (or the command is interrupted) you can
examine the returncode (the 'rc' variable). 'rc' will contain
0 if there was no error or the PowerVisor error code if there was
an error.

Because you can't use the '-' prefix to ²hide output for a command there
is another way to hide output. The 'hide' and 'unhide' commands are
provided for this. After 'hide' all output from the ARexx commands is
hidden (as if there was a '-' in front of the commandline).
'unhide' restores this situation. Note that you must use 'unhide' otherwise
you might confuse yourselves when you use other ARexx scripts.

Normally the output for the ARexx scripts goes to the ³current logical window
('Main' or 'Extra'). If you open the ³'Rexx' logical window with 'awin',
all the ARexx output will go to that logical window.

The 'front' command brings the ²PowerVisor screen to the front.

Normally you would use 'rx' to start ARexx scripts. But you can also
use this command to start ARexx commands from within PowerVisor :

< rx 'disp 3+4' <enter>
> 00000007 , 7

or something more useful :

< rx 'address command dir' <enter>
CLI> ...

And the directory appears on the shell output window. You can thus use
the 'rx' command to start ²cli commands from within PowerVisor.

The last extra command for ARexx is 'assign'. With this command you
can assign something to a ²PowerVisor variable.
For example, the following ARexx script :

      file< /* */
      file< address rexx_powervisor
      file< a=1
      file< assign 'a=2'
      file< disp a
      file< disp 'a'

Will have as output :

      < rx file <enter>
      > 00000001 , 1
      > 00000002 , 2

You should understand why
   a=1
is not the same as
   assign 'a=1'

The first command assigns 1 to the ²ARexx variable 'a'. This variable
is not directly accessable from within PowerVisor.

The second command assign 1 to the PowerVisor variable 'a'. This variable
is not directly accesable from within the ARexx script. You can ask the value
of PowerVisor variables with 'void' :

   ARexx< options results
   ARexx< a=1
   ARexx< assign 'a=2'
   ARexx< 'void a'
   ARexx< var1=result
   ARexx< 'void' a
   ARexx< var2=result

Note ! var1 will be equal to 2, but var2 will be equal to 1. Can you explain
why ?

¹s:pv/ShowAscii.pv, ¹s:pv/PrintMode.pv and ¹s:pv/PrintHist.pv are three ARexx
script examples that you can examine.

========================= Machinelanguage scripts ============================

The following explanation is rather technical. Most PowerVisor users will
probably never write ²²machinelanguage scripts.

Machinelanguage scripts or ML scripts are normal AmigaDOS executable files.
In practice these can be programmed in several languages (like C), but
for naming conventions we call them ML scripts.

You can execute ML scripts the same way as normal PowerVisor scripts :
with the 'script' command. PowerVisor will automatically check if the
script is a machinelanguage script by reading the first four bytes.
AmigaDOS executable files always begin with the same four bytes.


Example :

< script execfile 10 <enter>

will execute the file 'execfile' and give 10 as the first argument
to the machinelanguage script.

When a ml-script gets executed some registers contain predefined
information :

   a0       A pointer to the rest of the commandline
   a1       Is the pointer to the ²'rc' variable. You can use this pointer
            to store results or to get some value. The 'rc' variable is a
            longword
   a2       Is the pointer to the ¹PVCallTable. This is a table with routines
            for you to use. See the 'TheWizardCorner' file for more
            information about the PVCallTable and the 'pvcall' command

You can put the returnvalue in d0. This returnvalue will be the result of
the 'script' command.

This is really all there is to machinelanguage scripts. But you should
read the 'TheWizardCorner' file if you really want to make more advanced
ML scripts. ¹s:pv/SearchHist.asm is an example ML script. This script can
be installed on a key to provide a history search utility.

======================= Making ML-scripts resident ===========================

If you want you can make ²ml scripts ³resident in memory. This is certainly
a lot faster if you use diskdrives and if the script is big.

You can use the 'resident' command to make ML scripts resident. Here
follows an example :

< _a={-resident s:pv/SearchHist} <enter>
< attach 'go \(_a)' 04c 2 e <enter>
< attach 'go \(_a)' 04c 1 e <enter>
< remvar _a <enter>

These four commands install the 'SearchHist' ML script on the shift-arrow
up key. When these four commands are executed you can search in the
PowerVisor history buffer with this key.

The first command ('resident') loads the ML script into memory and assigns
the pointer to the code to the '_a' variable.

Using the 'attach' command we attach the 'go' command to the shift-arrow
up key. Note that when 'attach' parses the command string it will replace
\(_a) with the contents of the variable '_a'. This is the pointer to the
code of the ML script.

The last command removes the variable.

This is actually not very difficult once you get used to it.

The 'go' command works very analogous to the 'script' command. The only
difference is that the script must be located in memory instead of a
file. The register conventions are the same.

Now you can use <shift>+<up> to search in the ²history buffer. The text
at the left of the cursor in the stringgagdet will remain unchanged. The
script will search all lines beginning with this text.

You can use 'unresident' to remove a loaded file. All resident files
are also automatically removed when PowerVisor quits.