SEND PACKET

version 11 (Modified)

SEND PACKET ({docRef; }packet)

SEND PACKET sends a packet to a serial port or to a document. If docRef is specified, the packet is written to the document referenced by docRef. If docRef is not specified, the packet is written to the serial port or document previously opened by the SET CHANNEL command.

A packet is just a piece of data, generally a string of characters.

You can also pass a BLOB in packet. This allows you to bypass the constraints related to encoding for characters sent in text mode (see example 2).

Note: When you pass a BLOB in packet, the command does not take into account any character set defined by the USE CHARACTER SET command. The BLOB is sent without any modification.

Before you use SEND PACKET, you must open a serial port or a document with SET CHANNEL, or open a document with one of the document commands.

When writing to a document, the first SEND PACKET begins writing at the beginning of the document unless the document was opened with Append document. Until the document is closed, each subsequent packet is appended to any previously sent packets.

Note: This command is useful for a document opened with SET CHANNEL. On the other hand, for a document opened with Open document, Create document and Append document, you can use the 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.

Important: In non-Unicode mode (compatibility mode), SEND PACKET writes Mac OS ASCII data on both Windows and Macintosh platforms. Mac OS ASCII data uses eight bits. Standard ASCII uses only the lower seven bits. Many devices do not use the eighth bit in the same way as does Windows/Macintosh. If the string to be sent contains data that uses the eighth bit, be sure to create an ASCII map to translate the ASCII characters, and execute USE CHARACTER SET before using SEND PACKET. You can also use the Mac to Win function (for more information, refer to the example for this function). Protocols like XON/XOFF use some low ASCII codes to establish communication between machines. Be careful to not send such ASCII codes, as this may interfere with the protocol or even break communication.

1. The following example writes data from fields to a document. It writes the fields as fixed-length fields. Fixed-length fields are always of a specific length. If a field is shorter than the specified length, the field is padded with spaces. (That is, spaces are added to make up the specified length.) Although the use of fixed-length fields is an inefficient method of storing data, some computer systems and applications still use them:

   $vhDocRef := Create document ("")  ` Create a document 
   If (OK=1)  ` Was the document created? 
      For ($vlRecord; 1; Records in selection ([People]))  ` Loop once for each record
            ` Send a packet. Create the packet from a string of 15 spaces containing the first name field 
         SEND PACKET ($vhDocRef; Change string(15 * Char(Space); [People]First;1))
            ` Send a second packet. Create the packet from a string of 15 spaces containing the last name field 
            ` This could be in the first SEND PACKET, but is separated for clarity 
         SEND PACKET ($vhDocRef; Change string (15 * Char(Space); [People]Last; 1)) 
         NEXT RECORD([People]) 
      End for
         ` Send a Char(26), which is used as an end-of-file marker for some computers 
      SEND PACKET ($vhDocRef; Char(SUB ASCII Code))
      CLOSE DOCUMENT ($vhDocRef)  ` Close the document 
   End if

2. This example illustrates the sending and retrieval of extended characters via a BLOB in a document:

   C_BLOB($send_blob)
   C_BLOB($receive_blob)
   TEXT TO BLOB("âzértÿ";$send_blob;UTF8 Text without length)
   SET BLOB SIZE($send_blob;16;255)
   $send_blob{6}:=0
   $send_blob{7}:=1
   $send_blob{8}:=2
   $send_blob{9}:=3
   $send_blob{10}:=0
   $vlDocRef:=Create document("blob.test")
   If(OK=1)
      SEND PACKET($vlDocRef;$send_blob)
      CLOSE DOCUMENT($vlDocRef)
   End if
   $vlDocRef:=Open document(document)
      End(OK=1)
      RECEIVE PACKET($vlDocRef;$receive_blob;65536)
      CLOSE DOCUMENT($vlDocRef)
   End if

Get document position, RECEIVE PACKET, SET DOCUMENT POSITION.