Unsolicited Data

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.