@DATABASE "ARB56"
@INDEX "ARB:Misc/Index.Text/Main"
@HELP "ARB:Misc/Help/Main"
@NODE "Main" "ARexx For Beginners - Article 56 - Using ARexx With Amigaguide & Multiview"

@{B}@{U}@{JCENTER}AREXX FOR BEGINNERS

ARTICLE 56 - USING AREXX WITH AMIGAGUIDE/MULTIVIEW

BY FRANK BUNTON@{UB}@{UU}

@{" COPYRIGHT © FRANK P. BUNTON 1995-1998 " LINK "ARB:Misc/Read_Me_First!!/Copyright"}

@{" Starting An ARexx Script From Within A Document " LINK "Starting"}
@{"    Attribute   Commands RX or RXS               " LINK "Attribute"}
@{"    Global/Node Commands ONOPEN or ONCLOSE       " LINK "Global"}

@{" The Amigaguide & Multiview Port Names           " LINK "Ports"}
@{" Sending Commands To Amigaguide or Multiview     " LINK "Sending"}

@{" Starting Amigaguide From ARexx                  " LINK "StartingExARexx"}


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Starting" "Article 56 - Using ARexx With Amigaguide & Multiview - Starting Scripts"

@{B}@{U}@{JCENTER}STARTING AN AREXX SCRIPT FROM WITHIN AN AMIGAGUIDE OR MULTIVIEW DOCUMENT@{UB}@{UU}
@{JLEFT}

When using Amigaguide or Multiview to read documents of the Amigaguide
datatype, then ARexx program scripts can be run from within the document.

You can do this with either of:-

@{" Attribute   Commands RX or RXS         " LINK "Attribute"} All versions Amigaguide/Multiview

@{" Global/Node Commands ONOPEN or ONCLOSE " LINK "Global"} Only in Versions 40 Onwards


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Attribute" "Article 51 - Using ARexx With Other Programs - Using RX and RXS With Amigaguide/Multiview"

@{B}@{U}@{JCENTER}USING ATTRIBUTE COMMANDS RX AND RXS WITH AMIGAGUIDE/MULTIVIEW@{UB}@{UU}
@{JLEFT}
Attribute commands available in all versions of Amigaguide/Multiview are:-

  RX         to execute an ARexx script
  RXS        to execute an ARexx string

Attribute commands are set up like this:-

  \@{"Text to be highlighted" COMMAND "Command line to be sent"}

and are illustrated below for RX and RXS

@{B}@{U}Example Of The RX Command@{UB}@{UU}

An example of RX is:-

  \@{"Click here to run program" RX "ARB:Articles_01-10/testprogram"}

This would appear in the text like this: @{"Click here to run program" RX "ARB:Articles_01-10/testprogram"} and
if the user clicks on the highlighted area, the ARexx program with the
path/filename:-

    "ARB:Articles_01-10/testprogram.guide"

would be executed. This is the program I demonstrated in @{"Article 2" LINK "ARB:Articles_01-10/02.Program_Elements/Suffixes"19}.

Note that the @{"program's suffix" LINK "ARB:Articles_01-10/02.Program_Elements/Suffixes"30} is ".guide". When Amigaguide/Multiview
calls a program in the above way, the program name in the @{B}command line@{UB}
does not have to have a suffix if the suffix in the @{B}actual disk file name@{UB}
is ".guide". Amigaguide/Multiview automatically looks for a file with
the ".guide" suffix before looking for that program name without a
suffix.

@{B}@{U}Example Of The RXS Command@{UB}@{UU}

An example of RXS is:-

\@{"Click here to open a CLI window" RXS "ADDRESS 'COMMAND' 'NewCLI'"}

This would appear in the text like this: @{"Click here to open a CLI window" RXS "ADDRESS 'COMMAND' 'NewCLI'"}
and if the user clicks on the highlighted area, then a new Shell/CLI window
will open.

This does @{B}not@{UB} depend on a disk file. It simply sends the string to ARexx
which, in this case, is:-

   "ADDRESS 'COMMAND' 'NewCLI'"

It is the same as entering single line ARexx programs at a Shell/CLI prompt,
as in:-

  > RX "ADDRESS 'COMMAND' 'NewCLI'"

Thus AmigaDOS (address 'COMMAND') is addressed and a "NewCLI" command sent.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Global" "Article 51 - Using ARexx With Other Programs - Using ONOPEN  & ONCLOSE With Amigaguide/Multiview"

@ONOPEN  "ARB:Articles_51-60/51.testprogram_open"
@ONCLOSE "ARB:Articles_51-60/51.testprogram_close"

@{B}@{U}@{JCENTER}USING GLOBAL/NODE COMMANDS ONOPEN AND ONCLOSE WITH AMIGAGUIDE/MULTIVIEW@{UB}@{UU}
@{JLEFT}
@{B}PROVIDED THAT YOU HAVE AMIGAGUIDE.LIBRAY VERSION 40 OR LATER@{UB}, you should
have noticed that, when you selected this node, a small window opened
up telling you that you had selected it.

When you exit this node, another window should open giving a message that
you are exiting the node, also provided that you that you have the proper
library version.

Available in Amigaguide/Multiview from v40 onwards are these two commands:-

          \@ONOPEN  "Path/filename of ARexx script"
          \@ONCLOSE "Path/filename of ARexx script"

The two windows referred to above were achieved with these
commands:-

  \@ONOPEN  "ARB:Articles_51-60/51.testprogram_open"
  \@ONCLOSE "ARB:Articles_51-60/51.testprogram_close"

These two ARexx programs are basically the same as the example used earlier
in this article, i.e. that first used in @{"Article 2" LINK "ARB:Articles_01-10/02.Program_Elements/Suffixes"19}.

@{B}To be used as GLOBAL commands@{UB}, they must be placed in either one of these
positions.:-

- @{B}after@{UB} the \@DATABASE and @{B}before@{UB} the \@NODE "Main".

  For example:-

  \@DATABASE

  \@ONOPEN  Path/Filename of ARexx Script
  \@ONCLOSE Path/Filename of ARexx Script

  \@NODE "Main"

- @{B}after@{UB} the very last \@ENDNODE of the document.

I prefer the first as you see the commands immediately you load the document
for editing.

The ARexx script given after the ONOPEN will be executed as soon as the
document is loaded up by Amigaguide/Multiview and before any text is
shown.

The ARexx script given after ONCLOSE will be executed after the document
has been exited. This may be either when QUIT is selected, or after RETRACE
takes you back to another document.

@{B}To be used as NODE commands@{UB}, they should be placed anywhere between the
\@NODE "NodeName" and \@ENDNODE. However, I prefer them to be placed
immediately after the \@NODE "Name" as you see the commands immediately you
reach the start of the node while editing it.

The ARexx script given after the ONOPEN will be executed as soon as the
node is loaded up by Amigaguide/Multiview and before any text is
shown.

The ARexx script given after ONCLOSE will be executed after the node has
been exited. This may be either when QUIT is selected, or after RETRACE
takes you back to another node.

@{B}Note that@{UB} the @{B}full filename MUST be used!@{UB} even if it includes the suffix
".guide".

This is @{B}different@{UB} to the RX and RXS attribute commands where the suffix
".guide" @{"could be omitted" LINK "Attribute"28}.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Ports" "Article 56 - Amigaguide & Multiview Port Names"

@{B}@{U}@{JCENTER}AMIGAGUIDE AND MULTIVIEW PORT NAMES@{UB}@{UU}
@{JLEFT}

If, while an older version of Amigaguide is running, you us @{"SHOW('P')" LINK "ARB:Articles_21-30/24.Talking-Programs-2/P"}
in a direct ARexx command:-

  > RX "SAY SHOW('P')

you will get this @{"port name" LINK "ARB:Articles_21-30/23.Talking-Programs-1/Host"} included in the list of ports:-

  AMIGAGUIDE.1

If a second Amigaguide is also running, you will get this:-

  AMIGAGUIDE.1
  AMIGAGUIDE.2

If you do it with Multiview running then the list of names will include:-

  MULTIVIEW.1
  MULTIVIEW.1.1

or

  MULTIVIEW.1
  MULTIVIEW.1.1
  MULTIVIEW.2
  MULTIVIEW.2.1

Each additional Amigaguide or Multiview that is run will add to the list
of names with the ".x" number incrementing by one each time.

I have @{"already discussed" LINK "ARB:Articles_21-30/24.Talking-Programs-2/Address()"116} the method of determining which host address to
use when multiple copies are running.

With Multiview, two port names are shown for each copy of Multiview that
is running.

The ADDRESS() function returns the longer of the two names. For example:-

    MULTIVIEW.1.1    or    MULTIVIEW.2.1

However, when using the ADDRESS instruction, we have to use the shorter of
the two names. For example:-

    MULTIVIEW.1      or    MULTIVIEW.2

(Don't ask - I haven't got a manual that discusses this and I haven't had
time yet to work it out. If you know why, please @{"let me know" LINK "ARB:Misc/Read_Me_First!!/Author"}!!.)

To overcome this problem, we can use this bit of coding:-

  Hostname = ADDRESS()
  Hostname =LEFT(Hostname,INDEX(Hostname,'.')+1)

  ADDRESS VALUE Hostname

Lets say the Hostname obtained by ADDRESS() was:-

  MULTIVIEW.2.1

We can use @{"INDEX()" LINK "ARB:Articles_31-40/34.Strings_More/Index()"} to find the position in the string value of "Hostname"
of the first "." with:-

  INDEX(Hostname,'.')

This should return the number 10 for Multiview or 11 for Amigaguide.

We then use the @{"LEFT()" LINK "ARB:Articles_11-20/18.Functions-String/Left()"} function to take the left part of the string.

We add 1 the the number returned by INDEX() to make sure that we include
the character after the first stop (.).

We therefore end up with:-

  For Amigaguide:-   AMIGAGUIDE.x       where  x  is the number
  For Multiview:-    MULTIVIEW.x        of the  particular port.

This is only needed for Multiview but, in writing this series of articles,
I do not know which program the user will have.

The use of this method is illustrated in @{"Example56-1." LINK "Sending"56}


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Sending" "Article 56 - Using ARexx With AmigaGuide & MultiView - Sending Commands"

@{B}@{U}@{JCENTER}SENDING COMMANDS TO AMIGAGUIDE OR MULTIVIEW FROM AN AREXX SCRIPT@{UB}@{UU}
@{JLEFT}

As well as using the @{"attribute" LINK "Attribute"} and @{"Global/Nodal" LINK "Global"} commands, it is also
possible to send Amigaguide/Multiview commands from an ARexx program TO
Amigaguide/Multiview. I have not seen any documentation on what these
commands are and how to use them. However, from examining the
Amiguide.library file and the Multiview file with a "hex" reader it is
apparent that there ARE ARexx commands available for these two programs.

Commands that I have found and that seem to work in all version are:-

  QUIT
  WINDOWTOFRONT
  WINDOWTOBACK
  ACTIVATEWINDOW
  ZOOMWINDOW
  UNZOOMWINDOW

As indicated earlier, I have never seen anything on how these can be used
and I have not made a real attempt to analyse them.

However, some are fairly obvious and I will give brief examples of them
in Example56-1.

I will explain the program line by line below but @{"click here" LINK "ARB:Articles_51-60/Example56-1.guide/Main"} to read it
all at once.

To see it operate, first open a Shell/CLI window (if one is not already
open) and position it so that it is underneath this window, i.e. NOT visible.

The program will carry out these operations (with a 2 second break between
each one:-

1. Send the Amigaguide or Multiview window to the back.
   The Shell/CLI window should now become visible.

2. Bring the Amigaguide or Multiview window to the front again

3. Shrink the window to minimum size (like clicking on the zoom gadget)

4. Bring the window back to normal size.
   (Note the actual size will depend on the version of amigaguide.library
    that you have.)

5. If you have later versions of amigaguide.library then the last
   action will be a screen flash and/or beep.

@{"Click here" RX "ARB:Articles_51-60/Example56-1"} to start the program.

In the following explanations, the program is in @{B}bold@{UB} and the explanations
in plain text.


@{B}/* Example56-1.guide */

/* illustration of Amigaguide commands */

Hostname = ADDRESS()
Hostname =LEFT(Hostname,INDEX(Hostname,'.')+1)@{UB}

This bit of programming was explained @{"earlier" LINK "Ports"51}

@{B}IF LEFT(Hostname,10) ~= 'AMIGAGUIDE' & LEFT(Hostname,9) ~= 'MULTIVIEW'
   THEN DO

  SAY 'This program must be run from AMIGAGUIDE or MULTIVIEW'
  EXIT

END@{UB}

All the above does is to ensure that the program was started from
Amigaguide or Multiview and abort the program if it was not.

@{B}  ADDRESS 'COMMAND' 'Version >Nil: amigaguide.library 40'

  IF RC = 5 THEN Prog = 'AG'
  IF RC = 0 THEN Prog = 'MV'@{UB}

We now send the AmigaDOS command "Version" to see which version of the
"amigaguide.library" is in use. This usage of "Version" sets the return
code to 5 is the library version is less than the number given and to 0 if
it is equal to or more than the version number given.

If the version is LESS than 40 then the @{"variable RC" LINK "ARB:Articles_31-40/33.signalling/SiglRC"} will be set to 5
and the user must be using Amigaguide.

If the version is 40 or more, then the variable RC will be set to 0
and the user must be using Multiview.

(At least, to the best of my knowledge, that is the way that it should be
If it is not that way for you then are you using a standard Workbench??)

The variable "Prog" is set to "AG" or "MV" accordingly so that we can
select commands according to which program is in use.

@{B}ADDRESS VALUE Hostname@{UB}

All the rest of the commands to be sent will be to the host program.

Between each command a call to an internal function "Wait2" is made to
create a delay of two seconds.

@{B}'WINDOWTOBACK'

CALL Wait2

'WINDOWTOFRONT'

CALL Wait2@{UB}

The above two commands send the Amigaguide or Multiview window to the back
of all others and to the front of all others. They are common to all
versions of "amigaguide.library".

@{B}IF Prog = 'AG' THEN DO

  'ZOOMWINDOW'

  CALL Wait2

  'UNZOOMWINDOW'

END@{UB}

If Amigaguide is in use then the above two commands (that are not available
in Multiview) are sent.

@{B}ELSE DO

  'MINIMUMSIZE'

  CALL Wait2

  'NORMALSIZE'

  CALL Wait2

  'BEEPSCREEN'

END@{UB}

If Multiview is in use then the above three commands (that are not
available in Amigaguide) are sent.

@{B}EXIT@{UB}

We exit here as the program is over.

@{B}Wait2:

  CALL TIME('R')
  DO UNTIL TIME('E') >2
  END
RETURN@{UB}

All this does is @{"reset" LINK "ARB:Articles_11-20/20.Functions-Date&Time/Reset"} the timing clock then wait until 2 seconds have
@{"elapsed" LINK "ARB:Articles_11-20/20.Functions-Date&Time/Elapsed"}.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "StartingExARexx" "Article 56 - Using ARexx With AG & MV - Starting Amigaguide Ex ARexx"

@{B}@{U}@{JCENTER}STARTING AMIGAGUIDE FROM AN AREXX SCRIPT@{UB}@{UU}
@{JLEFT}
It is possible to start up Amigaguide showing a specified node of a document
(NOT necessarily the MAIN node) from an ARexx script even if there is no
current Amigaguide or Multiview window open.

This can be done by opening the "amigaguide.library" with @{"ADDLIB" LINK "ARB:Articles_31-40/38.Functions-More/Addlib()"} as follows:-

  CALL ADDLIB('amigaguide.library',0,-30,0)

and then using its "SHOWNODE" function which has the following format:-

  SHOWNODE(PUBSCREEN,DATABASE,NODE,LINE,XREF)

     PUBSCREEN - Name of public screen that the AG window should open on.
                 Defaults to the Workbench screen.

     DATABASE  - Path and name of Amigaguide document to be displayed.

     NODE      - Name of node within the document to be displayed.
                 Defaults to MAIN node.

     LINE      - Line number within the node to be put at top of window.
                 (I have not yet been able to get this to work).

     XREF      - I have not yet determined exactly what this argument does
                 but I guess it has something to do with cross reference
                 tables. It is not needed in the context of what we are
                 doing here.

                 Note that XREF is not in the format of the v34
                 amigaguide.library.

The only essential argument is DATABASE so that you could use the following
to show the MAIN node (which is the default node if no node is specified):-

  CALL SHOWNODE(,'Path/DatabaseName',,,)

But if you wanted to show a node other than MAIN you should use:-

  CALL SHOWNODE(,'Path/DatabaseName','NodeName',,)

Note the positioning of the commas to ensure that the POSITION of each
argument is included - a null string is then included for the arguments not
used and their default values (if any) are taken.

@{B}Amigaguide Version 34 note@{UB} - you MUST use one less argument as v34 does not
support the XREF argument. In the above examples, leave out the last comma!!

There are two example scripts to demonstrate this procedure. They are:-

  @{" Example56-2 " LINK "Example56-2"} which will display an item from the glossary of this set.
                 It does NOT use the PUBSCREEN argument so it defaults to
                 the workbench screen.

  @{" Example56-3 " LINK "Example56-3"} which uses a PUBSCREEN argument of "DOPUS.1" and will
                 display a node on the Directory Opus screen.

@{B}Amigaguide Version 34 Note@{UB} - If you are using amigaguide.library v34 then
you will have to amend these two scripts to remove the last comma from the
SHOWNODE function call so that they read:-

  Example56-2      CALL SHOWNODE(,FileName,NodeName.Count.1,)

  Example56-3      CALL SHOWNODE('DOPUS.1',FileName,NodeName,)

@{B}@{U}Notes@{UB}@{UU}

1. This method does not appear to use either of the actual programs
   "Amigaguide" or "Multiview". It uses the files:-

  - amigaguide.library   (all versions of Amigaguide)
  - amigaguide.datatype  (Amigaguide versions 39 & 40)

2. An ARexx port does @{B}NOT@{UB} appear to be available when Amigaguide is
   started by this means!!


@{JCENTER}=== End of Text ===

@ENDNODE

@NODE "Example56-2" "Article 56 - Starting Amigaguide Ex ARexx - Example56-2"

@{B}@{U}@{JCENTER}STARTING AMIGAGUIDE FROM AN AREXX SCRIPT

EXAMPLE 56-2@{UB}@{UU}
@{JLEFT}
@{JLEFT}This example will display a menu of a few of the glossary items from this
set and allows the user to enter a number to read one of the items.

You can read this example script in full by  @{"Clicking here" LINK "ARB:Articles_51-60/Example56-2.rexx/MAIN"}.

This example is very simplistic and not of much practical value but it does
demonstrate the use of the SHOWNODE function:-

 -  without a PUBSCREEN argument,
 -  with a number of user options.

@{"Example56-3" LINK "Example56-3"} is even simpler but it does demonstrate the use of the
PUBSCREEN argument.

To use this ARexx script, you should follow these steps:-

1. Quit this Amigaguide or Multiview (AG/MV) display so that no AG/MV
   program is running. This is NOT really necessary but it will demonstrate
   that the ARexx script really will start up AG/MV without it being already
   in operation.

2. Open a Shell/CLI window if you have not already got one open.

3. Enter in the Shell/CLI window:-

   > RX ARB:Articles_51-60/Example56-2


@{JCENTER}=== End of Text ===

@ENDNODE


@NODE "Example56-3" "Article 56 - Starting Amigaguide Ex ARexx - Example56-3"

@{B}@{U}@{JCENTER}STARTING AMIGAGUIDE FROM AN AREXX SCRIPT

EXAMPLE 56-3@{UB}@{UU}
@{JLEFT}
The second example will display the node "Encrypt" from the file
"Dopus5.Guide". 

This script will only work if:-

- you have Directory Opus v5 running, and
- it has a public screen name of "DOPUS.1", and
- it is @{B}not "hidden".@{UB}

(I could write a complex ARexx script to overcome these restrictions but it
is just not worth it for this simple example of the PUBSCREEN argument.)

You can read this example script in full by  @{"clicking here" LINK "ARB:Articles_51-60/Example56-3.rexx/MAIN"}

"DOPUS.1" is the name of the public screen of the first copy of Directory
Opus that is run. If another copy is run while the first is still running
then that will be "DOPUS.2". However, "DOPUS.1" should still be available@{UB}
unless you have closed down the first copy after starting up the second
copy.

@{B}NOTE@{UB} I chose Directory Opus as it is a very commonly owned program.
     If you do not own Directory Opus then you could edit the example script
     to include a public screen name of a program that you do own, and
     change the file name and node name to some other Amigaguide document.

     These three items are included as @{"symbol values" LINK "ARB:Articles_51-60/Example56-3.rexx/MAIN"21} to make it easy to
     change them.

It is even more simplistic than @{"Example56-2" LINK "Example56-2"}. Its only use is to
demonstrate the use of the PUBSCREEN argument as in this line from the
script which uses the Directory Opus public screen name "DOPUS.1":-

  CALL SHOWNODE(ScreenName,FileName,NodeName,,)

To use this ARexx script, you should follow these steps:-

1. Make sure that your have your Directory Opus v5 running, that it has the
   public screen name "DOPUS.1" and that it is not "hidden".

   Also make sure that the assignment to "Dopus5:" has been made. This
   assignment should have been added to your "User-Startup" file by the
   Directory Opus installation script.

2. Open a Shell/CLI window if you have not already got one open.

3. Enter in the Shell/CLI window:-

   > RX ARB:Articles_51-60/Example56-3

The "Encrypt" node the the "Dopus5.guide" file should now be displayed on
the Directory Opus screen.

@{B}Amigaguide Version 34 note@{UB} - the Directory Opus screen does not come to the
front as it does does with Amigaguide versions 39 and 40.


@{JCENTER}=== End of Text ===

@ENDNODE