Corel SCRIPT structure

A simple Corel SCRIPT executes in a linear manner. Each statement is executed line by line up to the last script statement. If you have a group of instructions that will be executed in different parts of your script, you can write a subroutine containing these instructions. The instructions are written once in the script, and can be called from different places within the script. If the instructions are changed, the changes take effect everywhere. Using these user-defined subroutines can make your scripts easier to change and debug as well as decrease the script length.

Each Corel SCRIPT is comprised of three types of procedures:

main section of a script (one per script)
user-defined functions (optional and more than one can exist)
user-defined subroutines (optional and more than one can exist)

Functions and subroutines are groups of Corel SCRIPT statements that are executed when the procedure is called by another Corel SCRIPT statement. Both types of procedures are useful in cases where a group of instructions will be repeated. The instructions are written once in the script, and can be called from different places within the script or with different parameters. You can have more than one of each type of procedure in a script.

Although, user-defined subroutines and functions are both Corel SCRIPT procedures that execute instructions, functions can also be used to return values to a script that can be either assigned to a variable or compared with other expressions.

Subroutines begin with the word SUB which is followed by the subroutine name you give to identify the subroutine and call later. A subroutine cannot be executed unless it is called. To call a subroutine just specify its name in the place the subroutine must be executed. You can use CALL subroutine_name statement but CALL is optional. Each subroutine must end with the words END SUB:

SUB MySubroutine
  YourName$=INPUTBOX("Enter your name:")
  MESSAGE "Hello, "+YourName$+"!"
END SUB

This subroutine asks you for your name and then greets you. To use the subroutine you can use the following statements:

CALL MySubroutine

or simply

MySubroutine

Each time you use a subroutine name it is substituted with the subroutine body (a list of statements between SUB and END SUB words).

MESSAGE "Before 1st call"
MySubroutine
MESSAGE "After 1st call"
MESSAGE "Before 2nd call"
MySubroutine
MESSAGE "After 2nd call"

When executing the above scripts is actually the following:

MESSAGE "Before 1st call"
  YourName$=INPUTBOX("Enter your name:")
  MESSAGE "Hello, "+YourName$+"!"
MESSAGE "After 1st call"
MESSAGE "Before 2nd call"
  YourName$=INPUTBOX("Enter your name:")
  MESSAGE "Hello, "+YourName$+"!"
MESSAGE "After 2nd call"

You can take an advantage of using subroutines even if some parts of your script is not identical but very similar. For example, there are 10 loops in your script that do exactly the same but different number of times. In this case you can place the entire loop in a subroutine that takes the number of cycles as its parameter. A parameter is a value (usually a number but can by of any type including String, Boolean, etc.) that is passed to the subroutine body and can be used in it. In our case, the parameter is a number of repetitions of the loop body.

To define a subroutine that takes one or more parameters, use the following declaration:

SUB subroutine_name(parameter₁ AS type₁, parameter₂ AS type₂,...)
  Subroutine body
END SUB

where parameter₁, parameter₂, etc. are the name of parameters given to identify them later in the subroutine body. These names are used just as ordinary variables in a subroutine. As for variables, a parameter must be declared first to let CorelSCRIPT know its type. This will allow CorelSCRIPT to reserve a sufficient amount of computer memory to store the parameter's value and to check the script syntax just in case you specify a parameter of wrong type.

Calling statement consists of a subroutine name followed by a list of parameters. Please note, that in CorelSCRIPT version 6 you have to enclose the parameter list with parentheses but in version 7 it just follow the subroutine name with no parentheses at all:

CorelSCRIPT version 6 usage:	CorelSCRIPT version 7/8 usage:
CALL MySub(parameter₁, parameter₂, ...)	CALL MySub parameter₁, parameter₂, ...

A subroutine must be defined before it is called for the first time. If this is not convenient for you, you should use a subroutine prototype - only the words DECLARE SUB followed by the subroutine name and a list of parameters without the body and END SUB statement. This only declares the subroutine and make it possible for CorelSCRIPT to know the exact number of parameters required by the subroutine and their types. For example:

REM ======== the prototype =======
DECLARE SUB MyLoop(Number AS integer)

REM === main section of a script ======
MyLoop 3 ' Here the number 3 is passed to the subroutine as a parameter
MyLoop 5+2 ' The expression 5+2 is evaluated to be 7 and this value
            ' is passed to the subroutine

REM === Subroutine definition =======
SUB MyLoop(Number as integer)
  FOR i%=1 to Number
    Message i
  NEXT i
END SUB

Note the specific usage of MESSAGE command in the above example. When its parameter is a string, the string is displayed in a message window. But when the parameter is a numeric expression, MESSAGE displays its value.

You can use a type character to specify a parameter type rather than use AS type statement:

SUB MySub(i%,t&)

is equivalent to

SUB MySub(i as integer, t as long)

Here is one more short example of using a subroutine. It prompts the user for password and doesn't let him to work until he enters the correct one.

'====== Subroutine declaration (protorype)=======
DECLARE SUB EnterPassword(Password as string)

'===== Main Section =========
EnterPassword("secret")
Message "Welcome to the top secret script!!!"

'========= Subroutine ==========
SUB EnterPassword(Password as string)
retry:
	pass$=INPUTBOX("Enter the password:")
	IF pass<>Password then 
		Message "Access denied. Please retry"
		goto retry
	ENDIF
END SUB

In this example the subroutine EnterPassword is declared. It takes the password as a parameter and asks the user to enter the exact string that is equal to that passed to the subroutine. This is useful when you want to protect with password several parts in your script - for example one password on entering the system, one for openning your private document etc. Each call to EnterPassword will ask the user for the password and the execution will not proceed until he enters the correct one:

'====== Here we enter the script =====
EnterPassword("secret")
'
' some actions
'
'====== We are about to open a document ====
EnterPassword("pandora")
'
' continue execution
'

You can modify EnterPassword subroutine using loops in order to avoid labels and GOTO statement:

SUB EnterPassword(Password as string)
  DO
	pass$=INPUTBOX("Enter the password:")
	IF pass<>Password then Message "Access denied. Please retry"
  LOOP WHILE pass<>Password
END SUB

Here, INPUTBOX asks for the password to be entered. The password entered is assigned to variable pass that is of string type (as specified by '$' character). If the password is not equal to that passed to the subroutine (variable Password), the message "Access denied. Please retry" is issued.

All the above actions are repeated until the user enters the correct password.

The last LOOP statement could be changed to

LOOP UNTIL pass=Password

with the same meaning.

There is one more class of procedures similar to subroutines - functions. A function is a subroutine that can return a value. For example, a subroutine that checks for the user password can notify the script whether the password entered is valid or not. If you use a function instead of the subroutine in the above example with passwords, you can build more 'intellectual' password checking system that could shut down script if the user failed to enter the correct password withing, say, three attempts.

A function is defined in the same way as a subroutine using the following syntax:

FUNCTION function_name AS function_type
	Function body
	function_name=return_vakue
END FUNCTION

or if the function requires some parameters:

FUNCTION function_name(Parameter₁ as type₁, Parameter₂ as type₂, ...) as function_type
	Function body
	function_name=return_vakue
END FUNCTION

Here function_type is a type of the result returned by function. Here is an example of a simple arithmetic function that multiplies two numbers:

FUNCTION Multiply(Number1 as integer, Number2 as integer) as integer
   Multiply=Number1*Number2
END FUNCTION

As you can see, to define the returned value you must simply assign it to the function name in the function body. This value can be used later anywhere in a script:

Message Multiply(5,7)+2

This will show a message window with the number 37 in it.

Don't forget to define a function before it is used or use a prototype to declare it prior to usage:

DECLARE FUNCTION Multiply(Number1 as integer, Number2 as integer) as integer

Now let's create a script that asks the user for the password and if the user fails to enter the correct one within three attempts, the script terminates:

'====== Function declaration (protorype)=======
DECLARE FUNCTION EnterPassword(Password as string) as boolean

'===== Main Section =========
if EnterPassword("secret") then
   Message "Welcome to the top secret script!!!"
else
   Message "Access denied"
   STOP
endif

'========= Function ==========
FUNCTION EnterPassword(Password as string) as boolean
  FOR i%=1 to 3
    pass$=INPUTBOX("Enter the password:")
    IF pass<>Password then
      Message "Wrong password. Please retry"
    else 
      EXIT FOR
    ENDIF
  NEXT i
  EnterPassword=(pass=password)
END SUB

In this example the function EnterPassword accepts the password required as a parameter and returns TRUE if the password entered is correct and FALSE otherwise. This return value can be used in conditional expressions for checking the password validity. For this purposes an IF...THEN...ELSE statement used. If the password was correctly entered, the THEN clause is executed showing a greeting message "Welcome to the top secret script!!!" but if it was not correct, the ELSE part of IF...THEN..ELSE statement is executed that results in the message "Access denied" and the script is terminated by STOP instruction.

The body of the function itself is a loop that repeats its body three times. As in previous examples, the password entered by the user is assigned to the variable pass. If it is not equal to Password, the message "Wrong password. Please retry" is issued and the loop continues at INPUTBOX again until the variable i becomes 3 (this variable is increased by 1 each loop cycle as was described on the previous page in Looping statements section).

If the password is correct, the loop is finished by EXIT FOR command. After exit from the loop (in either case) the function should return TRUE if the password entered is equal to that passed to the function and FALSE otherwise. This is achieved by assigning the result of comparison of the vatiable pass to password. The logical expression pass=password is evaluated to TRUE if the two variables are equal and FALSE otherwise, just the case needed in this example.

You can also use type characters (%, $, &, @, !) to declare the type of the function return value and function parameters. For example:

FUNCTION Funct(param as integer) as string

is equal to

FUNCTION Funct$(param%)

If a function doesn't require any parameters, it may be declared as follows:

FUNCTION s%

FUNCTION s%()

You may use parentheses or omit them in declaration, but they are mandatory when calling the function:

a%=2+s%()

What next?

On the next page you will learn about standard CorelSCRIPT functions and procedures.