Socket Script Manual

                    Release version 1.16 - Feb 1999
                    -------------------------------





                          Table of contents
                          -----------------

1  -  Introduction

2  -  Installation
 2.1  -  Getting Socket Script
 2.2  -  Uncompressing
 2.3  -  Configuring
 2.4  -  SOCKS5 support
 2.5  -  Compiling

3  -  Getting started
 3.1  -  Interpreter
 3.2  -  Composer
 3.3  -  Debugger
 3.4  -  Enterprise Remote Script Serving
 3.5  -  Getting your hands in Socket Script coding

4  -  Functions
 4.1  -  Commands
 4.2  -  Variables
 4.3  -  Libraries
 4.4  -  Adding commands to SScript
 4.5  -  DES encryption
 4.6  -  SSL support
 4.7  -  PGP encryption

5  -  Getting help

A  -  Release and technical notes

B  -  Contact information

C  -  Error codes

D  -  Legal notice



-----------------------------------------
1                            Introduction
-----------------------------------------

Socket Script is a simple scripting language to access sockets. It was 
designed to provide users with a quick and easy scripting language to
make powerfull networking applications, without the need to learn C or 
complicated socket code. You can easily learn it by reading the tutorial
and using this file as reference. It can be used for functions including
retrieving web pages, making an IRC bot, information server, redir
program, network monitor tool, online forms, web server, ICMP watcher,
and many more. It was made to do simple or complex scripts that use the
network. Socket Script is always under development, so please contact me
if you find any bug. Note that Socket Script is a language, while the
sscript binary is the language interpreter. Main Socket Script functions
are available as a C library on the SScript web page for those who wants
to code in C.


-----------------------------------------
2                            Installation
-----------------------------------------
2.1 Getting Socket Script

Socket Script (also called SScript) is available for free on the web.
You can use any browser to go on the main SScript page at:

http://devplanet.fastethernet.net/sscript.html
or http://mirrors.darkelf.net
or ftp://sunsite.unc.edu/pub/Linux/devel

You can use 'Lynx' to see our web site from the command line. Or, if you
use a GUI, 'Xmosaic' is available from NCSA, or 'Netscape Navigator'
from www.netscape.com

The systems where SScript was tested on are Linux ELF 2.x, Solaris 2.5.x,
BSD/OS 3.0, FreeBSD 2.2.x and Windows 95/NT. Note that the Windows 95/NT
(also called win32) is far from being 100% compatible with the functions
in the Unix version. See the win32 documentation for win32 help.

You can also order a CD-ROM (ISO9660 CD) from DevPlanet. See Appendix B
for contact information.

The CD-ROM contains binaries and source for all the SScript releases in
/sscript/binaries and /sscript/source.

2.2 Uncompressing

Once you have the latest SScript .tar.gz file, you can uncompress it with
the following command:

gzip -d sscriptX.XX.tar.gz
tar -xvf sscriptX.XX.tar

Where X.XX is the version number.

2.3 Configuring

When SScript is uncompressed, you need to configure it to check your
system and your preferences. To do this, simply type in:

./configure

This will launch a configuration program that will ask you a few
questions on how you want to compile Socket Script. The first asks you
for your platform. You can find this out by typing, in the shell:

uname

The second asks you if you want to compile as a graphical application, or
as a console (text only) application. For graphical application you need
to have access to the X-Window system, and have the GTK library
available at

http://www.gtk.org

SScript was made with GTK 1.0.x, but should work with future versions.
Then it will ask you some questions on what to include in SScript.

When the config is done, it will create two files: config.h and
Makefile. You then may want to customize your config.h and sscript.h by
editing them in the directory /src.

2.4 SOCKS5 support

SScript can be easily made to work with a SOCKS5 proxy server. You need
the SOCKS5 package (which is available from www.socks.nec.com) installed
on the system, and the file /etc/libsocks5.conf configured like, for
example:

socks5 - - - - <ip of proxy server>

Ask your system admin to do this if you aren't root. You also need to
tell the SScript configuration program that you want SOCKS5 support.

2.5 Compiling

When the config is done, you can compile SScript by typing:

make

It can possibly print a few warnings on your screen, but it shouldn't
have any error. If there are errors, you can contact me about it (see
Appendix B).


-----------------------------------------
3                         Getting started
-----------------------------------------
3.1 Interpreter

To start SScript type:

./sscript

Note that SScript is a multi-languages program. You can change the
language with the LANG environment variable with the following command:

setenv LANG english

or

export LANG=english

depending on the shell you're using.
The supported languages are english, french and spanish.

This program reads the file sscript.file when you start it up, or you
can specify a script or project file in the command line. If you specify
a project file, it must be name.prj and it must contain a list of script
you want SScript to merge, one after the other, in the following syntax:
$include script-name. See example.prj for details about project files.
There are many examples with this version of SScript that you can use to
create your own applications.

I suggest you begin by simply trying the examples, then looking at how
they were made:

./sscript ./examples/<example name>

Where <example name> is the example you want to try.

SScript logs by default in sscript.log. It also has a few other command
line commands, including the composer and debugger, as you will see
below. Use:

sscript -help

for a complete list.

3.2 Composer

SScript comes with a composer. This is a graphical frontend that allows
you to write scripts. You can write your scripts with any text editor,
but in the case where you don't have one handy, you can always use the
SScript composer. To start it, type:

./sscript -c <script name>

This will load <script name> into the composer and allow you to edit,
add, remove and modify text in it. The main menu of the composer has a
File menu, and menus for all kind of commands you might want to add to
your script. In the File menu, you can save the script, or quit the
composer. The other menus are subjects regrouping multiple commands. By
clicking on one command, the composer will add it to the text, at your
current position. Note that all commands are not in those menus, and you
should check with:

sscript -help index

for a complete list.

Here are the keyboard commands you can use from within the composer:
ctrl+a               go to begining of line
ctrl+e               go to end of the line
ctrl+c               copy
ctrl+v               paste
ctrl+d (or DEL)      delete a char
ctrl+k               remove a line
ctrl+w               delete the selected text

Note that the composer only works as a graphical function, so if you try
to start it in console mode, SScript will simply start the editor
specified in config.h

3.3 Debugger

SScript has a debugger that will check a script for a few common
mistakes. You can use it with the following command:

./sscript -d <script name>

Note that the debugger only checks a few possible errors, and is not a
fail safe device.

3.4 Enterprise Remote Script Serving

For companies and organizations that need to keep every system with
up-to-date scripts, it is often too long to upload a script every day
to every system. That's why a user can use the -r command to make
SScript fetch a script from a remote server:

./sscript -r <remote server IP> <remote port> <script to fetch>

On the server, the script sscript.script-serving must be running. This
script will serve any script requested by anyone connecting on the port
set in this file.

3.5 Getting your hands in Socket Script coding

Socket Script was made to be simple, easy and powerfull. Here are the
main areas of programming you might need to use, and how to do it in
Socket Script.

* The header

The header of sscript.file must always begin with the server, port, 
debug, chop and virtual commands. They define the basic features of what
your script will do. They say if you want to connect somewhere, wait for
clients, or stay connectionless. They also say if you want to enter debug
mode, chop the end for all input gathered from the network, and bind to a
virtual IP.

* Files

SScript has multiple commands to access files. For input, for example,
you can use sequential input with the 'file access' command, or random
input with the 'input' command. The 'save' command is used to save files.
The log is also a file, and you can interact with it with the 'addlog'
command.

* Networking

Networking is obviously the main part of SScript. Basic commands includes
'read' and 'write'. These commands are used to read and write data on the
main connection, the one you open in the header by the 'server' command.
You can also open an other connection with the 'rconnect' command, and
access it with the 'rread' and 'rwrite' commands. There are also a lot
more functions including 'remoteip', 'udpsend', 'resolve', 'redir' etc.

* System

You can get simple system information with the 'sysinfo' and 'procinfo'
commands, although they only work on Linux systems. You can also use
'servicename' to get the port number for a service name, or use the
'uname' command to get the OS version and info.

* Graphics

SScript supports both console graphics with curses and X Window graphics
with GTK. Both are libraries that you can include at compile time and
access with the 'draw' and 'gui' functions.

* Extensions

SScript has support for a lot of extensions, either with shared libraries
that you include at compile time, or with shell commands. It provides,
for each of them, a set of commands that will interact with the right
C libraries and functions to do what you want to do. So all you have
to do is download and install the libraries, and you don't have to learn
how to work with each of them like you would in C, since SScript does the
work for you. For example, you can access PGP, SNMP, DBM, sound, modem
and compression functions with libraries or binaries.

* System dependant commands

Socket Script is being developed on a Linux system, and some functions
unfortunatly are made Linux specific, either because I don't know how to
make them work on other Unix systems, or because they use a library that
was made only for Linux. Fortunatly, they are few, and the majority of
functions will work on any Unix flavor with no or few changes.


-----------------------------------------
4                               Functions
-----------------------------------------
4.1 Commands

The header of sscript.file must always begin with the server, port,
debug, chop and virtual commands. The error handling has changed, and
now an error code is reported at every single error or warning. You can
get the last error reported with the lasterror command. You should check
often enough to see if something failed. Error codes are in apx C.
Also, a few commands return error notices in their returns variable. 
See the examples to know which ones. Note that you have 1000 variable
numbers available, from 1 to 1000, of 512 bytes each. Variable number 0
contains the command line arguments. Also note that if you do not
provide the right number of parameters for a command, the script will 
crash. Here are the commands:

server <ip> ;
Tells the program what IP to connect to. Enter 0 there if you want to
use SScript as a server, or "no-connection" (without the quotes) for
a connection-less script. See sscript.server for more.

port <port> ;
Tells the program what port to connect to.

debug <mode> ;
If mode is 1, the program will output everything it reads to the
screen. Default use should be mode 0.

chop <mode> ;
Tells the program to chop the last char of a string. You choose this
option depending on what kind of server you need to connect to. Use
mode 1 for IRC servers, and mode 0 for WEB server and most others.

virtual <ip> ;
Binds to a virtual IP if available. If no virtual IP is available,
simply put 0 there.

include <name> <cl binary> ;
This launch <cl binary> whenever SScript sees 'cl <name> ...' in the
script. See plugins.txt for details.

require <version> ;
Requires a Socket Script interpreter <version> or more. Version is a 2
number word, ie. 110 for version 1.10.

require-gui ;
This means that SScript must be compiled as a GUI app for this script to
work.

read <variable number> ;
Reads a line of text. Variable number is the variable to save the
line to. You have from 1 to 1000. You can always use the same, or use
different ones if you need to save something for later use.

write <string>
Sends <string> to the remote server.

print <string>
Prints <string> on the screen.

save <variable number> <file> ;
Saves the line of text in <variable number> to <file>. It overwrites
what's in the file.

append <variable number> <file> ;
Saves the line of text in <variable number> to <file>. It does not
overwrite the file.

rementry <variable number> <file> ;
Remove the lines matching the 1st word in <variable number> from 
<file>.

remove <variable number> <file> ; 
Remove the lines matching the string in <variable number> from
<file>.

version ;
Prints the version information.

ping <remote ip> ;
Used to check if the remote IP is alive. Will not return if it's
not (of if port 7 is filtered).

test <variable number> ;
Tests to see if a remote port is listening. <variable number> must
contain "<remote ip> <remote port> ;" (without the quotes). This
returns 0 if the port is listening, or -1 if not.

parse [<,<<,>>,>,!,_>,<_,%] <variable number> <char> ;
This will remove everything in the first word of <variable
number> before (<<), before and including (<), after (>>), or
after and including (>) the <char> if it exists. (!) is used to remove
every space in the string. So "this is a string" will become
"thisisastring". Can be useful for matching commands. The <_ command
puts a space *before* every <char> in the string, and the _> command
puts a space *after* every <char>. Use the % command to remove every word
in the string that match the <char>, which can be a masked word,
containing * and ? chars.

dump <variable number> ;
Writes everything from the file in <variable number>.

set <variable number> <string>
Enter <string> in <variable number> for future retrieval.

setmaster <file containing: <masked nick!user@host> ;> ;
Used mainly for IRC bots. Defines who will have access to the
ifmaster and ifmaster2 functions.

setinputchop ;
The input command chops the ending '\n' char.
 
setuserhost ;
From that point the program will try to get a nick!user@host from
what it gets from the server. Useful for IRC bots.

setservice ;
Sets the sscript to be a service server for IRC.

setreversechop ;
Puts a ' ' before a word rather than after a word when parsing a
command line.

setstrictcheck ;
Strict check for empty strings which might get the script to SEG
FAULT.

setstrictwrite ;
Don't append a space at the end of a 'write' command. Useful for web
servers mainly.

setlogfile <filename> ;
Changes the LOGFILE name. Set it to 'syslog' to make SScript log with the
syslogd facility.

settrace ;
Traces every command in trace.log for debugging purposes. Can get pretty
large.

setwindows ;
Set Windows compatibility. Unfortunatly Windows's telnet doesn't follow
normal rules and needs SScript to tell it there's a return sign AND a
new line for it to parse text properly. Turn this on if you want to make
Windows-compatible server-oriented scripts. This is not compatible with
setstrictwrite.

setsignalsoff ;
This function sets the signal handling off, so SScript won't say
anything if it dies from errors like Seg fault or Broken pipe. Useful
for server-oriented scripts.

setremoteecho ;
Make a server-oriented script return everything it reads from to the
remote host.

rconnect <variable number> ;
Makes an other connection. <variable number> must contain
"<remote ip> <remote port> ;" (without the quotes). You can then read
and write with rread and rwrite.

rread <variable number> ;
Reads from the second connection and puts the result in
<variable number>.

rwrite <variable number> ;
Writes what's in <variable number> to the second connection.

rdisconnect ;
Disconnects the other remote connection.

for <for number> <start number> to <end number> ;
This is a loop which begins at <start number> and ends at <end
number>. The current number where the loop is currently at can be
accessed with $%. You can set <end number> to -1 to get an infinite
loop.

endfor <for number> ;
Goes back to the 'for' corresponding to <for number> until <end
number> is reached.

ask <variable number> ;
Waits for input from the user.

exit [exit code] ;
Makes the program quit. The exit code is optional and for error reporting
only.

ifword <variable number> <word number> <word> <string>
This function compares 2 words. It matches <word> with the word in
<variable number> at position <word number> and if it does match, it
sends <string> to the server.

ifword2 <variable number> <word number> <word> <word number 2> <word 2> <string>
This is like ifword, but tries to match 2 different sets of words.

ifmaster <variable number> <word number> <word> <string>
This is like ifword, but the sender must also be the nick!user@host
set by setmaster. Used in IRC bots.

ifmaster2 <variable number> <word number> <word> <word number 2> <word 2> <string>
This is like ifword2, but the sender must also be the nick!user@host  
set by setmaster. Used in IRC bots.

ifmatch <variable number> <masked word> <string>
If there is a match for <masked word> in <variable number>, then
writes <string>.

?compare <variable number 1> <variable number 2> <sub name> ;
If the first word of <variable number 1> is the same as <variable number
2> then go to <sub name>.

?match <variable number 1> <variable number 2> <sub name> ;
If the masked word in <variable number 1> matches the one in <variable
number 2> then go to <sub name>.

!compare <variable number 1> <variable number 2> <sub name> ;
If the first word of <variable number 1> is NOT the same as <variable
number 2> then go to <sub name>.

!match <variable number 1> <variable number 2> <sub name> ;
If the masked word in <variable number 1> does NOT match the one in
<variable number 2> then go to <sub name>.

loop start <loop number> ;
This is used to start a loop.

loop end <loop number> ;
This is the end of the loop. When the program reaches this line, it
goes back to the right loop start ; line and loops indefinitly.

saveall <file> ;
Reads all there is to read from the server and saves it in <file>.

addlog <variable number> ;
Add to SScript's log file what's in <variable number>.

run <variable number> ;
Executes a shell command contained in <variable number>.

goto <function name> ;
Go to a function. You need to define a function with the sub
command.

sub <function name> ;
Declares a function to be called with goto to $goto.

wait ;
Makes the bot wait 1 sec. Useful for debugging purposes or if you
want to see what the program is reading.

if <variable number 1> [<,>,=] <variable number 2> <sub name> ;
Check if the number in <variable number 1> is '>', '<' or '=' than the
one in <variable number 2>. If it is, goto <sub name>.

cron <command line>
SScript will run that command line every time just before it exits. Can
be useful to restart itself when it gets a segfault or some other
error. Note that this can be a dangerous command if not used wisely. If
you run into a loop it can hang resources down. Be very careful when
using it. Also the <command line> should end with a '&' if you want
sscript to sucessfully quit.

remoteip <variable number> ;
For server-oriented scripts, set the remote IP number in <variable
number>.

random <variable number> <max number> ;
This will output a random number from 0 to <max number> in <variable
number>.

command <variable number> ;
This will make SScript execute a command line in <variable number> just
as if it was a line in the current script.

resolve [ip,host] <variable number 1> <variable number 2> ;
Resolve an IP from <variable number 1> to a host and put it in
<variable number 2>, or resolve a host from <variable number 1> to an
IP and put it in <variable number 2>.

cl <library> <args>
This loads a custom library. SScript comes currently with 1
library: the gui-tk library that provides a graphical interface
to SScript. See section plugins.txt for more.

udpsend <variable number> ;
Send an UDP message to a remote host. <variable number> must contain
'<ip> <port> <message>'.

udplisten <variable number> <port number> ;
Listens for UDP calls at the specified port and returns what it got.

icmplisten <variable number> ;
This will return the next ICMP packet it caught in <variable number> in 
the form: '<time> <type> <ip of sender> ;' See ICMP.types for 
descriptions of ICMP types. Must be run as root. This is an unreliable
implementation (mainly because of linux's include tree that prevented
some of my code to fit in...).

raw <variable number 1> <number of loops> <variable number 2> ;
This command scans an ethernet device for TCP packets. It waits for a
packet from the device in <variable number 1> (for example eth0), and 
returns it in <variable number 2> in the following format: "<source ip>
<source port> -> <dest ip> <dest port> ;" It does this <number of loops>
times. If the number of loops is more than 1, <variable number 2> is
overwrited at every new packet. This can be useful to monitor packets
and check for remote addresses that access the system. Note that sscript
must be run as root and it only works on Linux for now.

rawp <variable number> <number of loops> ;
This does the same as raw, but prints the result directly to the screen.

msgbox <variable number> ;
Show an info box with the string in <variable box>. You must have
specified the graphical mode in the config.

query <variable number 1> <variable number 2> ;
Asks the user a question, showing the string in <variable number 1> as
the question, and storing the user's input in <variable number 2>. You
must have specified the graphical mode in the config.

viewfile <file name> [-query <variable number>] ;
Open a text box to view the whole content of the file <file name>. You
must have specified the graphical mode in the config. If you add the
-query option, SScript will also ask the question in <variable number>
to the user, and put his answer in <vairable number>. You need graphical
mode for this.

choicebox <variable number> <button 1> <button 2> ... | <label>
The choicebox command will popup a window to the user and ask him the
question <label>, with buttons for him to choose an answer. There can be
up to 10 buttons, where <button 1>, <button 2>, etc are the button's
labels. The command will return the button chosen (1, 2, 3... 10) in
<variable number>. This command needs graphical mode.

devstat <device> <variable number> ;
This reports stats about a network device like eth0 or lo and reports it
in <variable number> in the following format: <device> <promisc> <up>
<pointopoint> <broadcast> <multicast> <allmulti> <no arp>. All stats are
0 for OFF or 1 for ON. See sscript.devstat for an example.

setowner <userid> ;
Sets the owner to <userid>. This can be useful for a server-side script
running as root to set its children as user 'nobody' (userid: 65534).
Must be run as root. Use carefully.

background ;
Send the script in the background. This shouldn't be use with
server-oriented scripts if you set FORK_START to ON in config.h

getenv <word> <variable number> ;
Put the environment value corresponding to <word> in <variable number>.

file <type> <variable number 1> [variable number 2] ;
Get stats about a file. <type> must be exist, size, owner, group, mode,
mtime, atime, ctime, open-r, access, open-w, open-a, write or close. The
file name must be in <variable number 1>, and it returns the expected
result in <variable number 2>. Check sscript.files for an example.

nodelay ;
Sets the connection in non-blocking mode.

constat <type> <variable number> ;
This gives connection stats about the opened socket on the <type>
requested. <type> must be type, error, recvbuf or sendbuf. The result is
a number returned in <variable number>.

lasterror <variable number> ;
This returns the last error reported.

clearlasterror ;
Clear the lasterror variable so an error that already occured isn't
catched by your script later on.

expr <variable number 1> <+,-,*,/> <variable number 2> > <variable
number 3> ;
This will add (+), substract (-), multiply (*) or divide (/) <variable
number 1> to <variable number 2>, and put the result in <variable number
3>. The numbers must be integers.

binary-send <variable number> <connection> ;
Sends the binary file in <variable number>. If <connection> is 0, it will
be sent to the main connection. If it's 1, to the connection opened by
rconnect.

binary-get <variable number> <connection> ;
Waits for a binary file and save it in the file specified in <variable
number>. If <connection> is 0, it will wait on the main connection. If
it's 1, to the connection opened by rconnect.

uu-send <variable number> ;
Uses uuencode to convert the binary file in <variable number> and send
it. Obsolete, replaced with binary-send.

uu-get ;
Get a binary file sent by uu-send. Requires uudecode. Obsolete, replaced
with binary-get.

chdir <variable number> ;
Change the current directory to the path in <variable number>. Note that
you must start the script with an absolute path if you use the chdir
command.

input <variable number 1> <variable number 2> <variable number 3> ;
This reads a line number <variable number 2> from the file in <variable
number 1>, and put it in <variable number 3>.

uname <variable number> ;
This will provide the same information as the Unix shell command
'uname'. It will put in <variable number> the system's OS, name,
release, version, machine and domain.

firewall [add|rem] [allow|deny] <source ip> <destination ip> <port> 
<protocol>
This command is a simple frontend for the system's ipfwadm(8) command.
It will add or remove a firewalling rule allowing or denying <source ip>
to send packets to <destination ip> to <port>, using <protocol>. The
last 4 parameters can be the keyword 'ALL' meaning all IPs, ports or
protocols. Protocols available are TCP, UDP and ICMP. Usualy,
<destination ip> is your own IP, or ALL. You must be root to use this
command, and you must have the binary ipfwadm on the system, at the path
defined by IPFW in config.h

textbox <file name> ;
This command allows people to type in a graphical text box, and the text
is saved in <file name>. SScript needs to be compiled in GUI mode for
this to work.

sysinfo <variable number> ;
This returns information on the system. It returns the uptime, 1min load
average, 5mins load average, 15mins load average, total RAM size, free
RAM size, shared RAM size, memory in buffers, total swap size, free swap
size, number of processes running in <variable number>. This command
only runs on Linux systems.

varlenght <variable number 1> <variable number 2> ;
Calculates the number of chars in the first word of <variable number 1>,
and puts the result in <variable number 2>.

users <variable number 1> <variable number 2> ;
This command returns information from the system password file about a
user and should be used carefully. <variable number 1> must contain
"[NAME|UID] <string>" where string is either a login name, or a user id.
This returns the "<login name> <user id> <group id> <password> <user
path>" in <variable number 2>, without the quotes of course.

encryptfile <variable number> ;
This function uses the DES encryption utility to encrypt a file.
<variable number> must contain: "<file name> <key> ;" without the quotes,
where <file name> is the file to encrypt and <key> is a 8 letters or less
key to encrypt it. The encrypted file name will be added a .des
extention. The file can then be sent somewhere with binary-send. See
section 4.5 for more about SScript's encryption and where to get the DES
binary.

decryptfile <variable number> ;
This decrypts a file that was encrypted with encryptfile. The syntax of
<variable number> is the same. Do not put .des in the <file name>, this
function will add it automaticly. See section 4.5 for more about
SScript's encryption and where to get the DES binary.

timer <time> <variable number> ;
This command changes the variable <variable number> from 0 to 1 when
<time> seconds have passed.

math <variable number> [LOG|LN|E|SQRT|EXPR] <number> ;
This will calculate the log, natural log, e raised to the power of, and
square root of <number>, and put the result in <variable number>. EXPR
works the same way as the expr command, with <variable number 1>
[+,-,*,/] <variable number 2>.

password <variable number> ;
Asks for a 8 chars password on the screen, without returning the echo,
and puts it in <variable number>.

draw [INIT|SET|UNSET|PRINT|BEEP|REFRESH|ASK|CLEAR|ERASE|GOTO|COLOR|BOX|DELBOX|BREFRESH|PRINTBOX|END|LINES|COLS] <args...>
The draw command enables you to use formatted text in console, text-only
mode. You need to INIT it at first, and END it at the end. You can SET
and UNSET BOLD, UNDERLINE, BLINK, NORMAL, REVERSE or DIM. You can print
in it with PRINT  <x location> <y location> <variable number>. No change
you make is actualy made on the screen until you REFRESH the screen. You
can also use the COLOR GREEN, RED, WHITE or CYAN. ASK <variable number>
will wait for user input. You can also make a window with BOX <number of
cols> <number of lines> <x location> <y location>, print in it with
PRINTBOX <x location> <y location> <variable number>, and refresh the
window with BREFRESH. Everything is based on curses or ncurses, so you
need that library on the system to use this command. You also need to
include the curses or ncurses library in SScript for this to work. See
the example sscript.draw. LINES and COLS return the number of lines and
columns of the current terminal.

utime <variable number> ;
Copies the current time in UNIX-time format in <variable number>.

wordlength <variable number 1> <variable number 2> ;
Returns the number of words (where word is anything with separed with a
space) in <variable number 1> and puts the result in <variable number 2>.
Returns 0 if no word is there.

varchop <variable number> ;
Removes the last char from <variable number>.

clear ;
Clears the screen using the shell command 'tput clear'.

servicename <name> <variable number> ;
Request the port number for service <name>.

ascii [TOUPPER|TOLOWER|ISNUMBER] <variable number 1> <variable number 2> ;
Converts the input string into all upper-case chars (toupper) or all
lower-case chars (tolower), or return 1 if <variable number 1> begins
with a digit, or 0 if not. Input is <variable number 1> and the result is
<variable number 2>.

cwd <variable number> ;
This command returns the current working directory.

redir ;
This command makes a redirect between the main connection and the remote
connection (rconnect). Both connections must be open. See sscript.redir
for an example.

listen <variable number> ;
This commands returns which of the connections, the main one or the
remote one (rconnect), is ready for reading. Note that you should prefer 
the 'redir' command rather than this to make a redirect program. Both
connections must be opened. Returns 1 in <variable number> if the main
connection is ready for reading (read), returns 2 if the remote
connection is ready for reading (rread), or returns 0 if an error
occured, or no connection is ready. Can block if not ready.

multilisten <mode> <variable number 1> <variable number 2> ;
This command is used to wait for input on 2 connections. If <mode> is 1,
it will wait for input from the keyboard and from the main connection. If
<mode> is 2, it will wait for input from the keyboard and from the second
connection (rconnect). If <mode> is 3, it will wait for the main and
second connection. When it reads something on either connection, it will
return which one in <variable number 1>, 1 being the first choice and 2
the second, and the actual read data in <variable number 2>.

zipstring <variable number> <file name> ;
Takes the content of a variable and compress it into file <file name>.
Requires SScript to be compiled with LIBZ.

unzipstring <variable number> <file name> ;
Uncompress <file name> and puts the line of text in <variable number>.
Requires SScript to be compiled with LIBZ.

http <command> <variable number> ;
Executes an HTTP related command. Available commands for now are 'html'
and 'js <script> <file>'. The html command takes the line in <variable
number> and prints it in text-only mode, interpreting HTML tags. See
sscript.web for examples. The js command is used to make a very simple
sample html page with JavaScript in it. Supported scripts are 'scrolling'
and 'entry'.

modem [dial|write|read|hangup] <variable number> ;
You can dial to the phone number in <variable number>, write the string
in <variable number>, read and put the input in <variable number>, or
hangup the modem. Needs libmodem and a proper /etc/modems.

snmp <hostname> <community name> <query object> <variable number> ;
Queries the <hostname> SNMP deamon, using <community name> for <query
object> and returns it in <variable number>.

zipfile <in file> <out file> ;
This will compress the <in file> into <out file> using the gzip
compression format.

unzipfile <in file> <out file> ;
This will uncompress the <in file> gzip file into <out file>. 

?compareword <variable 1> <word 1> <variable 2> <word 2> <sub name> ;
If <word 1> from <variable 1> is the same as <word 2> in <variable 2>,
then goto <sub name>.

!compareword <variable 1> <word 1> <variable 2> <word 2> <sub name> ;
If <word 1> from <variable 1> is not the same as <word 2> in <variable
2>, then goto <sub name>.

gui <args...>
With the GUI command, you can make your own graphical window with
buttons, an entry box, a text box, separators, and labels. You must begin
with gui main and end with gui show. Before using an horizontal control,
gui hbox must be used. Here are the available arguments for the gui
command:
gui main <title>
This is used to begin the GUI building process.
gui size <horizontal size> <vertical size> ;
This command sets the window size.
gui position <horizontal> <vertical> ;
This sets the window's position on the screen.
gui toolbar ;
This is used to make a toolbar of buttons, and should be considered as 
horizontal.
gui label [horizontal|vertical] <label>
This command shows <label>, lined up horizontaly or verticaly.
gui textbox [horizontal|vertical] ;
This shows a textbox.
gui insert <variable number> ;
This command inserts what's in <varable number> in the text box, or an
end-of-line is <variable number> is EOL.
gui text-editable ;
Set the textbox editable by the user.
gui hbox ;
Sets the [horizontal] feature possible.
gui entry [horizontal|vertical] ;
This shows an entry box for user input.
gui button [horizontal|vertical] <button number> <label>
This will show a button, and when pressed, <button number> is returned.
gui icon [horizontal|vertical] <button number> <xpm file name> ;
This will show a button with the image in <xpm file name>.
gui show <variable number> <file name> ;
This will show the whole window and wait for user input. When a button is
pressed, <variable number> will return the button number, and the content
of the entry box, if one was used. The content of the textbox, if
used, is put in <file name>.
For an example, see sscript.gui in the examples directory.

pgp <args...>
This command is used to call the PGP binaries to encrypt and decrypt
files to allow secure sending over the Internet. See section 4.7 on how
to setup PGP. Here is how to use the PGP command:
pgp generate <output file> ;
This is used to make your private and public keys so someone can send you
encrypted messages. Your public key will be put in <output file> so you
can publish it.
pgp add-key <location> ;
This is used to add someone else's public key to encrypt files so that
person can decrypt them. <location> is a file containing the key, or an
URL.
pgp encrypt <user id> <file> ;
This is used to encrypt <file> using <user id>'s public key (that you
added with add-key previously, of course). The resulting encrypted file
is saved under <file>.asc in text-only format.
pgp decrypt <in file> <out file> ;
This will decrypt <in file> and save the result in <out file>.

say <variable number> ;
Say the string in <variable number> on the speakers. This assumes that
you have access to /dev/dsp and that you said yes in the configure
choice.

db <args...>
This command is used to access GDBM databases. SScript must be compiled
to support it for this command to work. Here are how to use it:
db open-write <file name> ;
Open a database file for writing.
db open-read <file name> ;
Open a database file for reading.
db close ;
Close the opened database.
db insert <key> <data> ;
Insert <key> with corresponding <data> in a database opened for writing.
db get <key> <variable number> ;
Get the data corresponding to <key> and put it in <variable number>.
db delete <key> ;
Delete <key> from the database.
See sscript.dbm for an example.

printparams ;
Print the current settings on the screen.

rawprint <string> ;
Prints <string> with no end-of-line char.

boolean [TRUE|FALSE] ;
Set a boolean value true or false.

iftrue <sub name> ;
If boolean is true, goto <sub name>.

iffalse <sub name> ;
If boolean is false, goto <sub name>.

procinfo <variable number> <query> ;
This command looks in the Linux proc directory to get system info, and
puts it in <variable number>. <query> can be cpu, model, vendor, fpu,
totalmem, freemem, totalswap or freeswap. This only works on systems
supporting the proc file-system.

sleep <time> ;
Will halt the program for <time> seconds.

timeout <time> <variable number> ;
This command works like read and waits for data from the main connection
for <time> seconds. It returns the data in <variable number>, or
"timeout" if no data was read in the specified time.

massread <variable number 1> <variable number 2> ;
Reads from the network and dumps everything in the file specified in
<variable number 1>, untill the data matches what's in <variable number
2>.

rmassread <variable number 1> <variable number 2> ;
Reads from the second connection (rconnect) and dumps everything in the
file specified in <variable number 1>, untill the data matches
what's in <variable number 2>.

gpg <args...>
This is partial support for the GNUPG program, which is a completly
GPL'ed replacement for PGP. It is still in development and might be
unstable! Commands:
gpg generate <key file> ;
Generate a key for yourself and export it to <key file> in ascii
format.
gpg import <key file> ;
Import a public key from <key file> into your key ring.
gpg encrypt <in file> <out file> ;
Encrypt <in file> into <out file> using a key.
gpg decrypt <in file> <out file> ;
Decrypt <in file> into <out file> using a key.

return ;
Return to the line after the last goto.

4.2 Variables

There are variables available for the write, print, set, ifword,
ifword2, ifmaster and ifmaster2 functions: 

$word <variable number> <word number>
Retrieve a word from <variable number>.

$string <variable number> <word number>
Retrieve everything after <word number> in <variable number>.

$nick
Nick name who sent the line (for IRC apps).

$user
user@host who sent the line of text (for IRC apps).

$break
Breaks from a loop ie. doesn't go to loop start on the next loop
end.

$exit
Makes the program quit.

$input <file name> <line number>
Inputs a line from <file name>.

$goto <function name>
Go to a sub. Same as the goto command.

$remote <file> ;
Runs a sub from an other file.

$pid
Shows the PID number when the script is in the background.

$time
Inserts the current time.

$%
Current loop number in a for/endfor.

$\
A bold char '\002'

$/ <number>
An ansi char. <number> is the char, from 0 to 9

$_
Inserts a space.

$$
Insert the char '$'.

$l
Inserts a new line char '\n'.

$n (where n is 1 to 9)
Makes the program sleep 1 to 9 secs.

I suggest you look at the examples to get used to these commands.

4.3 Libraries

Custom libraries is the way to add more commands to Socket Script. See
plugins.txt for more details. Currently, SScript has 4 custom libraries
examples: The gui-tk which provides a graphical TK window to the scripts,
the utils lib, the ssdb for databases, and a new ssdb2 for databases.
They can be accessed using the cl command. See sscript.ssdb or
sscript.utils for an example.

* Here are the commands for the gui-tk library:
cl gui-tk <command> <args> <command> <args> ... -end

-nonblocking
Does not block the operations of the script while the window is
up. This can be useful if the window only provides information.

-info <text>
Provides a text for information.

-entry
Provides an entry. There should usually be only 1 entry per cl line.

-processbutton <name> <entry number> <variable number>
This provides a button to process the entry <entry number>. It
then puts the string in <variable number>. <name> must be 1 word.
Note that the <entry number> might be tricky. It is a number from
0, and it includes -info and buttons.

-cancelbutton <name>
This closes the GUI window when clicked.

-end
Ends the line of commands

example: cl gui-tk -nonblocking -info Enter a string -entry
-processbutton Ok 1 105 -cancelbutton Cancel -end

* here are the commands for utils cl:
cl utils <command> <args> ...

crypt <variable number 1> <variable number 2> ;
Takes the first word in the <variable number 1>, crypt it with
the Unix crypt() call and put it in <variable number 2>.

localhost <variable number> ;
Fetches the local hostname from the system and puts it in
<variable number>.

unixtime <variable number 1> <variable number 2> ;
Takes the UNIX time format in <variable number 1> and convert it into
human-readable time in <variable number 2>.

perl <variable number> ;
This will run a perl script contained in <variable number> and output
results in file ".perl.results".

* Here are the commands for the SSDB library:
cl ssdb <command> <args> ...

create <number of headers> <database name> <headers>
This is to create a database named <database name> with <number
of headers> header's and that specifies the headers. This will
overwrite any existing database by that name.

add <database name> <entry name> <variable number containing data>
This is to add data to <entry name> in <database name>.

listheaders <database name> <variable number>
This will put a list of headers in <variable number>.

list <database name> <entry name> <variable number containing the
first word of data> <variable number>
This will list all the data going with <first word of data> in
<entry name> from <database name> and put it in <variable number>.

remove <database name> <entry name> <variable number containing the
first word of data> ;
This is to remove all corresponding entries in <database name> matching
the data in <entry name>.

get <database name> <entry name> <variable containing <line number>> <variable number>
Get the data for <entry name> number <line number> from <database name>
and put it in <variable number>

Note that if you ask for an entry that doesnt exist, SSDB will return
the last entry in the file.
You can get an example in sscript.ssdb

* SSDB2 library commands:

cl ssdb2 create <database name> <variable number> ;
This is used to make a new database (and will erase any previous
database of that name) called <database name>. <variable number> must
contain "<number of cards> <field 1> <field 2> ..." where <number of
cards> is the number of cards that SScript will make, each cards
containing <field 1>, <field 2>, etc...

cl ssdb2 find <database name> <entry name> <variable number 1> <variable
number 2> ;
This will make SScript search <database name> for the word in <variable
number 1> in entries <entry name> in every cards, and will return the
card number where it found it in <variable number 2>, or "Too many
matches" if there is more than 1. Note that <variable number 1> must
contain only 1 word to look for, and that word can be masked (ie.
*w?rd*ing).

cl ssdb2 get <database name> <entry name> <variable number 1> <variable
number 2> ;
This will get the data from <database name> in <entry name> from the
card specified in <variable number 1>, and will put that data in
<variable number 2>, or "Not found" if it didn't find any corresponding 
entry.

cl ssdb2 add <database name> <entry name> <variable number 1> <variable
number 2> ;
This will add to <database name> the data in <variable number 2> to the
entry <entry name> from the card number specified in <variable number 1>.

4.4 Adding commands to SScript

The license permits you to modify SScript to fit your needs if you
follow the conditions (see appx D). But the easiest way to add commands
is with the CL interface. You can easily add Custom Libraries. See the
file plugins.txt for more.

4.5 DES encryption

Socket Script can encrypt and decrypt files using the DES encryption
binary by Eric Young. It is available from:

ftp://ftp.psy.uq.oz.au/pub/Crypto/DES

You can also include the des.c code to SScript if you keep the library on
the system on which this will be used. Also note that you must provide
the right key to decryptfile or it won't be able to decrypt it. The key
must be the same to encrypt and decrypt it, and can be a way to prevent
3rd parties to get important files you might want to send over the
network. About the legal part, the library SScript uses for encryptfile
and decryptfile has been made outside of the USA, so it will be legal in
any country. As for the USA, is *should* be legal, but I'm not 100% sure.

4.6 SSL support

At first, I wanted to add complete SSL server-side support to Socket
Script. However, 2 reasons decided me otherwise. First, the usual SSL 
port is 443 and can only be used by root. Second, since SSL is about
security, tried products like the Apache web server are best suited for
web serving.

This is how to build a secure SSL-based web server. First, get Apache,
SSLeay and the Apache+SSL patch from:

http://www.apache-ssl.org

Read the instructions with the Apache SSL patch (README.SSL) on how to
configure them. Then, configure your web server's cgi-bin directory to
/examples/web (use the complete, absolute path). Then, you need to
customize the path to your SScript directory in /examples/web/script.cgi

From the web, everything is accessed with /cgi-bin/script.cgi which in
turn calls sscript.serv. The example sscript.serv displays a simple form
to order Books. You can modify them to fit your needs. You now have a 
fully working secure SSL server running the (trusted) Apache web server,
with dynamic contents you can change with SScript scripts.

4.7 PGP encryption

Socket Script provides a simple interface to the PGP (Pretty Good
Privacy) encryption binaries. This allows you to take someone else's
public key, encrypt a file, and send this file over the network and only
that person can decrypt the file using his private key. You can also
generate yourself a private and public key so someone can take your
public key, encrypt a file, and only you can decrypt it, using your own
private key. To be able to use the pgp command, you must do 2 steps.
First, download the PGP 5.0 binary package from

http://web.mit.edu/network/pgp.html

Then, simply use pgpinst to install the binaries into place (as root,
preferably). Then you can use a SScript script to do all your PGP work.
First, you'll want to make yourself a private a public key with the 'pgp
generate' command, and publish your public key on the web, or someone
where other people that might want to send you encrypted files or e-mail
can access it. Then, use add-key to add someone else's public key to be
able to send him encrypted files, and then use 'pgp encrypt' and 'pgp
decrypt' to encrypt and decrypt files.


-----------------------------------------
5                            Getting help
-----------------------------------------

SScript has an online help system. You can access it with:

./sscript -help

Every command is in there, with its description. For a list of commands
try:

./sscript -help index

You can also go look at the FAQ on the web page for the latest news
about SScript. Also note that sscript -help contains some colors for
part of the text if you compiled as a graphical app with GTK. You can
turn the coloring off by undefining GTK_HELP_COLORS in sscript.h


-----------------------------------------
Appendix A    Release and technical notes
-----------------------------------------

In a script, if a 'read' returns an empty string, it will be
replaced with the string: <NO-STRING>

Variable numbers can contain anything from strings to numbers. When a
command expects a number and you give him a variable containing a
string, it will default to 0.

If Perl or TCL/TK GUI fails, you might need to set the right paths in
config.h

If you kill a server-oriented script running and then try to start it
again, you might get a bind error. This is because the script couldn't
close his socket correctly and can't bind the socket. Usually waiting a
few minutes before restarting it will do the trick. You can also run the
script as root (be sure to use the setowner command for security) if you
want to avoid this error.

For server-oriented scripts, Windows's telnet needs 'local echo' turned
ON unless your script pastes everything the user types, and you should
use setwindows so the display is right.


-----------------------------------------
Appendix B            Contact information
-----------------------------------------

You can send me feedback on comments, bugs reports, questions, or else
on the DevPlanet page at http://devplanet.fastethernet.net/feedback.html
or you can send me email at drow@wildstar.net


-----------------------------------------
Appendix C                    Error codes
-----------------------------------------

Every command can return an error code on failure, or warning. You can
get it with the lasterror command. Here are the possible error codes:

0 - No error
101 - File name too long
102 - GUI initialization failed
103 - Can't open file for writing
104 - Requested environment variable does not exist
105 - Not in graphical mode
106 - Setowner failed. Not running as root
107 - Can't open file for reading
108 - File doesn't exist
109 - Socket creation failed
110 - Connection failed
111 - Tried to write when the socket wasn't created
112 - This command is Linux specific
113 - Tried to get a word number beyong the end of the string
114 - Can't open LOG file
115 - Socket binding failed
116 - Message receiving failed (UDP)
117 - Can't get socket name
118 - Reading failed (ICMP)
119 - Can't get device options
120 - Cannot change directory
121 - End Of File reached
122 - Reading failed (TCP)
123 - Input line truncated at 511 bytes
124 - ZLIB error
125 - SNMP query failed
126 - GDBM file opening failed
127 - GDBM storing failed
128 - Can't open temporary file
200 - FIREWALL - No command specified
201 - FIREWALL - Wrong parameter


-----------------------------------------
Appendix D                   Legal notice
-----------------------------------------

(C) Copyright 1998-99 Patrick Lambert <drow@wildstar.net>

Socket Script is under the GPL. This applies to all Socket Script
software, documentation, source, web page and examples.

See the file docs/tech_papers/COPYING for the full GPL license.