RECEIVE PACKET

version 6.8 (Modified)

RECEIVE PACKET ({docRef; }receiveVar; stopChar | numChars)

Parameter	Type		Description
docRef	DocRef		Document reference number, or
			Current channel (serial port or document)
receiveVar	Variable		Variable to receive data
stopChar | numChars	String | Number		Character(s) at which to stop receiving, or
			Number of characters to receive

RECEIVE PACKET reads characters from a serial port or from a document.

If docRef is specified, this command reads characters from a document opened using Open document, Create document or Append document. If docRef is omitted, this command reads characters from the serial port or the document opened using SET CHANNEL.

Whatever the source, the characters read are returned in receiveVar, which must be a Text or String variable. To read a particular number of characters, pass this number in numChars. To read characters until a particular string (composed of one or more characters) is encountered, pass this string in stopChar (the string is not returned in receiveVar).

When reading a document, if stopChar | numChars is not specified, RECEIVE PACKET will stop reading at the end of the document. However, remember that while a string variable has a fixed length, a text variable accepts up to 32000 characters. When reading from a serial port, RECEIVE PACKET will attempt to wait indefinitely until the timeout (if any) has elapsed (see SET TIMEOUT) or until the user interrupts the reception (see below).

During execution of RECEIVE PACKET, the user can interrupt the reception by pressing Ctrl-Alt-Shift (Windows) or Command-Option-Shift (Macintosh). This interruption generates an error -9994 that you can catch with an error-handling method installed using ON ERR CALL. Usually, you will only have to handle interruption of a reception when communicating over a serial port.

When reading a document, the first RECEIVE PACKET begins reading at the beginning of the document. The reading of each subsequent packet begins at the character following the last character read.

Version 6 Note: This command is still useful for document opened with SET CHANNEL. On the other hand, for a document opened with Open document, Create document and Append document, you can now use the new commands Get document position and SET DOCUMENT POSITION to get and change the location in the document where the next writing (SEND PACKET) or reading (RECEIVE PACKET) will occur.

When attempting to read past the end of a file, RECEIVE PACKET will return with the data read up to that point and the variable OK will be set to 1. Then, the next RECEIVE PACKET will return an empty string and set the OK variable to zero.

Note: When you use the RECEIVE PACKET command to read characters from a Windows document and do not want to use ASCII maps to convert Windows characters into Mac OS characters, you can use the Win to Mac function.

1. The following example reads 20 characters from a serial port into the variable getTwenty:

   RECEIVE PACKET (getTwenty; 20)

2. The following example reads data from the document referenced by the variable myDoc into the variable vData. It reads until it encounters a carriage return:

   RECEIVE PACKET (myDoc;vData;Char (Carriage Return))

3. The following example reads data from the document referenced by the variable myDoc into the variable vData. It reads until it encounters the </TD> (end of table cell) HTML tag:

   RECEIVE PACKET (myDoc;vData;"</TD>")

4. The following example reads data from a document into fields. The data is stored as fixed-length fields. The method calls a subroutine to strip any trailing spaces (spaces at the end of the string). The subroutine follows the method:

   $vhDocRef := Open document ("";"TEXT")  ` Open a TEXT document 
   If (OK=1)  ` If the document was opened
      Repeat  ` Loop until no more data 
         RECEIVE PACKET ($vhDocRef; $Var1; 15)  ` Read 15 characters 
         RECEIVE PACKET ($vhDocRef; $Var2; 15)  ` Do same as above for second field 
         If (OK = 1)  ` If we are not beyond the end of the document
            CREATE RECORD([People])  ` Create a new record 
            [People]First := Strip ($Var1)  ` Save the first name 
            [People]Last := Strip ($Var2)  ` Save the last name 
            SAVE RECORD([People])  ` Save the record 
         End if 
      Until (OK =0) 
      CLOSE DOCUMENT ($vhDocRef)  ` Close the document 
   End if

The spaces at the end of the data are stripped by the following method, called Strip:

   For ($i; Length ($1); 1; –1)  ` Loop from end of string to start 
      If ($1[[$i]] # " ")  ` If it is not a space… 
               $i := -$i  ` Force the loop to end 
      End if 
   End for 
   $0 := Delete string ($1; –$i; Length ($1))  ` Delete the spaces

Get document position, RECEIVE PACKET, SEND PACKET, SET DOCUMENT POSITION, SET TIMEOUT.

After a call to RECEIVE PACKET, the OK system variable is set to 1 if the packet is received without error. Otherwise, the OK system variable is set to 0.