SCI Programming Language/Data Types and Variables

Official SCI Documentation

Chapter: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | Index

Data Types and Variables
Author: Jeff Stephenson

 

Page 9

Numbers

All numbers in SCI are 16 bit integers with a range of -32768 to +32767. Numbers may be written as decimal (1024), hex ($400), or binary (%10000000000).

Variables

Variables hold numbers. Variables can be either global, local, or temporary, depending on when they are created and destroyed. The maximum variable name length is 2047 characters. SCI variables are case sensitive (i.e.: MyVariable!= myVARIABLE). A variable cannot begin with a number or a special character: # () , . @ [ ] ` " { - nul ^| ^J ^M space.

Local variables are created when a script is loaded and destroyed when it is purged. They are only available while the script is in memory and will not retain a value through a purge-reload cycle. Local variables may also be assigned an optional value at the time of definition (as in the following example: firstVar is assigned the value of 4).

Local variables may be single variables:

Code:

(local
   firstVar      = 4
   secondVar
   thirdVar
      ...
)

or defined as arrays. When defining an array, you have the option of assigning a value to the first element of the array only (the succeeding elements must be assigned their values in additional statements). Note that the brackets surrounding the array definitions do not mean "optional." They are required. Also note that the first element of an array is designated as element 0, the second as element 1, etc. In the following, firstArray is defined to have 10 elements (0 -9), the first element of which is assigned the value of 2:

Code:

(local
   [firstArray 10]      = 2
   [secondArray 5]
   [thirdArray 3]
      ...
)

Use the statement:

[myArray n]

to access element n of myArray. To access the fourth element of firstArray (the ten element array from the above example), write:

[firstArray 3]

Since each file may have only one local statement, that statement must include all the local variables used in that file. Therefore, the statement may contain both single and multiple (array) definitions:

Page 10

Code:

(local
   [firstVar 5]
   secondVar
   thirdVar
   [fourthVar 3]
      ...
)

Despite the syntactic difference between single variable and local array declarations, SCI really makes no distinction between them. Think of the local declaration statement as a single array containing all the variables (including array elements) listed consecutively. Any variable may be accessed as an element of this "super-array," using any other variable as an index into the array. To clarify this concept, consider the following statement:

Code:

(local
   var1
   var2
   var3
   var4
)

Although these are all single variables, they are considered by SCI to be elements of a four element "super-array." Thus, the value of var1 can be set to that of var4 by any of the following statements:

(= var1 var4) (= var1 [var2 2]) (= var1 [var3 1]) (= [var2 -1] [var1 3])

The first method is obviously the preferred method for clarity, but this array property of all variables allows access to variable numbers of parameters in a procedure (see section on procedures).

Global variables live for the duration of the entire game and are accessible to all scripts at all times. Thus they must be defined at the start of the game, either in room 0 or in a header file included by room O. The definition of a global variable includes its name followed by a unique index number to be used by the table of global variables. An optional value assignment is also permitted. In this example, firstVar has the index number 0 and contains the value 7:

Code:

(global
   firstVar  0      = 7
   secondVar 1
   thirdVar  2      = 20
      ...
)

The syntax for a global array differs slightly from that of a local array, though the philosophy of consecutive elements remains the same. To declare a global variable, leave an array-sized gap in the numbering sequence. In the following, var2 is defined as a global array of 10 elements:

Page 11

Code:

(global
   varl	23
   var2	24
   var3	34
)

To access the seventh element of var2, write:

[var2 6]

Temporary variables are created when a procedure or method is entered and destroyed when it is left. Therefore they are only available to the declaring procedure and do not retain a value between calls to that procedure. Temporary variables are defined using the symbol &tmp. The discussion on temporary variables will be continued in the section on user-defined procedures.

Text

Text strings are strings of characters enclosed in double quotes, and may be used anywhere you like. Note that the older notation enclosed text within curly braces; this notation may still be seen in some code modules.

(Prints "This is immediate text.")

prints the text string within the quotes.

(= textToPrint "This text is referenced through a variable.")

sets the variable to the pointer to the text string. A text string may also be defined as the name property of an object (this concept will be clarified in the appendix on object-oriented programming).

When SCI goes to squirrel a text string away, it first checks to see if it has seen the string before. If so, it just uses the previous text, rather than duplicating it in another location. If you are using the same lengthy text string in several places, it is possible that you will not type the identical string in each case. Therefore, you can save yourself some trouble (and some memory) by putting the text into a define statement:

(define lotsOfText "This is a long text string. I am using a define statement to avoid having to type it repeatedly.")

This introduces another aspect of text strings. If text is too long fit on a single line, you may enter it on several lines. Multiple white-spaces (spaces, tabs, and new lines) get converted to a single space, so the text above ends up with just one space between the words on each line. If you want multiple spaces, enter them as underscores (_). These are converted to spaces in the string and are not compacted.

To include an underscore in the text, type \_ where \ (backslash) is the escape character. Explicit new lines (line feeds without carriage returns) are entered as \n (as they are in C). A CR/LF (carriage return/line feed) pair is entered as \r. Note that the \r should be used in place of \n in all strings destined for a file. Characters which are not on the keyboard, but are defined in a font can be included in a text string by preceding the character's two-digit hex value with the \. For example:

(Prints "This is the Sierra symbol: \01")

Page 12

would put the value 1 at the end of the string, and this character in the default font is the Sierra symbol.

The maximum length of a text string is 2047 bytes.

Characters

Characters are single ASCII characters, denoted by preceding the character with a reverse single quote (or tick). For example:

'A represents uppercase A '? represents the question mark

Several character sequences represent special key combinations:

'^a represents ctrl-A '@b represents alt-B '#4 represents the F4 key

Literal selectors

Selectors represent methods or properties (and will be further defined in the appendix on object-oriented programming). Placing a pound sign (#) in front of the selector will return the numeric value for use as a parameter. In the following example, the value of the selector showSelf is passed as a parameter to the method eachElementDo:

(cast eachElementDo: #showSelf)

Literal selectors are commonly used by Collection objects to pass a selector to each of their elements in turn.

Page 13

Files

Source files for the script compiler traditionally have the extension .sc. Header (include) files traditionally have the extension .sh. Message editor header files traditionally have the extension .shm. Source files may have any filename; two examples are banner.sc and castle.sc. The two output files from the compilation will have the names number.scr and number.hep where number is the script# (defined below) of the module. Following are other files (besides the source file and any user-defined header files) which are involved in a compilation.

classdef This file contains the information about the structure of the classes which have been defined in the application. It is read automatically by the compiler and is rewritten by the compiler after a successful compilation in order to keep it up to date.

selector This file contains definitions of selectors which are used in object-oriented programming. It is automatically included in a compile and, like classdef, is rewritten after a successful compile. Any symbol in a properties or methods statement or in the selector position in a send to an object is assumed to be a selector and is assigned a selector number included in selector.

system.sh This contains the definitions for interfacing with the various system classes and procedures. It also contains the system global variable definitions and defines for keycodes, script numbers, etc. It is automatically included in all compiles.

kernel.sh This contains the definitions for interfacing with the kernel.

game.sh This is the game-specific header file. It contains global variables, procedure declarations, and definitions for an individual game. It is automatically included in the compile after system.sh.

classes.txt This is a text file produced by the compiler that is used by a BRIEF macro to browse the SCI class system.

offsets.txt This is a text file that contains a list of class-selector pairs for frequently used properties. It is used by the compiler to produce 994.voc.

994.voc For each class-selector pair in offsets.txt, the compiler writes an entry to this file containing the offset of that property in an SCI object. With this information, the interpreter can access a frequently used property without going through the message-passing mechanism. It is generated by the compiler when the -0 command line parameter is used.

996.voc This is the class table. It specifies the number of the script files that contain each class.

997.voc This file contains the names of selectors. It is only used by the debugger and in printing error messages.

Page 25

$$$sc.lck This read-only file serves as a semaphore, indicating that a compile is occurring in the current directory. This prevents two compiles from trying to do the same task concurrently (updating the same classdef, for instance). $$$sc.lck is created at the beginning of a compile and deleted at the end.

The following two SCI commands deal with source code organization:

script# The script# command sets the script number of the output file.

(script# 4)

sets the output file names to 4.scr and 4.hep, regardless of the actual name of the source file.

include

This includes a header file in the current source file at the current position.

(include "/sc/foo.sh") or (include /sc/foo.sh)

includes the file /sc/foo.sh. Include files may be nested as deeply as desired.

When compiling or including a file, the compiler first looks in the current directory. If it fails to find it there, it next looks for the file in the directories specified in the environment variable sinclude. This variable is just like the DOS path variable. The search directories are separated by semicolons. To set the compiler to look for include files in f:/games/scilsystem and c:/include if it doesn't find them in the current directory, add the line:

set sinclude=f:/games/sci/system;c:/include

to your autoexec.bat file.

Page 26

Compiling SCI Code

The SCI compiler is invoked with the command:

sc filel [file2] [file3] [options]

Any number of file specifications may be entered on the command line, and a file specification may include wild-card names.

Options

-a Abort compile if the file is already locked.

-d Include debugging information so that the debugger can display source code.

-D<str> Create a command line define which has the same result as using the define statement in a source file (except that spaces and some other characters are not permitted).

-g<num> Define maximum number of global or local variables. The default is 750.

-I Generate an assembly language code listing for the file with the original source interspersed. This is useful when using the built-in debugger of SCI. When compiling filename.sc, the list file is named filename.sl.

-n Turns off "auto-naming" of objects. As described in the appendix on object-oriented programming, each object has a name property which is used to represent the object textually. Unless the property is explicitly set, the compiler will generate the value for this property automatically, using the object's symbol string for the name. The object names, however, take up space. While they are useful (almost vital) for debugging, if you're running out of memory in a room, it might help to compile with the -n option to leave the names out.

-O Use offset.txt to generate 994.voc.

-oout-dir Set the directory for the output files to out-dir.

-s Display a message when a forward referenced selector is used.

-v Do not lock the class database.

-w Output words high-byte first (for the Macintosh).

-z Turn off optimization. Not a particularly useful option except for those of us who must maintain the compiler.