Objectives

In this session, you will learn the following:

1. Difference between a script file and a function file
2. Writing a script file
3. Developing a simple function to calculate the length of a line segment

Introduction

Script files are comparable to shell scripts in *nix and batch files in Windows. They are executable files containing statements that are valid Scilab commands. It is simply the non-interactive version of the interactive sessions with Scilab that we are used to up to now. Thus, when you need to type a series of Scilab commands one after the other, not just once, but a number of times, then the best way to do it is to put all those Scilab commands in a text file with a .sce extension and ask Scilab to execute the commands in that file.

On the other hand, a function file is intended to be modular in the sense that it takes certain input, processes that input and generates certain output. Thus, the main difference is the thought that goes into:

1. Identifying what the function is expected to do,
2. What input should the function take,
3. What output should the function generate, and
4. What steps (algorithm) and commands are required to process the input in order to generate the required output

Once a function is properly designed, it can then be treated as a black box, focus mainly on what input to give and what output to expect and forget the details of how it is implemented.

Therfeore, the main difference is the way script files and functions exchange data with Scilab. Whatever input data a script file accesses is taken from Scilab workspace. Whatever data a script file outputs is put into Scilab workspace. The semantics of input data, local variables being visible only within the function and output variables being handed to the parent function is not applicable to a script file.

Writing a Script File

The rules for writing a script file are as follows:

1. Script file must contain only valid Scilab statements,
2. The first word in the script file must not be the keyword function,
3. Script file must be text file (typically with the extension .sce)

To execute a script file, one of the following methods can be used:

1. From the main menu, choose File -> Execute. This opens a dialog box. Pick the script file and press OK to execute the script file
2. Use the command exec(). To execute a script file test.sce, located in the current working directory, the command is
   -->exec('test.sce')
   Knowing about current working directory (Session 3) is important.
3. From the main menu choose File -> Open. This opens a dialog box. Pick the script file and press OK to open the script file in SciNotes, the built-in code editor. From the main menu of SciNotes, choose Execute -> ... file with echo or Execute -> ... file with no echo.

Remember that statements in a script file are executed by Scilab as if they were typed interactively at the Scilab prompt.

Let us write a script file to calculate the length of a line segment connecting the points P1 with coordiantes (x1, y1, z1) and P2 with coordinates (x2, y2, z2). Start Scilab, from the main menu choose Applications -> SciNotes. This will open the SciNotes source code editor. In a new file, type the following Scilab statements:

p1 = [0, 0, 0];
p2 = [3, 4, 5];
delta = p2 - p1
L = sqrt(sum(delta.^2))

Save this file as len1.sce in a different directory of your choice. Take care to note the filename and directory in order to access this file later. Then execute it from inside SciNotes from the main menu Execute -> ... file with echo. The lines from the file will be executed and you will see the results of these statements, anmely:

-->p1 = [0, 0, 0]
 p1  =
    0.   0.   0.
-->p2 = [3, 4, 5]
 p2  =
    3.   4.   5.
 delta = 
    3.   4.   5.
 L  =
    7.0710678

Developing a Function

We will develop a function based on the above calculation. The specifications of the function are:

1. Purpose: Function calculates the length of a line segment joining two points in 3D space with specified coordinates.
2. Name of the function: len. Note: There is a function named length() already in use by Scilab.
3. Input: Coordinates of the two end points. Coordinates of each point are in the form of 1x3 row vector.
4. Output: Length of the line segment

The skeleton of a typical Scilab function is as follows:

function [output1, output2, ...] = function_name(input1, input2, ...)
  statement_1
  statement_2
  ...
  statement_n
endfunction

Note the following:

1. Scilab keywords: function and endfunction are Scilab keywords indicating the start and end of a function
2. function_name is the name of the function chosen by the programmer
3. Input arguments are listed after the function name, within parentheses and separated by commas. A function can have zero or more number of input arguments
4. Output arguments are listed to the left of the assignment operator, within square brackets and separated by commas. A function can have one or more output arguments.
5. If a variable appears both in the list of input as well as output arguments, it means that its value can be used by the function as well as its altered value is returned to the parent function
6. A function can have any numbr of statements within its body

Here is our function to calculate the length of the line segment in 3D space:

function [L] = len(p1, p2)
  delta = p2 - p1;
  L = sqrt(sum(delta .^2))
endfunction

Save this in a file (note down its name and directory) and load the function into Scilab workspace (Execute -> ... file with echo). Check that it is loaded into Scilab workspace using the whos -type function command (See Session 3 for details). Once the function is loaded into Scilab workspace, it is available for use, in the same way as Scilab functions are available for use. The difference is, it may be necessary to explicitly load it into Scilab workspace before it is available for use. This is how you could use the function:

-->L1 = len([0 0 0], [3 4 5])
 L1  =
   7.0710678
-->p1 = [0 0 0]; p2 = [3 4 5]; L2 = len(p1, p2)
 L2  =
   7.0710678