VidiCode ARGUS BASIC User Guide

ARGUS BASIC

Programmer’s Reference Manual

VIDICODE Datacommunicatie BV

Zoetermeer 1990 - 1997

ARGUS BASIC Programmer’s Reference Manual

Zoetermeer

Designed, edited and typeset in The Netherlands.

No part of this publication may be used or reproduced, stored in a

database or retrieval system, transmitted in any form or by any means,

electronic, mechanical, photocopying, recording, or otherwise, without

the prior written permission of the publisher, except in the cases

of brief quotations embodied in critical articles and reviews.

Making copies of any part of this book for any purpose other than

your own personal use is a violation of copyright laws.

Further copies of this manual and information on the Argus range of products and services may be obtained from the publishers.

Please address all inquiries to:

EUROPE:

Vidicode Datacommunicatie BV Blauwroodlaan 140 2718 SK Zoetermeer Netherlands

Voice: (+31) 79 3617181 Fax: (+31) 79 3618092 Email: VIDICODE@VIDICODE.NL Website: WWW.VIDICODE.NL

USA:

Vidicode Datacommunication Inc. 1616 Shipyard Blvd. Suite 259 Wilmington, NC 28412

Voice: (+1) 910-452-5600 Fax: (+1) 910-254-3525 Email: SALES@VIDICODE.COM Website: WWW.VIDICODE.COM

Table of Contents

PROGRAMMING THE MODEM 7

1.1 Program structure 7

Program lines & commands 7 Variables & constants 7 Variable names 8 Integers & integer arrays 8 Strings & string arrays 8 Labels 9 Calculations & expressions 10 Hexadecimal numbers 10 Logical operations 10 Events 11

1.2 Writing programs 12

Direct programming 12 Indirect programming 13

1.3 Running programs 14

Running files from the filing system 15

1.4 Program and variable storage 15

1.5 I/O ports 16

Port syntax 17

1.6 The Argus filing system 18

Text files 19 Binary files 20 BASIC programs 20

1.7 Program backup 20

Backing up Program memory 21 Backing up the RAM-, FLASH- or Hard-disk 21

ARGUS BASIC - COMMAND REFERENCE 22

Syntax 22 ABS absolute value 24 ACTIVE set modem active 25 ADC read analogue to digital conversion 27 AND logical AND 28 ANSWER answer a call 29 ASC ASCII value 30 AT AT scan 31

AT (#[port]) (SLASH) ON/OFF 32

AT INPUT (#[port]) 32

AT REPEAT 32

AT [string] 32 AUTO automatic line numbering 34

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

BAUD set baud rate 35 BOOT ON/OFF enable/disable BOOT file 37 BRK transmit a break 38 BUFFER reserve buffer space 39 BUTTON read the S/A button position 42 CALL jump to machine code subroutine 43 CHR$ character string 44 CLEAR clear variables/memory 45

1. CLEAR 45

2. CLEAR ALL 45

3. CLEAR (#[port]) 45

4. CLEAR INPUT (#[port]) 45

5. CLEAR OUTPUT (#[port]) 45

6. CLEAR BUFFER 45

7. CLEAR PRINTER 45

8. CLEAR! or CLEAR FILE 45

9. CLEAR ROM 45 CLOCK$ read internal clock 47 CONNECT connect to remote modem 48 COPY copy files 49 CTS Clear To Send 50 DATA define constant data 51 DATE$ read system date 52 DAY read/set day of week 53 DCD Data Carrier Detect 54 DDAY read/set day in month 55 DELETE or DEL delete program lines/files 56 DIAL dial number 58 DIM reserve space for arrays 59 DIR list file directory 60 DIR ROM list ROM directory 62 DIV integer divide 63 DSR Data Set Ready 64 DTMF ON/OFF dial tone multiple frequency 65 [var] = DTMF read DTMF receiver 66 DTR Data Terminal Ready 67 DUTCH select language and screen mode 68 ECHO enable/disable character echo 69 END end of program 70 ENGLISH select language and screen mode 71 EOR logical Exclusive OR 72 ERL error line system variable 73 ERN error number system variable 74 ESCAPE set Escape character 75 FALSE Boolean system variable 76 FAX MODEM ON/OFF enable/disable fax selector 77 FAX ON/OFF turn FAX on or off 78 FAX RECEIVE receive fax file 79 FAX SEND ...TO... send fax file 80 FOR ... (TO) ... (NEXT) ... (STEP) loop structure 85 FREQ read frequency measurement 87 GET get byte (with wait) 88 GET$ get character (with wait) 89 GOSUB ... RETURN jump to subroutine 90 GOTO unconditional jump 92 HANDSHAKE select/enable handshaking 93

RTS/CTS selected: 93 XON/XOFF selected: 93

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Handshaking via LINKed ports 93 HANGUP disconnect a call 95 HOOK hook control 96 HOUR read/set hour of day 97 IF ... THEN ... ELSE condition test 98 ILINE read input line 99 INPUT read string/number 100 IPORT default input port 102 KEY get byte (without wait) 103 KEY$ get character (without wait) 104 LCASE convert ASCII to lowercase 105 LCASE$ convert string to lowercase 106 LED control LEDs 107 LEFT$ extract left part of a string 108 LEN get length of string 109 LENGTH set or read serial port word length 110 LINEFEED enable/disable Line Feeds 111 LINK connect logical data streams 112 LIST list BASIC program 115 LIST AUTO list program for editing 116 LOAD load BASIC program or data 117 LOAD ROM load BASIC programs from socket 2 118 LTRIM$ remove leading spaces 119 MATCH find matching files/data 120 MATCH ROM find matching files in socket 2 122 MID$ extract middle portion of string 123 MIN set/read minute value 124 MNP (4/5) ON/OFF turn error correction on/off 125 MOD integer remainder operator 126 MODEM select standard modem mode 127 MONTH set/read month of year 128 NETWORK Argus LAN network command 125 NEW new program 132 OLD restore program 133 OLINE set/read digital output line 134 ON AT AT scan event handler 136 ON BRK BRK event handler 137 ON BUTTON USER button event handler 138 ON CONNECT connection detect event handler 139 ON DTD DTR loss event handler 140 ON DTR DTR event handler 141 ON ERROR error handler 142 ON ESCAPE Escape event handler 143 ON ... GOSUB/GOTO jump on value 144 ON HANGUP loss of connection event handler 145 ON OFF disable all events 146 ON RESET reset event handler 147

(a) A !BOOT program is found on the disk 147

(b) No program running at moment of reset 147

ON RESET RUN [filename] 148

ON RESET RUN 148

ON RESET ... 148 ON RING RING event handler 150 ON SEQUENCE Esc. sequence event handler 151 ON SLASH AT scan event handler 152 ON TIMEOUT timeout event handler 153 OPORT default output port 155

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

ORI output ring indicator 157 OUTPUT send data to port 158 PARITY read or set parity 159 PBOT program bottom 160 PEEK read byte from memory 162 PEEK$ read string from memory 163 PLAY [filename] playback a recorded file 164 PLAY ON/OFF turn play on/off 166 PLAY VOLUME [num] playback attenuation 167 POKE put byte into memory 168 POKE$ put string into memory 169 PORT last event port system variable 170 PRINT send data to port 171

PRINT positioning & formatting 171 PRINTER enable/disable printer port 173

PRINTER and PRINTER ON 173

PRINTER OFF 173

PRINTER LINEFEED ON/OFF 173

PRINTER INPUT/OUTPUT 173 PROTOCOL set file transfer protocol 174 PTOP program top system variable 178 PULSE set/do pulse dialing 179 PUT write byte value to port 180 PUT$ write character to port 181 READ read data items 182 RECEIVE receive file or data 183 RECEIVE #[port], [address] receive data 184 RECEIVE [filename], [type] receive file 185 RECEIVE ALL receive disk backup 189 RECEIVE TIMEOUT = [int] set Sreg66 timeout 190 RECORD [filename] record a voice file 191 RECORD ON/OFF turn record mode on/off 193 RECORD TIMEOUT [num] set record timeout 194 REM remark 195 RENAME rename files 196 RENUM renumber program 197 REPEAT ... UNTIL loop structure 198 REPORT report result or error 199

REPORT ERN 199

REPORT or REPORT RESULT 199 RESET generate hardware reset 200 RESET ALL SREG reset all S-registers to factory settings 201 RESET MODEM 2 reset modem-chip only 202 RESTORE restore pointer to data command/buffer/RAM-disk 203 RESULT last status of modem action 204 RETURN return from procedure/ set return character 206

1. Return from procedure 206

2. Set value of RETURN character. 206 RIGHT$ extract right portion of string 207 RING ring counter 208 ROM access RAM/ROM-disk in socket 2 209 RPT$ repeat string 211 RTRIM$ remove trailing spaces 212 RTS ready to send 213 RUN run a program 214 RUN ROM run a program from ROM/RAM-disk in socket 2 215 SAVE save program or data to memory/disk 216 SAVE ROM save files in RAM-disk in socket 2 217

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

SCAN set answering speed/scan 218 SEC read/set seconds value 219 SEND send file or data 220 SEND #[port], [address], [address] send data 221 SEND [filename], [type], [option] send file 222 SEND ALL make a backup of disk 227 SEQUENCE select escape sequence character 228 SGN get sign of number 229 SOUND (MODEM) make a sound on speaker or phoneline 230 SPC$ repeat spaces 231 SPEAKER ON/OFF speaker control 232 SPEED set line modem-speed 233 SPEED BUFFER ON/OFF speed buffer on/off 234 SREG set/read S-registers 235 STOP stop program execution 236 TIME$ read or set time 237 TRACE trace program-lines execution 238 TRIM$ remove spaces 239 UCASE convert ASCII to uppercase 240 UCASE$ convert string to uppercase 241 VAL convert string to number 242 VAL$ convert number to string 243 VOICE set modem to voice-mode 244 VOLUME set speaker volume 246 WAIT ... (SEC/MIN) wait some time 247 WHILE ... DO ... WEND loop structure 248 XOFF define XOFF character 249 XON define XON character 250 YEAR read/set year value 251 BASIC Error Messages 252 BASIC Keywords and associated short forms 256 Keyboard & LCD codes 266

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

This page intentionally left blank

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Programming the modem

1.1 Program structure

Argus BASIC is part of the Argus Programmable Modem, the Argus Call Recorder and of the Telecommunications Centre Lite (T.C.Lite). A keyboard and LCD display are optional for the Argus Programmable Modem and always available on the Argus Call recorder and the T.C.Lite. A filing system is optional for the Argus Programmable Modem and can be a RAMdisk, a FLASH-disk, a Hard-disk or an Argus LAN (Local Area Network). The T.C.Lite only supports the FLASH-disk.

Argus BASIC is much like any other version of BASIC in terms of both syntax and structure, but there are also many significant differences. This chapter provides an overall description of the modem programming environment and goes on to describe each of the Argus BASIC commands in detail.

Program lines & commands

A BASIC program consists of a series of lines which must start with a 'line number' and may contain up to 255 characters. A line that is entered without a line number will not be treated as part of a program but will be executed immediately. For example, the following command :

PRINT "Of Mice and Men - by John Steinbeck"

will display the quoted message on your screen as soon as you press [Return]. Alternatively, when you type the line:

10 PRINT "Of Mice and Men - by John Steinbeck"

it will be treated as line 10 of the current program and stored in the modem's memory until the program is executed. Program lines may be entered in any order but the modem will always list and execute them sequentially from lower line numbers to higher ones (unless control of flow is changed by a branch command such as GOTO).

A single program line may contain more than one command with individual commands being separated by a colon. The following line contains three commands:

10 X=9 : PRINT "The square of ";X;" is "; : PRINT X^2

The first command defines a 'variable' called X and gives it the value 9. The second command outputs a message, including the value of X, to the currently selected output port, and finally, another PRINT command outputs the value of X^2. The overall effect of the line is to output the following:

The square of 9 is 81

As many commands may be placed on a single line as will fit in the maximum line length of 255 characters.

BASIC keywords such as PRINT may be entered in upper or lower case but the modem will convert them all to capitals. Also, it is not necessary to leave spaces between commands, as the modem will insert them automatically.

During program entry it is advisable to leave (numerical) gaps in the line numbering, so that additional lines may be inserted later. The convention is to number lines 10, 20, 30 etc., although there is a command for re-numbering programs (RENUM).

Variables & constants

Data stored or used in a BASIC program may exist as a 'constant' or as a 'variable'. The following examples are constants:

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

"The quality of mercy is not strained.."

Constants are so-called because they have a fixed value that does not change during program execution.

The term variable is used to describe a named piece of data whose value can change during program execution. For example:

X=25

Quote$="The quality of mercy is not strained.."

Here, X and Quote$ are variables which can be given different values at different times. After the command:

X=43

the value of X will be 43, not 25 as previously.

There are only two types of constants and variables in modem BASIC which are known as 'integers' and 'strings'. Floating point (fractional) numbers are not allowed.

Variable names

Variable names must start with a letter, may contain letters, numbers and the underline character and may be up to 127 characters long. They may be typed in upper or lower case but the modem will convert them during listing so that only the first character is capitalized. The underline character is generally used to split a variable name into two or more parts to make it more readable, in which case the first letter after each underline will also be capitalized.

The following are examples of valid variable names:

A X395

Home_Num$ Start_Pointer

Inp_Line$ S$

Name$ Start_Date$

Telephone Temperature

String variable names are suffixed by '$' as in most versions of BASIC, but, whereas it is normal to use the '%' or '#' symbols to distinguish between integer and floating point variables, this is not necessary on the modem so that any variable not suffixed by '$' will be treated as an integer.

Integers & integer arrays

Argus BASIC will handle integer numbers and variables in the range -32768 to 32767 ($0000 - $FFFF). Arrays (tables) can only have one dimension and the number of elements is limited to 32767. Space for arrays is allocated using the standard form of the DIM command. For example:

DIM A(100)

reserves space for 100 integers in array A. Only 1 dimensional arrays are allowed. Multiple arrays can be defined in a single DIM command:

DIM Table1(300), Table2(500)

To assign the contents of the tenth element in the array Table1 above, to the integer variable R, you would use the notation:

R=Table1(9)

Element 0 is the first element.

Integers occupy two bytes of memory.

Strings & string arrays

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Strings are sequences of up to 32767 characters enclosed in double quotes. String variables are assigned values using the equal '=' sign:

Postcode$="GL53 7PJ"

Title$="Introduction to Basic"

Arrays of strings can also be defined:

DIM Options$(8)

DIM Lines1$(200), Line2$(50)

Strings can be added using the '+' sign, or by just writing the one after the other; thus A$B$ is the same as A$+B$.

When A$="ABC" and B$="DEF" and these two strings are added, the result will be "ABCDEF" as one string. The minus sign can also be used with strings, but its operation is very different. It will search for the numerical location where a given string is found within another string. Thus:

x="HELLO" - "LL"

will result in x=3.

If the result is 0, the string was not found. E.g.:

IF A$ - "Post" GOSUB Zip

will execute the procedure Zip only if "Post" is found in A$.

Normally when you input a string a carriage return will terminate the input. To insert a carriage return between B$ and C$ use A$=B$'C$; or to add a carriage return use A$=A$'.

Labels

In addition to line numbers, Argus BASIC allows the use of 'labels' to uniquely identify particular program lines; e.g. the first line of a subroutine.

Label names must be preceded by a '%' symbol and must appear at the start of a line immediately following the line number. In all other respects labels obey the same rules as variable names and, as with variables it is advisable to choose meaningful names that indicate the function of the label.

300%Count_pulses

550%Check_password

Labels can be used interchangeably with line numbers in commands such as GOSUB and GOTO:

GOTO Try_again

GOSUB Mail

IF A=1 GOTO Yes ELSE GOTO No

The commands LIST and DELETE can also be used with labels:

LIST phone

LIST p1,p2

DELETE part3,part16

To retain compatibility with earlier versions of Argus BASIC, it is permissible to precede the label with '%'. Thus:

GOSUB %Mail

is equivalent to:

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

GOSUB Mail

If you want to use a label with the same name as an existing command, you must always place a % sign in front of the label, e.g.:

GOTO %Connect

GOSUB %Delete

Calculations & expressions

Like any version of BASIC, Argus BASIC can be used for calculations; but as a result of the fact that only integer numbers are allowed, all mathematical operations give integer results.

The following mathematical operators are available:

+ : addition

- : subtraction

* : multiplication

/ : integer division

DIV : same as /

MOD : remainder from integer division

ABS : absolute value

SGN : sign

The following are examples of expressions using integer variables:

X=10 * Y

Scs =(HOUR * 60 * 60) + (MIN * 60)

Res=X/3+Y

Hexadecimal numbers

Numbers can be entered and displayed in decimal or hexadecimal format. Hex numbers must be preceded by the ampersand (&) character:

Hex=&3AC0

Address=PTOP+&1000

Print &A84B

Converting hexadecimal numbers into decimal format is achieved by preceding the hex value by the tilde (~) character. For instance, to print the decimal equivalent of a hex value or variable:

PRINT ~1200 displays 4608

PRINT ~PTOP displays the value of PTOP in

decimal

PRINT ~1000+50 displays 4146 (i.e. 4096 + 50)

By adding the command VAL$, the decimal value can be stored in a text string:

G$=VAL$~120

assigns the value "78" to the string variable G$.

Logical operations

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Argus BASIC also supports a full range of logical operators which are used to make comparisons between expressions, usually within conditional commands such as IF...THEN...ELSE, REPEAT...UNTIL etc.

The logical operators are:

AND

EOR

FALSE

NOT

TRUE

: bitwise AND

: bitwise Exclusive OR

: logical 0

: bitwise negation

: bitwise OR

: logical 1

: equal to

: greater than

: less than

: less than or equal to

: greater than or equal to

: not equal to

Logical operations by the modem are carried out in a 'bitwise' fashion. For example, the command:

X=6AND8

would set X to 0 as follows:

00000110 AND 00001000 = 00000000

Similarly:

X=6OR8

would set X to 12:

00000110 OR 00001000 = 00001110

Strings can be compared using logical operators:

IF A$="Z" THEN ...

IF A$>B$ THEN ...

X=A$<=B$

Events

Argus BASIC recognizes many events, partly on the hardware side, that makes programming a lot easier. You can cause any part of your program to be triggered into action when these events occur While the modem is in BASIC mode, the events enabled will always be operative, even if the program is not running. The events are:

ON AT

ON BRK

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

ON BUTTON(1/2/3)

ON CONNECT

ON DTD

ON DTR

ON ERROR

ON ESCAPE

ON HANGUP

ON RESET

ON RING

ON SEQUENCE

ON SLASH

ON TIMEOUT

So, if you would like your modem to welcome you with a start-up message whenever you start your terminal program, you might include in your program:

10 ON DTR GOSUB Welcome

1100%Welcome

1110 Print "Hello there, this is your modem."

1120 RETURN

1.2 Writing programs

There are two distinct methods of programming the modem.

The first, which you have used so far, is referred to as direct programming; i.e. programs are typed straight into the modem from your computer, using the terminal mode of your communications software. This method is suitable for entering small programs and for testing individual functions; but due to the lack of editing facilities provided by the modem, it is impractical for large programs.

Large programs are best created using a word processor on your computer and then 'downloading' them into the modem when they are ready for testing. This is referred to as indirect programming.

Direct programming

Assuming that the modem is now in command mode with the >1 prompt displayed on screen, you can enter BASIC commands or program lines. The modem is now functioning as a computer and is simply using your PC's keyboard and screen for input and output respectively.

Before starting to enter any new program you should use the following commands to ensure that no other programs are loaded and that the new program is stored in the correct place:

BUFFER OFF

NEW

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

For reasons of speed, direct programming is best carried out at 19200 baud or 38400 baud. If your terminal does not support 38400 baud, use the next highest speed that is available. If your terminal is currently running at a slower speed, you may reconfigure the modem as follows:

• Enter the command WAIT FOR AT, or press the STOP button on the front panel. This will put the modem into 'AT' scan mode.

• Change the baud rate in your terminal software to the required speed.

• Go back on-line. If you pressed the STOP button, type:

AT*B [Return]

if you entered the command WAIT FOR AT, type:

• The baud rate serial and data format for port 1 will now be set to match that of your terminal, and the command mode prompt will be shown.

There is only one editing tool available if you are editing on-line. CTRL-R will display the last line entered. The cursor will be at the end of the line and you can delete the characters backwards and/or add new characters.

Despite the limited editing facilities that are available when entering programs directly, it is still an ideal way to explore the modem and learn about the various functions that are provided. Most commands or commands when entered without line numbers will be executed immediately, and you will see the results.

Indirect programming

It is simpler and more efficient to use the word processing or text editing facilities on your computer to write larger programs. In this case you will first create an ASCII text file of the program and save it on disk. This file may then be transferred (downloaded) into the modem, using the ASCII file transfer option in your communications software. The sequence of events for creating and loading a program in this way is as follows:

• Use a word processor or text editor to create the ASCII version of the program.

• Save the program in a file on disk.

• Load your communications software and get the command mode prompt from the modem.

• Use the ASCII file transfer option in your communications software (NOT X/Y-MODEM or any other error correcting

protocol), to send the program file to the modem.

Note: If you encounter problems with 'echo' during the transfer procedure, you should reset the modem before disabling echo (using the ECHO OFF command), and try again.

When programming indirectly, the first few lines of your program file must contain certain commands which prepare the modem to receive the remainder of the program. Specifically the following must be included:

• CLEAR or BUFFER OFF - to clear that part of the modem's memory which is used for variable storage.

• PBOT=&3000 - sets the address in the modem's memory at which the program will be stored. PBOT is a

system variable that stands for Program BOTtom.

• NEW - clears program memory and prepares the modem BASIC interpreter to accept a new program.

If you include line numbers in your word-processed file you must keep track of them yourself. For obvious reasons you will not be able to use the modem's RENUM command until you have uploaded the program.

If you do not include line numbers in your program text file, you must include the AUTO command at the beginning of the file so that line numbers will be generated for you during uploading. One disadvantage of using a word processor to create program files without line numbers is the difficulty of implementing GOTOs or GOSUBs to line numbers. As an alternative to line numbers in programs where a limited number of subroutine calls or GOTO commands are used, you should use labels. Because labels are easier to remember, we recommend that you only use labels.

The first few lines of your program should be:

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

With line numbers: Without line numbers:

PBOT=&3000 PBOT=&3000

BUFFER OFF BUFFER OFF

NEW NEW

10 REM Program start AUTO

. REM Program start

Prior to downloading you should ensure that you have hardware handshaking (RTS/CTS), enabled within your terminal software to avoid losing characters during the transfer.

Note: the modem uses hardware handshake by default, but software handshaking can also be selected using the HANDSHAKE command.

You should also ensure that ESCAPE is enabled in order that it can be used to cancel auto line-numbering when downloading is complete. (See ESCAPE.)

Remarks in a text file can be best implemented by using the '\' sign instead of the REM command. The BASIC interpreter discards the rest of the line behind \ when it is in auto mode. Example:

X=12 \ Start for X

1.3 Running programs

The modem has two (2) different operating modes: it can be used either as a Hayes compatible modem or as a Programmable (or BASIC) modem. It is important that you know exactly how to change from one mode to the other.

To go from modem-mode to BASIC-mode:

• enter AT*B [Return]

To go from BASIC to modem-mode:

• enter MODEM [Return], or have MODEM as a command in a program line.

• In case of an Argus with 5 buttons: first set the S/A button in the in-position and push the STOP button, then set the S/A button in the out-position again.

• In case of an Argus with keyboard: press > + >> + >>> at the same time. This will jump directly to modem-mode.

The effect of entering modem-mode from BASIC is to:

• disable all events but ON RESET. You must be careful here, since once ON RESET is effective, the modem will execute the command associated with ON RESET after every reset or power shutdown.

• leave all variables and buffers as they are.

While still under development, a program will normally be executed using the RUN command. Once development is complete, it is recommended that the program be started with the command ON RESET, or ON RESET GOTO <line number>. This will make your program start whenever you press the RESET button, or after a power failure in the same way. No variables or buffers will be cleared when this happens. If you want the variables and buffers to be cleared, make

CLEAR one of your first program commands.

10 ON RESET PRINT "You are in BASIC once again"

20 PRINT "*";

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

30 WAIT 300

40 GOTO 20

If the RESET button is pressed immediately after this program has been entered (but before it has been run), nothing will happen. After the program has been run once, the modem will return to BASIC mode after you press the RESET button, print "You are in BASIC once again", and send asterisks to your screen.

Pressing the RESET button will restart the program again from the first line. If an [Esc]ape sequence ([Ctrl-C]) is now entered , the program will stop; but ON RESET will still be enabled. Pressing the START button prints 'You are in BASIC once again' and the program will show the asterisks again. If you now press the STOP button again, you will return to modem mode once more.

As soon as you press the RESET button again after that you will return to BASIC once more and the program will run once more, etc.

Running files from the filing system

If you have a filing system (RAM-, FLASH- or Hard-disk or LAN), you can load and save BASIC programs. The command RUN "Name" will first load the program ‘Name’ in system memory on address PBOT (default &3000) and then run it. Once ON RESET RUN "Name" has been entered, you will always start the program 'Name', when you push the RESET button. For standard applications, we have also included a special program named 'BOOT'. This means that if there is a program in memory/disk with the name BOOT, it will always run when you press RESET or after a power shutdown, even if ON RESET is active or inactive. The only way to disable BOOT is with the command BOOT OFF.

1.4 Program and variable storage

The area of memory between &3000 and &7FFF is known as Program memory. BASIC programs are normally stored starting at location &3000 and working upwards, while the variables used by a program are stored in the area just below &7FFF.

A system variable PBOT is used to hold the current program start address, and can be changed to allow two or more programs to be stored at the same time in Program memory.

The highest location used by a program is held in another system variable called PTOP. The size of a program can therefore be calculated by subtracting PBOT from PTOP, and the amount of space remaining for variable storage may be calculated by subtracting PTOP from &7FFF.

Two other commands will reduce the amount of space available for variables:

BUFFER ... if the BUFFER command has been used to define a 'user buffer', the specified amount of space

will be reserved starting from &7FFF and working downwards. This means that variables will be stored at a lower location than usual.

BUFFER OFF may be used to release previously allocated space.

Note: the use of BUFFER will always clear all variables and is therfore recommended to be one of the first commands in any program.

If a program runs out of memory, it is also possible to split up a big program into smaller programs. Depending on the application, a program can be called from within another program with RUN “Name2”, without loosing all variables!

Variables are stored in alphabetical order in memory so that, for example, if an integer A is the first used variable, its value will be stored in locations &7FFE and &7FFF.

The first letter of a variable name is therefore very important as two 26-entry tables are maintained (one for integers and the other for strings), which contain the start address for variables starting with a specific letter. Once an entry has been created in the table, all variables with the same first character are stored in the same memory area. As only the first defined variable

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

with a specific start character is directly accessible, a sequential search of memory must be made to find other variables starting with the same letter. For this reason you should try to use as many different start characters as possible when speed of operation is important.

This method of storage results in the creation of up to 52 separate storage areas. If no variables starting with the letter 'T' are used then no space will be reserved for them. The CLEAR command which is used to destroy all program variables simply clears the look-up table and sets the variable pointer to &7FFF.

Assuming that no buffer memory is allocated, the memory map will be as follows:

Address Letter/variable type

&7FFF

integer variables starting with Z

integer variables starting with A

string variables starting with Z

string variables starting with A

PTOP

PBOT

end of program

start of program

The way in which variables are allocated can be demonstrated by entering the following program:

PBOT=&3000

NEW

DIM A(6000)

After execution of this program, a single variable with 12K allocated has been created in memory. When variable B is defined with the command:

B=0

you might notice that it takes a little while before the prompt returns. This is because the entire area of memory allocated for the integer array A must be shifted in order to create space for the integer variable B. Once this has been done, further access of B will take no noticeable time, a fact that you may prove by now entering the command:

B=1

1.5 I/O ports

Each I/O port on the modem is identified by a unique port number:

Port Device

1 Serial port 1 (25 pin D type)

2 Serial port 2 (9 pin D type)

3 Telephone line (modem chip)

4 reserved

5 reserved

6 Keyboard input & LCD display output

7 Parallel Printer port

8 Memory buffer

Port 1 is serial communications port 1 with asynchronous speeds up to 115200 baud. Synchronous operation is also possible.

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Port 2 is serial communications port 2 with asynchronous speeds up to 38400 baud.

Port 3 is the telephone line and is only used if a modem connection is active.

All data streams associated with these ports (receive and send for each), are managed by the modem's operating system, using interrupt driven buffers. All BASIC commands related to the receipt of data (INPUT, GET, etc.) automatically use the input buffers. Commands which serve to transmit characters, such as PRINT and PUT, use the output buffers. Buffer management is therefore transparent to the user, whose only concern should be the type of handshaking used (see below).

I/O buffers are 256 bytes in length and are filled and emptied automatically as data is transferred. However, overflow of input buffers will occur at any speed if data is removed from the input buffers more slowly than new data is received AND no handshaking protocol is in use. Loss of data due to overflow can be avoided by enabling either software (XON/XOFF), or hardware (RTS/CTS) handshaking as appropriate.

Under normal conditions, a program attempting to place data into a full output buffer will be suspended until space becomes available. However when a LINK has been established between two ports handshaking must again be used to prevent overflow. Full descriptions of the HANDSHAKE and LINK commands are given under the appropriate headings in the BASIC reference section.

Port 6 is used for the keyboard as an input and the LCD display as an output (if available). At the back of this manual there are tables for both keyboard and LCD codes..

Port 7 is the parallel printer port. The connector is situated inside the case but a slot in the rear panel is provided for a parallel cable. The parallel port can be defined as an input only or output only.

Port 8 is unusual in that it is not a hardware port, but refers to an area of memory that may be used as a data buffer by BASIC programs. The buffer must be created explicitly using the BUFFER command before it can be used, but thereafter it may be treated in the same way as any other port, using commands such as PUT, GET, PRINT and INPUT. It can be used for input and output in the way a FIFO stack works.

Port syntax

Port numbers in BASIC commands must always be preceded by the hash or pound (#) character. For example, to print a message to port 2 you could use the following:

PRINT#2, "Message from port 2"

In all cases the word "PORT" can also be used e.g.:

PRINT PORT1, "Message from port 1"

Similarly, to read a string from port 2:

INPUT#2, A$

Your program may be easier to understand if you give names to the ports that you use by assigning them to variables:

P=3

PRINT#P, "text"

INPUT#P, A$

For those commands used to set port attributes such as the baud rate, and those used to output data, you may specify more than one port. The following command will print the message "Commencing file transfer..." to both ports 1 and 2 simultaneously:

PRINT#1,#2, "Commencing file transfer..."

Commas between the port numbers are optional (PRINT#1#2).

Listed below are those commands which may include one or more port numbers as parameters:

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

AT ESCAPE LENGTH PARITY SBITS

BAUD GET LINEFEED PRINT SEND

CLEAR GET$ LINK PUT XOFF

CTS HANDSHAKE LIST PUT$ XON

DCD INPUT MATCH RECEIVE

DSR KEY ORI RTS

DTR KEY$ OUTPUT

For obvious reasons commands used to input data may only specify a single port.

When repeated access is required to one or more ports you may define default values for input and output using the IPORT and OPORT system variables which are described fully under the relevant BASIC reference headings.

1.6 The Argus filing system

The primary aim of any communications system is the successful transfer of information. However temporary storage of information is very often required to synchronize communications between two different systems. Very different from any other modem, this modem can store data to be sent, or data that has been received temporarily, to allow transfer to a remote or to the local system later. The data may consist of computer programs, text files or other forms of data. Various standards have been adopted over the years to suit different applications, including MNP or V42 error correction and Xmodem or Ymodem file transfer. The mechanism to support some of the common standards have been built into the modem, and have, as far as possible, been made transparent to the programmer. As a result, the task of receiving, storing and sending files and messages is handled almost entirely by the modem.

In order to manage the various types of information that may exist, the modem can have its own filing system. There are 4 types:

1. RAM-disk (up to 1 Mb)

2. FLASH-disk (up to 2 Mb)

3. Hard-disk (up to 3.6 Gb)

4. Argus LAN (network server + station’s)

The RAM/FLASH-disk is 'bank-switched' into the memory map from &A000 to &C000. Bank-switching is fully automatic and requires no special action by the programmer. In the case of an Argus Programmable Modem, there are two 32-pin sockets provided inside the modem, each of which will accept a 128Kb, 256Kb or 512Kb RAM module. The second socket will accept a 128Kb or 512Kb FLASH module, only if the first socket contains a 128Kb RAM module. In the case of a T.C.Lite (with keyboard and LCD display) there is only one socket which will accept a 128Kb, 512Kb or 2Mb FLASH module.

The Hard-disk and LAN are only available for the Argus Programmable Modem. The network server is an Argus with Harddisk and a station is an Argus with build-in network facilities.

The filing system is not a standard feature of the modem, but an option that you can order with your modem, or add later, as and when required.

The filing system of the modem recognizes three distinct types of files:

• Text messages

• Binary files (voice also)

• Argus BASIC programs

File storage is handled entirely by the modem's operating system. Files are stored sequentially in RAM/FLASH-disk, the oldest first.

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

On a Hard-disk, the files are stored in ‘directories’ which are created and removed automatically by the operating system; the first character of a filename is the directory entry. Only the characters 0-9, @, and A-Z are possible as the first character in a filename!

The following commands can be used to manipulate files:

CLEAR PLAY/RECORD

COPY RECEIVE

DELETE RENAME

DIR RESTORE

FAX RUN

LOAD SAVE

MATCH SEND

The syntax for manipulating files in general is:

COMMAND ![filename]

COMMAND FILE [filename]

However in most cases the exclamation mark (!) or the word "FILE" can be left out. Only with MATCH, CLEAR and RESTORE they must be used.

Filenames may be up to 16 characters long and may only contain ASCII characters from 33 to 127 (so they cannot include spaces). Two other characters with special meanings that can be used in filenames are:

* : the asterisk (star), which is used as a multiple character 'wildcard'.

? : the question mark, which is used as a single character ‘wildcard’.

. : the full point (dot), which is used to split filenames into a maximum of three sections called extensions. This

allows groups of related files to be given the same extension.

In order for files of a similar type to be grouped together within a directory listing, it is logical to use filename extensions. For example, all BASIC program files could be given the extension '.BAS'; text files could be '.TXT'; etc. To display a list of BASIC programs you would then use:

DIR "*.BAS"

Text files

Straightforward text files are stored in the disk 'as is', i.e. one byte is used for each ASCII character. However, when it comes to transferring text files the modem supports a number of the conventions used by telex-based systems. For instance, the command:

RECEIVE#1, "TEST", T

prepares the modem to receive a text file via serial port 1 (the T is short for Text or Teletype). First, the modem transmits the message:

Please enter your message:

to port 1. It then reads any characters received from port 1 and places them in the disk in a file called "TEST". The file is only closed when either:

or:

a) a single line containing the characters "NNNN" is encountered in the input stream

b) an ESCAPE is received.

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

The second method can be disabled if necessary by using the ESCAPE OFF command.

When a transfer is complete, the DIR command may be used to verify that a new file has been created. DIR will also show the type of the file, how many 256-byte blocks it occupies and how many free blocks (or clusters on hard disk) remain.

A text file can be 'read' by sending it to the port to which you are connected. Thus to display the file "TEST" from the previous example you would use:

SEND "TEST",T

Text files can be removed from the disk using the DELETE command, but they must be read at least once before this can be done.

Binary files

Binary files may contain any type of data and are transferred using the Xmodem or Ymodem file transfer protocol. For example, to download a binary file into the modem using Xmodem, you could use the command:

RECEIVE "DATA1",X

Once this has been entered the modem will initiate an Xmodem receive sequence. The required file can now be downloaded by selecting the Xmodem file transmit option in your terminal software. When the transfer is complete the file will be stored in the disk using the name given in the RECEIVE command.

To re-transmit the file use:

SEND "NAME",X

This will only work if the receiving system supports Xmodem file transfer. Multiple files can be merged by using the wildcard character in the filename specification:

SEND "*.DATA",X

However in most cases it is better to use the Ymodem file transfer, because file length is preserved (see PROTOCOL command).

BASIC programs

BASIC programs can be stored to and retrieved from disk using the SAVE and LOAD commands. Disk programs are accessed by their filename:

SAVE "TESTPROG1.PRG"

LOAD "TESTPROG2.PRG"

The file type as shown in a directory listing will be 'B' for BASIC program.

Programs may also be loaded into Program memory and executed with a single RUN command:

RUN "HOSTSYS.PRG"

1.7 Program backup

The importance of making regular backup copies of both programs and data from your computer cannot be stressed too often, and the same golden rule applies when writing programs for the modem.

If you use a word processor to create and edit programs, your normal computer backup procedures can be applied. Backups should be made every time you modify a program.

A different procedure will be required to maintain backups of programs entered directly into the modem. Although the modem memory is battery-backed and does not lose its contents when power is shut off, it is possible that low usage over a

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

period of time will cause the battery to run down and memory to be corrupted. For this reason you should make copies of programs from the modem into your computer or to diskette, to use as permanent backups.

Backing up Program memory

Currently active programs, i.e. those in Program memory, are stored in a compact, encoded (tokenized) form, and cannot therefore be read without the aid of the LIST command. When you use LIST, the stored program is decoded and displayed as ASCII text in the form in which it was originally entered. You may take advantage of this fact to obtain backups in ASCII format of programs that have been entered directly, by using the following procedure:

• Load your terminal software and put the modem into Command mode.

• Use your terminal software to open a file for the reception of ASCII text.

• Go back on-line to the modem and use the LIST command to list the program.

• When listing is complete, close the file and save it on disk.

This file can now be stored permanently as a backup, or it can be edited and downloaded back into the modem when editing is complete. To avoid loss of data while using LIST in this way, make sure that either software or hardware handshaking is selected as appropriate.

Backing up the RAM-, FLASH- or Hard-disk

Even when you have a filing system installed, the need to make a back-up of all your programs and data, is still there. Normally you will save programs, text and binary files in the disk. It is extremely difficult to erase the disk by accident, and the battery backup (in case of RAM-disk) is quite reliable because of the watchdog facility. Nevertheless, we think that it is a wise precaution to backup valuable data now and then onto floppy or the hard disk of your computer.

The easiest way to create a backup is to connect to the modem locally or from a remote terminal and go into BASIC. Then tell the modem:

SEND ALL or SEND "*.*.*.*",C

and use your communications program to download the complete contents of the disk with Xmodem-CRC file transfer.

To restore the complete contents of the disk from your PC, tell your modem to:

RECEIVE ALL or RECEIVE "C",C

and use your communications program to return the same data you have received earlier (also with Xmodem-CRC file transfer).

Of course you can also back up separate files from the disk by using the ,C option. In this way you get a backup-part:

SEND "*.PRG",C

SEND "MESS*.SYS",C

Seperate received backup-parts can be added together in the PC as one big file, which can be used later to restore a disk.

The ,C option tells the modem that it is a file Copy, meaning that all information such as name, length and date, is included in the transfer.

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

Argus BASIC - Command Reference

Argus BASIC is a custom communications' variant of the popular BASIC language found on many micro-computers. It is a relatively fast implementation which owes much of its speed to the use of a 68HC11 microprocessor running at 3.68 MHz, and integer-only operation. However, multiple high-speed communication streams can still present problems, and some care may be required when developing more adventurous applications in order to avoid potential timing problems; especially if you are using error correction and/or data compression at the same time, at high baud rates such as 9600 baud. Remember also that the execution speed of a program can depend greatly upon how it is written. In this respect you should take note of the following if speed is critical in your application:

• Avoid using port numbers in commands - use default values by assigning IPORT and OPORT appropriately where this is possible.

• Minimize the use of brackets in expressions and function calls - CHR$7 is the same as CHR$(7).

•

Use short variable names.

• Distribute the first characters of variable names across the whole alphabet.

• Combine multiple commands into single program lines.

• Omit variable names with the NEXT clause of FOR ... NEXT loops.

• Minimize the use of string variables.

• Split long calculations into separate, short sections.

• Avoid using the READ and DATA commands - they are relatively slow.

• Using line numbers for GOTOs is faster than using labels.

• If you do use labels keep them short (e.g. %OL, %2).

You should realize that the application of these guidelines may result in poorly structured programs that are difficult to read. Some compromise may be required, particularly during the development stage.

Syntax

Each of the command descriptions in this section is followed by a series of examples, a syntax description, and a list of associated commands to be used as a cross-reference.

The following notation is used in the syntax descriptions:

[-] items in square brackets indicate one of the program 'elements' listed below.

[num-var] : numeric variable

[num] : a numeric variable or constant

[string-var] : string variable; e.g. Name$

[string] : string variable or constant

[integer] : an integer value from -32767 to 32768

[integer n1 ... n2] : an integer value in the range n1 to n2

[port] : a port number (1,2,3,7 or 8)

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

[option] : a single character option code

[type] : a single character type code

x|y : either x or y

( [...] ) : the enclosed item is optional

( , ... ) : optional repetition of the previous item

Other items that appear in the syntax of a command, e.g. #, are shown 'as is'.

ARGUS Programmable Modem

BASIC Programmer's Reference Manual

ABS absolute value

ABS is used to obtain the absolute value of an integer; i.e. its magnitude.

ABS(-10)

will return the value 10.

It is commonly used to find the difference between two numbers:

diff=ABS(X-Y)

Examples:

A=ABS(B)

PRINT ABS(Temp-38)

Syntax:

[num-var] = ABS [num]

VidiCode ARGUS BASIC User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual