RECEIVE RECORD
RECEIVE RECORD {( aTable )}
| Parameter | Type | Description | |
|---|---|---|---|
| aTable | Table | → | Table into which to receive the record, or Default table, if omitted |
Description
RECEIVE RECORD receives a record into table from the serial port or document opened by the SET CHANNEL command. The record must have been sent with SEND RECORD. When you execute RECEIVE RECORD, a new record is automatically created for table. If the record is received correctly, you must then use SAVE RECORD to save the new record.
The complete record is received. This means that pictures and BLOBs stored in or with the record are also received.
Important: When records are being sent and received using SEND RECORD and RECEIVE RECORD, the source table structure and the destination table structure must be compatible. If they are not, 4D will convert values according to the table definitions when RECEIVE RECORD is executed.
Notes:
- If you receive a record from a document using this command, the document must have been opened using the SET CHANNEL command. You cannot use RECEIVE RECORD with a document opened with Open document, Create document or Append document.
- During the execution of RECEIVE RECORD, 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 only need to handle the interruption of a reception while communicating over a serial port.
Example
A combined use of SEND VARIABLE, SEND RECORD, RECEIVE VARIABLE and RECEIVE RECORD is ideal for archiving data or for exchanging data between identical single-user databases used in different places. You can exchange data between 4D databases using the import/export commands such as EXPORT TEXT and IMPORT TEXT. However, if your data contains graphics and/or related tables, using SEND RECORD and RECEIVE RECORD is far more convenient.
For instance, consider a documentation system based on 4D and 4D Write. Since several writers in different locations wordwide work on it, we need a simple way to exchange data between the different databases. Here is a simplified view of the database structure:
The table [Commands] contains the description of each command or topic. The tables [CM US Params] and [CM FR Params] respectivily contain the parameter list for each command in English and in French. The table [CM See Also] contains the commands listed as reference (See Also section) for each command. Exchanging documentation between databases therefore consists in sending the [Commands] records and their related records. To do so, we use SEND RECORD and RECEIVE RECORD. In addition, we use SEND VARIABLE and SEND RECORD in order to mark the import/export document with tags.
Here is the (simplified) project method for exporting the documentation:
// CM_EXPORT_SEL project method
// This method works with the current selection of the [Commands] table
SET CHANNEL(12;"") // Let's the user create an open a channel document
If(OK=1)
// Tag the document with a variable that indicates its contents
// Note: the BUILD_LANG process variable indicates if US (English) or FR (French) data is sent
$vsTag:="4DV6COMMAND"+BUILD_LANG
SEND VARIABLE($vsTag)
// Send a variable indicationg how many [Commands] are sent
$vlNbCmd:=Records in selection([Commands])
SEND VARIABLE($vlNbCmd)
FIRST RECORD([Commands])
// For each command
For($vlCmd;1;$vlNbCmd)
// Send the [Commands] record
SEND RECORD([Commands])
// Select all the related records
RELATE MANY([Commands])
// Depending on the language, send a variable indicating
// the number of parameters that will follow
Case of
:(BUILD_LANG="US")
$vlNbParm:=Records in selection([CM US Params])
:(BUILD_LANG="FR")
$vlNbParm:=Records in selection([CM FR Params])
End case
SEND VARIABLE($vlNbParm)
// Send the parameter records (if any)
For($vlParm;1;$vlNbParm)
Case of
:(BUILD_LANG="US")
SEND RECORD([CM US Params])
NEXT RECORD([CM US Params])
:(BUILD_LANG="FR")
SEND RECORD([CM FR Params])
NEXT RECORD([CM FR Params])
End case
End for
// Send a variable indicating how many “See Also” will follow
$vlNbSee:=Records in selection([CM See Also])
SEND VARIABLE($vlNbSee)
// Send the [See Also] records (if any)
For($vlSee;1;$vlNbSee)
SEND RECORD([CM See Also])
NEXT RECORD([CM See Also])
End for
// Go to the next [Commands] record and continue the export
NEXT RECORD([Commands])
End for
SET CHANNEL(11) // Close the document
End if
Here is the (simplified) project method for importing the documentation:
// CM_IMPORT_SEL project method
SET CHANNEL(10;"") // Let's user open an existing document
If(OK=1) // If a document was open
RECEIVE VARIABLE($vsTag) // Try receiving the expected tag variable
If($vsTag="4DV6COMMAND@") // Did we get the right tag?
$CurLang:=Substring($vsTag;Length($vsTag)-1) // Extract language from the tag
If(($CurLang="US")|($CurLang="FR")) // Did we get a valid language
RECEIVE VARIABLE($vlNbCmd) // How many commands are there in this document?
If($vlNbCmd>0) // If at least one
For($vlCmd;1;$vlNbCmd) // For each archived [Commands] record
// Receive the record
RECEIVE RECORD([Commands])
// Call a subroutine that saves the new record or copies its values
// into an already existing record
CM_IMP_CMD($CurLang)
// Receive the number of parameters (if any)
RECEIVE VARIABLE($vlNbParm)
If($vlNbParm>=0)
// Call a subroutine that calls RECEIVE RECORD then saves the new records
// or copies them into already existing records
CM_IMP_PARM($vlNbParm;$CurLang)
End if
// Receive the number of “See Also” (if any)
RECEIVE VARIABLE($vlNbSee)
If($vlNbSee>0)
// Call a subroutine that calls RECEIVE RECORD then saves the new records
// or copies them into already existing records
CM_IMP_SEEA($vlNbSee;$CurLang)
End if
End for
Else
ALERT("The number of commands in this export document is invalid.")
End if
Else
ALERT("The language of this export document is unkown.")
End if
Else
ALERT("This document is NOT a Commands export document.")
End if
SET CHANNEL(11) // Close document
End if
Note that we do not test the OK variable while receiving the data nor try to catch the errors. However, because we stored variables in the document that describes the document itself, if these variables, once received, made sense, the probability for an error is very low. If for instance a user opens a wrong document, the first test stops the operation right away.
System variables and sets
The OK system variable is set to 1 if the record is received. Otherwise, the OK system variable is set to 0.