| gclib 2.4.1 Galil Communications Library

Loading...
Searching...
No Matches
Functions
Unsolicited Data
C (Legacy) » Controller

Receive messages, interrupts, and data records. More...

## Functions
GCLIB_DEPRECATED GReturn | GRecord (GCon g, union GDataRecord *record, GOption method)
| Provides a fresh copy of the controller's data record. Data is cast into a union, GDataRecord.
GCLIB_DEPRECATED GReturn | GMessage (GCon g, GCStringOut buffer, GSize buffer_len)
| Provides access to unsolicited messages from the controller.
GCLIB_DEPRECATED GReturn | GInterrupt (GCon g, GStatus *status_byte)
| Provides access to PCI and UDP interrupts from the controller.
GCLIB_DEPRECATED GReturn | GRecordRate (GCon g, double period_ms)
| Sets the asynchronous data record to a user-specified period via DR.

## Detailed Description

Receive messages, interrupts, and data records.

## Function Documentation

## ◆ GRecord()

GCLIB_DEPRECATED GReturn GRecord | ( | GCon | g,
|  | union GDataRecord * | record,
|  | GOption | method )

Provides a fresh copy of the controller's data record. Data is cast into a union, GDataRecord.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_data_record() instead.

Parameters

  g | Connection's handle.
  record | A pointer to the user's DataRecord union to hold the copy.
  method | Determines the method for acquiring the data. G_QR: QR is used via command-and-response. G_DR: DR is used for asynchronous acquisition.

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

When using G_DR, the asynchronous data record must already be set up.

- -s DR must be used in the GOpen() address string to subscribe to records. The driver will automatically set the second argument of DR, where applicable.
- GRecordRate() should be issued to set DR to an appropriate interval, n. The interval must be no faster than the rate at which GRecord() is called.
- If GRecord() is called more slowly than the data record rate, stale data will be returned until GRecord() has been called once for each record sent by the controller.

GRecord() will block until the data record is received, or the transaction times out.

Note
  If this function is called with a timeout of zero and the G_DR method, a non-blocking read is performed. If a data record has been processed since the last time the function was called, this data will be returned. If there is not a processed data reecord, 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.

## ◆ GMessage()

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

Provides access to unsolicited messages from the controller.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_message() instead.

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(). If multiple messages have been sent from the controller since the last call to GMessage(), they will all be placed in the buffer, separated by newline characters.

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.

## ◆ GInterrupt()

GCLIB_DEPRECATED GReturn GInterrupt | ( | GCon | g,
|  | GStatus * | status_byte )

Provides access to PCI and UDP interrupts from the controller.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_interrupt() instead.

Interrupts can be generated automatically by the firmware on important events via EI (Enable Interrupt) or by the user in embedded DMC code via UI (User Interrupt). To use this function, -s EI must be used in the GOpen() address string to subscribe to interrupts.

Parameters

  g | Connection's handle.
  status_byte | A pointer to a GStatus to receive the status byte.

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

GInterrupt() will block until an interrupt 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 interrupt data is waiting in the interrupt queue, the oldest byte will be popped off the queue. If there is no interrupt data queued, 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.

## ◆ GRecordRate()

GCLIB_DEPRECATED GReturn GRecordRate | ( | GCon | g,
|  | double | period_ms )

Sets the asynchronous data record to a user-specified period via DR.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_set_data_records() instead.

Takes TM and product type into account and sets the DR period to the period requested by the user, if possible.

Parameters

  g | Connection's handle.
  period_ms | Period, in milliseconds, to set up for the asynchronous data record.

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