4D Doc Center : RECEIVE RECORD

4D v13.4

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 oder 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.