TERMINATE, THE TOUR - PRESCRIPTION



* The world's most *
* powerful communications program *




Alt-G menu to start your scripts FAST


Demo script main screen


Demo script main menu


Editing demo script example




Back to tour back to Tour Index




DETAILED INFORMATION




PreScription, The Terminate Programming Language IN NO EVENT WILL STRATHRORY SYSTEMS LIMITED, SERWIZ COMM OR ASSOCIATES BE LIABLE TO YOU FOR ADDITIONAL DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE PRESCRIPTION OR SCRIPTS FOR PRESCRIPTION, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Terminate has an extended script programming language. It is not only designed for logging onto a system and downloading a mail package, it has been designed with a wider view in mind.

As usual Terminate throws up the ball and gives you loads of options, however if you want additional commands you cannot write yourself, then just contact us and we will try to include your suggestions.

If you have never done any programming before it might be a little difficult to start out without prober guidance, however we have included various simple examples which will help you get started more easily.

If you do not know what programming means, perhaps learning this simple, but yet powerful language can get you hook on the idea. You will not need this language unless you have special needs that Terminate cannot solve.

BUT please be aware when you start programming. Anything is possible. That means that any possible error is also possible, and as Murphy's law describes, if anything can go wrong it will go wrong. So please do not blame us if something does goes wrong.

What can a script do for me ?

A script can do many things. First of all it can automate some of your daily needs. Many would use a script language for getting onto a system and uploading and downloading mail packages or perhaps to check if there is a new filelist and download it. There are really many more things you can do easily.

Compiling scripts

Before running a script Terminate will automatically detect if it has been compiled and will compile it if necessary. The source code is in files with the extension .TSL and the compiled ready to run script is the .TSC file. It is possible to run .TSC files without having the source code. Just access the Alt-G script menu or call Terminate with the command line /SCRIPT:script to start a script.

Include files

The Include command enables you to put certain functions into smaller files or libraries if you like. Just remember that the entire contents are put into the finished compiled script.

Include SCREEN.INC

Will include the source code library called SCREEN.INC.

Language syntax

You can enter all commands or system variables in both upper, lower or mixed case. PRS will upper case everything while compiling, which means you could both enter the command "Print" or "PRINT". PRS will only keep the case of strings inside the " signs. WriteStr x,1, "Hello" would be translated to WRITESTR X,1,"Hello"

If you make an error somewhere in your code you will be told at which line the error occurred. However runtime errors will only be shown at the time the error occurs. For example division by zero will make your program abort.

Comment lines

Comment lines are used to make the source code more easily understood the next time you or somebody else have to add or change something. You could almost say the more comment lines the better, since they are not compiled into the finished module and therefore do not take up any memory. A comment can either be the only thing on the line or after a command and must start with a % sign.

Example:

% This is a comment line only.
Set Turbo = "ON" % Everything after here is comments.

As a special compiler command you can use the "Comment". In this way you can insert comments that can later be retrieved. To insert your own copyright lines you could do:

Comment "The Terminate PreScription demonstration script"
Comment "This script is (Freeware) 1995 by Bo Bendtsen"

You can use 5 Comment lines each of 50 characters.

Program structure

A program consists of functions and variables. You can have as many functions as you like and in any order you like. Making a structured program can increase speed and make it easier to change. You do not need to have functions or variables, you can simply use commands that are built in. You can start immediately without any definitions or strange syntaxes. One of the smallest scripts you can make could be one single line like this:

Print "Hello world"

Variables

A simple programming language first of all needs variables. A variable is like variable X and Y you perhaps learned about in school. It simply means a given identifier can be assigned a value. With PreScription hereafter always mentioned as "PRS" you have two kinds of variables called numbers and strings.

The limit on variables is 16000 but you will probably never need that many or you will run out of memory first and it is always considered best to use as few variables as possible.

All variables are global variables which can be accessed from all parts of the script. The syntax of a variable name is simple. It must begin with a letter from A to Z and then can be followed by A-Z,0-9,_.

Valid names: Apple Computer X X49 Cool_5_dude
Invalid names: 25XX *Hello* _NotMe

Numbers

PRS uses something called floating point numbers. These numbers are limited to 2.9e-39..1.7e38 which are very very large numbers, so you should never be concerned about using too many decimals. Please note that all decimal number must use dot (.) and not comma (,) The numbers are used for storing information and for calculating, here are a few examples that might help you understand better. Identifier Value
| |
Set Apples = 5

The variable called Apples now has the value 5. If someone eats one of the apples you can calculate:

Set Apples = Apples - 1

You now have 4 apples.

Another example to calculate how much discount you got on your new modem

Set NewModem = 495
Set Discount = 0.15
Set NewModem = NewModem * Discount

The result in NewModem would now be 74.25

Strings

Strings are characters after each other and could look like this:

"This is a string"

The " signs are to tell PRS when the string starts and stops. A string can be up to 255 characters long and can have any value from ASCII 0 to ASCII 255.

Some examples:

Set Part1 = "A Terminate "

Set Part2 = "a day keeps the doctor away"

Set Joke = Part1 + Part2
To manipulate the strings there are many commands described later in this document, please look at the examples and see how some of them work.

Arrays

You have 32 different Arrays you can use to store various tables or data. Arrays are controlled by these commands and functions. All will return a non-zero value in DosError if failed.

InitArray (Command)

Syntax: InitArray Array,Elements,ElementSize

Array 1-32
Elements 1-32500
ElementSize 1-64999 bytes

The total size of each array CANNOT exceed 65000 bytes. You can calculate the total size like this: Elements * (ElementSize+1).

Use the FreeMem function to test for free memory before initialising an array.

Example: InitArray 1,10,80
Array 1 = 10 Elements * (80 bytes + 1) = 810 bytes

PutArray (Command)

Syntax: PutArray Array,Element,Expression

Save a value in an array.

Example: PutArray 1,5,"Save Me!"

GetArray (Function)

Syntax: GetArray Array,Element

Returns the value that was saved in the array.

Example: PrintLn GetArray(1,5)

FreeArray (Command)

Syntax: FreeArray Array

Free memory and allow array to be re-used. PreScription will automatically free all arrays on exit, but for your own sake ALWAYS free an array when it is no longer in use.

Example: FreeArray 1

Example of array

Set ArrayName=1 Set name of array
InitArray ArrayName,10,100 Init array 10x(100+1) = 1010
PutArray ArrayName,1,"HELLO "+"WORLD" Set element 1 to "HELLO WORLD"
PrintLn GetArray(ArrayName,1) Print element 1 on screen
FreeArray ArrayName Free memory

Expressions and operators

An expression is made out of operators and constants or variables.

An expression could look like this:

80186 + (301 - 1)
Carrier = "ON"
28800 / 2400 * 12
X = 500 < Y

The operators PRS understands:

+ Addition < Less than
- Subtraction > Greater than
* Multiplication = Equal to
/ Division <> Not equal to
\ Mod (remainder) <= Less than or equal to
^ Power >= Greater than or equal to
& And
| Or
! Not

The various operators have different priorities in order to determine which ones to process first.

Unary operators !
Multiplying operators * \ / & ^
Adding operators + - |
Relational operators = <> < > <= >=
If you want different priorities just use the parentheses ()

20 - 2 * 5 = 10 * is higher than -
(20 - 2) * 5 = 90 () is higher than any operator.
User defined functions

Creating your own functions is useful when you do the same thing over and over again or simply want a more structured program.

A function is completely user defined and can contain either built-in commands or calls to other functions you have made.

Function CountTo100()
Set X=1
Repeat
GotoXY 1,1
Print x
Set X=X+1
Until X>100
EndFunc

This simple function does nothing other than count to 100 on the top left corner of your screen. You call the function by entering

CountTo100()

To send variables to a function you need to include the variable name in the parentheses () like this:

Function CountMore(HowMany)
Set X=1
Repeat
GotoXY 1,1
Print x
Set X=X+1
Until X>HowMany
EndFunc

Now you can count to as many as you like. Enter:

CountMore(50)

And the function will count to 50.

The harder part with understanding functions is to see how it can be used to return results. Here is an easy example.

Function HappyHour(Drinks)

Set ExtraDrinks = Drinks * 2

EndFunc ExtraDrinks

To call the function you need to display or store the return value. To display you could:

PrintLn "Normal hours I get ",5," drinks"
PrintLn "When it is happy hour I get ",HappyHour(5)," drinks"

If you want to store the result in another variable use the following:

Set DrinkResult = HappyHour(5)

A function can also return a value directly. Whatever is on the EndFunc line will be returned as the result.

Function names follow the same rules as variable names and must at least end with () if no parameter is used.

IMPORTANT: A function must be defined before it is called.

Statements

PRS supports many basic statements which will be explained below.

If Else Endif

The If statement is used for evaluating an expression. You can use it for testing if certain variables have a certain value like this:

Set Apples = 6
If Apples > 5
Print "Plenty left"
Endif

Since Apples is 6 you will see Plenty left printed on the screen. If you set Apples = 5 or less then everything will be skipped until the Endif.

An If statement must always end with an Endif command, which tells PRS that the statement stops here.

The Else statement means what it says. If the If statement is false the Else statement will be used.

Set Apples = 4
If Apples > 5
Print "Plenty left"
Else
Print "Please buy more"
Endif

Now Apples is 4 which makes the If statement false and you will see Please buy more on your screen.

Goto Labels

The Goto command is used to jump to other locations in your script. You will need to define a label which uses the following format

:LabelName

The label follow the same rules as variable names and must start with a colon :

Some examples:

:Start
:End

The Goto command syntax: Goto LabelName

:Start
PrintLn "Start"
Goto JumpJump
PrintLn "NeverMe"

:JumpJump
PrintLn "Finished"

PrintLn "NeverMe" will then be skipped. Goto command should be avoided as much as possible since it creates unstructured programs. Only use for simple small programs.

Gosub Labels Return

Gosub commands are almost the same as Functions except that you cannot send any variables or get any results back. It simply carries out a single task and returns to the previous location. If,for example, you have a menu you want to display from several places in your script using the Gosub command could save you having the same menu twice. However it is recommended to use functions which are more flexible. The Return command tells PRS to return to the next line following the Gosub.

Goto Main

:Menu
PrintLn "Start"
Return

PrintLn "NeverMe"

:Main
Gosub Menu

Loops

Loop statements are using for repeating the same commands a variable number of times, until something is true or something is false.

For Next

For is used for performing the same commands a defined number of times. For has 4 parameters that have to be given.

For Variable,Start,End,Increase

The variable is a normal variable.
Start is the starting value.
End is the ending value
Increase is the value to be increased after every Next command.
When Counter is equal to the ending value the script will proceed.

For Counter,1,10,1
PrintLn Counter
Next

Will display the numbers 1 - 10

For Counter,10,1,-1
PrintLn Counter
Next

Will display the numbers 10 - 1

While EndWhile

This loop continues until the statement is false. In other words while the statement is true all commands until the EndWhile will be executed.

Set Counter = 10
While Counter <= 20
PrintLn Counter
Set Counter = Counter + 1
EndWhile

This will print out the numbers 10-20

Repeat Until

Repeat is much like While except that Repeat continues until the statement is true.

Set Counter = 20
Repeat
PrintLn Counter
Set Counter = Counter - 1
Until Counter < 10

This will also print out the numbers 20-10

Stopping a script SHIFT-ESC, K

If your script goes into an endless loop, you can force or at least
try to stop it by first pressing Shift-Esc and then K for Kill.

Built-in commands and functions

In addition to your own variables you can use and change certain
pre-defined variables. A system function can, for example, tell you
how much memory you have left (FREEMEM). A system variable could be
ATTR which holds the current color attribute and which you can change
as you like. A command is just like a system function except that it
does not return anything.

In the following section of the manual you will find 3 things:

System commands = Executes a command only, no value returned (Command)
System functions = Executes command and returns value (Function)
System variables = Like a normal variable which can be changed (Variable)

Please note that all system variables are changed for the entire Terminate,
so be careful and if you change something, remember to set it back to the
original value afterwards. Please note the () which will be mentioned
for each description.


Screen, sound handling

Attr (Variable)

Purpose: Current screen color attribute byte. Use the T-COLOR.EXE or the
color selector inside Terminate to find the colors you need.
Returns: 0-255
Example: Set Attr = 14 Set screen attribute to yellow
Set Color = Attr Save the current attribute in variable

AttrBlock (Command)

Purpose: Fills an area on the screen with a certain attribute
Syntax : AttrBlock x1,y1,x2,y2,attribute
Example: AttrBlock 1,2,70,20,10
Fill area (1,2)-(70,20) with color attribute light green

Box (Command)

Purpose: Make a textbox on the screen using boxtypes and attributes
Syntax : Box x1,y1,x2,y2,attribute,boxtype
boxtype: 0=Blank, 1=Single, 2=Double, 3=Double top+single side,
4=Double side+single top, 5=* and -|, 6=Single top only,
7=Double top only
Example: Box 1,1,80,25,23,1
Draw a box on the screen using single boxes and gray on blue.
Notes : Attribute is same format as the Attr variable

CharBlock (Command)

Purpose: Draws a block of the same character using default attribute
Syntax : CharBlock x1,y1,x2,y2,character
Example: CharBlock 1,1,80,25,"*"
Fills the entire screen with the * character

ClearScreen (Command)

Purpose: Clears the entire screen, using the current attribute
Syntax : ClearScreen

Cursor (Command)

Purpose: Cursor control
Syntax : Cursor cursortype
cursortype: 0 = Off, 1 = On, 2 = Max
Example: Cursor 0 Turns cursor off

FillBlock (Command)

Purpose: Fill an area on the screen, with an attribute and a character
Syntax : FillBlock x1,y1,x2,y2,attribute,character
Example: FillBlock 2,2,79,24,3,"#"
Fills the area (2,2)-(79,24) with # in the cyan color

GetAttrXY (Function)

Purpose: Returns attribute byte from screen on location x,y
Syntax : GetAttrXY(x,y)
Example: Set SaveColor = GetAttrXY 79,5
Sets SaveColor to the color of 79,5 on the screen

GetCharXY (Function)

Purpose: Returns the character from screen on location x,y
Syntax : GetCharXY(x,y)
Example: Set SaveChar = GetCharXY 1,1
Sets SaveChar to the character of position 1,1 on the screen

GotoXY (Command)

Purpose: Move cursor to location x,y
Syntax : GotoXY x,y
Example: GotoXY 40,12
Goto the middle of the screen

InWindow (Variable)

Purpose: Use Window offset for certain screen commands
Returns: 0 or 1
Example: Set InWindow=0
Current window offset not used
Set InWindow=1
Current window offset used
Does not work for Print, PrintLn, GotoXY

Mouse (Command)

Purpose: Turn on/off the mouse
Syntax : Mouse action
action: 0=Off, 1=On
Example: Mouse 1
Turns on mouse

MouseDetected (Functions)

Purpose: Report if a mouse driver was detected
Syntax : MouseDetected
Returns: 0=No, 1=Yes
Example: If MouseDetected=1


MouseGotoXY (Command)

Purpose: Sets mouse to X,Y on the screen
Syntax : MouseGotoXY x,y
Example: MouseGotoXY 1,1
Move mouse to top left corner

MouseLeft (Functions)

Purpose: Report if the left button was pressed
Syntax : MouseLeft
Returns: 0=No, 1=Yes
Example: If MouseLeft=1

MouseRight (Functions)

Purpose: Report if the right button was pressed
Syntax : MouseRight
Returns: 0=No, 1=Yes
Example: If MouseRight=1

MouseWindow (Command)

Purpose: Sets coordinates where mouse is visible
Syntax : MouseWindow x1,y1,x2,y2
Example: MouseWindow 5,10,15,70
Force mouse to be inside (5,10)-(15,70)

MouseX (Functions)

Purpose: Report the X position of the mouse
Returns: MouseX
Example: If MouseX<10

MouseY (Functions)

Purpose: Report the Y position of the mouse
Syntax : MouseY
Example: If MouseY>=25

NoSound (Command)

Purpose: Turn off sound soundcard or internal speaker
Syntax : NoSound

Print (Command)

Purpose: Display a string on the screen at current cursor position
Syntax : Print expression
Example: Print "Hello world"
Displays hello on the screen
Print 25*10
Calculates result 250 and displays on screen

PrintLn (Command)

Purpose: Display a string on the screen and press enter
Syntax : PrintLn expression
Example: Same command as Print except that CR+LF is added to string

RemoveWindow (Command)

Purpose: Remove a window that was set by the Window command
Syntax : RemoveWindow
Removes top window from screen

ScrCol (Variable)

Purpose: Holds the number of columns on the screen (80)
Returns: 40-132
Example: Print ScrCol
Displays the current number of columns on screen

ScrLen (Variable)

Purpose: Holds the number of lines on the screen (25)
Returns: 25-60
Example: Print ScrLen
Displays the current number of lines on screen

Scroll (Command)

Purpose: Scroll a region of the screen
Syntax : Scroll direction,x1,y1,x2,y2,positions,attribute
direction: 0=Clear, 1=uP, 2=DOWN, 3=LEFT, 4=RIGHT a=attribute }
positions are number of columns or lines to scroll
attribute is the attribute to use in the cleared area
Example: Scroll 4,1,1,30,5,2,7
Scroll (1,1)-(30,5) to columns to the right, clear with gray

SelectBar (Function)

Purpose: The menubar selector option used in most menus in Terminate
Syntax : Selectbar(y,ylen,start,attr,barx1,barx2,bartxty)
Returns: 0-25
Example: Set x=SelectBar(1,3,x,113,1,20,0)
Menubar starts at in the top corner of the active window or
screen and is 3 lines long, starting on menuline x. Menubar
is color 113 and is visible from columns 1-20. No bartext is
available. Returns selection in x. 0=Esc pressed.
Notes : SetBarTxt can be used to define helplines, set bartxty to
the line where you want it, ScrLen is normal, 0=disable

SetAttr (Command)

Purpose: Sets the current color attribute
Syntax : SetAttr attribute
Example: SetAttr 9
Set color to light blue

SetBarTxt (Command)

Purpose: Sets helplines for SelectBar
Syntax : SetBarTxt num,string
Example: SetBarTxt 1,"This is helpline 1"
When selectbar is in menu-position 1 this can be displayed

Sound (Command)

Purpose: Sound a tune using the sound card or internal speaker
Syntax : Sound frequency
Example: Sound 440
Set the sound to the concert pitch

WhereX (Function)

Purpose: To return the current X position of the cursor
Returns: 1-132
Example: Print WhereX
Displays the current X position of the cursor

WhereY (Function)

Purpose: To return the current Y position of the cursor
Returns: 1-60
Example: Print WhereX
Displays the current Y position of the cursor

Window (Command)

Purpose: Set a window and make it the current window for all functions
Syntax : Window x1,y1,x2,y2,boxtype,shadow,frameattr,txtattr,
headerattr,headertxt
boxtype: Same as the box-command
shadow : 0=no-shadow, 1=shadowtype 1, 2=shadowtype 2
Example: Window 10,1,70,10,1,1,30,23,27," Test window "
Sets window at (10,1)-(70,10) using single boxes and shadowtype
1, blue background and various foreground and header as above.

WriteAStr (Command)

Purpose: Display a string at position x,y and change default color
Syntax : WriteAStr x,y,attribute,expression
Example: WriteAStr 1,1,11,"I am light cyan"
Displays the string at 1,1 in light cyan color

WriteAttr (Command)

Purpose: Write a single attribute at position x,y
Syntax : WriteAttr x,y,attribute
Example: WriteAttr 1,1,14
Change attribute at 1,1 to yellow

WriteChar (Command)

Purpose: Write a single character at x,y
Syntax : WriteChar x,y,character
Example: WriteChar 1,1,"X"
Displays X in position 1,1

WriteColorStr (Command)

Purpose: Display a string with several colors
Syntax : WriteColorStr x,y,expression
Example: WriteColorStr 1,1,"^014 Yellow ^007 Gray"
The ^014 means change to color 14 at this position. It is
the same values as the normal attribute color.

WriteStr (Command)

Purpose: Display a string at position x,y
Syntax : WriteStr x,y,expression
Example: WriteStr 1,1,"Hello world"
Writes the string at 1,1

Keyboard control

AltPressed (Function)

Purpose: Checks if a Alternate is pressed on the keyboard
Returns: 0=No, 1=Yes, Alt is being pressed
Example: If AltPressed=1

CtrlPressed (Function)

Purpose: Checks if a Control is pressed on the keyboard
Returns: 0=No, 1=Yes, Ctrl is being pressed
Example: If CtrlPressed=1

Getkey (Function)

Purpose: Retrieves a key from the keyboard, wait if no key is ready
Returns: 0-65535, value of key
Example: PrintLn(GetKey)
Display the value of the key pressed

Input (Function)

Purpose: Input a string on screen
Syntax : Input(x,y,length,textattribute,editattribute,string)
Returns: String
Example: Set Result=Input(1,1,40,11,3,"Input string")
Inputs a string at position 1,1 with the length of 40
characters on the colors cyan and light cyan.

Key (Variable)

Purpose: Hold the last keyboard code
Returns: 0-65535
Example: While Key<>13
While Escape is not pressed run the loop

KeyPressed (Function)

Purpose: Checks if a key has been pressed on the keyboard
Returns: 0=No key ready, 1=key ready to be read by Getkey
Example: While KeyPressed=0
While no key is pressed run the loop

ShiftPressed (Function)

Purpose: Checks if a Shift is pressed on the keyboard
Returns: 0=No, 1=Yes, Shift is being pressed
Example: If ShiftPressed=1

WaitEnter (Command)

Purpose: Wait until someone presses the ENTER key
Syntax : WaitEnter

Variable manipulation

BlankAfter (Function)

Purpose: Add spaces after a string until a specified length is obtained
Example: BlankAfter(string,length)
Returns: String
Example: Print BlankAfter("Test",7)
Displays "Test " on the screen

BlankBefore (Function)

Purpose: Add spaces before a string until a specified length is obtained
Example: BlankBefore(string,length)
Returns: String
Example: Print BlankBefore("Test",7)
Displays " Test" on the screen

Chr (Function)

Purpose: Converts a number to the ASCII value
Syntax : Chr(number)
Returns: Character #0-#255
Example: Set Val=Chr(200)

Copy (Function)

Purpose: Copy out part of a string
Example: Copy(string,start,characters)
Returns: String
Example: Print Copy("Test",1,2)
Displays "Te" on the screen

Delete (Function)

Purpose: Delete part of string
Syntax : Delete(string,index,characters)
Returns: String
Example: Print Delete("Hello",4,2)
Displays "Hel" on screen

Grabword (Function)

Purpose: Return a single word in a string
Syntax : GrabWord(expression,word-number)
Returns: String
Example: Print GrabWord("Hello World",2)
Displays "World" on screen

Integer (Function)

Purpose: Cut off all decimals and returner integer
Syntax : Integer(number)
Returns: Integer
Example: Print Integer(1.50)
Prints the number 1

Length (Function)

Purpose: Return the length of a string
Syntax : Length(string)
Returns: 0-255
Example: Print length("test")
Displays the number 4 on screen

Numchars (Function)

Purpose: Return a string with a number of the same characters
Syntax : Numchars(character,numbers)
Returns: String
Example: Print Numchars("-",5)
Displays "-----" on screen

Ord (Function)

Purpose: Converts an ASCII value to ordinary value
Syntax : Ord(number)
Returns: Character #0-#255
Example: Set Val=Ord("A")

Parameter (Function)

Purpose: Return command line parameter when calling script
Syntax : Parameter(number)
Returns: String
Example: Set ComPort=Parameter(1)

Pos (Function)

Purpose: Search for sub-string in string
Syntax : Pos(sub-string,string)
Returns: 0=Not found, 1=255 position found
Example: Print Pos("World","Hello World")
Displays the number 6 on screen

Round (Function)

Purpose: Round an real number
Syntax : Round(number)
Returns: Integer
Example: Print Round(1.49) Prints the number 1
Print Round(1.50) Prints the number 2

Set (Command)

Purpose: Assign a value to a variable
Syntax : Set variable name = value
Example: Set Result = 20*10
Set Apples = "Good tasting"

StLocase (Function)

Purpose: Lowercase a string
Syntax : StLocase(string)
Returns: String
Example: Print LoUpcase("HELLO")
Displays hello on screen

StUpcase (Function)

Purpose: Uppercase a string
Syntax : StUpcase(string)
Returns: String
Example: Print StUpcase("hello")
Displays HELLO on screen

Stacks and queues

A stack is a First-In-Last-Out buffer, which can be used for saving
variables or values that need to be used later.

A queue is a First-In-First-Out buffer (FIFO) which can be used for
buffering variables.

QueueLook (Command)

Purpose: Retrieves the latest variable from the queue without popping
Syntax : QueueLook variable
Example: QueueLook Count
Count is set to latest value pushed on queue without popping

QueuePop (Command)

Purpose: Retrieve the latest variable pushed on the user-queue
Syntax : QueuePop variable
Example: QueuePop Count
Takes the latest pushed value from queue and puts into Count

QueuePush (Command)

Purpose: Pushes a variable on the user-queue to be retrieved later
Syntax : QueuePush variable
Example: QueuePush Count
Push Count on the user-queue

StackLook (Command)

Purpose: Retrieves the latest variable from the stack without popping
Syntax : StackLook variable
Example: StackLook Count
Count is set to latest value pushed on stack without popping

StackPop (Command)

Purpose: Retrieve the latest variable pushed on the user-stack
Syntax : StackPop variable
Example: StackPop Count
Takes the latest pushed value from stack and puts into Count

StackPush (Command)

Purpose: Pushes a variable on the user-stack to be retrieved later
Syntax : StackPush variable
Example: StackPush Count
Push Count on the user-stack

Serial interface handling

All commands will return a resultcode in DeviceResult, if 0 the command
was executed succesfully.

Carrier (Function)

Purpose: Check if the carrier is high
Returns: 0=Carrier low, 1=Carrier high
Example: While Carrier=1
While carrier detect is high run the loop

CharsWaiting (Function)

Purpose: Get number of chars waiting in input buffer
Returns: 0-65535
Example: Print "Waiting characters ",CharsWaiting

CloseCom (Command)

Purpose: Close the current device
Syntax : CloseCom

ClrLastIncoming (Command)

Purpose: Clear LastIncoming to 255 #0
Syntax : ClrLastIncoming

DeviceResult (Variable)

Purpose: The last result code from the device, 0=Ok
Returns: 0-65535
Example: Print "Device result ",DeviceResult

DeviceResultStr (Function)

Purpose: Return error text of the last result code from the device, 0=Ok
Syntax : DeviceResultStr(Resultcode)
Returns: String
Example: Print "Device result ",DeviceResultStr(DeviceResult)

FlushInBuffer (Command)

Purpose: Flush the incoming device buffer
Syntax : FlushInBuffer

GetBaud (Function)

Purpose: Get the current baud rate
Returns: 0-115200
Example: Print "Current baud ",GetBaud

GetChar (Function)

Purpose: Get a character from the device
Returns: #0..#255
Example: Print GetChar

GetCharTimeout (Function)

Purpose: Get a character from the device, timeout in tics
Syntax : GetCharTimeout(number-of-tics)
Example: Set Received=GetCharTimeout(91)
Try to get a character from the device timeout in 5 seconds
Notes : A PC has 18.2 tics per second 5x18.2 = 91 tics = 5 seconds

GetData (Function)

Purpose: Get the current databits
Returns: 7-8
Example: Print "Current databits ",GetData

GetInterface (Function)

Purpose: Get the serial interface type in use
Returns: 0=NoDevice, 1=UartDevice, 2=Int 14h, 3=Fossil, 4=Digiboard
Example: Print "Active serial interface type ",GetInterface

GetParity (Function)

Purpose: Get the current parity in use
Returns: N=None, O=Odd, E=Even, M=Mark, S=Space
Example: Print "Current parity in use ",GetParity

GetPort (Function)

Purpose: Get the active port number
Returns: 1-8
Example: Print "Active port ",GetPort

GetStop (Function)

Purpose: Get the current stopbits
Returns: 1-2
Example: Print "Current stopbits ",GetStop

Hangup (Command)

Purpose: Drop the carrier, using the hangup string or toggling DTR
Syntax : Hangup

InitDevice (Command)

Purpose: Open one of the devices in Terminate
Syntax : InitDevice devicenumber,port,baud
Example: InitDevice 4,2,57600
Open device 4, using port 2 with baud 57600
Notes : If another device is already open it will be closed.

InitDirect (Command)

Purpose: Open a device and initialise the communications port directly
Syntax : InitDirect interface,port,baud,databits,stopbits,parity,
inbufsize,outbufsize,flowctrl
Interface : 0=NoDevice, 1=UartDevice, 2=Int 14h,
3=Fossil, 4=Digiboard
Port : 1-8
Databits : 7-8
Stopbits : 1-2
Parity : N=None, O=Odd, E=Even, M=Mark, S=Space
Inbufsize : 10-65000
Outbufsize: 10-65000
Flowctrl : 0=None, 1=RTS/CTS, 2=XonXoff, 3=DSR/DTR
Example: InitDirect 1,2,38400,8,1,"N",1024,1024,1
Use Uart on COM2 with 38400,8N1 and 1024 bytes buffers
for in/out. RTS/CTS flowcontrol
Notes : If another device is already open it will be closed.

LastIncoming (Variable)

Purpose: Holds the last 255 characters received by GetChar
Returns: String
Example: Print LastIncoming

Send (Command)

Purpose: Send a string to the device with modem delay.
Syntax : Send expression
Example: Send "ATA^M"
Send the HAYES answering command to device

SendRaw (Command)

Purpose: Send a string to the device in raw format
Syntax : SendRaw expression
Example: Sendraw "----------------"

WaitFor (Command)

Purpose: Wait for a string from device
Syntax : WaitFor expression,seconds
Example: WaitFor "Enter name:",20
If IOResult<>0
Goto Timeout
Endif
Notes : IOResult=0 Got String, IOResult=2 Timeout

File handling

All file commands will give the result code in IOResult.

IOResult (Variable)

Purpose: Result of the last file operation
Returns: 0-65535, 0=Ok
Example: Print IOResult

PRS supports two kind of files. Binary files and text files. Binary
files are data files like TERMINAT.EXE which contain characters from
#0..#255. Text files like AUTOEXEC.BAT are line based and easier to
use.

PRS allows you to have 8 open files at the same time. 4 binary files
and 4 text files.

Text files

Textfiles are easier to understand when you see the following example:

OpenText 1,"C:\AUTOEXEC.BAT",0
While EndofTextFile(1)=0
PrintLn readtext(1)
EndWhile
CloseText 1

This will open a text file and print the entire file on your screen.

CloseText (Command)

Purpose: Close a text file
Syntax : CloseText handle
Example: CloseText 1

EndOfTextFile (Function)

Purpose: Tells you if we are on the last line in the file
Syntax : EndofTextFile(handle)
Returns: 0=No, 1=Yes, end-of-file
Example: While EndofTextFile(1)=0
Continue until end-of-file

OpenText (Command)

Purpose: Opens a text file for reading, writing or appending.
Syntax : OpenText handle,filename,mode
handle : 1-4
filename: Full pathname of file
mode : 0=Read, 1=Write, 2=Append
Example: OpenText 1,"C:\AUTOEXEC.BAT",0
Opens text file 1 for reading.

PosText (Function)

Purpose: Report the byte position in a text file.
Syntax : PosText(handle)
Example: Print "Position ",PosText(1)
Show the byte-position on text file 1

ReadText (Function)

Purpose: Read 1 line from a text file
Syntax : ReadText(handle)
Returns: String
Example: PrintLn ReadText(1)
Reads and displays one line from text file 1

SeekText (Command)

Purpose: Seek to a file position in a text file.
Syntax : SeekText handle,position
Position is the byte-position in file 0=First byte
Example: SeekText 1,1000
Seeks to position 1000 in the file

SizeText (Function)

Purpose: Report the size in bytes on a text file
Syntax : SizeText(handle)
Returns: filesize-in-bytes
Example: Print SizeText(handle)

WriteLnText (Command)

Purpose: Write a string to a text file
Syntax : WriteLnText handle,string
Example: WriteLnText 1,OutString
Writes the contents of OutString to text file 1

WriteText (Command)

Purpose: Write a string to a text file without CR+LF
Syntax : WriteText handle,string
Example: WriteText 1,OutString
Writes the contents of OutString to text file 1

Binary files

Close (Command)

Purpose: Close a file
Syntax : Close handle
Example: Close 1

Eof (Function)

Purpose: Tells you if we are on the last position in the binary file
Syntax : EndofTextFile(handle)
Returns: 0=No, 1=Yes, end-of-file
Example: While Eof(1)=0
Continue until end-of-file

FilePos (Function)

Purpose: Report the byte position in a binary file.
Syntax : FilePos(handle)
Example: Print "Position ",FilePos(1)
Show the byte-position on binary file 1

FileSize (Function)

Purpose: Report the size in bytes on a binary file
Syntax : FileSize(handle)
Returns: filesize-in-bytes
Example: Print FileSize(handle)

Open (Command)

Purpose: Opens a binary file for reading, writing or both.
Syntax : Open handle,filename,mode,filemode
handle : 1-4
filename: Full pathname of file
mode : 0=Read, 1=Write, 2=Append
filemode: 0=ReadOnly,1=WriteOnly,2=ReadWrite,+64=DenyNone
Example: Open 1,"TERMINAT.CFG",0,0
Opens binary file 1 for reading.

Read (Function)

Purpose: Reads a number of characters from a binary file
Syntax : Read(handle,numbytes)
Returns: String
Example: Set FileGrab=Read(1,20)
Read 20 characters into FileGrab

Seek (Command)

Purpose: Seek to a file position in a binary file.
Syntax : Seek handle,position
Position is the byte-position in file 0=First byte
Example: Seek 1,1000
Seeks to position 1000 in the file

Write (Command)

Purpose: Write a number of characters to a binary file
Syntax : Write(1,expression)
Example: Write(1,"HELLO")

DOS commands

The result of each call is stored in IOResult

DeleteFile (Command)

Purpose: Deletes a file
Syntax : DeleteFile filename
Example: DeleteFile "TERMINAT.BAK"

Exec (Command)

Purpose: Call a DOS command
Syntax : Exec expression
Example: Exec "TERMAIL\TM.EXE !M"
Call the TerMail program
Notes : All the !-commands described other places in the manual
can be used here. !M=Swap out memory

FindFirst (Function)

Purpose: Finds a file allowing wildcards
Syntax : FindFirst(expression,attribute)
Attribute: 1=ReadOnly, 2=Hidden, 4=System, 8=VolumeID,
16=Directory, 32=Archive, 63=AnyFile
Returns: Filename only or blank if no mathces
Example: Print FindFirst("C:\*.*",32)

FindNext (Command)

Purpose: Find next match after a FindFirst use
Returns: Filename found
Example: PrintLn FindFirst("C:\*.*",32)
While IOResult=0
PrintLn FindNext
EndWhile
Will display to entire root of your C-drive

FindNextSize (Variable)

Purpose: Returns filesize of last FindNext
Returns: Size in bytes
Example: PrintLn FindNextSize

FindNextAttr (Variable)

Purpose: Returns file attribute of last FindNext
Returns: Byte
Example: PrintLn FindNextAttr

FindNextTime (Variable)

Purpose: Returns filetime of last FindNext
Returns: Time in unix number
Example: PrintLn FindNextTime

Rename (Command)

Purpose: Rename a file to another name
Syntax : Rename filename new-filename
Example: Rename "TEST.TXT","TEST2.TXT"
Renames TEST.TXT -> TEST2.TXT

Date, time handling

GetDate (Variable)

Purpose: Returns date in formatted form
Returns: Date-string DD-Mmm-YYYY (Day, Month-string, Year)
Example: PrintLn GetDate
Print todays date: 7-Aug-1995, 21-Jan-96

GetDateRaw (Variable)

Purpose: Returns date in raw form
Returns: String YYYY MM DD DOW (Year, Month, Day, Day-of-week)
Example: PrintLn GetDateRaw
Print current date: 1995 08 07 01

GetTime (Variable)

Purpose: Returns time in formatted form
Returns: Time-string HH:MM:SS
Example: PrintLn GetTime
Print current time: 18:39:25

ResetTimer (Command)

Purpose: Resets timer 1-4
Syntax : ResetTimer timer-num,seconds
Example: ResetTimer 1,60
Sets timer to expire after 60 seconds

TimeElapsed (Function)

Purpose: Returns in milliseconds time elapsed since ResetTimer
Syntax : TimeElapsed(timer-num)
Returns: Milliseconds elapsed
Example: PrintLn TimeElapsed(1)

TimerExpired (Function)

Purpose: Check if a timer has expired.
Syntax : TimerExpired(timer-num)
Returns: 0=No, 1=Timer expired
Example: Until TimerExpired(1)=1

Wait (Command)

Purpose: Pause in 1/100 seconds
Syntax : Wait num-1/100-seconds
Example: Wait 200
Wait 2 seconds before continuing

File transfers

One of the most common tasks you will need the scripts for is to
transfer files to/from another system. To do this you need to
use the internal or external protocols specified below.

Protocols

1 + Zmodem + = Batch protocol
2 + ZedZap
3 Ascii
4 Xmodem
5 Xmodem-1K
6 Xmodem-1K-G
7 + Ymodem
8 + Ymodem-G
9 + Kermit
10 + CompuServe B+
11..22 ? External protocols

Download (Command)

Purpose: Receive files from another system
Syntax : Download protocol,filename
Example: Download 1
Download 3,"CAPTURE.TXT"
Notes : All protocols that are not batch must have a filename

Upload (Command)

Purpose: Send files to another system
Syntax : Upload protocol,filename(s)/wildcards
Example: Upload 1,"C:\TERMINAT\UPLOAD\DANBBS.QWK"
Upload 3,"C:\TERMINAT\UPLOAD\*.* C:\TERMINAT\DOCS\*.DOC"

Emulations

SetTerminal (Command)

Purpose: Change to terminal slot
Syntax : SetTerminal slot
Example: SetTerminal 1
ANSI-BBS is now the current terminal

WriteTerminal (Command)

Purpose: Send a string to terminal emulation
Syntax : WriteTerminal expression
Example: If CharsWaiting<>0
WriteTerminal GetChar
Endif
Displays received character from device

Terminate control

Dial (Command)

Purpose: Dial number in the phonebook
Syntax : Dial numbers,numbers,numbers.....
Example: Dial 1,2,3,4
Dial 27
Notes : IOResult=0 No connect, IOResult=1 Connection

GetUserName (Variable)

Purpose: Get username from phonebook record
Syntax : GetUserName
Returns: String
Example: Send GetUserName
Send username to device

GetUserPassword (Variable)

Purpose: Get password from phonebook record or default
Syntax : GetUserPassword
Returns: String
Example: Send GetUserPassword
Send password to device

MainLoop (Command)

Purpose: Run Terminate main loop
Syntax : MainLoop times
Example: MainLoop 10
Allow the script to access all the Terminate functions

Direct hardware control

Direct memory commands can be dangerous since it can access your
hardware directly or indirectly. Please do not use any memory
commands if you are the slightest bit insecure on their use.

FreeMem (Function)

Purpose: How much memory is left
Returns: Number of bytes available for script language
Example: Print FreeMem
Displays free memory on screen

Interrupt (Function)

Purpose: Call any interrupt with register value *WARNING DANGEROUS*
Syntax : Interrupt(interrupt-number,ax,bx,cx,dx,si,di,ds,es)
Returns: String: ah al bh bl ch cl dh dl si di ds es flags
Example: Print "Videomode:",GrabWord(Interrupt(16,3840,0,0,0,0,0,0,0),2)
Get videomode in word 2 in string
Notes : Be very careful with command. It gives you access to the
complete PC and therefore one wrong call can result in the
worst errors. If you are not an expirenced programmer do not
under any circumstances use this command.

Mem (Function)

Purpose: Get a byte directly from memory location
Syntax : Mem(segment,offset)
Returns: 0-255
Example: Print "Memory 0:0",Mem(0,0)

PortIn (Function)

Purpose: Get a byte directly from a hardware port
Syntax : PortIn(port)
Example: You will know if you need it!

PortOut (Command)

Purpose: Send a byte to a hardware port
Syntax : PortOut port,byte
Example: You will know if you need it!

PutMem (Command)

Purpose: Put a byte directly to memory location
Syntax : PutMem byte,segment,offset
Example: PutMem 65,47104,0
Notes : BE CAREFULL!

Fax commands

SendFax (Command)

Purpose: Send a fax to a specific telephone number
Syntax : SendFax filename,number,[to-name,subject]
Example: SendFax "DOCS\PROBLEM.DOC","43627178","Sysop","Problem"
SendFax "C:\AUTOEXEC.BAT","43627178"
Notes : Text, TIFF or PCX files will be converted to APF format first
Note that the default fax settings and cover page will be used.

Numeric conversion

Binary (Function)

Purpose: Returns an binary string
Syntax : Binary(Integer,bits)
Example: PrintLn Binary(255,8)
PrintLn Binary(256,16)

BinToInt (Function)

Purpose: Returns an integer from a binary string
Syntax : BinToInt(string)
Example: PrintLn BinToInt("11111111")

ByteToHex (Function)

Purpose: Returns a string with hex value of byte 8-bit
Syntax : ByteToHex(Byte)
Example: PrintLn ByteToHex(255)

HexToInteger (Function)

Purpose: Returns an integer converted from a hex-string
Syntax : HexToInteger(String)
Example: PrintLn HexToInteger("FFFF")

LongToHex (Function)

Purpose: Returns a string with hex value of a double word 32-bit
Syntax : LongToHex(Byte)
Example: PrintLn LongToHex(255)

WordToHex (Function)

Purpose: Returns a string with hex value of word 16-bit
Syntax : WordToHex(Byte)
Example: PrintLn WordToHex(65000)

Other commands

ExitTerminate (Command)

Purpose: Exit the script and Terminate with errorlevel
Syntax : ExitTerminal [errorlevel]
Example: ExitTerminate 100 (Errorlevel 100)
ExitTerminate (Errorlevel 1)

GetCrc (Function)

Purpose: Update a Crc-16 checksum
Syntax : GetCrc(Byte,Old-Crc)
Example: Set Crc=GetCrc(X,Crc)

GetCrcLong (Function)

Purpose: Update a Crc-32 checksum
Syntax : GetCrcLong(Byte,Old-Crc)
Example: Set Crc=GetCrcLong(X,Crc)

Random (Function)

Purpose: Get a random number between 0-65535
Syntax : Random(max)
Example: Print Random(100)
Displays a random number between 0-99

Randomize (Command)

Purpose: To initialise the random factor for the Random function
Syntax : Randomize

CommentNum (Function)

Purpose: Get number of script comments
Syntax : CommentNum(0)
Example: Set Comments=CommentNum(0) <- Must be zero!

CommentStr (Function)

Purpose: Get script comments
Syntax : CommentStr(Commentnumber)
Example: PrintLn CommentStr(1)

Terminate (Command)

Purpose: Exit the script
Syntax : Exit




EXAMPLES

% -----------------------------------------------------------------------------
% Dump raw datafile to screen *TERMINATE PRESCRIPTION*
% -----------------------------------------------------------------------------
%
% Version : 1.00
% Filename : DUMPFILE.TSL
% Company : SerWiz Comm
% Programmer : Bo Bendtsen
% Module created : 08 Aug 1995
% Latest revision : 08 Aug 1995
% Language/version : Terminate Prescription 1.00
% Remarks : Data/hex/loop example
%
% -----------------------------------------------------------------------------

Clearscreen

Window 1,1,80,3,1,0,23,23,27," File dump "
WriteAStr 2,0,31," Esc to Abort "
WriteAStr 28,1,23," DUMP OF TERMINAT.DAT "
Window 1,4,80,25,6,0,14,14,27,""

:AgainPlease

Cursor 0

Open 1,"TERMINAT.DAT",0,0

Set Pos=0

Repeat
Set Line=LongToHex(Pos)+" - "
SetAttr 11
Print Line
Set Line=Read(1,16)
Set Pos=Pos+16
Set NewLine=""
For Y,1,Length(Line),1
Set NewLine=NewLine+ByteToHex(Ord(Copy(Line,Y,1)))+" "
Next
SetAttr 3
Print BlankAfter(NewLine,48)
Set NewLine=" - "
For Y,1,Length(Line),1
Set B=Ord(Copy(Line,Y,1))
If B<32
Set NewLine=NewLine+"."
Else
Set NewLine=NewLine+Chr(B)
Endif
Next
SetAttr 14
PrintLn NewLine
Until Eof(1) | (Keypressed=1)

Close 1

Window 26,8,54,10,1,0,23,23,27," Make a decision "
WriteStr 2,1,"Press RETURN to try again"
Set Key=GetKey
RemoveWindow

If Key=13
FillBlock 1,5,80,20,7," "
Goto AgainPlease
Endif

RemoveWindow
RemoveWindow


% -----------------------------------------------------------------------------
% Mini Terminal Demonstration *TERMINATE PRESCRIPTION*
% -----------------------------------------------------------------------------
%
% Version : 1.01
% Filename : MINITERM.TSL
% Company : SerWiz Comm
% Programmer : Bo Bendtsen
% Module created : 06 Aug 1995
% Latest revision : 09-Aug-1995 by Joop Blokker
% Language/version : Terminate Prescription 1.00
% Remarks : Easy demonstration to create the simplest terminal
%
% -----------------------------------------------------------------------------

SetTerminal 1

ClearScreen
WriteAStr 48,25,31," Alt-X=Abort F1=AT&V F2=ATI4 "
SetAttr 7

print "Interface : "
Set Interf = GetInterface % Get Interface
print Interf
if Interf=0
Set InterfS = "No Device"
else
if Interf=1
Set InterfS="Uart device"
else
if Interf=2
Set InterfS="INT 14h"
else
if Interf=3
Set InterfS="Fossil"
else
If Interf=4
Set InterfS="DigiBoard"
else
Set InterfS = "Unknown"
endif
endif
endif
endif
endif
println " - ",InterfS

print "Port : ", % Get Port number
Set Port = GetPort
println Port

print "Baud : ", % Get Baud
Set Baud = GetBaud
PrintLn Baud

print "Data bits : ", % Get Databits
Set DataBits = GetData
PrintLn DataBits

print "Stop bits : ", % Get Stopbits
Set StopBits = GetStop
PrintLn StopBits

print "Parity : ", % Get Parity
Set ParS = GetParity
print ParS, " - "
if ParS = "N"
Set ParityS = "None"
else
if ParS = "O"
Set ParityS = "Odd"
else
if ParS = "E"
Set ParityS = "Even"
else
if ParS = "M"
Set ParityS = "Mark"
else
if ParS = "S"
Set ParityS = "Space"
else
Set ParityS = "Unknown"
endif
endif
endif
endif
endif

println ParityS

print "Set Input buffer : ", % Set Input buffer size
Set InBuf = 1024
println InBuf

print "Set Output buffer : ", % Set Output buffer size
Set OutBuf = 1024
println OutBuf

print "Set Flow Control : ", % Set Flow Control

Set Flow = 1 % init

if Flow=0
Set FlowS = "None"
else
if Flow=1
Set FlowS = "RTS/CTS"
else
if Flow=2
Set FlowS = "Xon/Xoff"
else
if Flow=3
Set FlowS = "DSR/DTR"
else
Set FlowS = "Unknown"
endif
endif
endif
endif
println FlowS
println ""
Println "Press Enter, please..." % Wait
WaitEnter
Scroll 1,1,1,80,20,20,7 % Clear screen partial

InitDirect Interf, Port, Baud, DataBits, StopBits, ParS, InBuf, OutBuf, Flow

If DeviceResult<>0
PrintLn "Error opening COM",GetPort
PrintLn "Result code: ",DeviceResult
PrintLn "Result text: ",DeviceResultStr(DeviceResult)
WaitEnter
Goto End
Endif

Set Key=0
Repeat
If CharsWaiting<>0
WriteTerminal GetChar
Endif
If Keypressed<>0
Set Key = GetKey
If Key=315
Send "AT&V^M"
Else
If Key=316
Send "ATI4^M"
Else
Send Chr(Key)
Endif
Endif
Endif
Until Key=301

CloseCom

:End
RemoveWindow



Back to tour back to Tour Index