home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The C Users' Group Library 1994 August
/
wc-cdrom-cusersgrouplibrary-1994-08.iso
/
vol_200
/
200_01
/
user.man
< prev
Wrap
Text File
|
1979-12-31
|
101KB
|
3,403 lines
Introduction 1
1. IIIInnnnttttrrrroooodddduuuuccccttttiiiioooonnnn
SCI is a C language interpreter that supports a very usable
subset of C. It is a fully interactive interpreter that
includes a powerful full screen editor and a program trace
facility. SCI was meant to be a stepping stone for the
experienced BASIC programmer who is ready to venture into
the exciting world of C!
SCI will run on any MS-DOS or PC-DOS computer that has a
minimum of 64Kbytes of RAM, although 128Kbytes is
recommended. The available free memory (that portion of
memory not used by the interpreter's code and data storage)
is automatically divided among "user progam code", "variable
table", "function table" and "stack" memory segments. If
necessary, the sizes of these segments may be changed at
program startup, however their total may not exceed
64Kbytes.
The integrated full-screen editor does require that the
terminal emulation firmware in your computer be capable of
recognizing certain terminal control character sequences
(also known as "escape sequences") that perform cursor
positioning and erasing of portions of the screen. See the
installation instructions in the "Editor" section of this
manual.
The SCI interpreter is very similar to BASIC internally.
Each line of input is first scanned and "tokenized", a
process in which language elements (numbers, variables,
keywords, etc.) are converted to "tokens". These tokens are
easier to handle by a computer than arbitrarily long
character sequences. Unlike BASIC however, SCI programs do
not require line numbers - the program flow is directed by
SCI purely through the structured programming constructs
inherent in the C language. This tokenization process
allows SCI to run much faster than other interpreters that
deal with the raw program text. However, the C language was
never designed to be an interpreted programming language
like BASIC was, and the price that must be paid for this
advantage is in the form of incompatibilities with standard
__________
0. "The C Programming Language" by Brian W. Kernighan &
Dennis M. Ritchie, published by Prentice-Hall, Inc.
SCI Users Manual Copyright (C) 1986, Bob Brodt
2 Introduction
C as defined by Kernighan and Ritchie[0].
1.1 SSSSttttaaaarrrrttttiiiinnnngggg OOOOuuuutttt
The files contained on the distribution diskette are:
SCI.EXE the interpreter program
SHELL.SCI the command shell, written in SCI's
dialect of C
CALC.SCI a sample calculator program, also
written in "SCI C"
USER.MAN User's Manual
PROG.MAN Programmer's Manual
As always, it is a good idea to make a working copy, and
then store your distribution diskette in a safe place.
To start up SCI, make sure that the file SHELL.SCI resides
on the current drive and then execute SCI.EXE. The
interpreter will then read and execute the C program it
finds in SHELL.SCI. The program provided for you in this
file contains several items of information needed by the
built in editor, as well as some other useful functions.
The program in SHELL.SCI that gets executed by the
interpreter is simply an endless loop that prompts you for a
line of input from the console and hands it off to the
interpreter for execution. Actually this function could
have been performed by the SCI program itself, but by
placing this routine outside of the executable program, you
have the option of customizing the interpreter to suit your
tastes. The shell will be discussed in more detail later.
You may also specify a different program file for SCI to
execute on startup. By typing the following operating
system command line, for example:
A>SCI B:STARTUP
the interpreter will search disk B: for a file called
STARTUP and execute it in lieu of the default SHELL.SCI
file. Be aware, however, that the standard SHELL.SCI file
contains many often-used operating system interface
functions that must be copied over to your customized
startup program if they are going to be used by that
program. See the section on Library Functions for a list of
these functions.
SCI Users Manual Copyright (C) 1986, Bob Brodt
Introduction 3
1.2 MMMMeeeemmmmoooorrrryyyy AAAAllllllllooooccccaaaattttiiiioooonnnn
The interpreter automatically divides up whatever free
memory is available (after SCI is loaded) among four
segments for use by your programs and data. These segments
are: the Program Code, Variable Table, Function Table and
Stack. The Program Code segment contains the tokenized
version of your program code. The Variable Table contains
information about all "active" variables. Each function
takes up exactly one entry in the Function Table. Finally,
memory requirement for the Stack segment will grow and
shrink as your program executes. The stack is used only for
temporary storage when expressions are evaluated.
If the interpreter complains about "out of memory", "too
many variables", "too many functions" or "stack overflow",
you may be able to circumvent the problem by telling SCI how
much memory to assign to each of these four segments using
the following MS-DOS command line options:
-P nnnn - assign "nnnn" decimal bytes for program storage.
-V nn - allow space for a maximum of "nn" variables.
-F nn - allow space for a maximum of "nn" functions.
-S nn - set the stack size to "nn".
For example the command line:
A>SCI -P 8000 -V 30 -F 80 -S 40
will reserve 8000 bytes for program storage, allow a maximum
of 30 variables to be active at one time, allow a maximum of
80 function declarations and leave 40 stack entries. Please
be aware that each stack entry requires 5 bytes of RAM, each
variable table entry 14 bytes and each function table entry
8 bytes of RAM. Thus, in the example above, the total
amount of RAM required by SCI's tables are 8000 + 14x30 +
8x80 + 4x40 = 9260 bytes; The total amount of RAM for all
SCI tables may not exceed 65,535 (64K) bytes.
SCI Users Manual Copyright (C) 1986, Bob Brodt
4 The Shell
2. TTTThhhheeee SSSShhhheeeellllllll
The stock version of the shell program in SHELL.SCI simply
displays a prompt on the console, reads a line of input, and
attempts to execute the input line. When SCI is started up,
it reads the shell file and executes it. The shell file
will then print an identification banner, like so:
SCI V1.5 20Oct86 Copyright (C) 1986 Bob Brodt
SCI shell V1.5 20Oct86 Copyright (C) 1986 Bob Brodt
sci>
The prompt "sci>" tells you that the shell is ready to
accept commands.
The shell maintains your program in its "program buffer" in
memory. Initially, this buffer is empty so you must either
create a program using SCI's editor or retrieve a previously
created program from disk. Before you exit from the shell,
be sure to save your program on disk or the contents of the
program buffer will be lost.
The standard shell recognizes four commands: "edit", "list",
"load", "save", "dir" and "exit". These are functionally
similar to the BASIC commands: "EDIT", "LIST", "LOAD",
"SAVE", "FILES" and "SYSTEM" respectively. Later as you
become more familiar with the C language, you may wish to
modify the shell program and add your own commands.
Anything else typed at the shell prompt is assumed to be a
valid C statement and is handed off to the interpreter to be
executed.
2.1 SSSShhhheeeellllllll CCCCoooommmmmmmmaaaannnnddddssss
Listed here are the shell commands. In the descriptions
below, anything enclosed in square brackets ([ and ]) is
optional and anything enclosed in angle brackets (< and >)
is a verbose description of the item required by the
command.
_e_d_i_t [<_l_i_n_e#>]
The "edit" command invokes SCI's built-in screen editor (see
the "Editor" section in the User's Manual for more details).
If the word "edit" is followed with a line number, the
editor will start up by displaying the page of the program
that contains the line number, and move the cursor to that
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Shell 5
line. If the requested line number is greater than the
number of lines in the program buffer, the last page of the
program is displayed.
list [<from_line#>] [<to_line#>]
This command lists the program currently in the program
buffer on the screen in its entirety. The listing may be
stoped by pressing any key. If the word "list" is followed
by one number, the listing starts at that line number in the
program. If two numbers separated by one or more spaces
follow "list", the program listing will start with the first
and end with the second line number in the program.
_l_o_a_d <_f_i_l_e_n_a_m_e>
The "load" command will load the program buffer from the
given disk file name. This command will destroy the current
contents of the program buffer. If the file name is omitted
or the file is not found, SCI will display a "file error"
message and erase the program buffer. This command can be
used to intentionally erase the program buffer by simply
omitting the <filename>.
_s_a_v_e <_f_i_l_e_n_a_m_e>
This will write the contents of the program buffer out to
the named disk file. If the file name is omitted or the
file can't be created, SCI displays the "file error"
message. This command does not alter the program buffer in
memory.
NOTE: Programs that are "save"d by SCI are ordinary text
files, suitable for editing with your favourite text editor.
_d_i_r [<_f_i_l_e_s_p_e_c>]
The "dir" command is exactly the same as in MS-DOS with the
exception that no file attribute information (size, creation
date, etc) is displayed, only the file name.
_e_x_i_t
This command returns you to the MS-DOS command level. If
anything was left in the shell's program buffer, it will be
lost unless you have previously "save"ed it in a disk file.
SCI Users Manual Copyright (C) 1986, Bob Brodt
6 The Shell
2.2 RRRRuuuunnnnnnnniiiinnnngggg YYYYoooouuuurrrr PPPPrrrrooooggggrrrraaaammmm
A C program is simply a collection of "functions" which
(hopefully) all participate to successfully perform a single
task. In "standard" C, every program must have one and only
one function called "main". This is where the program will
start executing from. In SCI's C, you need not have a
"main" function because SCI allows you to run any function
in the program buffer by simply typing its name at the SCI
input prompt. Suppose for example that our program buffer
contained only the following two functions:
hex(n)
{
printf("%d = %x Hexadecimal\n",n,n);
}
oct(n)
{
printf("%d = %o Octal\n",n,n);
}
We could execute any of these functions from the shell by
simply typing, for example:
sci> hex(256)
256 = 100 Hexadecimal
sci>
Note that we showed the shell's prompt (sci>) above for
demonstration purposes only; don't type "sci>"!
From the above example, you can see that an SCI program is
simply a collection of not necessarily related functions
that can be run and debuged individually or in combination
with other functions in the program buffer. Thus if you
plan to transport your program to a standard C compiler, be
sure to include a "main" function in the final product.
2.3 PPPPrrrrooooggggrrrraaaammmm VVVVaaaarrrriiiiaaaabbbblllleeeessss
The interpreter always clears to zero all program variables
before each shell statement is executed. So if you
initialize a variable from the shell, the same variable will
be set to zero again before the very next "c" statement
entered from the shell.
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Shell 7
To illustrate, assume we have the following program in the
program buffer:
int total;
sum(n)
{
total = total + n;
}
This program uses the variable "total" to keep a running
total of numbers. However, repeated calls to "sum()" from
the shell would be futile since the interpreter would always
set "total" to zero before each call.
SCI Users Manual Copyright (C) 1986, Bob Brodt
8 The Editor
3. TTTThhhheeee EEEEddddiiiittttoooorrrr
SCI's built in editor is screen oriented and is similar to
the "standard" set by the popular WORDSTAR word processor.
The editor can be modified to work with almost any personal
computer, by simply changing some variables in the shell
file (SHELL.SCI). This section will describe the
installation procedure and give needed information for some
of the more common personal computers.
3.1 KKKKeeeeyyyyssss
The alphabetic character keys on your PC's keyboard are
probably arranged in a typewriter keyboard pattern as shown
below. All editing commands (cursor motion, deleting,
inserting, etc.) are control-key combinations (i.e. press
and hold the CONTROL key and then press a letter key). In
this manual, we will use an up arrow, or circumflex (^)
followed by a letter to indicate that the keystroke is a
control-key combination. In the keyboard diagram below,
only the letter keys marked with a circumflex are valid
editing command control-keys. What each of these control-
keys does will be explained in detail later.
----------------------------------------------
| |
| ----------------------------------------- |
| | ^Q| ^W| ^E| ^R| T | ^Y| U | I | O | P | |
| ----------------------------------------- |
| | ^A| ^S| ^D| ^F| ^G| ^H| J | ^K| ^L| |
| ------------------------------------- |
| | ^Z| ^X| ^C| ^V| ^B| N | M | |
| ----------------------------- |
| |
----------------------------------------------
3.2 SSSSccccrrrreeeeeeeennnn LLLLaaaayyyyoooouuuutttt
The editor uses all of the screen, except for the last line,
as a window into your program. The last screen line is
reserved for status and prompts. The status line is divided
into several fields as shown below. The current line and
column numbers are updated only if you haven't pressed a key
within the last two seconds or so. This lets you enter text
or commands at typamatic speeds without slowing you down.
If an error should occur while you are editing your program,
the status line will be erased and the error message
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Editor 9
L:nnnn C:nn Insert Mark:nnnn:nnnn
| | | |
| | | line numbers of start and
| | | end of a marked block
| | |
| | insert/replace mode indicator
| |
| current column number
|
current line number
displayed in its place. You must then hit the <ESCAPE> key
to acknowledge that you have seen the error message before
you may continue editing. Also, if the editor needs
information from you (such as search strings, etc.) the
appropriate prompts will appear in the status line.
3.3 SSSSccccrrrreeeeeeeennnn CCCCuuuussssttttoooommmmiiiizzzzaaaattttiiiioooonnnn
Modern computer terminals allow a programmer to manipulate
the cursor and text displayed on the screen by means of
specific character sequences sent to the terminal. These
character sequences are known interchangably as "control
codes" or "escape sequences".
Most personal computers have a program in ROM that emulates
a specific terminal's control codes. In the case of the IBM
PC, this emulation program is a "device driver" program on
disk, known as "ANSI.SYS", and must be loaded into RAM when
PC-DOS is first booted up. See your IBM PC-DOS manual for
installation procedures of this device driver.
Your personal computer must have as a minimum, control codes
to directly position the cursor anywhere on the screen, and
either an "erase to end of line" or "erase to end of screen"
control code. The "erase to end of line" code must clear to
spaces all character locations to the right of and including
the cursor postion. The "erase to end of screen" control
code performs an "erase to end of line" function and then
erases all lines below the current line to spaces. If your
terminal recognizes both of these erase control codes, use
"erase to end of screen" instead of "erase to end of line"
because it is slightly faster.
If your computer does not provide these minimal control
codes, SCI's built in editor can not be used. In this case,
you must resort to using your own text editor to write and
modify your programs.
SCI Users Manual Copyright (C) 1986, Bob Brodt
10 The Editor
Your PC may also have control codes that perform more
complicated functions such as inserting and deleting
characters and lines. These are not really necessary,
however the editor is designed to take advantage of them if
they exist. You may need to do some experimenting with
different combinations of escape sequence to achieve optimum
speed performance from the editor.
A Terminal's control codes are made known to the SCI editor
by way of system global program variables. These program
variables must be declared in your shell program file
(normally SHELL.SCI) before the "entry" keyword and must be
assigned values in the mainline shell program (the function
"main" in SHELL.SCI). There is one variable for each
control code. If your PC does not have a particular control
code, that corresponding variable should not be declared.
All variables must be declared as character pointers (i.e.
"char *") with the exception of "_nr", "_nc", "_ro", "_co"
and _mhz, which are all "char's". The variable names and
their corresponding control code function are listed below:
_cp cursor postion.
_el erase to end of line.
_es erase to end of screen.
_dc delete the character under the cursor and move left
all characters to the right of the cursor.
_dl delete the line the cursor is on and move up all
lines below it.
_ic insert a character before the one under the cursor
and move all characters to the right. The cursor
must remain at the same position (i.e. at the
inserted character).
_il insert a line before the one the cursor is on and
move all lines below it down. The cursor must remain
at the same position (i.e. on the newly created
blank line).
_bl rings the console bell. If this variable is
omitted, the standard ASCII BEL character will be
used (octal 007). You may also wish to flash the
screen momentarily to a different color if your PC
has color or reverse video capabilities.
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Editor 11
_nr number of rows (lines) on the screen. Typically,
this is set to 24 (use 25 for the IBM PC).
_nc number of columns, usually 80 but may be set to 40
on the IBM PC if you are in 40 column mode.
_ro row offset. The cursor position control code assumes
that the screen "home" position (top left corner)
starts at 0,0. If this is not the case for your PC
you can add this offset, otherwise omit this
variable.
_co column offset, same as above.
_mhz CPU speed (in Megahertz) of your PC. This variable
controls the frequency at which the editor's status
line is updated.
As mentioned earlier, the above variables are pointers to
characters which should be assigned in your shell mainline
program. The assigned character strings may contain any of
the data conversion codes recognized by the Library Function
"printf()". See the section on Sample Configurations below
for examples.
3.4 KKKKeeeeyyyybbbbooooaaaarrrrdddd CCCCuuuussssttttoooommmmiiiizzzzaaaattttiiiioooonnnn
In addition, if any of the character pointer variables
"_ka", "_kb", ... "_kz" are declared, the string pointed at
by these variables is assumed to be the character sequence
sent by a function key on your keyboard and will be
recognized as an alias of the corresponding control-letter
key combination.
For example, The VT-100 terminals send the character
sequence: "ESCAPE [ A", "ESCAPE [ B", "ESCAPE [ C" and
"ESCAPE [ D" for the up, down right and left arrow keys
respectively. So, instead of typing ^E, ^X, ^D and ^S to
move the cursor around, we could declare the following
variables:
char *_ke, *_kx, *_kd, *_ks;
_ke="\033[A"; # alias for ^E
_kx="\033[B"; # alias for ^X
_kd="\033[C"; # alias for ^D
_ks="\033[D"; # alias for ^S
SCI Users Manual Copyright (C) 1986, Bob Brodt
12 The Editor
and then use the VT-100's arrow keys instead. Similarly,
other keyboard function keys that transmit multiple
characters or single control characters can be used to
perform other editor functions.
3.5 SSSSaaaammmmpppplllleeee CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnnssss
This section contains the data declarations and assignments
required by some of the more common personal computers. The
data declarations must be made before the "entry" keyword in
SHELL.SCI, and the variable assignments must be done within
the function immediately following the "entry" keyword. For
example, the figure below shows the configuration for the
IBM PC in the distribution version of the SHELL.SCI file.
char _nr,_nc,_ro,_co,*_cp,*_el; <--editor variable declarations
.
.
<Library Function declarations>
.
.
entry <--Note the "entry" keyword here!
main()
{
.
.
_nr=25; <--editor variable assignments
_nc=80;
_ro=1;
_co=1;
_cp="\033[%d;%dH";
_el="\033[0K";
for (;;) {
.
.
<main program loop>
.
.
}
}
Only a skeleton of the file is shown here so that you can
see the relative locations of the editor variables'
declarations and assignments. Note that the declarations
must appear somewhere before the "entry" keyword, and the
control character strings must be assignmed to these
variables somewhere before the start of the main program
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Editor 13
loop.
In the sample configuration listings that follow, only the
control character string assignments are shown for brevity.
3.5.1 _I_B_M__P_C
The IBM PC is probably the most common. Note that the
ANSI.SYS device driver must be installed for the SCI editor
to work.
_nr=25; # the PC has 25 lines
_nc=80; # of 80 columns each
_ro=_co=1; # row/column numbering starts at 1
_cp="\033[%d;%dH"; # esc. seq. to position cursor
_el="\033[0K"; # esc. seq. to erase to end of line
3.5.2 _D_E_C__R_a_i_n_b_o_w__1_0_0
Digital Equipment Corp.s' Rainbow 100 recognizes a subset of
the American National Standards Institute (ANSI) Control
Sequences for Video Terminals (X3.64).
_nr=24;
_nc=80;
_ro=1;
_co=1;
_cp="\033[%d;%dH"; # position cursor
_es="\033[J"; # erase to end of screen
_il="\033[M"; # insert a line
_ic="\033[4h%c\033[4l"; # insert a character
_dc="\033[P"; # delete a character
_bl="\033[?5h\033[?5l"; # bell flashes screen momentarily
_ke="\033[A"; # up-arrow key
_kx="\033[B"; # down-arrow key
_kd="\033[C"; # right-arrow key
_ks="\033[D"; # left-arrow key
3.5.3 _H_e_a_t_h__H_1_9
_nr=24;
_nc=80;
_ro=' ';
_co=' ';
_cp="\033Y%c%c"; # position cursor
_es="\033E"; # erase to end of screen
SCI Users Manual Copyright (C) 1986, Bob Brodt
14 The Editor
3.5.4 _Z_e_n_i_t_h__P_C
_nr=24;
_nc=80;
_ro=' ';
_co=' ';
_cp="\033Y%c%c"; # position cursor
_es="\033E"; # erase to end of screen
_il="\033L"; # insert line
_dl="\033M"; # delete line
3.5.5 _T_e_l_e_v_i_d_e_o__9_1_0
_nr=24;
_nc=80;
_ro=' ';
_co=' ';
_cp="\033=%c%c"; # position cursor
_el="\033T"; # erase to end of line
3.6 EEEEddddiiiittttoooorrrr CCCCoooommmmmmmmaaaannnnddddssss
Now that you have modified the file SHELL.SCI for your
particular terminal, you are ready to use the editor. This
section describes all of the editor's commands in detail.
All of the editor commands are control-key combinations
(press and hold the CONTROL key while pressing a letter
key). We will use an up arrow, or circumflex (^) followed
by a letter to indicate that the keystroke is a control-key
combination. All other non-printing keys, such as the
<RETURN> and <BACKSPACE> keys, will be in UPPERCASE.
3.6.1 _E_x_i_t_i_n_g__f_r_o_m__t_h_e__E_d_i_t_o_r
To exit the editor and return to the SCI shell, type a ^Z.
3.6.2 _C_u_r_s_o_r__M_o_v_e_m_e_n_t
^E move cursor up to previous line. Screen scrolls down
if cursor is at the top of the screen.
^X move cursor down to next line. Screen scrolls up if
cursor is at the bottom of the screen.
^S move cursor left one character position. Cursor
stops at left margin.
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Editor 15
^D move cursor right one character position. Cursor
stops at right margin.
^A move cursor to beginning of previous "word". A
"word" is defined as a continuous sequence of
alphanumeric characters (i.e. letters and numbers -
no punctuation).
^F move cursor to beginning of next word.
^R move cursor one page (the height of the display) up
towards the beginning of the program.
^C move cursor one page down, towards the end of the
program.
<RETURN> or <LINEFEED> if the status line shows "Replace"
mode instead of "Insert", these keys will move the
cursor down to the beginning of the next line.
3.6.3 _I_n_s_e_r_t_i_n_g__a_n_d__D_e_l_e_t_i_n_g
^V toggles Insert/Replace mode. The status line at the
bottom of the screen will indicate the current mode.
In Insert mode, any characters you type will be
inserted before the current cursor position. In
Replace mode, old characters on a line are simply
overwritten as you enter text.
^G delete the character under the cursor. The cursor
stays in the same position.
^H or <BACKSPACE> delete the character to the left of the
cursor and move the cursor left one character.
^Y delete the current line. The cursor stays at the
same line. Note that the <EOF> mark at the end of
the program can not be deleted.
^L restore the original line if the cursor has not been
moved off the line.
<RETURN> or <LINEFEED> if the status line shows "Insert"
mode, these keys will insert a new blank line as
follows: If the cursor is at line one, column one
(top, left-most column) when a <RETURN> or
<LINEFEED> is pressed, a new blank line is inserted
above the current line; everywhere else, the new
SCI Users Manual Copyright (C) 1986, Bob Brodt
16 The Editor
line is inserted below the current line. The cursor
will rest on the newly inserted line and directly
below the first non-space character in the previous
line.
3.6.4 _E_x_t_e_n_d_e_d__M_o_v_e_m_e_n_t
The extended cursor motion commands require two control-key
keystrokes. The first is always a ^Q (mnemonic for Quickly
move somewhere), and the second can be one of the following:
^F find a character sequence. The cursor will move to
the status line's prompt/error message field and you
will be prompted for the character sequence to be
searched for. The search starts at the next
character position to the right of the cursor on the
current line. When the character sequence is found,
the cursor will rest on the first character of the
sequence.
^A find and replace character sequence. You are
prompted for the character sequence to be searched
for, as above. Next you are prompted for the
character sequence that will replace the search
string. Finally, you have the option of performing
the search/replace "globally" that is for every
occurance in the program.
^L find next occurence of previously specified
character sequence. You will not be prompted for
the sequence to be searched for.
^G go to a specified line. You are prompted for the
line number to be displayed. The cursor will rest
on the requested line usually in the center of the
screen.
^S move cursor to beginning of current line.
^D move cursor to end of current line.
^E move cursor to top of screen.
^X move cursor to bottom of screen.
^R move cursor to first line of program.
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Editor 17
^C move cursor so that the last page of the program is
displayed.
^B move cursor to the beginning of a marked block.
^K move cursor to the end of a marked block.
3.6.5 _B_l_o_c_k__a_n_d__M_i_s_c_e_l_l_a_n_e_o_u_s__C_o_m_m_a_n_d_s
These commands also require two control-key keystrokes and
include block marking, inserting/deleting and some "too late
to classify" commands.
Unlike the popular WORDSTAR word processor, SCI's editor
treats blocks as groups of lines instead of groups of
characters. That is, a block starts at the beginning of a
line and includes all characters up to the end of a line.
The first of these two-keystroke block commands must be a ^K
(mnemonic for blocK (?)) and the second may be one of:
^B mark beginning of a block. The status line will show
the line number of the beginning of the block.
^K mark end of a block. The status line is updated to
show the line number of the end of the block.
^V make a copy of a marked block and insert it before
the current line. You may not copy a block to
itself: for example if the block starts at line 3
and ends at line 10 and the cursor is currently
resting on line 5, you will be severely beeped at by
the editor.
^Y delete the marked block.
^U "unmark" the block. The block markers (if any) are
removed from the status line display.
^R read a file from disk and insert its contents before
the current line in the program. You will be
prompted for the file name.
^W write the marked block to a disk file. You will be
prompted for the file name.
SCI Users Manual Copyright (C) 1986, Bob Brodt
18 The Editor
3.6.6 _T_a_b_s
Tabs are set at every 3 columns. A ^I (or the <TAB> key on
your keyboard if you have one) will either insert spaces or
replace with spaces, depending on the current Insert/Replace
mode parameter, up to the next tab stop.
SCI Users Manual Copyright (C) 1986, Bob Brodt
Language Summary 19
4. LLLLaaaannnngggguuuuaaaaggggeeee SSSSuuuummmmmmmmaaaarrrryyyy
Although SCI implements only a subset of the C language, it
is powerful enough to teach you the major principles of C.
This section is meant to be used in conjunction with a good
C tutorial textbook to highlight the differences between the
SCI C subset and standard C. It also serves as a reference
for the experienced C programmer that wants to get started
with SCI quickly.
4.1 LLLLiiiinnnneeee TTTTeeeerrrrmmmmiiiinnnnaaaattttoooorrrrssss
In standard C, a statement is terminated with a semicolon
(;). In SCI, all statements are terminated by either the
end of the line or by a semicolon, although the semicolon is
optional. This means that an expression MUST be completely
contained on one line.
An SCI program line may be a maximum of 79 characters long.
The built-in editor will not allow you to create lines
longer than 79 columns.
4.2 CCCCoooommmmmmmmeeeennnnttttssss
Comments start with a number symbol (#) and end at the end
of the current program line. The standard C comment
delimiters, /* and */ are not recognized and will cause a
"syntax error" message.
4.3 IIIIddddeeeennnnttttiiiiffffiiiieeeerrrrssss
Identifiers are any sequence of characters, the first of
which must be an uppercase or lowercase letter ("a-z", "A-
Z") or an underscore ("_"). The remaining characters may
include digits ("0-9").
The following are all examples of valid identifiers:
this_is_an_identifier
_0123
XYZ
Note that there is no limit to the number of significant
characters in an identifier, except the maximum line length
limit of 79 characters.
SCI Users Manual Copyright (C) 1986, Bob Brodt
20 Language Summary
4.4 KKKKeeeeyyyywwwwoooorrrrddddssss
The following words are reserved by SCI and may not be used
as variable names:
break entry return
char for switch
case if sys
else int while
Most of these keywords are the standard language elements
and are described in any C text book.
The "entry" keyword is used to tell the interpreter which
function in the startup program (normally in the file
SHELL.SCI) is to be executed first after the program has
been loaded. There may be only one "entry" within a
program. Any functions or variables that were declared
before the "entry" keyword are considered "system globals"
and are globally known to all functions. Among the system
globals in the standard shell file are the Library Functions
and the editor's control variables.
Functions and variables declared after the "entry" keyword
are hidden from user-written functions. These include the
standard shell's control program (main) and its associated
variables (the program and input line buffer).
The keyword "sys" is an interface function to some useful
interpreter functions, such as the program editor. These
are described in the Library Functions section.
4.5 NNNNuuuummmmeeeerrrriiiicccc CCCCoooonnnnssssttttaaaannnnttttssss
SCI supports decimal integer constants in the range -32768
to 32767. SCI also supports the standard C notation for
integer hexadecimal and octal notation.
4.6 CCCChhhhaaaarrrraaaacccctttteeeerrrr CCCCoooonnnnssssttttaaaannnnttttssss
A character constant must be surrounded by apostrophes (')
and may be one of the following:
1. a single ASCII alphanumeric or punctuation (i.e.
printable) character
2. a backslash (\) character followed by 3 octal digits
which may be used to represent any one byte value
SCI Users Manual Copyright (C) 1986, Bob Brodt
Language Summary 21
3. a backslash followed by one of the characters n, r, b or
t which represent the <LINEFEED> (a.k.a. "newline"),
<RETURN> (carriage return), <BACKSPACE> and <TAB>
characters respectively
The following are examples of valid character constants:
'A' the ASCII character "A"
'\177' octal character
'\n' newline
'\r' carriage return
'\b' backspace
'\t' horizontal tab
'\\' the backslash character
'\'' the apostrophe character
4.7 SSSSttttrrrriiiinnnngggg CCCCoooonnnnssssttttaaaannnnttttssss
Strings may include any of the character constants mentioned
above, as for example:
"this is a string\007\n"
Strings always include a null (zero) byte, marking the end
of the string. A zero-length string may be written as two
consecutive quotes, thus: "". A string is always terminated
by either the matching right quote or end of line; strings
may not be continued on the next line as in standard C.
4.8 DDDDaaaattttaaaa TTTTyyyyppppeeeessss
Only the "char" and "int" data types are supported.
Characters (char's) are 1 byte and integers (int's) 2 bytes
in length. Both are treated as signed quantities. Chars may
range in value from -128 to +127, ints range from -32768 to
32767.
SCI also supports pointers and single dimensioned arrays of
both char and int. Pointers require 2 bytes of storage.
char *cp;
int ip[];
int array[10];
Pointers to pointers (to pointers, to pointers, etc.) and
single dimension arrays of pointers (to pointers, etc.) are
also supported:
SCI Users Manual Copyright (C) 1986, Bob Brodt
22 Language Summary
char **argv;
char ***etc;
int *array_of_ptr_to_ints[20];
char **vec[20];
4.9 OOOOppppeeeerrrraaaattttoooorrrrssss
The following operators are supported. The operators are
listed from highest to lowest precedence.
Operator Summary (Part 1)
_______________________________________________________
operator meaning examples
_______________________________________________________
[] subscripting pointer[expr]
() function call expr(expr_list)
() resolve precedence ( expr )
associativity: left to right
________________________________________________________
! not !expr
~ complement ~expr
++ pre/post increment ++lvalue lvalue++
-- pre/post decrement --lvalue lvalue--
* pointer dereference *expr
& address of &lvalue
associativity: right to left
_________________________________________________________
* multiplication expr * expr
/ division expr / expr
% modulo (remainder) expr % expr
associativity: left to right
_________________________________________________________
+ addition expr + expr
- subtraction expr - expr
associativity: left to right
_______________________________________________________
SCI Users Manual Copyright (C) 1986, Bob Brodt
Language Summary 23
Operator Summary (Part 2)
_______________________________________________________
operator meaning examples
_________________________________________________________
<< shift left expr << expr
>> shift right expr >> expr
associativity: left to right
_________________________________________________________
< less than expr < expr
<= less than or equal expr <= expr
> greater than expr > expr
>= greater than or equal expr >= expr
associativity: left to right
_________________________________________________________
== equal expr == expr
!= not equal expr != expr
associativity: left to right
_________________________________________________________
& bitwise AND expr & expr
associativity: left to right
_________________________________________________________
^ bitwise exclusive OR expr ^ expr
associativity: left to right
_________________________________________________________
| bitwise inclusive OR expr | expr
associativity: left to right
_________________________________________________________
&& logical AND expr && expr
associativity: left to right
_________________________________________________________
|| logical OR expr || expr
associativity: left to right
_________________________________________________________
= assignment lvalue = expr
associativity: right to left
_________________________________________________________
4.10 CCCCoooommmmmmmmaaaa OOOOppppeeeerrrraaaattttoooorrrr
The Comma Operator (,) as used by SCI is not an operator per
se, but rather a function argument and variable seperator.
Trying to use a comma anywhere other than in function calls,
or data declarations will cause a "syntax error".
SCI Users Manual Copyright (C) 1986, Bob Brodt
24 Language Summary
4.11 PPPPrrrrooooggggrrrraaaammmm CCCCoooonnnnttttrrrroooollll FFFFlllloooowwww CCCCoooonnnnssssttttrrrruuuuccccttttssss
SCI supports the following programming constructs:
if ( <expression> ) <statement>
if ( <expression> ) <statement> else <statement>
while ( <expression> ) <statement>
for ( <expression> ; <expression> ; <expression> ) <statement>
switch ( <expression> )
{
case <constant expression> : <statement>
case <constant expression> : <statement>
case <constant expression> : <statement>
.
.
.
default : <statement>
}
All of these constructs require that the keyword ("if",
"while", etc.) and its associated "( <expression> )" all
appear on the same line of text. The <statement> portion
may appear on the same or on a separate line of text.
SCI's "switch" statement works slightly differently than
usual: The <expression> part following the "switch" keyword
is first evaluated. Then, reading from top to bottom, each
of the <constant expressions> are evaluated. If a "default"
is encountered before any <constant expressions> are found
that match <expression>, then execution continues with the
<statement> following the "default" keyword and all the
other "cases" are ignored. This is in contrast to standard
C that only executes the "default" statement after all
<constant expressions> have been tested.
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 25
5. LLLLiiiibbbbrrrraaaarrrryyyy FFFFuuuunnnnccccttttiiiioooonnnnssss
The "sys" keyword has been reserved by SCI as a means of
communicating between a user's program and the interpreter.
It is treated exactly as a (pre-defined) function that may
be referenced by a user program.
A "sys" call may have several arguments, the number and type
of which depends upon the integer value of the last (right-
most) argument. This right-most argument is called the "sys
number" and defines the actual function performed by a "sys"
call. To make life easier and to provide a more or less
"standard" programming environment, higher- level functions
have been wrapped around these "sys" calls - these are known
as the "Library Functions" and may be found in the standard
command shell included in the distribution disk. The "sys
numbers" and their corresponding mnemonic name are listed
below.
SCI Users Manual Copyright (C) 1986, Bob Brodt
26 Library Functions
0 version
1 fputc
2 fgetc
3 fputs
4 fgets
5 sprintf
6 sscanf
7 fopen
8 fread
9 fwrite
10 fclose
11 fseek
12 ftell
13 bdos
14 system
15 exit
16 stmt
17 totok
18 untok
19 edit
20 strcmp and strncmp
21 strcpy and strncpy
22 strlen
23 malloc
24 free
25 load
26 save
27 list
28 debug
29 dirscan
30 int86
31 memleft
The Library Functions are described below in more detail.
Some of the "sys" functions do not have a corresponding
Library Function interface in SHELL.SCI, but are described
here anyway for completeness.
5.1 aaaattttooooiiii
atoi( str )
char *str;
Converts the string "str" containing the ASCII
representation of a decimal number to an integer. The string
consists of optional leading spaces or tabs, an optional
plus or minus sign (+ or -) followed by one or more decimal
digits. Returns the integer value of the ASCII number
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 27
string.
This function does not have a "sys" call number equivalent
but rather it uses the "sscanf" Library Function.
5.2 bbbbddddoooossss
bdos( cx, dx )
int cx, dx;
Performs a call on the operating system's BDOS. The
arguments "cx" and "dx" will be copied to the machine's CX
and DX registers respectively before the BDOS call. The
function returns the value of the CPU's AX register after
the call. See your MS-DOS programmer's manual for more
details on BDOS calls.
5.3 ddddeeeebbbbuuuugggg
debug( level, check )
int level, check;
Allows a program to enable or disable the SCI debugger.
There are three levels of debug mode:
0. If "level" is zero the debugger is disabled and the
program runs normally.
1. At level 1 a running program may be halted at any time
by pressing the <ESCAPE> key. At this point the
debugger enters level 2 debug mode.
2. In level 2 mode every statement is first displayed
before it is executed, and the debugger is invoked. See
the "Debugger" section for more details.
The argument "check" is _o_p_t_i_o_n_a_l and allows you to enable or
disable memory access range checks and language syntax
compatability checks:
1. If "check" is one, SCI performs range checks on all data
fetch and store operations to ensure that the program
boundaries are not being exceeded. This is useful for
finding "bent pointers". However, if you are going to
intentionally peek and poke around in the operating
system, you will want to disable this feature. The
default setting at program startup is "enabled".
SCI Users Manual Copyright (C) 1986, Bob Brodt
28 Library Functions
2. If "check" is two, SCI points out missing semicolons
which, if you recall, are optional in SCI's dialect of
C. Also, attempts to multiply or divide a pointer by a
constant or another pointer, or to add two pointers is
not allowed.
3. If "check" is three, both of the above checks are
enabled.
5.4 ddddiiiirrrrssssccccaaaannnn
dirscan( afn, file )
char *afn, file[20];
This function will scan the disk directory for file names
that match the "ambiguous file name" given by the string
"afn". Ambiguous file names may contain "*" and "?"
wildcard characters as explained in your MS-DOS manual. The
first file name found in the directory that matches will be
copied into the buffer at "file". To continue the directory
scan and search for the next matching file name, set "afn"
equal to zero. Dirscan will return a 1 if a matching file
name was found, zero if not.
5.5 eeeeddddiiiitttt
edit( line_num, program )
int line_num
char *program
Invokes the built-in program editor, starting at the line
given by "line_num" on the tokenized program buffer
"program". Returns the new size of the program buffer after
the editing session. This function is not included in
SHELL.SCI
5.6 eeeexxxxiiiitttt
exit( value )
int value
Causes the currently executing program to return control to
the operating system. The number "value" is returned to the
operating system shell (usually COMMAND.COM in MS-DOS).
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 29
5.7 ffffcccclllloooosssseeee
fclose( channel )
int channel;
Closes a disk file previously opened by the Library Function
"fopen". Returns zero if successful, -1 on error.
5.8 ffffggggeeeettttcccc
fgetc( channel )
Reads a single character from the given channel. Returns
the character read, or a -1 on error or end of file.
5.9 ffffggggeeeettttssss
fgets( buffer, length, channel )
char *buffer;
int length;
int channel;
Reads characters from the file associated with "channel".
Characters are read from the file until either a newline is
encountered, length minus 1 characters have been read, or an
end of file is found. Returns the address of "buffer", or a
zero on end of file.
5.10 ffffooooppppeeeennnn
fopen( file_name, mode )
char *file_name, *mode;
Opens a disk file whose name is given by the string
"file_name". The string "mode" determines how the file will
be opened:
r open for ASCII read. The file MUST exist or fopen
returns an error code.
rw open for ASCII read/write. The file MUST exist.
w open for ASCII write. If the file exists, it is first
deleted.
wr open for ASCII read/write. If the file already exists,
it is first deleted.
SCI Users Manual Copyright (C) 1986, Bob Brodt
30 Library Functions
a open for ASCII write append. If the file does not
exist, it is created. If it does exist, the file
position pointer is positioned to the end of the file.
ar open for ASCII read/write append. If the file does not
exist it is created. If it DOES exist, it is opened and
the file pointer positioned to the end of the file. The
file may then be read or written.
By appending a "b" to any of the modes above, the file is
opened in BINARY mode instead of ASCII.
When a file is opened in ASCII mode, all <LINEFEED>s ("\n")
are converted to <RETURN> <LINEFEED> character pairs when
writing to the file. Similarly, <RETURN> <LINEFEED> pairs
are converted to a single <LINEFEED> character on input from
the file.
In BINARY read/write mode, no such conversions are
performed.
Returns an integer value known as a "channel". The special
channels 1, 2 and 3 refer to the standard input, standard
output and standard error files, and are initially set for
I/O on the console. The channel number must be used in all
Library calls that perform file I/O functions. A value of
zero is returned if the file could not be opened.
5.11 ffffppppuuuuttttcccc
fputc( c, channel )
char c;
int channel;
Writes the character "c" to the specified file channel.
Returns the character written, or a -1 on error.
5.12 ffffppppuuuuttttssss
fputs( string, channel )
char *string;
int channel;
Writes the string to the specified file channel. Returns
zero, or a -1 on error.
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 31
5.13 ffffrrrreeeeaaaadddd
fread( buffer, length, channel )
char *buffer;
int length;
int channel;
Reads a maximum of "length" bytes into memory at the address
pointed to by "buffer" from the open file, "channel". If
the file was opened in ASCII read or read/write mode,
"fread" only reads up to and including a newline character.
If the file was opened in binary read mode, "length" number
of characters are read if they are available. Note that
"channel" must be the value returned from a previous "fopen"
Library Function call, and the file must still be open.
Returns the number of characters that were actually read, or
0 on EOF.
5.14 ffffrrrreeeeeeee
free( memory )
char *memory
Returns to the memory pool the block of memory pointed to by
"memory" that was previously gotten from a "malloc" Library
Function call.
5.15 ffffsssseeeeeeeekkkk aaaannnndddd fffftttteeeellllllll
fseek( channel, offset, whence )
int channel, offset, whence;
ftell( channel )
These functions manipulate a file's position pointer. The
file position pointer determines where in the file the next
byte of data will be read from or written to. The argument
"channel" is the file channel number; "offset" is a byte
position offset; "whence" determines how the "offset" will
be applied to the current file position pointer. If
"whence" is zero, "fseek" will move the file position
pointer to "offset" bytes from the _b_e_g_i_n_n_i_n_g of the file.
If "whence" is one, "fseek" will move the file position
pointer to "offset" bytes from its _c_u_r_r_e_n_t _l_o_c_a_t_i_o_n, either
forward ("offset" is positive) or backward ("offset" is
negative) in the file If "whence" is two, "fseek" will move
the file position pointer to "offset" bytes from the _e_n_d of
the file. In this case, "offset" must be negative to move
SCI Users Manual Copyright (C) 1986, Bob Brodt
32 Library Functions
the file position pointer towards the beginning of the file.
Ftell simply returns the current file position.
NOTE
Because SCI supports only integer variables, these functions
may only be used on files that are smaller than 32767
characters. Standard C allows you to manipulate much larger
files.
5.16 ffffwwwwrrrriiiitttteeee
fwrite( buffer, length, channel )
char *buffer;
int length;
int channel;
Writes "length" number of characters from memory at the
address pointed to by "buffer" to the file associated with
"channel". Note that "channel" must be the value returned
from a previous "fopen" Library Function call, and the file
must still be open. Returns the number of characters
actually written if successful, or a -1 on error.
5.17 iiiinnnntttt88886666
int86( interrupt_num, in_regs, out_regs ) int interrupt_num,
in_regs[8], out_regs[8]
Performs an 8086 interrupt. The argument "interrupt_num" is
the interrupt number. Before the interrupt is issued, the
machine registers AX, BX, CX, DX, SI, DI, DS and ES are
loaded with the 8 integers pointed to by "in_regs". When
the interrupt routine returns to the program, the values of
the registers will be found at the address pointed to by
"out_regs" in the same order as "in_regs".
5.18 llllooooaaaadddd
load( file, program )
char *file, *program
Loads a program from the file whose name is pointed at by
"file", tokenizes the statements therein and places the
tokenized program at "program". Returns the size of the
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 33
resulting tokenized program. If the file could not be
found, an error message is printed on the console. This
function is not included in SHELL.SCI
5.19 mmmmaaaalllllllloooocccc
malloc( size )
int size
Main memory allocator. This function is responsible for
handing out (to programs) chunks of free memory to be used
by the program as it sees fit.
WARNING
wreckless programs that write data beyond the size of the
allocated chunk of memory will cause the allocator to loose
its mind and dole out "rotten" chunks of memory. This will
almost surely cause SCI to crash and burn. Returns a
pointer to a block of memory "size" bytes long. Be sure to
de-allocate the block using the Library Function "free" when
you're done with it, or it will be lost forever... Also, do
not use malloc to allocate memory for SCI program buffers,
or you will surely crash the system.
5.20 mmmmeeeemmmmlllleeeefffftttt
memleft()
Returns the amount of memory remaining in the program
buffer. Note that the program buffer is unrelated to the
memory pool accessed by malloc() and free().
5.21 pppprrrriiiinnnnttttffff
printf( format, arg1, arg2, ... arg8 )
char *format;
int arg1, arg2, ... arg8;
Prints a formatted string to the standard output file. The
characters in the string "format" are copied to the standard
output file. If a percent character ("%") is encountered in
the format string, it is assumed to be a conversion
specification. Each conversion specification converts
exactly one argument in the list "arg1", "arg2", ... "arg8".
Once an argument has been converted and output, it is
skipped over the next time a conversion specification is
SCI Users Manual Copyright (C) 1986, Bob Brodt
34 Library Functions
encountered. Therefore, you need just as many arguments as
you have conversion specifications (%-somethings).
The character(s) that follow a conversion specification may
be one or more of the following:
minus sign (-) Indicates that output should be left
justified instead of right justified.
zero fill character (0) The field will be padded on the left
with zeros.
field width (number other than 0) This is the minimum # of
characters output. The field will be padded with
zeros or blanks depending on the fill character
(above).
precision (. followed by a number) For numeric fields, this
is the # of decimal places to the right of the
decimal point. For string fields, at most that many
characters of the string will be output.
conversion code (the letter d, u, x, o, b, s or c) A
conversion code indicates the type of conversion
that is to be done on the argument as follows:
d - convert to a decimal (base 10) number
u - unsigned decimal number
x - hexadecimal (base 16) number
o - octal (base 8) number
b - binary (base 2) number
s - string constant
c - single ASCII character
5.22 ssssaaaavvvveeee
save( file, program )
char *file, *program
Saves a program in its tokenized form at "program" to the
file whose name is in the string "file". Returns the number
of bytes written to the file. If the file could not be
created, an error message is printed on the console. This
function is not included in SHELL.SCI
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 35
5.23 ssssccccaaaannnnffff
scanf( format, arg1, arg2, ... arg8 )
char *format
int arg1, arg2, ... arg8
Reads characters from the standard input file and converts
them using the conversion string "format" (same as for
Library Function "printf"). The arguments "arg1", "arg2",
... "arg8" must be pointers to the appropriate data types.
5.24 sssspppprrrriiiinnnnttttffff
sprintf( buffer, format, arg1, arg2, ... arg8 )
char *buffer, *format
int arg1, arg2, ... arg8
Performs formated conversion of the arguments, exactly like
the Library Function "printf()", but writes its output to
the "buffer" instead of the standard output file.
5.25 ssssssssccccaaaannnnffff
sscanf( buffer, format, arg1, arg2, ... arg8 )
char *buffer, *format
int arg1, arg2, ... arg8
Performs formated input conversion of the arguments, exactly
like the Library Function "scanf()" but reads its input from
the "buffer" instead of the standard input file.
5.26 ssssttttmmmmtttt
stmt( line, program )
char *line, *program
Hands a C statement off to the interpreter for execution.
The statement is in its untokenized form at "line". The
program, also in tokenized form, at "program" is used by the
interpreter to satisfy any global variable or function
references made by the statement. This function is not
included in SHELL.SCI
SCI Users Manual Copyright (C) 1986, Bob Brodt
36 Library Functions
5.27 ssssttttrrrrccccmmmmpppp,,,, ssssttttrrrrnnnnccccmmmmpppp
strcmp( string_1, string_2 )
char *string_1, *string_2
or
strncmp( string_1, string_2, limit )
char *string_1, *string_2
int limit
Compares (character-by-character) the two strings. The
comparison stops when a zero is encountered in either of the
two strings. "strncmp" does the same thing, but at most
"limit" number of bytes are compared. Returns a 0 if the
two strings are identical, non- zero if they differ.
5.28 ssssttttrrrrccccppppyyyy,,,, ssssttttrrrrnnnnccccppppyyyy
strcpy( string_1, string_2 )
char *string_1, *string_2
or
strncpy( string_1, string_2, limit )
char *string_1, *string_2
int limit
Copies (character-by-character) "string_2" into "string_1".
The functions stops after the first null character is
encountered in "string_2". "strncpy" does the same thing,
but at most "limit" number of bytes are copied. Returns
nothing interesting.
5.29 ssssttttrrrrlllleeeennnn
strlen( string )
char *string;
Returns the number of characters in the given string,
excluding the string's trailing zero byte.
5.30 ssssyyyysssstttteeeemmmm
system( command_string )
char *command_string;
SCI Users Manual Copyright (C) 1986, Bob Brodt
Library Functions 37
Executes the MS-DOS command interpreter (usually the program
in COMMAND.COM) and passes it the MS-DOS command found in
"command_string". SCI remains suspended in memory in its
current state and will continue execution when the command
has completed. The return value from "system" is the
completion status of the MS-DOS program, which may be used
to test for success or failure.
5.31 ttttoooottttooookkkk
totok( sourcebuf, tokenbuf )
char *sourcebuf, *tokenbuf
Converts the C statement at "sourcebuf" to its tokenized
equivalent and places the result at "tokenbuf". Returns the
length of "tokenbuf". This function is not included in
SHELL.SCI
5.32 uuuunnnnttttooookkkk
untok( tokenbuf, sourcebuf )
char *tokenbuf, *sourcebuf
Converts the tokenized statement at "tokenbuf" to its
printable form at "sourcebuf". Returns the length of
"tokenbuf" (not "sourcebuf"!). This function is the
opposite of the "totok" function. This function is not
included in SHELL.SCI
5.33 vvvveeeerrrrssssiiiioooonnnn
version()
Returns a character string that contains SCI's program
identification and copyright notice, and the program's
current version number, namely the string:
Small C Interpreter Vr.l ddmmmyy Copyright (C) 1986 Bob Brodt
where "r.l" is the version number (release.level) and
ddmmmyy is the date of the release. This function is not
included in SHELL.SCI
SCI Users Manual Copyright (C) 1986, Bob Brodt
38 The Debuger
6. TTTThhhheeee DDDDeeeebbbbuuuuggggeeeerrrr
The Library Function "debug()" allows you to enable or
disable the SCI debuger. When the debuger is enabled in
mode 2, you can set and remove breakpoints, examine and
modify program variables and control the execution of your
program.
When the debuger is enabled, it first displays each line of
the program on the console before it is executed, followed
by its "debug>" prompt. At this point, you may either enter
another valid C statement (to display the contents of a
variable for example), or enter one of the following
commands (NOTE: all of these commands must start with a dot
(.) immediately following the "debug>" prompt to distinguish
them from a valid C statement):
.b# sets a breakpoint at a given line in your program.
The "#" symbol represents the line number at which
the program will be halted.
.B displays all breakpoints set in the program.
.c continues program execution until the next
breakpoint is encountered.
.d# deletes the breakpoint at line number "#". The
breakpoint must have been previously set with a ".b"
command.
.D deletes all breakpoints.
.e# lets you examine the program with the program
editor. Editor commands that would normally modify
the program are disabled. The editor's status line
indicates "Readonly" mode where "Insert" or
"Replace" would normally be displayed.
.g displays all of the program's global variables and
their values. If the variable is an array, its
address is printed followed by the first 10 elements
of the array.
.G same as ".g" but also displays the first line of
every function in the program along with its line
number. This is useful for locating a function in a
long program.
SCI Users Manual Copyright (C) 1986, Bob Brodt
The Debuger 39
.q quits program execution and returns to the shell
program.
.s# steps through the program without displaying each
line as it is executed. The "#" is the number of
lines to be executed before control returns to the
debuger.
.t displays the list of active functions with the
current one at the top of the list. This is handy
for finding out "how did I get here?".
.T same as ".t" but also displays each function's local
variables and their values.
<RETURN> same as a ".s1".
<ESCAPE> is used to interrupt a program while it is running
and enable the debuger. This key is active only in
debug mode 1 or 2.
If the SCI interpreter finds an error in your program, it
will automatically enable the debuger and halt the program
at the line where the error occurred. This can be a little
confusing if you are already in the debuger and you happen
to make a mistake while typing a statement for the debuger
to execute, because the resulting error message and the
"debug>>" prompt will refer to the statement you just
entered. If this happens, just hit a <RETURN> and you will
be returned to the program debug session.
SCI Users Manual Copyright (C) 1986, Bob Brodt
40 APPENDIX
A. SSSSCCCCIIII LLLLaaaannnngggguuuuaaaaggggeeee SSSSyyyynnnnttttaaaaxxxx
This appendix contains what is known as the "Backus-Naur
Form", or "BNF" of the SCI language. Named after its
inventors, BNF is a very precise description of a language
and is useful as a reference for proper syntax. The BNF of
a language may at first be a little confusing, but with
practice it can be a very natural way of expressing the
syntax structure of any language.
The following rules apply to the BNF notation in this
appendix:
1. words that appear in UPPER CASE represent key elements
of the language like the "if" and "while" keywords, or
like the symbol for multiplication (*). These types of
words are known as "TERMINALS" and can be considered to
be similar to atoms; the basic building blocks of a
language.
2. Words in "lower case" represent what are called "non-
terminals". Just as a molecule may consist of one or
more atoms, non-terminals may consist of one or more
TERMINALS.
3. the word to be defined will appear on a line by itself,
followed by a colon (:) followed by its definitions
indented below it.
4. within a definition, language elements are separated by
a space.
5. depending upon its context, a language element may not
appear at all and its definition is the special "empty"
definition.
6. the SCI-style comment mark (#) is used only to clarify a
definition and is not part of the definition
We have always been taught never to use a word we are
defining in its definition, that "recursive definitions" are
blasphemous! However when defining language syntax it is
often desirable, indeed necessary, to use recursive
definitions. Take for example the BNF description of a word
in the english language: a word may be one or more letters
strung together. More formally,
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 41
a "word" may be either:
1. a "letter", or
2. a "word" followed by a "letter"
Here we can deduce definition number 2 because the first
letter of a word qualifies as a word itself, according to
our definition 1. Even more formally,
word:
LETTER # for example the word "a"
word LETTER # for example the word "as"
We have written "LETTER" in upper case to indicate that a
letter can not be broken down any further, i.e. it is a
"TERMINAL". Similarly, "word" appears in lower case because
it can be broken down into smaller parts; it is a "non-
terminal".
Here then, is the BNF of the SCI language. Assume that you
already know what the terminals LETTER (one of: a b c...z,
or A B C...Z, or _), NUMBER (one of: 0 1 2...9), HEXDIGITS
(0 1 2...9 A B...F) and OCTALDIGITS (0 1 2...7) are.
id-list: # identifier (variable) list
empty # may be non-existent
id # or a single identifier
id-list , id # or two or more id's separated by a comma
id: # an identifier (variable)
LETTER
id LETTER
id NUMBER
hex-constant: # hexadecimal constant
0 X HEXDIGITS
oct-constant: # octal constant
0 OCTALDIGITS
dec-constant: # decimal constant
NUMBER
dec-constant NUMBER
chr-constant: # character constant
' CHARACTER '
str-constant: # string constant
" CHARACTER-LIST "
SCI Users Manual Copyright (C) 1986, Bob Brodt
42 APPENDIX
constant: # constants are all of the above
dec-constant
hex-constant
oct-constant
chr-constant
str-constant
expression-list:
empty
expression
expression-list , expression
expression:
primary
* expression
& lvalue
++ lvalue
-- lvalue
lvalue ++
lvalue --
- primary
+ primary
! expression
~ expression
expression binop expression
lvalue = expression
primary:
id # a variable
constant # a constant
( expression ) # a parenthesized expression
id ( expression-list ) # a function call
id [ expression ] # an array element
lvalue:
id # a simple variable
id [ expression ] # an array element
* expression # a pointer expression
binop: # the binary operators:
* # multiplication
/ # division
% # modulo
+ # addition
- # subtraction
<< # aritmetic shift left
>> # aritmetic shift right
< # "is less than"
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 43
<= # "is less than or equal to"
> # "is greater than"
>= # "is greater than or equal to"
== # "is equal to"
!= # "is not equal to"
& # bit-wise AND
^ # bit-wise XOR
| # bit-wise OR
&& # logical AND
|| # logical OR
declaration-list:
empty
declaration
declaration-list declaration
declaration:
type-spec declarator-list ;
type-spec:
CHAR
INT
declarator-list:
declarator
declarator-list , declarator
declarator:
ptr id
ptr id [ constant ]
ptr: # pointer operators
empty # this just means that SCI supports
* # simple pointers, or
ptr * # pointers to pointers (to pointers, etc.)
statement-list:
statement
statement-list statement
compound-statement:
{ declaration-list statement-list }
statement:
; # a no-op statement
compound-statement
expression ;
IF ( expression ) statement
SCI Users Manual Copyright (C) 1986, Bob Brodt
44 APPENDIX
IF ( expression ) statement ELSE statement
SWITCH ( expression ) statement
CASE constant : statement
DEFAULT : statement
BREAK ;
WHILE ( expression ) statement
FOR ( expression ; expression ; expression ) statement ;
RETURN ;
RETURN expression ;
function:
id ( id-list ) declaration-list statement
function-list:
empty
function
function-list function
program:
empty
declaration-list
function-list
program declaration-list
program function-list
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 45
B. EEEEddddiiiittttoooorrrr CCCCoooommmmmmmmaaaannnndddd SSSSuuuummmmmmmmaaaarrrryyyy
This is a quick reference guide for the SCI screen editor.
^Z exit
^E cursor up
^X cursor down
^S cursor left
^D cursor right
^A cursor to end of previous word
^F cursor to beginning of next word.
^R page up
^C page down
<RETURN> or <LINEFEED> Replace Mode: cursor to beginning of
next line Insert Mode: append blank line after
current line
^V toggle Insert/Replace Mode
^G delete character under cursor
^H or <BACKSPACE> delete character to left of cursor
^Y delete line
^L restore line
^Q^F find string
^Q^A find and replace string
^Q^L find next occurance of string
^Q^G go to line
^Q^S cursor to beginning of line
^Q^D cursor to end of line
SCI Users Manual Copyright (C) 1986, Bob Brodt
46 APPENDIX
^Q^E cursor to top of screen
^Q^X cursor to bottom of screen
^Q^R cursor to top of program
^Q^C cursor to end of program
^Q^B cursor to beginning of block
^Q^K cursor to end of block
^K^B mark beginning of block
^K^K mark end of block
^K^V insert block
^K^Y delete block
^K^U unmark block
^K^R read from disk file
^K^W write block to disk file
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 47
C. DDDDeeeebbbbuuuuggggeeeerrrr CCCCoooommmmmmmmaaaannnndddd SSSSuuuummmmmmmmaaaarrrryyyy
This is a quick reference guide to the SCI debuger. All
debuger commands start with a dot (.) as the first character
in the command to distinguish them from valid C statements.
.b# set a breakpoint at line number "#".
.B display all breakpoints set.
.c continue program execution to next breakpoint.
.d# delete breakpoint at line number "#".
.D delete all breakpoints.
.e# examine program with the SCI editor.
.g display global variables and their contents.
.G same as ".g" but also display the first line of
every function in the program.
.q quit and return to shell.
.s# step "#" lines without displaying each line.
.t display function call trace back.
.T same as ".t" but also displays each function's local
variables and contents.
<RETURN> same as ".s 1".
<ESCAPE> interrupts an executing program and enables
debuger.
SCI Users Manual Copyright (C) 1986, Bob Brodt
48 APPENDIX
D. DDDDiiiiffffffffeeeerrrreeeennnncccceeeessss FFFFrrrroooommmm SSSSttttaaaannnnddddaaaarrrrdddd CCCC
SCI supports a subset of the C language. There are,
however, some minor differences that have been dictated in
part by the fact that this is an interpreter. These are:
1. Program source lines are limited to 79 characters, just
to keep things simple. The editor will complain if you
try to create a line longer than 79 characters.
2. There are no #define or #include statements, simply
because there is no pre-processor!
3. Comments are introduced by the number symbol (#) and are
terminated by the end of the line. The "/*" and "*/"
combinations will only be barfed at by SCI.
4. Statements in general are terminated by the end of a
line - the semicolon required by the C language at the
end of a statement is superfluous. This restriction
imposes that an expression be completely on one line
(boooo, hissss!), however you no longer get penalized
for forgeting a semicolon (hurray, yay!). This also
implies that string and character constants are
terminated by the end of the line. In fact, if you
forget to add the terminating quote or apostrophe
delimiter, SCI will append one for you, whether you like
it or not.
5. Data variable initialization is not supported by SCI.
6. Local data variables declared inside a compound
statement within a function may not have the same name
as a previously declared local variable. A "variable
already declared" error will result. All other scope
rules apply.
7. The logical AND and OR operators (&& and ||) evaluate
both of their operands, unlike standard C which stops
evaluation once the truth or falsehood of an expression
is known. Watch out for subtle errors, like in the
following example:
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 49
var = 0;
if ( var && func() )
.
.
.
here the function "func()" would never be called in
standard C, but in SCI's dialect, it is called.
8. The comma operator is recognized only when used in
function calls and data declarations. For instance, it
would be illegal to say:
while ( argv++, argc-- );
9. The "default" statement inside a "switch" is executed as
soon as it is encountered (when scanning from the top to
the bottom of the "switch"). SCI is too lazy to do an
exhaustive test of all "case"s before executing the
"default", so be sure to place all "default"s as the
last statement in the "switch".
SCI Users Manual Copyright (C) 1986, Bob Brodt
50 APPENDIX
E. EEEErrrrrrrroooorrrr MMMMeeeessssssssaaaaggggeeeessss
When SCI detects an error in your program, it will stop
execution, display an error message and then the line number
and program text of the offending line. The SCI debuger is
then automatically enabled. The possible error messages are
listed below:
no entry point - You forgot to specify an entry function
with the "entry" keyword in your shell file.
out of memory - There was insufficient free memory
available for the shell program, variable, function
and stack segments. Specify a smaller -P, -V, -F or
-S value.
file error - The specified program file could not be
loaded, or SHELL.SCI does not exist on the default
disk drive, or the specified file could not be save
on disk because of an operating system error.
missing '}' - The interpreter wandered off the edge of your
program because you forgot a closing brace.
missing operator - The interpreter found two consecutive
operands as for example the statement: var 3;
missing ')' or ']' - Mismatched left and right parentheses
or brackets were detected.
not a pointer - A simple "char" or "int" variable or a
constant expression was used as an array or pointer.
syntax error - An error was detected in the structure of a
statement or function.
lexical error - An illegal character was found in a
statement.
need an lvalue - An attempt was made to assign a value to a
constant or an array variable.
stack underflow - Something is wrong! Contact the author.
stack overflow - The expression is too complex or function
calls are nested too deeply. Try specifying a
larger -S value when starting up SCI.
SCI Users Manual Copyright (C) 1986, Bob Brodt
APPENDIX 51
too many functions - The interpreter ran out of Function
Table space. Try specifying a larger -F value when
starting up SCI.
too many variables - The interpreter ran out of Variable
Table space. Try specifying a larger -V value when
starting up SCI.
stmt outside of function - There is something wrong with
the structure of your program. Typically this
results from a statement appearing outside of any
function body, or mismatched curly braces (}).
missing '{' - The left brace that introduces a function
body was missing.
bad sys call - The number of arguments passed to a "sys"
call is incorrect for the specified "sys" number, or
an invalid "sys" number was given.
undeclared variable - A variable has been used without ever
having been declared.
variable already declared - An attempt was made to re-
declare a variable name within the program or
function.
interrupt - The program was interrupted by pressing the
<ESCAPE> key.
multidimension arrays not supported - Just what it says: we
don't do multi dimensional arrays.
illegal pointer operation - A mathematical operation other
than addition or subtraction was attempted on two
pointers or a pointer and an integer.
invalid data address - The program attempted to access
memory outside of the program, variable or stack
space and the debug level was 1 or greater. If you
have confidence that your program will not corrupt
the operating system by wanton POKEs of data, you
may set the debug level to zero to disable this
error checking.
not a structure or union - A variable that was not declared
as a structure or union was used in a structure or
union reference.
SCI Users Manual Copyright (C) 1986, Bob Brodt
52 APPENDIX
compatability error - A semicolon was omitted, or a similar
type of error was detected that would cause
compatability problems with standard C.
SCI Users Manual Copyright (C) 1986, Bob Brodt
CONTENTS
1. Introduction........................................ 1
1.1 Starting Out.................................. 2
1.2 Memory Allocation............................. 3
2. The Shell........................................... 4
2.1 Shell Commands................................ 4
2.2 Running Your Program.......................... 6
2.3 Program Variables............................. 6
3. The Editor.......................................... 8
3.1 Keys.......................................... 8
3.2 Screen Layout................................. 8
3.3 Screen Customization.......................... 9
3.4 Keyboard Customization........................ 11
3.5 Sample Configurations......................... 12
3.6 Editor Commands............................... 14
4. Language Summary.................................... 19
4.1 Line Terminators.............................. 19
4.2 Comments...................................... 19
4.3 Identifiers................................... 19
4.4 Keywords...................................... 20
4.5 Numeric Constants............................. 20
4.6 Character Constants........................... 20
4.7 String Constants.............................. 21
4.8 Data Types.................................... 21
4.9 Operators..................................... 22
4.10 Comma Operator................................ 23
4.11 Program Control Flow Constructs............... 24
5. Library Functions................................... 25
5.1 atoi.......................................... 26
5.2 bdos.......................................... 27
5.3 debug......................................... 27
5.4 dirscan....................................... 28
5.5 edit.......................................... 28
5.6 exit.......................................... 28
5.7 fclose........................................ 29
5.8 fgetc......................................... 29
5.9 fgets......................................... 29
5.10 fopen......................................... 29
5.11 fputc......................................... 30
5.12 fputs......................................... 30
5.13 fread......................................... 31
5.14 free.......................................... 31
- i -
5.15 fseek and ftell............................... 31
5.16 fwrite........................................ 32
5.17 int86......................................... 32
5.18 load.......................................... 32
5.19 malloc........................................ 33
5.20 memleft....................................... 33
5.21 printf........................................ 33
5.22 save.......................................... 34
5.23 scanf......................................... 35
5.24 sprintf....................................... 35
5.25 sscanf........................................ 35
5.26 stmt.......................................... 35
5.27 strcmp, strncmp............................... 36
5.28 strcpy, strncpy............................... 36
5.29 strlen........................................ 36
5.30 system........................................ 36
5.31 totok......................................... 37
5.32 untok......................................... 37
5.33 version....................................... 37
6. The Debuger......................................... 38
A. SCI Language Syntax................................. 40
B. Editor Command Summary.............................. 45
C. Debuger Command Summary............................. 47
D. Differences From Standard C......................... 48
E. Error Messages...................................... 50
- ii -
