Vidicode Argus Basic Programmers Reference Manual

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
18
  
 
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 Hard-
disk 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 modems operating system. 
Files are stored sequentially in RAM/FLASH-disk, the oldest first.  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
19
  
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]
or 
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: 
a)  a single line containing the characters NNNN is encountered in the input stream 
or: 
b) an ESCAPE is received.  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
20
  
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
or 
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 Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
21
  
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 Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
22
  
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 Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
23
  
[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 Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
24
  
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]
See also: 
SGN
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
25
  
ACTIVE    set modem active 
This command will simulate any modem connection, after the two modems are connected.  It can therefore best be used 
after the ON CONNECT event.  When entering the command, it will set the link between the terminal port and the line port 
(3).  The terminal port must first be set with the system variables IPORT and OPORT.  A multiplexed or half duplex 
connection is also simulated if selected.  Exiting the command must be done by ON-events, which are set before the 
ACTIVE command was given. The following events are possible during ACTIVE. 
ON HANGUP
:  Connection is lost 
ON TIMEOUT
:  An inactivity timeout has passed 
ON SEQUENCE
:  The escape-sequence is detected (+++) 
ON DTD: :  DTR on the port has dropped 
ON ESCAPE
:  An escape is detected 
Example: 
10 ON CONNECT GOTO %Conn
20 DIAL 123456
30 REPORT:END
40%Conn
50 ON HANGUP GOTO %Loss
60 ON TIMEOUT 10 TIMEOUT OFF: GOTO %Hang
70 ON SEQUENCE GOTO %Hang
80 ON DTD GOTO %Hang
90 IPORT = 1: OPORT = 1
100 REPORT
110 ESCAPE OFF
120 ACTIVE
130%Hang
140 HANGUP
150%Loss
160 REPORT
170 ON OFF
180 END
Syntax: 
ACTIVE 
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
26
  
See also: 
ON CONNECT 
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
27
  
ADC    analogue to digital conversion 
The modem is capable of performing an analogue measurement of the signal voltage level on the line. A value between 0 
and 255 is returned. 
 
If the modem is on-hook the measurement is always zero. 
 
If you take the modem off-hook and your exchange applies a dial tone, or if a carrier is received, you will be able to see the 
signal voltage on the line. 
 
To test this, enter: 
10 DIAL 123456 : REM dial non-existent number
20 REPEAT : PRINT ADC :WAIT 10:UNTIL FALSE
RUN
For specialist applications ADC, together with FREQ can be extremely useful, to evaluate what is going over the line.  Most 
users however will have no need for these commands. 
Examples: 
PRINT ADC
Millivolts=ADC
Syntax: 
[num-var] = ADC
See Also: 
FREQ