| gclib 367 Communications API for Galil controllers and PLCs |

All Data Structures Files Functions Variables Typedefs Macros Pages

GCLIB_DLL_EXPORTED GReturn GCALL GMessage | ( | GCon | g,
|  | GCStringOut | buffer,
|  | GSize | buffer_len
| ) |  |

Provides access to unsolicited messages from the controller.

To use this function, `-s MG` must be used in the GOpen() `address` string to subscribe to messages. Unsolicited bytes must be flagged by the high-bit setting, `CW 1`. The driver will automatically set this when subscribing to messages. The user should not overwrite this setting.

Unsolicited messages are data generated by the controller that are not in response to a command, a data record, or an interrupt. Examples follow.

1. Data generated by the `MG` command from embedded code. `MG` sent from the host is solicited.
2. Any command in an embedded program that returns data, e.g. `TP`, `RP`, `var=?`
3. A run time error in an embedded program, e.g. `?55 i=var`

Note
  Messages are unframed byte streams. There is no guarantee that the user will get complete messages or single messages in a call to GMessage().

Parameters

  g | Connection's handle.
  buffer | The buffer to write the message data. The buffer will be null terminated.
  buffer_len | The length of the user's buffer.

Returns
  The success status or error code of the function. See gclib_errors.h for possible values.

GMessage() will block until a message is received, or the function times out.

Note
  If this function is called with a timeout of zero, a non-blocking read is performed. If message data has been processed since the last time the function was called, this data will be returned. If there is no processed message data, but there is data waiting in the socket or PCI FIFO, one read will be performed to process the waiting data. If new data is still not found after these two attempts, G_GCLIB_NON_BLOCKING_READ_EMPTY will be returned.

Warning
  When sending message streams through gcaps, the following non-printable bytes are illegal, `$00-$07` and `$10-$17`. These bytes may be routed to a third party device such as am HMI or display panel. See MG and CF.

See x_gmessage.cpp for an example. See x_nonblocking.cpp for an example of non-blocking usage.