user_process_unsolicited_data_stamp
Retrieves unsolicited data from a device and returns the data and timestamp.
You can find the template for this subroutine in:
usrtm_unsost.c
Syntax
void user_process_unsolicited_data_stamp(DEVICE_DATA *device_struct,
char *data,
ADDR_DATA *start_address,
int *sizeof_data,
int *more,
COR_STAMP *timestamp,
int *comm_status,
int *status)
Input Parameters
None
Output Parameters
device_struct
Is a pointer to the structure defining device data. DEVICE_DATA is a typedef to a structure defined in < inc_path/toolkit.h > .
The device_id field in this structure must be set.
data
Is the pointer to a buffer containing the data received.
If the devcomm has indicated support for quality data by setting
support.unsolicited_quality_data
to TOOLKIT_YES
and support.extended_user_bits
to TOOLKIT_NO
, then the following code illustrates how the buffer should be handled:
TOOLKIT_QUALDATA *pqual_data = (TOOLKIT_QUALDATA *)data;
pqual_data->sys_flags = 0; //bits to be retained
pqual_data->sys_changed_mask = 0; //indicate bits to be retained
pqual_data->user_flags = 0; //bits to be retained
pqual_data->user_changed_mask = 0; //indicate bits to be retained
data += sizeof (TOOLKIT_QUALDATA);
If the devcomm has indicated support for quality data by setting support.unsolicited_quality_data
to TOOLKIT_YES
and support.extended_user_bits
to TOOLKIT_YES
, then the following code illustrates how the buffer should be handled:
TOOLKIT_QUALDATA2 *pqual_data = (TOOLKIT_QUALDATA2 *)data;
pqual_data->sys_flags = 0; //bits to be retained
pqual_data->sys_changed_mask = 0; //indicate bits to be retained
pqual_data->user_flags = 0; //bits to be retained
pqual_data->user_changed_mask = 0; //indicate bits to be retained
data += sizeof (TOOLKIT_QUALDATA2);
The data pointer now points to the area containing the point values. Any quality data changes indicated by the masks and values will be applied to all points serviced by the return buffer.
TOOLKIT_QUALDATA and TOOLKIT_QUALDATA2 are typedefs
to a structure defined in
<
inc_path/toolkit.h
>
.
start_address
Is a pointer to a structure that defines domain starting addresses in the device memory. ADDR_DATA is a typedef to a structure defined in < inc_path/toolkit.h > .
If standard addressing is used, the domain_index and domain_offset should be correctly set.
For custom addressing, the address string should be set.
sizeof_data
Contains the number of bytes of data (must be less than TOOLKIT_MAX_INTERNAL_BUFFER bytes).
more
Indicates whether there is more unsolicited data to be processed. Valid values are:
TRUE | More data needs processing |
FALSE | All data has been sent |
timestamp
Is a pointer to a structure that defines the timestamp to be used to record the time at which the data is reported. COR_STAMP is a typedef to a structure defined in < inc_path/cor.h > .
comm_status
Indicates whether a status of TOOLKIT_FAILURE occurred as a result of a communication failure. Valid values are:
TOOLKIT_SUCCESS | Failure is not due to communications failure. |
TOOLKIT_FAILURE | Failure is due to communications failure. |
status
Indicates whether the function successfully obtained all of the requested information. Valid values are:
TOOLKIT_SUCCESS | Function completed successfully. |
TOOLKIT_FAILURE | Function did not complete successfully. Check comm_status to see if the failure was the result of a communication failure. |
Return Value
None.
Programming Note
The following is an example of how to use the user_process_unsolicited_data_stamp subroutine:
void user_process_unsolicited_data_stamp (DEVICE_DATA *device_struct,
char *data,
ADDR_DATA *start_address,
int *sizeof_data,
int *more,
COR_STAMP *timestamp,
int *comm_status,
int *status)
{
int I;
strcpy (device_struct->device_id, "TOOLKIT_DEVICE");
reg_plc_data[3]++
start_address->domain_index = 0;
start_address->domain_offset = 3;
*sizeof_data=2;
memcpy (data, ®_plc_data[3], *sizeof_data);
*more = FALSE;
*comm_status = TOOLKIT_SUCCESS;
*status = TOOLKIT_SUCCESS
/* set the timestamp to September 12, 1995 at 16:12:03:00 */
timestamp->yyyymmdd = 19950912;
timestamp->hhmmsstt = 16120300;
return;
}