13.2 REBOL

13.2.1 Introduction

REBOL is the Relative Expression-Based Object Language designed by Carl Sassenrath, the software architect responsible for the Amiga OS -- one of the world's first personal computer multitasking operating systems.

REBOL is the next generation of distributed communications. REBOL code and data can span more than 40 platforms without modification using ten built-in Internet protocols. A script written and executed on a Windows platform can also be run on a UNIX platform with no changes. REBOL can exchange not only traditional files and text, but also graphical user interface content and domain specific dialects that communicate specific meaning between systems. Distributed communications includes information exchanged between computers, between people and computers, and between people. REBOL can be used for all of these.

REBOL is a messaging language that provides a broad range of practical solutions to the daily challenges of Internet computing. REBOL/Core is the foundation for al of REBOL’s technology. While designed to be simple and productive for novices, the language extends a new dimension of power to professionals. REBOL offers a new approach to the exchange and interpretation of network-based information over a wide variety of computing platforms.

REBOL scripts are as easy to write as HTML or shell scripts. A script can be a single line or an entire application.

(from REBOL/core User Guide, Copyright © 2000 REBOL Technologies)

PowerNet plug-in includes an interface to manage REBOL scripts. By these scripts, you can control the VEGA ZZ functions in order to automate the most common and repetitive operations.

13.2.2 How to create a simple REBOL script

This manual isn't a full exhaustive REBOL guide and for a complete description of this language, it's recommended the original documentation available at REBOL Technologies Web site.
PowerNet offers a set of REBOL functions in order to simplify the access to the VEGA ZZ TCP/IP port and they are included in  ...\VEGA ZZ\Scripts\Common\Vega.r file.
As first step, to create a REBOL script, you must add the script header:

REBOL [
  Title: "My first REBOL script"
  Date: 2-Feb-2000
  File: %test.r
  Author:  "My name"
  Version: 1.0.0
]

All keywords are optional. As second step, you must include the file with the predefined functions to interface REBOL to VEGA ZZ/PowerNet:

do %Common\Vega.r

You must remember to specify the path of Vega.r file in relation to the location where the script file is placed. In the present example, the file test.r must be placed in Script directory.
To activate the communication, you must use the VegaOpen function:

VegaOpen VegaDefHost VegaDefPort VegaDefUser VegaDefPass

VegaDefHost, VegaDefPort, VegaDefUser and VegaDefPass are special variables initialized by VEGA ZZ when it runs the script. They include the default values of host IP, host port, user name and password (see below).
Now the port is open and you can send commands by VegaCmd function:

VegaCmd {Open "..\Examples\Molecules\a3.msf"}

This command opens a3.msf file placed in the Molecules folder. The brackets ({ }) are string delimiters that allow the use of the " as  character and not as delimiter. Open is a VEGA ZZ extended command (click here for more information).
If you want to obtain a value of a VEGA ZZ environment variable, you must use Get or PluginGet command and the value is copied to VegaRes REBOL variable:

VegaCmd "Get TotAtm"
print VegaRes

The first line obtains the value of TotAtm variable (it's the total number of atoms), and the second one prints it to REBOL console (not to VEGA ZZ console). If you want to print the result to VEGA ZZ console, you must use Text command:

VegaCmd rejoin[{Text "Loaded atoms: } VegaRes {" 1}] 

The REBOL rejoin function join more strings together, creating a whole string that's the argument of VegaCmd function. For more information, consult the REBOL/Core user guide.
The script must end calling VegaClose function:

VegaClose

It closes the communication port and frees it for other applications. To run the script directly from VEGA ZZ, you must select File Run script in main menu as explained in PowerNet script section.

13.2.3 The REBOL functions included in Vega.r file

This section explains more in details the interface functions included in Scripts\Common\Vega.r file:

VegaClose
Close the communication port and free it.

Parameters:
None

Return values:
None.

Example:
VegaClose

VegaCmd   Command
Send a command to VEGA ZZ in synchronous mode.

Return values:
If an error occurs, this command returns the standard VEGA ZZ error code, otherwise it returns 0. The error code is also copied to VegaErrCode variable and the error description to VegaErrStr variable.  If the sent command returns a value, it's copied to VegaRes variable.

Example:
VegaCmd   "mOpen"

VegaGet   VariableName
Retrieve a system variable from VEGA ZZ.

Return values:
This command returns the value of the VEGA ZZ variable.

Example:
VegaPrint   join   "Number of atoms: "   VegaGet   "TotAtm"

VegaOpen   Host   Port   User   Password
Connect the REBOL interpreter to the VEGA ZZ TCP/IP port.

Return values:
None. If it fails, the execution of the script is halted and an error message is shown.

Example:
VegaOpen   127.0.0.1   2000   "MyUserName"   "MyPassword"

VegaPrint   Message
Print a string message to VEGA ZZ console.

Return values:
None.

Example:
VegaPrint   "Hello World !"

13.2.4 Notes

• Each VEGA ZZ session can run only one scripts at once.

• If the PowerNet plug-in isn't installed, REBOL scripts can't work.

• If the PowerNet telnet service is disabled, the scripts can't connect to VEGA ZZ port and thus they can't work. To enable it, see the PowerNet documentation.

• If the PowerNet remote access is disabled, the VEGA ZZ host can't be controlled by remote clients,

• Changing the VegaOpen parameters you can run a script on a PC that controls a remote VEGA ZZ host.

• VegaDefHost, VegaDefPort, VegaDefUser and VegaDefPass are valid for local connections only.