Vidicode Argus Basic Programmers Reference Manual

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
178
  
PTOP    program top 
This is an important (read-only) system variable that contains the address where a BASIC program ends.  The length of the 
program can be determined by subtracting the value of PBOT from PTOP: 
PRINT PTOP-PBOT
PTOP is useful when more than one program is stored in memory: 
start1=PBOT
PBOT=PTOP-1
(NEW)
LOAD ...
PBOT=start1
RENUM
Examples: 
End=PTOP
PRINT ~PTOP
Syntax: 
[num-var]=PTOP
See also: 
PBOT
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
179
  
PULSE    pulse dialing 
PULSE is used to select pulse dialing in dial commands, or to dial just one or more digits. 
Examples: 
DIAL PULSE 123456
PULSE 8
PULSE 2,6,4
Syntax: 
DIAL PULSE [string]
PULSE [integer] (,[...])
See also: 
TONE
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
180
  
PUT    write byte value to port 
PUT is used to write single byte values to the specified output port(s). 
 
If the port number is omitted, the default output port as defined by OPORT will be assumed.  The character to be written is 
given as a single byte which represents its ASCII value. 
 
For example, the command: 
PUT#1,65
will write ASCII character 65 (the letter A), to port 1 and is therefore equivalent to: 
PRINT#1,CHR$(65)
Multiple-byte data can be sent with a single PUT command by separating each ASCII value with a comma: 
PUT#2,12,9,9,10,10,65
When the PUT function is used to send a Carriage Return, the modem does NOT automatically append a Linefeed. 
 
PUT is often used in conjunction with GET as a simple means of passing characters received from one port as output to 
another: 
10 REPEAT
20 PUT#2,GET#1
30 UNTIL FALSE
In this example, the byte value returned from GET#1 is used as the parameter for the PUT function, so that all characters 
received from port 1 are written to port 2. 
Examples: 
PUT 12
PUT#2,32,32,32,13,10
PUT 30,13,13,255
PUT#2,#4,12
Syntax: 
PUT ( #[port],)(#... ) [integer 0..255]
See also: 
PRINT, PUT$
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
181
  
PUT$    write character to port 
PUT$ is used to write single ASCII characters to the specified output port(s). 
If the port number is omitted, the default output port as defined by OPORT is assumed.  The character to be written is given 
as a single character string. 
For example: 
PUT$#1,A
will print the character A to port 1.  If the parameter string is longer than a single character, only the first character in the 
string is used so that: 
PUT#1,Name$
is equivalent to: 
PRINT#1,LEFT$(A$,1);
PUT$ may be used in conjunction with KEY$ as a simple means of passing received characters from one port as output to 
another: 
10 REPEAT
20 PUT$#1,KEY$#2
30 PUT$#2,KEY$#1
40 UNTIL FALSE
Examples: 
PUT$ KEY$#1
PUT#1,#7,Id$
Syntax: 
PUT$ ( #[port], ) (#...) [string var]
See also: 
PRINT, PUT
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
182
  
READ    read data items 
READ is used to read information stored in DATA commands into integer or string variables.  As many items of data are 
read as is necessary to assign to the variables given in the READ command. 
 
If there is insufficient data to satisfy the READ, an Out of Data error message will be given. 
Examples: 
READ Name$,Code
READ Port(I),Rate(I),Wlen(I)
READ X,X$(X),Y,Y$(Y)
Syntax: 
READ ( [num-var] | [string-var]),...
See also: 
DATA, RESTORE
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
183
  
RECEIVE    receive file or data 
RECEIVE is one of the most powerful commands available with this modem, and provides a simple means of transferring 
data into the modem under program control, with minimum effort. 
 
There are 3 basic forms of the command: 
RECEIVE [port],[address]   : receive data using Xmodem 
RECEIVE [port],[filename],[type] : receive file 
RECEIVE ALL: receive a backup of the disk 
 
In addition, the second form can be used with one of a number of options which are dealt with individually in the following 
sections. 
  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
184
  
RECEIVE #[port], [address]    receive data 
Here, RECEIVE is used to transfer data as opposed to a file, using the Xmodem file transfer protocol to prevent the 
occurrence of errors. 
 
The command is followed by a port number (1 - 3 only) and an address, which are both optional. 
 
If the parameters are omitted, the default input port as defined by IPORT, and the start address defined by PBOT, will be 
used. 
Examples: 
RECEIVE#2
: receive data and store at PBOT 
RECEIVE &3000 
: receive data and store at address &3000. 
RECEIVE Location: receive data and store at address defined by variable 
Location. 
RECEIVE#3,&4321: receive data via modem (port 3) and store at address 
&4321 
This form of the RECEIVE command cannot be used to download BASIC programs in ASCII format into the modem, 
because during receive, data is simply copied into the modems memory, and would not undergo the tokenization process 
required by the BASIC interpreter. 
 
During a data RECEIVE, the ESCAPE and XOFF settings for the specified port will be temporarily disabled, and the 
character length will be set to 8 bits.  The original settings will be restored after completion of file reception. 
 
An error message (28) will be generated if, after 180 seconds, no characters have been received.  If this is likely to occur, 
you should trap the error using the ON ERROR command.  The same error message will be given if more than nine 
Xmodem transfer errors occur during reception of the same block. 
Examples: 
RECEIVE
RECEIVE#2
RECEIVE &4000
RECEIVE#Port,Address
Syntax: 
RECEIVE ( #[port], ) ( [integer] )
See also: 
SEND#[port],[address] 
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
185
  
RECEIVE [filename], [type]    receive file 
When followed by a string, the RECEIVE command is used to receive and store complete files in the filing system: 
RECEIVE [filename]
All types of files discussed under the DIR command may be received, and there are various options which are discussed 
below. 
RECEIVE [filename] (,T/N) 
RECEIVE without a parameter, or with the ,T parameter, prepares the modem to receive a text file.  On executing the 
command a file is opened and the message: 
 Please enter your message: 
will be transmitted. 
 
You may suppress this message by using ECHO OFF before RECEIVE, if necessary.  Any text now received by the 
modem will be stored in the specified file (if the file already exists it will be overwritten).  Text storage is terminated and the 
file closed when a single line containing NNNN or NNNNE is received.  At the same time the file directory will be updated 
to include the date and time at which the file was received. 
 
The sender may cancel the transfer at any time by entering CCCC on a line by itself, in which case none of the received 
text will be stored.  The transfer will also be aborted if an ESCAPE is entered, or the RESET buttons is pressed. 
 
All event handlers such as ON TIMEOUT will remain active during the transfer. 
 
On completion of the transfer, the DIR command can be used to check whether the file has been successfully received, how 
much memory it occupies, etc.  The message can be read back out of the modem by using the appropriate form of the 
SEND command. 
 
One further variations is used to receive text files from systems which do not support the [CR]NNNN[CR] convention: 
RECEIVE [filename],N
In both cases the prompt message is suppressed and the modem will wait for the first character to be received before 
initiating a countdown timer.  Whenever a character is received it is stored in the file and the timer is reset.  The file is closed 
when no characters have been received after a certain time (specified with RECEIVE TIMEOUT); or when either of the 
[CR]CCCC[CR] or [CR]NNNE[CR] sequences have been received; or when ESCAPE has been entered. 
 
On exit the system variable ERN can have the following values: 
ERN = 0 OK
: File stored 
ERN = 6 Cancelled
:  CCCC sequence detected 
ERN = 22 Out of memory
: Disk full 
 
RECEIVE [filename],F 
RECEIVE,F is used to capture all incoming data, including control codes, into a file of the specified name.  Received 
characters are not echoed, and capture will terminate automatically when no data has been received after a timeout that is 
specified with RECEIVE TIMEOUT.  Detecting ESCAPE is disabled during reception with the ,F option. 
 
RECEIVE,F can also be used to copy or manipulate files within the modem by using the BUFFER (port 8).  The following 
program demonstrates how this can be done: 
10 CLEAR
20 BUFFER &1000 
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
186
  
30 REPEAT
40 INPUT Enter Source file : ; Src$
50 MATCH Src$
60 IF NOT MATCH PRINT No such file : GOTO 40
70 INPUT Enter Destination file : ; Dest$
80 CLEAR#8
90 SEND#8, Src$, F
100 RECEIVE#8, Dest$, F
110 Print File copied OK
120 UNTIL FALSE
In this case, no timeout condition is applied and the RECEIVE will terminate automatically when the buffer is empty.  The 
buffer size specified must be large enough to accommodate the entire file.  If the file size is greater than 16K (i.e. larger than 
the maximum buffer size), copies must be made by using SEND [source],P (part) and RECEIVE [dest],A (append). 
 
Of course, you will normally use the command COPY to copy files! 
RECEIVE [filename](,T/F),A 
This command allows you to append data to the end of an existing file.  The file must be the last file in a RAM-disk otherwise 
ERN 93 (“Not last”) will be generated.  For a Hard-disk filing system it doesn’t matter which file on the disk is used.  When 
the file does not exist, it is created first. 
 
The input is determined by the ,T  or ,F options (text or binary).  When the disk becomes full, the system variable ERN is 
set to 22 (“Out of memory”) and the RECEIVE is aborted. 
RECEIVE [filename],X 
RECEIVE,X  is used to transfer files using the Xmodem / Ymodem error correction protocol.  Any type of file may be 
received from a compatible Xmodem / Ymodem system with complete safety, and although binary files may contain data 
from other computers and cannot be used by the modem itself, they can be stored for access by other systems using the 
SEND,X command. 
The PROTOCOL command must be set first to select the right transfer protocol.  If Ymodem-Batch is used, the filename is 
included in the transfer and can be a dummy filename in the RECEIVE,X command. 
 
After receiving, the system variable ERN must be checked to see if the receive was successfull. For example: 
PROTOCOL 7
RECEIVE dummy,X
IF ERN GOTO Err ELSE GOTO Ok
On exit the system variable ERN can have the following values: 
ERN = 0 OK
: File stored 
ERN = 7 Failed
:  Timeout or too many errors 
ERN = 22 Out of memory
: Disk full 
ERN = 23 Subscript
:  File too big (>16 Mbyte) 
ERN = 33 Aborted
:  CTRL-X detected twice 
ERN = 72 Bad name
:  Filename not correct (Ymodem-Batch)  
						

							ARGUS Programmable Modem 
BASIC Programmers Reference Manual 
© 1990 - 1997 Vidicode Datacommunicatie BV 
187
  
 
If Ymodem-Batch is used, the system variable MATCH contains the number of files received. 
RECEIVE [filename],C 
The RECEIVE,C command is very useful in combination with the SEND,C command to create and restore file copies.  
The used filename is not important (but must be filled in), because the received file contains all the original Argus filenames.  
All other Argus-filing-system related information is also included in the copy for each file.  The Xmodem-CRC protocol must 
be used and is set automatically with RECEIVE,C (PROTOCOL 1).  Example: 
RECEIVE dummy,C
On exit, the system variables ERN and MATCH can have the same values as with RECEIVE,X. 
RECEIVE [filename],B 
For every file stored in the modem, a 32-byte information block is created.  This block is provided for use by the programmer 
in storing additional information about the file, and may contain items such as telephone numbers, user names, date & time, 
etc. 
 
The information block is editted by using POKE, to put the appropriate data into memory locations &2BE0 to &2BFF.  This 
32-byte memory block is always saved together with the file after a successfull RECEIVE command (this is also true for 
SAVE and RECORD).  Setting the memory block before the RECEIVE command is more efficient, because in that case 
the RECEIVE,B command can be omitted.  RECEIVE,B is only used to incorporate the block into an existing file. 
 
The block on memory locations &2BE0 to &2BF0 and the block in a file are never changed or used by the filing system itself.  
So, the block is completely free for use by the programmer. 
 
SEND ...,B is used to extract the information block from a file and store it back into memory at locations &2BE0 to 
&2BFF.  The information can then be read using PEEK. 
 
DIR,B can be used to send the information block to a port (a Carriage Return will be automatically appended to the end of 
the block). 
 
For example: 
10 RECEIVE TESTMESSAGE, T
20 POKE$ 240,INFORMATION+SPC$(21)
30 RECEIVE TESTMESSAGE, B
40 SEND TESTMESSAGE, B
50 PRINT PEEK$ 240
60 DIR TESTMESSAGE,B
Line 10 is used to create the test message, which must be terminated with [CR]NNNN[CR] as usual. 
 
Lines 20 and 30 are then used to fill the information block afterwards. 
 
Line 40 extracts the information block from the file, and lines 50 and 60 illustrate the two methods of displaying the block. 
RECEIVE ROM [filename], [type] 
RECEIVE ROM is used to receive one file or a group of files to a RAM chip in socket 2 of an Argus Programmable Modem. 
See ROMfor further details. 
The type and options are used in the same manner as with the normal RECEIVE command.