AWeb ARexx Commands

Window and transfer related commands

CANCEL
CHANCLOSE
CHANDATA
CHANHEADER
CHANOPEN
CLOSE
COPYURL
FOCUS

GO
LOAD
NEW
OPEN
OPENREQ
RELOAD
RESETFRAME
SAVEAS

SAVEIFF
SCROLL
STATUSFIELD
URLFIELD
WAIT
WINDOW

CANCEL

Template:


   CANCEL LOADID/N,ALL/S

Cancel one or more transfers. Essentially the same as pressing the cancel gadget.

Argument Description
LOADID A number identifying which transfer to cancel. Use the GET TRANSFERS command to get load ID numbers for the current transfers.
ALL When set, the command cancels all transfers. Essentially the same as pressing the cancel all gadget in the network status window.

If neither a LOADID nor the ALL switch is given on the command, the current transfer for this window is cancelled.

Argument	Description
LOADID	A number identifying which transfer to cancel. Use the GET TRANSFERS command to get load ID numbers for the current transfers.
ALL	When set, the command cancels all transfers. Essentially the same as pressing the cancel all gadget in the network status window.

CHANCLOSE

Template:


   CHANCLOSE CHANNEL/A

Close this incremental input channel. If the channel was already closed then return code (RC) 5 is set.

Argument Description
CHANNEL The channel ID as returned by the CHANOPEN command.
See the CHANOPEN command for a brief explanation of incremental input channels.

Argument	Description
CHANNEL	The channel ID as returned by the CHANOPEN command.

CHANDATA

Template:


   CHANDATA CHANNEL/A,DATA/A,NL=NEWLINE/S

Send data to this incremental input channel. If the channel was closed then return code (RC) 5 is set.

Argument Description
CHANNEL The channel ID as returned by the CHANOPEN command.
DATA The string of data to send to the channel.
NEWLINE If this switch is set, a newline is appended to the data.
See the CHANOPEN command for a brief explanation of incremental input channels.

Argument	Description
CHANNEL	The channel ID as returned by the CHANOPEN command.
DATA	The string of data to send to the channel.
NEWLINE	If this switch is set, a newline is appended to the data.

CHANHEADER

Template:


   CHANHEADER CHANNEL/A,HEADER/A

Send a HTTP header to this incremental input channel. If the channel was closed then return code (RC) 5 is set.

All headers should be sent before any data is sent, otherwise results are unpredictable.

Argument Description
CHANNEL The channel ID as returned by the CHANOPEN command.
HEADER A HTTP header, e.g. "Content-Type: text/html".
See the CHANOPEN command for a brief explanation of incremental input channels.

Argument	Description
CHANNEL	The channel ID as returned by the CHANOPEN command.
HEADER	A HTTP header, e.g. "`Content-Type: text/html`".

CHANOPEN

Template:


   CHANOPEN URL/A

Open an incremental input channel for this URL.

The reserved ARexx variable RESULT will be set to the ID for the opened channel.

Argument Description
URL The URL to load via the channel.

Argument	Description
URL	The URL to load via the channel.

Incremental input channels can be used to generate and incrementally display a document, instead of writing data to a file and then use the OPEN command to load the file in one go.

Basically a retrieve process is started by this command, that uses the ARexx CHAN... commands as input source. You have to supply a URL for which this retrieve process is started. This can be any URL, in any format (but it is advised to adhere to the general URL format "scheme:scheme-specific-part"). This URL is not automatically displayed; you have to issue an OPEN command after opening the channel. Do not use RELOAD because that will abort any ongoing transfer for the URL and therefore closes the channel.

Use the CHANHEADER, CHANDATA and CHANCLOSE commands to send data over the channel. Note that the channel can be closed by the user (by cancelling the retrieve process). These commands will return with returncode (RC) set to 5 if the channel was closed.

Data sent through a channel will be cached (unless the URL matches the no-cache list). If the data shouldn't be cached, you should send a "Pragma: No-cache" header.

CLOSE

Template:


   CLOSE FORCE/S

Close the addressed window.

Argument Description
FORCE When set, this switch suppresses the "Are you sure" requester if this was the last open window.

Argument	Description
FORCE	When set, this switch suppresses the "Are you sure" requester if this was the last open window.

COPYURL

Template:


   COPYURL TARGET/K

Copy the URL displayed in the addressed window or the specified frame to the clipboard.

Argument Description
TARGET The target name of the window or frame to copy the URL from. If no target is given, the URL displayed in the main window is copied.

Argument	Description
TARGET	The target name of the window or frame to copy the URL from. If no target is given, the URL displayed in the main window is copied.

FOCUS

Template:


   FOCUS TARGET/K

Change the keyboard scroll focus to the specified frame.

Argument Description
TARGET The target name of the window or frame to make the new focus. If no target is given, the main window is made the focus.

Argument	Description
TARGET	The target name of the window or frame to make the new focus. If no target is given, the main window is made the focus.

GO

Template:


   GO N/N,BACK/S,FWD=FORWARD/S,HOME/S

Navigate through the window history.

Argument Description
N A number specifying how many steps to go through the window history. Default value is 1.
BACK Step back through the window history.
FORWARD Step forward through the window history.
HOME Go to the home document, if one is configured.
The BACK, FORWARD and HOME switches are mutually exclusive.

Argument	Description
N	A number specifying how many steps to go through the window history. Default value is 1.
BACK	Step back through the window history.
FORWARD	Step forward through the window history.
HOME	Go to the home document, if one is configured.

LOAD

Template:


   LOAD URL/A,RELOAD/S,SAVEAS/K,APPEND/S,SAVEREQ/S,NOICON/S,POST/K

Load a file in the background, or save a nondisplayed file.

Argument Description
URL The URL to retrieve in the background.
RELOAD When set, the specified URL will be reloaded even if it is still in the cache.
SAVEAS If a name is specified, the file will be saved into a file with this name.
APPEND When set, the saved source is appended to the file specified in the SAVEAS argument.
When not set, and the SAVEAS argument is given, the specified file will be overwritten.
SAVEREQ When set, a save filerequester will be opened to allow saving of the file.
NOICON In combination with the SAVEAS or SAVEREQ switch, this switch prevents AWeb from creating an icon for the saved file.
POST The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET).
See the OPEN command description for a note about POST messages

Argument	Description
URL	The URL to retrieve in the background.
RELOAD	When set, the specified URL will be reloaded even if it is still in the cache.
SAVEAS	If a name is specified, the file will be saved into a file with this name.
APPEND	When set, the saved source is appended to the file specified in the SAVEAS argument. When not set, and the SAVEAS argument is given, the specified file will be overwritten.
SAVEREQ	When set, a save filerequester will be opened to allow saving of the file.
NOICON	In combination with the SAVEAS or SAVEREQ switch, this switch prevents AWeb from creating an icon for the saved file.
POST	The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET). See the OPEN command description for a note about POST messages

NEW

Template:


   NEW URL/A,NAME/K,RELOAD/S,POST/K,SMART/S

Open a new window and retrieve the specified document to display in the new window.

The reserved ARexx variable RESULT will be set to the name of the ARexx port for the new window.

Argument Description
URL The URL to retrieve and display in the new window.
NAME Name of the new window. If given, the new window can be addressed from other windows documents by using the HTML TARGET attribute.
RELOAD When set, the specified URL will be reloaded even if it is still in the cache.
POST The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET).
See the OPEN command description for a note about POST messages
SMART When set, the URL string will be handled in exactly the same way as if it was typed into the URL gadget. That is, the http:// scheme is prepended if no scheme is given, and (if enabled and appropriate) autosearch is used.
When SMART is set, the RELOAD and POST arguments are ignored.

Argument	Description
URL	The URL to retrieve and display in the new window.
NAME	Name of the new window. If given, the new window can be addressed from other windows documents by using the HTML `TARGET` attribute.
RELOAD	When set, the specified URL will be reloaded even if it is still in the cache.
POST	The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET). See the OPEN command description for a note about POST messages
SMART	When set, the URL string will be handled in exactly the same way as if it was typed into the URL gadget. That is, the `http://` scheme is prepended if no scheme is given, and (if enabled and appropriate) autosearch is used. When SMART is set, the RELOAD and POST arguments are ignored.

OPEN

Template:


   OPEN URL/A,TARGET/K,RELOAD/S,POST/K,SMART/S

Retrieve the specified document and show it in the addressed window or in the specified frame.

Argument Description
URL The URL to retrieve and display.
TARGET The target name of the window or frame to display the new document in.
RELOAD When set, the specified URL will be reloaded even if it is still in the cache.
POST The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET).
SMART When set, the URL string will be handled in exactly the same way as if it was typed into the URL gadget. That is, the http:// scheme is prepended if no scheme is given, and (if enabled and appropriate) autosearch is used.
When SMART is set, the RELOAD and POST arguments are ignored.
Note about POST messages:
The message is posted exactly as it was supplied, so you must supply it in "form-urlencoded" format. In short, this means:

Argument	Description
URL	The URL to retrieve and display.
TARGET	The target name of the window or frame to display the new document in.
RELOAD	When set, the specified URL will be reloaded even if it is still in the cache.
POST	The message to post. If this parameter is specified the document will be retrieved with the POST method (instead of the usual GET).
SMART	When set, the URL string will be handled in exactly the same way as if it was typed into the URL gadget. That is, the `http://` scheme is prepended if no scheme is given, and (if enabled and appropriate) autosearch is used. When SMART is set, the RELOAD and POST arguments are ignored.

Name and value of form fields must be separated by =
Different form field name=value pairs must be separated by &
All spaces must be replaced by +
All other non-alphanumeric characters in field names and values must be replaced by a %XX sequence, where XX is the hexadecimal representation of the character.

You can use the URLENCODE command to perform the last two encodings.

OPENREQ

Template:


   OPENREQ FILE/S

Displays a requester for the URL to open in the addressed window, or a file requester for a file to load. This command does not wait until the requester is closed.

Argument Description
FILE If this switch is set, a file requester is displayed. The selected file will be loaded in the addressed window.
If not set, a requester is displayed prompting for an URL to load.

Argument	Description
FILE	If this switch is set, a file requester is displayed. The selected file will be loaded in the addressed window. If not set, a requester is displayed prompting for an URL to load.

RELOAD

Template:


   RELOAD TARGET/K,IMAGES/S

Reload the current document, or all the embedded images, in the addressed window or in the specified frame.

Argument Description
TARGET The target name of the window or frame to limit the reload operation to.
IMAGES When set, all embedded images in the document are reloaded.
When not set, the document itself is reloaded.

Argument	Description
TARGET	The target name of the window or frame to limit the reload operation to.
IMAGES	When set, all embedded images in the document are reloaded. When not set, the document itself is reloaded.

RESETFRAME

Template:


   RESETFRAME TARGET/K

Resets all frames contained in the addressed window or in the specified frame to their original sizes. Note that the size of the addressed frame itself is not restored.

Argument Description
TARGET The target name of the window or frame in which the frame sizes should be restored.

Argument	Description
TARGET	The target name of the window or frame in which the frame sizes should be restored.

SAVEAS

Template:


   SAVEAS NAME,APPEND/S,TARGET/K,NOICON/S

Save the source of the current document in the addressed window or in the specified frame.

Argument Description
NAME When given, the source is saved under this name.
When not given, a save requester will pop up.
APPEND When set, the saved source is appended to the file specified in the NAME argument.
When not set, and the NAME argument is given, the specified file will be overwritten.
TARGET The target name of the window or frame for which the source should be saved.
NOICON Prevent AWeb from creating an icon for the saved file.

Argument	Description
NAME	When given, the source is saved under this name. When not given, a save requester will pop up.
APPEND	When set, the saved source is appended to the file specified in the NAME argument. When not set, and the NAME argument is given, the specified file will be overwritten.
TARGET	The target name of the window or frame for which the source should be saved.
NOICON	Prevent AWeb from creating an icon for the saved file.

SAVEIFF

Template:


   SAVEIFF NAME,NOICON/S,WAIT/S

Save the current window contents as an IFF image file.

Argument Description
NAME The name of the file to save. If no name is given, a file requester will be opened prompting for the name.
NOICON If this switch is set, no icon will be saved for the file.
WAIT If set, this command will not return until the save operation has been completed.

Argument	Description
NAME	The name of the file to save. If no name is given, a file requester will be opened prompting for the name.
NOICON	If this switch is set, no icon will be saved for the file.
WAIT	If set, this command will not return until the save operation has been completed.

SCROLL

Template:


   SCROLL N/N,PAGE/S,FAR/S,UP/S,DOWN/S,LEFT/S,RIGHT/S,TARGET/K

Scroll the contents of the addressed window, or the specified frame.

Argument Description
N A number specifying the number of pixels to scroll. Default value is 1.
PAGE When set, the N argument will be treated as the number of pages rather than a number of pixels.
FAR When set, the contents will be scrolled to the extreme position in the given direction.
UP Move the visible area towards the top of the document.
DOWN Move the visible area towards the bottom of the document.
LEFT Move the visible area towards the left edge of the document.
RIGHT Move the visible area towards the right edge of the document.
TARGET The target name of the window or frame to scroll.
The UP and DOWN arguments are mutually exclusive. The LEFT and RIGHT arguments are mutually exclusive. At least one direction must be specified.

Argument	Description
N	A number specifying the number of pixels to scroll. Default value is 1.
PAGE	When set, the N argument will be treated as the number of pages rather than a number of pixels.
FAR	When set, the contents will be scrolled to the extreme position in the given direction.
UP	Move the visible area towards the top of the document.
DOWN	Move the visible area towards the bottom of the document.
LEFT	Move the visible area towards the left edge of the document.
RIGHT	Move the visible area towards the right edge of the document.
TARGET	The target name of the window or frame to scroll.

STATUSFIELD

Template:


   STATUSFIELD SET/A

Show a new text in this windows status field.

Argument Description
SET A new value to display in the status field.

Argument	Description
SET	A new value to display in the status field.

URLFIELD

Template:


   URLFIELD ACTIVATE/S,POS/K/N,SET/K,PASTE/S

Activate the URL field in the browser window, or set it to a value.

Argument Description
ACTIVATE Activate the URL field. This will only work if the window itself is the active window.
The cursor is positioned after the last character, unless you specify a position with the POS argument.
POS Specify a new location for the cursor (the first character is counted as 1).
SET A new value to load in the URL gadget.
PASTE If this switch is set, the new value for the URL gadget will be loaded from the clipboard.
The SET and PASTE arguments are mutually exclusive.

Argument	Description
ACTIVATE	Activate the URL field. This will only work if the window itself is the active window. The cursor is positioned after the last character, unless you specify a position with the POS argument.
POS	Specify a new location for the cursor (the first character is counted as 1).
SET	A new value to load in the URL gadget.
PASTE	If this switch is set, the new value for the URL gadget will be loaded from the clipboard.

WAIT

Template:


   WAIT URL,DOC=DOCUMENT/S,IMG=IMAGES/S,ALL/S

Wait until the specified transfers are completed.

Argument Description
URL When specified, the command will wait until the transfer for this URL is completed. If no transfer is running for this URL, the command will return immediately.
DOCUMENT When set, the command will wait only for document transfers. In this context, everything loaded directly at the top level in a window or frame is considered to be a document, even if it is an image or a sound file.
IMAGES When set, the command will wait only for embedded image transfers. In this context, everything loaded because it is embedded in a HTML document is considered to be an image. This includes background sounds.
ALL When set, the command will wait for transfers in all windows.
When not set, the command will only wait for transfers in the addressed window and its subordinate frames.

Argument	Description
URL	When specified, the command will wait until the transfer for this URL is completed. If no transfer is running for this URL, the command will return immediately.
DOCUMENT	When set, the command will wait only for document transfers. In this context, everything loaded directly at the top level in a window or frame is considered to be a document, even if it is an image or a sound file.
IMAGES	When set, the command will wait only for embedded image transfers. In this context, everything loaded because it is embedded in a HTML document is considered to be an image. This includes background sounds.
ALL	When set, the command will wait for transfers in all windows. When not set, the command will only wait for transfers in the addressed window and its subordinate frames.

WINDOW

Template:


   WINDOW RECT/K,ACTIVATE/S,TOFRONT/S,TOBACK/S,ZIP/S,NEXT/K/N

Change the location or size of the addressed window, or the next or previous window.

Argument Description
RECT A rectangle describing the new location and size of the window.
ACTIVATE When set, makes the window the active window.
TOFRONT When set, moves the window to the front of all other windows on the screen.
TOBACK When set, moves the window to the back of all other windows on the screen.
ZIP When set, toggles between the zoomed and unzoomed state of the window, as if the user clicked the zoom gadget.
NEXT If this is a positive number, the actions will be applied to the next window counting from the addressed window. If this is a negative number, the actions will be applied to the previous window.
If not given (or zero), the actions are applied to the addressed window.
The TOFRONT and TOBACK arguments are mutually exclusive.

Argument	Description
RECT	A rectangle describing the new location and size of the window.
ACTIVATE	When set, makes the window the active window.
TOFRONT	When set, moves the window to the front of all other windows on the screen.
TOBACK	When set, moves the window to the back of all other windows on the screen.
ZIP	When set, toggles between the zoomed and unzoomed state of the window, as if the user clicked the zoom gadget.
NEXT	If this is a positive number, the actions will be applied to the next window counting from the addressed window. If this is a negative number, the actions will be applied to the previous window. If not given (or zero), the actions are applied to the addressed window.