Unsolicited Data

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

Functions
GCLIB_DLL_EXPORTED GReturn GCALL	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_DLL_EXPORTED GReturn GCALL	GMessage (GCon g, GCStringOut buffer, GSize buffer_len)
	Provides access to unsolicited messages from the controller.
GCLIB_DLL_EXPORTED GReturn GCALL	GInterrupt (GCon g, GStatus *status_byte)
	Provides access to PCI and UDP interrupts from the controller.
GCLIB_DLL_EXPORTED GReturn GCALL	GRecordRate (GCon g, double period_ms)
	Sets the asynchronous data record to a user-specified period via DR.

Function Documentation

GRecord()

GCLIB_DLL_EXPORTED GReturn GCALL 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.

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.

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

GMessage()

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(). 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.

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

GInterrupt()

GCLIB_DLL_EXPORTED GReturn GCALL GInterrupt	(	GCon	g,
		GStatus *	status_byte )

Provides access to PCI and UDP interrupts from the controller.

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.

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

GRecordRate()

GCLIB_DLL_EXPORTED GReturn GCALL GRecordRate	(	GCon	g,
		double	period_ms )

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

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.

See x_grecord.cpp for an example.