* * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* SiMPLE *
* *
* Programmers Reference Manual *
* ---------------------------- *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * *
[In this document the generic term, "SiMPLE", refers to both
"Standard" SiMPLE and "Pro-SiMPLE" unless otherwise specified.]
This document is not intended to be a tutorial. It is merely a
reference manual for those users who already have some program-
ming experience and who would like to view a description of the
complete SiMPLE language.
_____________________________________________________________________________
SiMPLE Keywords
---------------
The SiMPLE language is defined by 23 keywords. They are:
And Break Call
Common Continue Display
Do Else End
Float (or Decimal) Float2 (or Decimal2) Goto
If Int (or Whole) Int2 (or Whole2)
Loop Or Return
Set Step Task
Text To
There are no reserved words in SiMPLE. However all keywords must begin with
a Capital Letter. The entire language is space insensitive. All spaces (ex-
cept for those enclosed between quotes and in AID comments) and blank lines
are stripped during the compilation operation.
A SiMPLE program is usually specified one statement per line. However,
multiple statements may be placed on a single line if they are separated by
a semicolon ( ; ) character.
In addition, it is possible to separate long statements so that they exist
on several separate lines. This is done by using the backslash ( \ ) char-
acter. When a backslash character appears as the last character on the
line, the very next line in the listing is assumed to be a continuation of
the line containing the backslash character. (However, the backslash must
NOT be embedded anywhere between a pair of quotation marks. Otherwise it
will be interpreted as being part of the text string.)
Comments
--------
Comments allow you to insert remarks about your program anywhere in the code.
A single comment is indicated by two consecutive slash characters ( // ).
SiMPLE ignores all characters to the right of the double slashes.
The sets of characters ( */ ) and ( */ ) are use to define a comment that
can span multiple lines.
Data Types
----------
All constants in a SiMPLE program exist as one of five data types:
1). Integer numbers are whole numbers without a decimal point. Since integer
numbers are stored as 2-byte quantities, integer numbers are confined to
the range -32768 through 32767.
2). Double precision integers are just like regular integers, except that
they are stored as 4-byte quantities.
3). Floating point numbers are numbers consisting of an exponent and
mantissa.
4). Double precision floating point numbers are just like regular floating
point numbers, except that they are stored as 8-byte quantities.
5). Text constants represent strings of ASCII characters. Text constants
are represented by a quote character ( " ) followed by any sequence of
characters, followed by an ending quote character ( " ). Text strings
are stored one character per byte and are automatically terminated by a
null character (binary zero).
If a backslash character appears inside of a string, the character following
the backslash is treated special. For example, to include a quote character
as part of a string, simply precede the quote character by a backslash. To
include a backslash character as part of a string, simply precede the back-
slash character with another backslash character. A backslash character fol-
lowed by the character 'n' imbeds a "carriage return/line feed" character in
the string.
Containers
----------
A container can be thought of as being similar to a memory location inside
the computer. Each container is capable of containing a single numerical
quantity, such as: 27, or 3.1416, or -10000, etc.
Each container is referenced by a name. This name can be any sequence of
lower case letters (a - z) and numbers (0 - 9). Additionally, the first
character in the name MUST be a letter. The number of characters in a name
can range from 1 to about 20 characters.
The name of each container must be unique. Two different containers in the
same program cannot have the same name, even if the two containers are of
different "types". (We will discuss type declarations shortly.)
Keyword: Set
------------
The "Set" keyword is used to indicate that information is to be stored into
a container. The general form for a statement which stores information into
a container is:
Set name = expression
where name is the name of the container, and expression is either a constant,
another container, or an arithmetic expression involving constants and/or
containers.
Each container must be associated with a "data type". The data type of a
container is determined by the data type of the first value which gets
stored into the container. Once the "type" is established, it remains in
effect for the duration of the program. For the numerical-type containers
(Int, Int2, Float, and Float2), if an attempt is made to store a different
type of numerical value into such a container the number will automatically
be converted into the type required by the container. (However attempting
to store either a numerical quantity into a Text container, or a Text string
into a numerical container, will produce a compiler error message.)
The use of the keyword "Set" is optional, except when used with a one-line
"If-statement" (which we will discuss later in this document).
Type Declarations
-----------------
Type declarations can be used to explicitly override the automatic typing
established by a "Set" statement. In addition, they are used to declare
dimensioned "arrays". (We will discuss arrays later.)
There are five keywords used to perform type declarations:
Int Int2 Float Float2 Text
(or, Whole) (or, Whole2) (or, Decimal) (or, Decimal2)
Type declarations can occur anywhere in a program, but it is customary to
place them at the beginning of the source listing ahead of any executable
code.
Keyword: Int
------------
The "Int" keyword is used to dimension and/or define storage for integer num-
bers.
Keyword: Int2
-------------
The "Int2" keyword is used to dimension and/or define storage for double
precision integer numbers.
Keyword: Float
--------------
The "Float" keyword is used to dimension and/or define storage for floating
point numbers.
Keyword: Float2
---------------
The "Float2" keyword is used to dimension and/or define storage for double
precision floating point numbers.
Keyword: Text
-------------
The "Text" keyword is used to dimension and/or define storage for ASCII
strings. Unlike the type declarations for numerical quantities (Int, Float,
etc.), text information is not stored as a pre-defined number of bytes.
Instead, text strings are stored one character per byte. So the number of
bytes needed is determined by the length of the text string. (A text string
can be up to 255 characters in length.)
Examples:
Int j, k, index
Float2 pi, total
Text line
Arrays
------
An array represents a group of containers, all of the same data type. An
array is specified by a name followed by one or more pairs of square
brackets ( [] ) containing the subscript(s). The rules for working with
arrays are consistent with (and determined by) the standard set by C++.
Before an array can be used it must first be "declared" at the beginning
of the source listing. The general form for declaring an array is:
type namea[size1][size2]...[sizen], nameb[sizep][sizeq]...[sizet], ...
where "type" is one of the type declaration keywords, and "size1", "size2".
etc. are numerical constants representing the number of "elements" (contain-
ers) in each dimension of the array.
Examples:
Float x[100], y[100]
Int chess[8][8]
Text names[20]
The first element of an array is referenced by the subscript 0 ("zero"), the
second element by the subscript 1 ("one"), etc. Therefore:
The maximum value that can be used as a subscript of an
array is one LESS than the corresponding number used in
declaring the size of the array.
Therefore, the array "x" (in the previous example) would have elements x[0],
x[1], ... x[99] only.
CAUTION: When using arrays, you must be extremely careful
not to specify subscripts that lie outside the
bounds of the array.
The elements of an array can be initialized by issuing a statement of the
form:
type name [size] = {value1, value2, ...}
[For simplicity we have shown an array with only a single subscript, but
the form can be extended to include multi-dimensional arrays as well.]
Optionally, initialization can also be formed without specifying the dimen-
sion of the array:
type name [ ] = {value1, value2, ...}
Arithmetic Operations
---------------------
Arithmetic Operations are indicated in the "standard" way (plus sign ( + )
means add, minus sign ( - ) means subtract, asterisk ( * ) means multiply,
and slash ( / ) means divide). In addition to these four standard opera-
tions, SiMPLE also provides the modulo operator ( % ) for computing "remain-
der after division", and the "raise to the power of" operator ( ^ ).
Expressions like:
Set name = numerical expression
mean "compute the numerical value of expression and store the result in the
container 'name'." In addition, parentheses can be used for grouping.
The rules for precedence of operations, mixing of data types, etc. are
consistent with (and determined by) the standard set by C++.
Text Operations
---------------
A text string is a sequence of characters enclosed between a pair of quotes.
(Example: "How now, brown cow.") Just as in the case of numerical data,
text strings can be stored into a container by using a "Set" statement.
Example: Set message = "I love SiMPLE"
The concatenation operation for strings is indicated by the plus sign ( + )
character. For example, the following program:
Set x = "abc"
Set y = x +"def"
Display y
would display:
abcdef
Note: Because of the unique way in which SiMPLE handles text strings, the
catination operation will NOT work as part of a task's (or function's)
calling parameters. For example, the program:
Set name = Keyin text ("Delete which file: ")
Call System ("del " + name)
will not compile. However, the program:
Set name = Keyin text ("Delete which file: ")
Set param = "del " + name
Call System (param)
WILL compile properly.
Display
-------
SiMPLE provides the "Display" keyword for displaying information on the CRT
screen. The general form of the "Display" statement is:
Display item1 , ... item2 , ...
where:
Display - a keyword
item1 - the first item to be displayed
, ... - one or more commas. (If n commas are present,
n - 1 spaces will appear between item1 and item2
when they are displayed.)
item2 - the second item1 to be displayed
, ... - one or more commas etc.
It is not necessary to specify any items following the keyword "Display".
If no items are specified, a blank line is produced.
If the "Display" statement ends with a comma following the last item to be
displayed, the automatic "carriage return-line feed" (cr-lf) is suppressed.
The "Display" keyword exists primarily as a convenience. Since all I/O can
be performed with tasks/functions, it is also possible to display information
on the screen by invoking the "Output" task in the system library. For ex-
ample, the following two statements are equivalent:
Display "Hello"
Call output ("Hello")
The "Output" task always issues an automatic cr-lf when only one calling
parameter is supplied. To suppress the cr-lf, simply include a second para-
meter (of type Int). This second parameter indicates how many spaces (on
the same line) are to follow the displayed information. For example, the
following program:
Set answer = 42
Call output ("The answer is", 1)
Call output (answer)
would display: The answer is 42
Generating Hard-copy Printouts
------------------------------
The current version of SiMPLE does not support direct access to a line-
printer. However it is easy to create an output text file which can then be
viewed/printed by using the text-editor program. Simply invoke the "Output-
mode" task (in the system library). All subsequent information transmitted
via the "Output" task can then be directed into a text file named "output" in
the current project.
For example, the following program:
Call output mode (2)
Set answer = 42
Call output ("The answer is", 1)
Call output (answer)
would create the local text file named "output" containing:
The answer is 42
To access the results, simply type:
edit output
from the command line.
Looping
-------
The statements of a SiMPLE program are executed in a top-down sequence.
Sometimes, however, it is desirable to redirect the flow of the program so
that certain groups of statements can be executed repeatedly. When this
happens, the program contains what is known as a "loop".
Except for "Goto"-loops, all loops in SiMPLE are defined by the keywords "Do"
and "Loop". There are two forms of "Do-Loops" in SiMPLE:
1). Uncontrolled Loops ("Infinite" Loops)
Do // Loop continues forever.
statement(s)
Loop
2). Controlled Loops
Do name = start To end Step increment
statement(s)
Loop name
where "To" and "Step" are keywords indicating the ending limit of the
loop's index ("name"), and the amount by which the index is to be in-
cremented each time through the loop.
In a controlled loop the index of the loop ("name") is first assigned the
value "start". If that value does not exceed the value specified by "end",
statement(s) are then executed. "Name" is then automatically incremented by
"increment". If "name" still does not exceed the value specified by "end",
the loop continues.
Example: Do radius = 5 To 125 Step 10
Call Circle (320, 240, radius)
Loop radius
If the keyword "Step" and its associated value, "increment", are omitted then
an increment of unity will be assumed. By unity we mean:
a) if the "start" value is less than the "end" value,
the increment will be +1.
b) if the "start" value is greater than the "end" value,
the increment will be -1.
The keywords, "To" and "Step", can both optionally be replaced by commas.
Also the loop's index ("name") can be optionally omitted from the "Loop"
statement. (Any information appearing to the right of the keyword "Loop"
is ignored.)
When defining a loop it is recommended that the statements contained in the
loop be indented several spaces in order to make the block structure of the
loop more readable. This is not a requirement but merely good programming
practice.
Example: Do k = 100, 5000
Call Sound (k)
Call Delay (2)
Loop
Keyword: Break
--------------
The "Break" keyword is used to prematurely terminate a loop. The "Break"
will transfer execution to the first statement immediately following the
"Loop" statement.
Keyword: Continue
-----------------
The "Continue" keyword is used to jump over all remaining statements in the
loop, and then begin the next pass, unless the loop would have terminated af-
ter the current pass. (You can think of the "Continue" statement as perform-
ing a "Goto" to the "Loop" statement.)
Logical Expressions
-------------------
A logical expression is a True or False statement about the relationship
between two entities. For example, one could say that "five is greater than
three". This would represent a True expression. However, a statement such
as "seven is less than four" would represent aa False expression. The
logical relationships (and the symbols used to define them in SiMPLE) are
given in the following list:
< "less than"
<= "less than or equal to"
= "equal to"
!= "not equal to"
>= "greater than or equal to"
> "greater than"
~ case insensitive "equal to" (for use
with text strings)
A logical expression can involve more than just one pair of relationships.
For example, the logical expression "one is less than two, and five is
greater than six" is False. To provide for such multiple relationships,
SiMPLE provides the keywords "And" and "Or".
In addition, logical true and logical false expressions need not require
the above symbols ( < , = , etc.). Any non-zero quantity will be regarded
as being logically True, and zero will be regarded as being logically False.
The If-structure
----------------
The general form of an "If-structure" is:
If (logical expression)
statement
statement
...
Endif
where:
If - a keyword which begins the structure
logical expression - an expression whose value is either true
or false
statement - zero or more program statements to be
statement executed if the "logical expression" is true
...
End - a keyword which ends the structure
You can optionally omit the parentheses around the logical expression:
If logical expression
While it is not necessary to do so, it is customary to include the word "if"
following the keyword "End" (i.e., "Endif") to explicitly indicate the end
of the "If-structure". (Any information on the same line following the "End"
is ignored.)
The If-Statement
----------------
The general form of the "If-structure" will allow you to handle any number
of statements following the "If" line of the structure. However, there are
many times when this generality is not necessary.
If an "If-structure" would have only a few simple statements (i.e., no other
embedded "If" statements) in the block of code immediately following the "If"
line, then those statements (separated by semi-colons) can appear on the same
line as the "If" itself, and no "End" statement is needed. However when using
such a one-line "If-statement", you MUST use parentheses to delimit the logi-
cal expression.
The Else-Clause
---------------
The "If-structure" provides a mechanism for executing a block of statements
if the logical expression in an "If-structure" is True. The "Else-clause"
provides an optional method for executing a block of statements if that
logical expression is False. An "Else-clause" can ONLY be used following
either an "If-structure" or an "If-statement".
The general form of the "Else-clause" is:
Else
statement
statement
...
Endelse
where "Else" is a keyword, and the "statements" immediately following the
"Else" statement represent a block of zero or more program statements. These
statements will be executed if the logical expression (in the "If-structure"
immediately preceding the "Else-clause") is False.
Just as in the case of the "If-structure" it is customary (but not necessary)
to include the word "else" following the keyword "End" (i.e., "Endelse") to
explicitly indicate the end of the Else-clause.
And just as in the case of the "If-structure", if an "Else-clause" would have
only a few simple statement in the block immediately following the "Else"
statement then those statements (separated by semi-colons) can appear on the
same line as the "Else" itself, and no "End" statement is needed.
If-Else-Structures
------------------
Combining the two possible forms of the "If-structure" with the two possible
forms of the "Else-clause" yields the following four "If-Else-structures":
If (logical expression) statement(s)
Else statement(s)
If (logical expression) statement(s)
Else
statement(s)
Endelse
If (logical expression)
statement(s)
Endif
Else statement(s)
If (logical expression)
statement(s)
Endif
Else
statement(s)
Endelse
Testing Strings
---------------
In addition to providing the ability to test numerical quantities, the "If-
statement" (and "If-structure") can also be used for testing text strings.
When comparing text strings using an equal sign ( = ) as the logical re-
lationship being tested, the entire string must match completely (character
for character, and case for case) in order for the relationship to be true.
Suppose you want to compare two text strings for equality of characters but
not for equality of case. (In other words, you want the text strings to be
reported as being equal if they match letter for letter, regardless of
whether the corresponding letters are uppercase or lowercase.) SiMPLE
provides the "similar to" symbol ( ~ ) to test for such an "almost equals"
condition. For example, the program:
Set a = "SiMPLE"
If (a = "simple) Display "YES"
Else Display "NO"
would display the word "NO". But the program:
Set a = "SiMPLE"
If (a ~ "simple) Display "YES"
Else Display "NO"
would display the word "YES".
Keyword: Goto
-------------
The "Goto-statement" provides another way of redirecting a program's flow
of execution. The form of the "Goto-statement" is:
Goto label
...
...
label: statement1
statement2
...
where:
Goto - a keyword
label - the name of a label in the program. The label must
be followed by a colon
statement1 - the statement to be executed next
The rules for naming a label in your program are the same as those for naming
the label on a container. (It must start with a lowercase letter and can be
followed by any sequence of lower case letters or numbers.)
Tasks and Functions
-------------------
A. Invoking Tasks
-----------------
A task is invoked by using the keyword "Call", followed by the name of the
task, followed by its calling parameters (if any) contained in parentheses.
(If a task has no calling parameters, the parentheses are optional.)
Just as in the case of the "Set" keyword, the use of the "Call" keyword is
optional, except when used in the "statement" portion of a one-line "If-
statement".
Every task resides inside either the program module or inside a task module.
And every task module resides inside either:
a) the system library
b) the local library (whose modules are accessible only to the current
project), or
c) the global library (whose modules are accessible to all projects).
Most tasks have calling parameters which pass information FROM the calling
program INTO the task. Sometimes, however, it is necessary for a task to
pass information BACK TO the calling program. When this is the case, YOU
must supply a container for the information to be received from the task.
(One way to do this is to simply initialize a container somewhere prior to
invoking such a value-returning task. Or you can declare a container by
using a type declaration statement.)
Invoking tasks which have been created by a third-party vendor requires the
specification of a "handle" along with the name of the task. (A handle can
be thought of as being a kind of "nickname" which identifies the creator of
the task). When specifying a handle it must be preceded by an "at-sign"
( @ ) character. [Note: You may optionally specify the creator's User ID in
liu of his handle.] This at-sign and handle combination follows the paren-
theses containing the calling parameters.
If the task that you are invoking is an "internally" defined task, you should
specify only the at-sign character WITHOUT indicating either a handle or a
user ID. (We will explain what we mean by "internally" and "externally" de-
fined tasks shortly.)
B. Creating Your Own Tasks
-----------------------
A task is defined by a block of code that begins with the keyword "Task",
followed by the name of task, followed by its calling parameters (if any)
and their data types. The data type of each calling parameter must be ex-
plicitly declared in the parameter list.
[Technical Note: In SiMPLE, all task calling parameters are passed by
"reference". This means that the calling parameters are "two-way streets"
in the sense that they can be used to transmit data TO the task as well as
receive data back FROM the task. All function calling parameters are passed
by "value". This means that a function's calling parameters are "one-way
streets" in the sense that they can be used only to transmit data TO the
function. They cannot be used to receive data back FROM the function.]
The "Return" keyword is used to terminate execution of a task or function
and transfer execution back to the calling program. If a "Return" would
appear as the last statement of a task, then that "Return" can be optionally
omitted.
The rules for naming tasks are the same as the rules for naming containers.
All user-created tasks MUST start with a lower case letter (a - z). [Remem-
ber, the use of capital letters is reserved for specifying "system words"
(specifically, "keywords"). However, since the system library is (in a
sense) also "part of the system", any task/function in the system library may
be referenced by using EITHER upper or lower case for the first letter of its
name.]
If the block of code defining a task exists in a program module, the task is
said to be an "internally" defined task. In that case, the code defining the
task appears following the main program listing.
C. A Module's Common Area
----------------------
Data generated inside a task exists only during the duration of that task's
execution. When a task finishes executing, all of its internal data may be-
come purged. However, there are times when it is necessary for a task to re-
tain some of its internally generated data. This is accomplished by storing
the data in the module's common area. In addition, the common area for a
module can be accessed by other tasks in the module, thereby providing a com-
mon pool of data storage.
The common area for any module is referenced by a statement of the form:
Common type name1, name2, ...
where:
Common - is a keyword
type - is a data type specifier (Int, Float, etc.)
name1, name2 .. - are one or more containers (or dimensioned arrays)
Each task (or function or main program) that wishes to access containers re-
siding in the common area must contain one or more "Common" statements at the
beginning of its block of code.
Example: The following listing is an example of a program that invokes an
------- internally defined task named "mytask". The program uses con-
tainers 'a' and 'b' in the Common area to pass information to the
task:
Common Int a, b // These three lines
Set a = 7; Set b = 3 // constitute the
Call mytask @ // main program.
Task mytask // These three lines
Common Int a, b // constitute the
Display a,,b // user-defined task.
Initializing the Elements of a Common Area
------------------------------------------
A task can initialize a container in the common area at compile time. Simply
specify an equal sign ( = ) followed by the value to be initially placed in
the container:
Common type container = initial value
where,
Common - is a keyword
type - is the data type (Int, Float, etc.)
container - is the container to be initialized
initial value - is the initial value to be placed into the container
If the common area contains a dimensioned array, the elements of the array
can be initialized by issuing a statement of the form:
Common type name [size] = {value1, value2, ...}
Optionally, the initialization can also be formed without specifying the
dimension of the array:
Common type name [ ] = {value1, value2, ...}
Functions
---------
The system library contains several functions, mostly dealing with
mathematical calculations (such as "Random", "Cos", "Sqrt", etc.)
A. Invoking Functions
------------------
A function is invoked by referencing it by its name (followed by its calling
parameters, if any, in parentheses) in an expression.
Even if a function has no calling parameters, an empty pair of parentheses
must still be supplied.
Examples: Set y = sqrt (2)
Set char = wait key ( )
B. Creating Your Own Functions
---------------------------
A function is defined by a block of code that begins with a type declaration
keyword ("Int", "Float", "Text", etc.) followed by the name of the function,
followed by its calling parameters (if any) contained in a single pair of
parenthesis. The data type of each calling parameter must be explicitly de-
clared in the parameter list. If there are no parameters, an empty pair of
parenthesis ( ) must be supplied anyway.
Just as in naming tasks, the name you choose for a function must start with
a lower case letter (a - z). The "Return" keyword, followed by the value to
be returned, will transfer execution back to the invoking program.
C. Use of the Common Area by Functions
-----------------------------------
(A function can work with the common area in exactly the same way as a
task can.)
Creating Your Own Task Modules
------------------------------
As we have seen, an internally defined task is a separate block of code con-
tained inside a program module. Such a task can be referenced (or "Called")
only from code inside that same program module.
However it is also possible to create "externally" defined tasks (i.e., tasks
that can be referenced from ANY module). To do so, simply put the code into
a "task module" instead of placing it in a program module. (This will then
produce the equivalent of a task that has been imported from a third-party
vendor - with YOU being the vendor!)
Since there is virtually no distinction between externally defined tasks and
imported tasks, they are both invoked in exactly the same manner. Therefore,
when you invoke an externally defined task that you've created, you must re-
member to include an at-sign character followed by the handle of the task's
creator. Since YOU are the creator, you would therefore specify YOUR OWN
handle following the at-sign. (In the next section we will show you how to
create a handle for yourself.)
The ACTIVATE Command
--------------------
SiMPLE implements a naming scheme in which a unique number ("user ID") is
assigned to each programmer. This user ID is appended to the name of every
task which that particular programmer defines. (This is done to prevent ac-
cidental "naming conflicts" that could otherwise occur when user-created
task modules are distributed to other programmers.)
A user ID can be as short as one digit or as long as eight digits. When you
first install SiMPLE on your computer, you are automatically assigned a user
ID of zero (0). This user ID of zero allows you to create only Program mod-
ules (i.e., modules containing main programs only, or modules containing main
programs along with their own internally defined tasks).
To create Task modules, you must first change your user ID to some non-zero
value. This is a one-time process which is performed by using the "ACTIVATE"
command. (On a multiple-user system, each user simply ACTIVATEs with a dif-
ferent user ID and handle.)
To ACTIVATE, type (from the command line) the command ACTIVATE followed by
the user ID you wish to use, followed by the handle you wish to use. For ex-
ample to ACTIVATE yourself as user 12345678 with the handle "johndoe", you
would type:
activate 12345678 johndoe
To prevent users from accidentally choosing the same user ID number that
someone else might have chosen, we have established that all user IDs of se-
ven digits or less require a password to be specified when ACTIVATEing. If
you are planning to become a professional SiMPLE developer, we recommend that
you contact us at The SiMPLE CodeWorks (www.simplecodeworks.com) to receive
your own unique user ID and password.
However 8-digit user IDs do NOT require a password. You are free to choose
any 8-digit number that you like. (We recommend using the right-most eight
digits of your SiMPLE serial number.)
The GET Command
---------------
To create a new task module (after you have ACTIVATEd), simply type the com-
mand "GET" followed by the name of the task module you wish to create. This
will invoke the text editor (much like the OPEN command does), except that
the first line of the editor screen will automatically display the keyword
"Task" followed by the name of the module. At this point you can add the
calling parameters (if any), along with the body of code defining the task.
You can even change the name of the task if you so choose. A task's name
does NOT have to be the same as the the name of the module in which it re-
sides (although it is generally a good idea to keep them the same). Further-
more, a single task module can define as many different tasks as you like.
When you are finished typing in the code, exit the editor to return to the
command line prompt. You will notice that the name of the module you just
created appears inside a new box at the top of the screen. (The upper box
displays the names of the main program modules in the project, and the lower
box displays the names of the task modules in the project).
Just as the OPEN command can be used to both create new program modules and
edit already existing Program modules, so too can the GET command be used
to create and/or edit Task modules. To edit an existing task module, simply
type the command GET followed by the name of the task module you wish to
edit. If the module is currently in the local library, the GET command will
remove it from the library for editing.
Putting Task Modules Into The Local Library
----------------------------------------------
After you have created (or edited) a task module, you must first "PUT" it in-
to a library before the module can be used. The PUT command will automati-
cally compile the module and (if there are no errors) put it into the local
library. (After a task module has been put into the local library, its name
is displayed in blue letters. Task modules that are not in the library are
displayed in pink letters.)
Transferring Task Modules To The Global Library
-----------------------------------------------
Since modules should never be placed into the global library until they are
thoroughly debugged, SiMPLE does not provide the equivalent of a PUT (and
GET) command for storing modules directly into (and retrieving modules from)
the global library. Instead, all task modules are moved into and out of the
global library using the "TRANSFER" command. The TRANSFER command will
transfer a specified task module from either the local library to the global
library, or vice versa, depending on where the specified module currently
resides.
Miscellaneous Topics
--------------------
Visibility of the Contents of Modules
-------------------------------------
Tasks in separate modules are "visible" to (can be called from) any other
task or function contained either inside the same module or contained inside
a different module. Functions are visible only inside the module in which
they are defined. Similarly, the elements of a module's common area are also
invisible outside the module.
Sometimes it is desirable to hide certain tasks so that they too cannot be
seen outside the module. This is easily accomplished by placing an asterisk
( * ) at the end of the line containing the keyword, "Task".
Example: Task mytask (Int param) *
Auxiliary Information Document (AID File)
-----------------------------------------
One of the unique features of SiMPLE is that every task module that you
create and compile automatically produces a corresponding Auxiliary Infor-
mation Document ("AID" file). An AID file supplies potential users of your
module with essential information telling them how to use the tasks con-
tained inside. Every visible task declaration is replicated in the AID file
so that a user can see the name of the task along with the names and types
of all of its calling parameters. (The SHOW command can be used to view a
module's AID file.)
In addition to this fundamental information, SiMPLE allows you to include in
the AID file any special instructions or comments that you think might be
helpful to users of your module. To include such additional information,
simply preceed each such instruction line in your source code with an aster-
isk ( * ) character.
Ownership Of Modules
--------------------
"Ownership" refers to the accessibility of a module's source code, especially
on systems supporting multiple users. However the following discussion is
not limited to only those systems on which more than one user ID has been ac-
tivated. The creators of imported modules also constitute a form of "multi-
user-ship" (since their modules now exist in your computer).
There are three levels of ownership:
- Any module whose source code is viewable and modifiable by
all users is said to be "publicly owned".
- Any module whose source code is only viewable (but not modi-
fiable) by all users is said to be "privately owned".
- Any module whose source code is inaccessible is said to be
"proprietary".
Unless its source code was deliberately deleted, every program module is pub-
licly owned. Any user on the system can simply OPEN the module and make
changes to it.
Every task module that is not currently residing in a library is also pub-
licly owned. Any ACTIVATEd user on the system can simply GET the module and
make changes to it.
Every task module that has been PUT (or TRANSFERed) into a library is pri-
vately owned. Any user on the system can view the module's source listing
(by using the SHOW command), but only the module's owner can make changes to
it.
Task modules that have been IMPORTed may be either privately owned or pro-
prietary, depending on whether or not the EXPORTer chose to include source
code with his modules. If a module is proprietary, only its AID file can be
viewed by users.
Note: Whenever a library contains a module with viewable source
code, the SHOW command's scroll box displays the module's
name in "aqua" color. Modules that do not contain view-
able source code have their names displayed in "rust" co-
lor. Descriptive AID files (such as the one you are now
reading) have their names displayed in light gray color.
You can use the SHOW command to view the source code for a privately owned
module. When selecting the module (from the scroll box) simply hold down the
'Ctrl' key while pressing the 'Enter' key. If the selected module does not
have viewable source code, its AID file will be displayed instead.
Even though a privately owned module's source code cannot be modified by any-
one but its owner, it is possible to CLONE a privately owned module into a
new publicly owned module. (See the CLONE command.) Whoever PUTs this new
module back into a library will then become the private owner of the module.
(The original module is still privately owned by its creator.)
The EXPUNGE Command
-------------------
Task modules that have been imported into a library constitute an integrated
system of capabilities. If even one of those modules were to be removed, the
functionality of the entire library could be compromised. (Other modules in
the library might require tasks contained in the removed module). Therefore
task modules that have been imported into a library should always remain in
the library forever.
However, for the benefit of those users who "know what they're doing" (or who
"think" they do!), SiMPLE provides the undocumented command, EXPUNGE, which
can be used to selectively delete an imported task module from a library.
The general form for the command is:
EXPUNGE library module handle
For example, to remove the "stars" module form the PLAYPEN's local library,
the user would type:
expunge L: stars toys
on the command line in project PLAYPEN.
Passing Calling Parameters to a Main Program
--------------------------------------------
Just as in the case of tasks, main programs can also have calling parameters
passed to them. (But information can NOT be passed back OUT to the user.)
SiMPLE and Ultra-SiMPLE each handle this capability slightly differently:
SiMPLE automatically predefines the Text array, "Param", for
passing parameters from the user to the program. Param[1] con-
tains the first input parameter, Param[2] the second, etc. The
number of parameters that have been passed is indicated by the
Int container, "Numargs". (Both "Param" and "Numargs" are ac-
cessible only from the main program. They cannot be referenced
from tasks or functions.)
Ultra-SiMPLE uses a Text function named "Param()" for retrieving
the calling parameters to the program. Param(1) retrieves the
first input parameter, Param(2) the second, etc. The number of
parameters that have been passed is retrieved by the Int function,
"Numargs()". (Both "Param" and "Numargs" are accessible from
the main program, tasks, and functions.)
A maximum of nine calling parameters can be passed to a program.
Intermixing C++ Statements with SiMPLE Statements
-------------------------------------------------
For those users who know how to program in C++, SiMPLE provides the
capability to intersperse C++ statements along with SiMPLE statements.
When doing so, there are five rules you must remember:
1). All C++ statements must begin with a plus sign ( + ) in the first
non-blank column.
2). All container names must end with an underscore ( _ ) character.
3). All task names invoked from the SiMPLE system library must begin
with an upper case letter.
4). All task names (other than tasks in the SiMPLE system library)
must end with an underscore character, followed by the User ID
number (not the handle) of the task's creator.
5). A main program cannot begin with a C++ statement.
Viewing/Modifying a Module's C++ Code
-------------------------------------
All SiMPLE source code modules are first translated into C++, and then com-
piled into object code by the C++ compiler. To view the C++ code that is
generated by the translator program, first type:
compile name
and then type:
edit name.cpp
where "name" is the name of the module. You can now make modifications to
the C++ code if you wish. To compile the modified C++ module into its object
module, type:
compilec name
If "name" is a program module, you can now produce its executable module
(name.exe) by simply typing:
link name
_____________________________________________________________________________
www.simplecodeworks.com
-----------------------