 |
Serial_Receive |
Receives data from a serial port with the specified name. The port needs to be opened first (see Serial_Open). If no data is available an empty string is returned: “”.
Syntax
Serial_Receive ( switches ; portname )
Parameters
| switches | (optional) specifies how this function receives the data |
| portname | the name of the port to receive data from |
Switches
switches can be left empty or can be:
| -GetLastMatch | get the last string of text that matches the match string |
You can also add one of these encoding switches, which determine how the incoming bytes are interpreted.
| -Encoding=ASCII_DOS | |
| -Encoding=ASCII_Windows | (Windows ANSI) |
| -Encoding=ASCII_Mac | (Mac Roman) |
| -Encoding=ISO_8859_1 | (Windows Latin-1) |
| -Encoding=UTF8 | |
| -Encoding=BytesOnly | returns all received bytes as the same Unicode byte values (Unicode 0 to 255) |
| -ConvertBytesToNumbers | converts all received bytes to their numeric value, with space as separator |
Returned Result
Data type returned
Text
Result
The returned result is the data received or an error code. An error always starts with 2 dollars, followed by the error code. You should always check for errors when receiving, by testing if the first two characters are dollars.
Returned error codes can be:
| $$-28 | notOpenErr | the port is not open |
| $$-108 | memFullErr | ran out of memory |
| $$-50 | paramErr | there was an error with the parameter |
| $$-4210 | portDoesnotExistErr | port with this name is not available on this computer |
| $$-4211 | allPortsNullErr | no serial ports are available on this computer |
| $$-207 | notEnoughBufferSpace | the input buffer is full |
Other errors may be returned.
Originated in
Troi Serial Plug-in 3.0
Compatibility
FileMaker Pro 16 to FileMaker Pro 2023
Considerations
The plug-in will get any data that is received at the time the function is called. This might not be all data coming in. You might need to wait and append new data coming in at a later time.
When you use the -GetLastMatch switch the last matching string of text is returned. Older text is discarded.
Please be aware that only the ASCII characters 0…255 will be received, as a serial port uses 8 bit characters. If the serial device is encoding the bytes as UTF-8 you can receive any Unicode character. In this case specify the switch -Encoding=UTF8.
When using the switch -ConvertBytesToNumbers all received bytes are converted to their numeric value. It will for example return “65 66 67 “, when receiving the bytes “ABC”. Note that each number is followed by a space, as separator, including after the last number.
Example
Set Field [ gResult ; Serial_Receive ( "-Unused" ; "SerialPort1" ) ]This will receive data from the SerialPort1. It might return “All the world is a sta”. If you call it again later new data may have come in and the result might be “ge and we are merely players.” It is best to concatenate the data coming in.
Example 2
Below you find a “Receive Data” script for receiving data into a global text field gTempResultReceived. The script tests for errors.
We assume that in your FileMaker file the following fields are defined:
gPortName Global, text, contains the name of the previously opened port
gTempResultReceived Global, text
gTotalResult Global, text, can also be a normal text fieldAdd the following script steps:
Set Field [ gTempResultReceived ; Serial_Receive ( "-Unused" ; gPortName ) ]
If [ Left ( gTempResultReceived , 2 ) = "$$" ]
Beep
If [ gTempResultReceived = "$$-28" ]
Show Message [ Open the port first ]
Else
If [ gTempResultReceived = "$$-207" ]
Show Message [ Buffer overflow error ]
Else
Show Message [ An error occurred! ]
End If
End If
Halt Script
Else
# no error, so concatenate the data somewhere and do your stuff.
Set Field [ gTotalResult ; gTotalResult & gTempResultReceived ]
# .... add your own steps here ...
End IfUsed in example files
SimpleSerial.fmp12
Terminal.fmp12
Related functions
| Serial_DataWasReceived |
| Serial_DelayMilliseconds |
| Serial_Open |
| Serial_Send |
Related script step
| Receive Serial Data |
Related topics
Troi Serial Plug-in online help (overview)
