@DATABASE PGS.MSU
@(C) 1994 Soft-Logik Publishing Corporation
@INDEX PageStream3:Help/PGS.INA/MAIN

@remark *** AREXX SUBJECTS SECTION ***

@node MAIN "PageStream3 Macros"

@{FG Highlight}PageStream3 Macros@{FG Text}

PageStream features a full ARexx implementation with hundreds of commands
to allow you to control every aspect of the program. PageStream's ARexx
features allow you to write your own scripts and to record scripts while
you use PageStream.

PageStream permits two kinds of macro scripts:
- internal PageStream macros
- external ARexx macros

Both kinds of macro scripts can be executed by assigning them to function
keys, adding them to the Macros menu, or by executing them with the
PageStream Macros or Execute ARexx Macro commands.

@{FG Highlight}Internal PageStream Macros@{FG Text}

Internal PageStream macros are made up of PageStream ARexx commands, but
may not include any ARexx language variables or commands (such as
IF...THEN or FOR...NEXT). They are executed internally without ARexx. This
allows fast execution and does not require that ARexx be loaded, but
limits you to the PageStream command set.

Internal PageStream macros can be created by recording program actions
with the Start Recording command, or by writing a macro with the
PageStream Macros command. Internal macros are stored in the
PageStream3.macros file and can only be edited from within PageStream.

@{" Recording a PageStream Macro " link RCPG}@{" Editing a PageStream Macro   " link EDPG}@{" Executing a PageStream Macro " link EXPG}@{" Possible Errors              " link ERPG}@{" Converting to an ARexx Macro " link CVAR}

@{FG Highlight}External ARexx Macros@{FG Text}

External ARexx macros are made up of PageStream ARexx commands and ARexx
language commands. They are executed externally with ARexx. This gives you
the full power of the ARexx language and all its features, but these
macros are slower to execute than internal macros.

External macros can be created by writing them with a text editor, or by
creating an internal PageStream macro and converting it to an external
ARexx macro. External ARexx macros are stored in separate text files and
must follow all ARexx conventions.

@{" What is ARexx?           " link WHAT}@{" Starting ARexx           " link MAST}@{" ARexx Port Address       " link ADDR}@{" Command Format           " link FORM}@{" ARexx Macro Layout       " link SCRP}@{" Executing an ARexx Macro " link EXAR}@{" Possible ARexx Errors    " link ERAR}@{" Recommended Reading      " link PageStream3:Help/sub/READ}

@{FG Highlight}Why Two Macro Systems?@{FG Text}

If you are already familiar with ARexx, PageStream's ARexx implementation
will be familiar to you. It follows all established ARexx guidelines and
provides the standard ARexx features. ARexx requires time to learn and
scripts take time to write, however, so some users may wish for a simpler
system that does not require programming knowledge. PageStream's internal
macros can be recorded without writing a script, and can be executed
faster because they are not sent through the ARexx interpreter.

This dual macro system provides the utmost in flexibility. The commands
for the two systems are the same, and are generally referred to as just
'ARexx commands'. Because you can convert an internal macro to an external
ARexx macro, you can have the best of both worlds.

@{FG Highlight}Macro Systems Comparison       Internal Macros   External ARexx Macros@{FG Text}

Use PageStream ARexx commands        yes                 yes
Use ARexx language commands          no                  yes
Use variables                        no                  yes
Edit in PageStream                   yes                 no
Edit in text editor                  no                  yes
Saved in PageStream3.macros file     yes                 no
Saved as separate ASCII files        no                  yes
Execution speed                      fast                slow
Execute from function keys           yes                 yes
Execute from Macros menu             yes                 yes
Execute from list                    yes                 yes


See Also:

@{" ARexx Command Index          " link ARexxIndex/A/MAIN}
@{" ARexx Command Contents       " link PageStream3:Help/arc/MAIN}
@toc PageStream3:Help/PGS.HEL/MAIN
@endnode

@node RCPG "Recording an Internal PageStream Macro"

@{FG Highlight}Recording an Internal PageStream Macro@{FG Text}

You can record any PageStream command to create a macro which you can
execute at a later time to repeat your commands. This is a good way to
automate common tasks without writing an ARexx script.

To record a PageStream macro, choose the @{"Start Recording" link PageStream3:Help/mac/STAR} command. This will put a 'record on' symbol (a flashing circle) in the top-right corner of the screen. Any commands you give PageStream now will be recorded, including:
- changing tools
- choosing commands
- drawing objects
- moving, scaling objects
- key presses

Note that PageStream records commands, not actions. The act of choosing a
command to open a requester is not recorded. PageStream has a non-modal
macro interface. Some programs that feature recordable macros record the
opening of a requester and the selection of gadgets within the requester.
This is a limited type of system because it is dependent on the mode of
the program when the macro script is started. PageStream does not record
that the requester is opened, but simply sets the options you choose from
within the requester. For example, nothing is recorded if you open a
requester and close it without selecting any options.

To finish recording a PageStream macro, choose the @{"Stop Recording" link PageStream3:Help/mac/STOP} command.
This will remove the 'record on' symbol from the top-right corner of the
screen. The @{"Edit Macro" link PageStream3:Help/mac/EDIT} requester will open to allow you to view,
name, edit, or assign the captured PageStream macro.

Note that internal macros are not saved to the PageStream3.macros file
until the Save command is selected from the Macros menu in the
@{"PageStream Macros" link PageStream3:Help/mac/PGMC} requester.
@endnode

@node EDPG "Editing an Internal PageStream Macro"

@{FG Highlight}Editing an Internal PageStream Macro@{FG Text}

Internal PageStream macros are stored in the PageStream3.macros file in the main PageStream3 directory. This file is compressed to save disk space and cannot be edited in a text editor; however, you can edit the macros directly in PageStream.

To edit a PageStream macro, choose the @{"PageStream Macros" link PageStream3:Help/mac/PGMC} command to open the PageStream Macros requester. This will list all the available PageStream macros. Select one from the scrolling list and choose the Edit gadget. This will open the @{"Edit Macros" link PageStream3:Help/mac/EDIT} requester.

Note that internal macros are not saved to the PageStream3.macros file until the Save command is selected from the Macros menu in the @{"PageStream Macros" link PageStream3:Help/mac/PGMC} requester.
@endnode

@node EXPG "Executing an Internal PageStream Macro"

@{FG Highlight}Executing an Internal PageStream Macro@{FG Text}

Internal PageStream macros can be executed in one of four ways:
- by pressing the assigned function key combination;
- by choosing the macro from the Macros menu;
- by choosing the macro from the Macro panel; or
- by selecting the the macro from the PageStream Macros requester.

@{fg highlight}Pressing an Assigned Function Key:@{fg text}

You can assign PageStream macros to the 10 function keys with the
@{"PageStream Macros" link PageStream3:Help/mac/PGMC} command. Once a macro has been assigned to a function
key, you can launch it by pressing its key. Note that internal PageStream
macros share the function keys with external ARexx macros.

@{FG Highlight}Choosing from the Macros Menu:@{FG Text}

You can add PageStream macros to the Macros menu with the
@{"PageStream Macros" link PageStream3:Help/mac/PGMC} command. Once a macro name has been added to the menu,
you can execute it by choosing it from the menu. Note that internal
PageStream macros and external ARexx macros are displayed together in the
Macros menu.

@{FG Highlight}Selecting from the Macro Panel:@{FG Text}

If the Macro panel is open (it can be opened with the @{"Macro Panel" link PageStream3:Help/set/MAPA}
command), you can execute a PageStream macro simply by clicking on it.
Note that internal PageStream macros and external ARexx macros are
displayed together in the Macro panel.

@{FG Highlight}Selecting from the PageStream Macros Requester:@{FG Text}

You can execute a PageStream macro from the @{"PageStream Macros" link PageStream3:Help/mac/PGMC}
requester by selecting a macro from the scrolling list and choosing the
Execute gadget.
@endnode

@node ERPG "Return Values and Errors"

@{FG Highlight}Return Values and Errors@{FG Text}

Many of PageStream's commands return values to the calling macro script.
These are only available when the macro is an external ARexx script,
because PageStream uses the standard ARexx RC and RESULT variables.

@{FG Highlight}Returned Values@{FG Text}

Returned values are always stored in the special RESULT variable, unless
there is more than one returned value, in which case a stem variable is
normally used. Note that in ARexx, you must enable results explicitly if
you wish to receive them. This is done by including a line near the top of
your ARexx macro:

    options results

@{FG Highlight}Errors@{FG Text}

It is possible for a command to fail, because the prerequisite conditions
for the command did not exist. PageStream returns error codes to the
special RC variable. When a command has finished executing, the RC
variable can be examined to determine whether the command was successful
or not. When RC is equal to zero, the command worked as expected. Any
other value indicates an error.

In general, the greater the RC number, the more severe the error. There
are four possible severity levels:

RC =  0  Normal; there was no error.
RC =  5  Slight error; not fatal.
RC = 10  Serious error.
RC = 20  Fatal Error.

Each command may have other errors that it returns. See the command
definitions for more information.
@endnode

@node WHAT "What is ARexx?"

@{FG Highlight}What is ARexx?@{FG Text}

ARexx is an interpreted programming language. Like Basic, ARexx macro
scripts (programs) can be written with a text editor and then run without
having to use a compiler. Unlike programming languages, however, ARexx
macro scripts can combine commands that are specific to applications, as
well as to ARexx. This allows an ARexx script to control PageStream.
@endnode

@node MAST "Starting ARexx"

@{FG Highlight}Starting ARexx@{FG Text}

Before you can use PageStream's ARexx features, you must start ARexx. Most
users start ARexx automatically when they boot their computers by adding
the ARexx program name to their User-Startup or Startup-Sequence file.

@{FG Highlight}Starting ARexx Automatically@{FG Text}

If you have not already done this, follow these steps:

1. Open a text editor.

2. Open the S:User-Startup file.

3. Add the following command at the end of the file:

   REXXMAST >NIL:

4. Save the file.

5. Reboot your Amiga.


@{FG Highlight}To Start ARexx Manually from the Workbench:@{FG Text}

1. Open the System drawer.

2. Double-click on the RexxMast icon.


@{FG Highlight}To Start ARexx Manually from the Shell:@{FG Text}

1. Open a Shell.

2. Type REXXMAST >NIL: and press Enter.
@endnode

@node ADDR "ARexx Port Address"

@{FG Highlight}ARexx Port Address@{FG Text}

Each ARexx compatible program opens an ARexx port to which you can send
commands. The first copy of PageStream you run will open a port called
'PAGESTREAM'. Subsequent copies will open ports called 'PAGESTREAM.1',
'PAGESTREAM.2' etc...

To address your commands to the default PageStream ARexx port, place the
ADDRESS command after the initial remark.

i.e., ADDRESS 'PAGESTREAM'

See also:

@{" ARexx Macro Layout " link SCRP}
@endnode

@node FORM "Command Format"

@{FG Highlight}ARexx Command Reference Format@{FG Text}

Format:   provides a template for the command:

< >   Angle brackets enclose MANDATORY parameters.
[ ]   Square brackets enclose OPTIONAL parameters.
 |    Vertical bars separate alternative parameters.
{ }   Parentheses enclose parameters that can be repeated as many times as
      required in a command. i.e., You can create multiple tabs with one
      settabs command.

NB: Do not type these as part of the commands. They are used only to show
the command format.

@{FG Highlight}Case:@{FG Text}

The case of PageStream ARexx commands is not important. Commands and
options are listed here in uppercase to distinguish them from the
explanations.

@{FG Highlight}Arguments and Variables:@{FG Text}

Some commands require you to enter an argument to the command or to
specify a variable to hold a result. Variables and arguments in the
command descriptions are followed by a backslash and a letter to indicate
their type. The following table describes each type of argument and
variable:

@{FG Highlight}\\I@{FG Text} Integer: Whole numbers, positive or negative. i.e., -2, -1, 0, 1, 2, 3

@{FG Highlight}\\D@{FG Text} Decimal: Any number.

@{FG Highlight}\\P@{FG Text} Percentage: Any number as a percent. i.e., enter 80 for 80%.

@{FG Highlight}\\A@{FG Text} Angles: Any number between 0 and 360.

@{FG Highlight}\\F@{FG Text} Filename: Used with commands that refer to a file. The filename is required for files, and the path is required for paths; the full file path may or may not be required for files, depending on the current path.

@{FG Highlight}\\V@{FG Text} Stem Variable: Used for multiple results.

@{FG Highlight}\\S@{FG Text} String: Used for text. Any character is acceptable.*

* Multiple lines in strings should be separated by a backslash and an 'n'.
i.e., "This is line 1.\nThis is line 2." To enter a true '\n', type '\\n'.
@endnode

@node SCRP "ARexx Macro Layout"

@{FG Highlight}ARexx Macro Layout@{FG Text}

All ARexx Macros must begin with a comment or remark. Remarks are
specified with a '/*' at the beginning and a '*/' at the end. This tells
ARexx to ignore the text within the remark indicators.

After the first remark (and any other desired remarks), you must specify
the PageStream ARexx port @{"address" link ADDR} so that the commands will be given to
the correct program.

Your scripts should normally enable results so that results of operations
can be returned and stored in the ARexx RESULT variable.

The rest of your script must be made up of valid PageStream ARexx commands
and standard ARexx functions.

@{FG Highlight}ARexx Script Framework Example@{FG Text}

/* SCRIPT NAME */
/* Script description */
/* Created by yourname */

ADDRESS 'PAGESTREAM.1'
OPTIONS RESULTS
TRACE OFF

/* MAIN PART OF SCRIPT */

etc...
@endnode

@node EXAR "Executing an External ARexx Macro"

@{FG Highlight}Executing an External ARexx Macro@{FG Text}

External ARexx macros are normally stored in the PageStream3/Macros
drawer, although you can assign the path for macros to any drawer with the
@{"Paths" link PageStream3:Help/set/PATH} command.

You may wish to install your ARexx macros in the REXX: directory because
then you can execute the macros from the Shell without having to type the
complete path and because it will centralize your scripts. However, most
people prefer to keep them in a separate directory to reduce clutter in
the REXX: directory.

The ARexx macros which come with PageStream3 have .PSRX filename
extensions. This ensures that you know which ARexx scripts are intended
for PageStream.

External ARexx macros can be executed in one of four ways:
- by pressing the assigned function key combination;
- by choosing the macro from the Macros menu;
- by choosing the macro from the Macro panel;
- by selecting the macro from the Execute ARexx Macro requester;
- by executing the macro from a Shell; or
- by double clicking on a macro icon.

@{fg highlight}Pressing an Assigned Function Key:@{fg text}

You can assign ARexx macros to the 10 function keys with the @{"Install
ARexx Macros" link PageStream3:Help/mac/INAR} command. Once a macro has been assigned to a function key,
you can launch it by pressing its key. Note that internal PageStream
macros share the function keys with external ARexx macros.

@{FG Highlight}Choosing from the Macros Menu:@{FG Text}

You can add ARexx macros to the Macros menu with the @{"Install ARexx Macros" link PageStream3:Help/mac/INAR}
command. Once a macro name has been added to the menu, you can execute it
by choosing it from the menu. Note that internal PageStream macros and
external ARexx macros are displayed together in the Macros menu.

@{FG Highlight}Selecting from the Macro Panel:@{FG Text}

If the Macro panel is open (it can be opened with the @{"Macro Panel" link PageStream3:Help/set/MAPA}
command), you can execute an ARexx macro simply by clicking on it. Note
that internal PageStream macros and external ARexx macros are displayed
together in the Macro panel.

@{FG Highlight}Selecting from the Execute ARexx Macros Requester:@{FG Text}

You can execute a PageStream macro from the @{"Execute ARexx Macro" link PageStream3:Help/mac/EXAR}
requester by selecting a macro from the scrolling list and choosing the
Execute gadget.

@{FG Highlight}Executing from the Shell:@{FG Text}

The RX command is used to run an ARexx macro script from the Shell. You
must include the full path for the file unless it is stored in REXX: or if
you are in the Macros directory.

ex: RX scriptname.psrx
    RX Work:PageStream3/Macros/scriptname.psrx

@{FG Highlight}Double Clicking on a Macro Icon:@{FG Text}

If the ARexx macro file has a project icon and if the default tool is set
to SYS:Rexxc/RX, you can run the macro from the Workbench by double
clicking on it. If RexxMast has not already been loaded, this will start
RexxMast and then run the macro script.
@endnode

@node ERAR "Possible Errors..."

@{FG Highlight}Possible Errors in Executing an External ARexx Macro@{FG Text}

PageStream returns a number to the ARexx RC variable after each command
it processes.

0   No errors
5   Warning
10  Command failed
20  Command has invalid parameters.
100 Unknown or invalid command.

There are additional error codes that are specific to each command. See the @{"command reference" link ARexxIndex/A/MAIN} for detailed information on each command.
@endnode

@node CONS "Constraints"

@{FG Highlight}Constraints@{FG Text}

Objects have a constraint flag which allows their @{"aspect ratio" link PageStream3:Help/sub/ASRA} to be fixed so that they cannot be accidentally resized non-proportionally. When the flag is set to CONSTRAIN, they can only be resized proportionally, and when the flag is set to FREE, they can be resized non-proportionally.
@endnode

@node WIND "Document, Window, Page and Style Tag Names"

@{FG Highlight}Document, Window, Page and Style Tag Names@{FG Text}

Many PageStream ARexx commands use the LAYOUTELEMENT, WINDOW, PAGE,
MASTERPAGE and DOCUMENT parameters. Depending on which parameter is used,
you may be able to enter the document, chapter, page, masterpage or window
names. Use the following table to decide which to enter.

LAYOUTELEMENT documentname[:chaptername[:subchaptername]]
              example: 'Untitled Document.1:Chapter 1'
DOCUMENT      documentname
              example: 'Untitled Document.1'
WINDOW        [documentname-]windowname
              example: 'Untitled Document.1-View.1'
PAGE          [documentname[:chaptername[:subchaptername]-]pagenumber
              example: 'Untitled Document.1:Chapter 1-13'
MASTERPAGE    [documentname[:chaptername[:subchaptername]-]masterpagename
              example: 'Untitled Document.1:Chapter 1-13'
STYLETAG      [documentname[:chaptername[:subchaptername]-]styletagname
              example: 'Untitled Document.1-Body Text'
ARTICLE       [documentname[:chaptername[:subchaptername]-]articlename
              example: 'Untitled Document.1-Story1'

Note that all of these parameters require string inputs except for the
PAGE parameter. If just the page number is given, you can enter the page
number without quotes. If the document name is added, you must enter it
as a string.
@endnode

@node CVAR "Converting a PageStream Macro to an ARexx Macro"

@{FG Highlight}Converting a PageStream Macro to an ARexx Macro@{FG Text}

Internal PageStream macros can be converted to external ARexx macros by exporting them from the @{"PageStream Macros" link PageStream3:Help/mac/PGMC} requester. Select a macro script from the scrolling list and choose the Export gadget. This will save the macro as an ASCII text file.
@endnode

@node COOR "Object Coordinates"

@{FG Highlight}Object Coordinates@{FG Text}

Most objects have four coordinate values: px1, py1, px2, py2. These are the coordinates of the top/left and bottom/right corners, respectively.

Other objects have eight coordinate values: px1, py1, px2, py2, px3, py3, px4, py4. These are the coordinates of the top/left, bottom/left, bottom/right and top/right coordinates, respectively.

Some objects have a center and radii coordinate values instead of corner coordinates: cx, cy, rx, ry. These are the coordinates of the center point and horizontal and vertical radii, respectively.
@endnode