ctGetProperty

Retrieves an object property or meta data for an object. Use this function in conjunction with the ctFindFirst() and ctFindNext() functions. i.e. First, you find an object, then you retrieve its properties.

To retrieve property meta data such as type, size and so on, use the following syntax for the szName argument:

• object.fields.count - the number of fields in the record
• object.fields(n).name - the name of the nth field of the record
• object.fields(n).type - the type of the nth field of the record
• object.fields(n).actualsize - the actual size of the nth field of the record

Syntax

ctGetProperty(hnd, szName, pData, dwBufferLength, dwResultLength, dwType)

hnd

Type: Handle
Input/output: Input
Description: Handle to the search, as returned by ctFindFirst().

szName

Type: LPCTSTR*
Input/output: Input
Description: The name of the property to be retrieved. The following properties are supported:

Name - The name of the tag.

FullName - The full name of the tag in the form cluster.tagname.

Network - The unique I/O Device Number.

BitWidth - Width of the data type in bits. for example digital will be 1, integer 16, long 32, etc.

UnitType - The protocol specific unit type.

UnitAddress - The protocol specific unit address.

UnitCount - The protocol specific unit count.

RawType - The raw data type of the point. The following types are returned: 0 (Digital), 1 (Integer), 2 (Real), 3 (BCD), 4 (Long), 5 (Long BCD), 6 (Long Real), 7 (String), 8 (Byte), 9 (Void), 10 (Unsigned integer).

Raw_Zero - Raw zero scale.

Raw_Full - Raw full scale.

Eng_Zero - Engineering zero scale.

Eng_Full - Engineering full scale.

Equipment – The associated equipment name

Name - The name of the equipment.

Cluster - The name of the cluster that this equipment runs on.

Type - The specific type of equipment in the system.

IoDevice - The I/O Device used to communicate with this piece of equipment.

Area - The area number or label to which this equipment belongs.

Location - A string describing the location of the equipment.

Comment - Comment.

Page - The name of the page on which this equipment appears.

Help - The help context string.

Parent - The name of the parent equipment derived from the name of the equipment.

Composite – The equipment specific composite name

Custom1 .. Custom8 - User-defined strings.

pData

Type: VOID*
Input/output: Output
Description: The result buffer to store the read data. The data is raw binary data, no data conversion or scaling is performed. If this buffer is not large enough to receive the data, the data will be truncated, and the function will return false.

dwBufferLength

Type: DWORD
Input/output: Input
Description: Length of result buffer. If the result buffer is not large enough to receive the data, the data will be truncated, and the function will return false.

dwResultLength

Type: DWORD*
Input/output: Output
Description: Length of returned result. You can pass NULL if you want to ignore this parameter

dwType

Type: DWORD
Input/output: Input
Description: The desired return type as follows:

Return Value

If the function succeeds, the return value is non-zero. If the function does not succeed, the return value is zero. To get extended error information, call GetLastError().

Related Functions

ctOpen, ctFindFirst, ctFindNext, ctFindPrev, ctFindClose

Example

Also see ctFindFirst().

// get the property of the TAG field
ctGetProperty(hObject, "TAG", sName, sizeof(sName), NULL, DBTYPE_STR);
// Use the meta property fields to enumerate the entire row of data
// first get number of fields in the row
ctGetProperty(hObject, "object.fields.count", &dwFields, sizeof(dwFields),
 NULL, DBTYPE_I4);
for (i = 0; i < dwFields; i++) {
	sprintf(sObject, "object.fields(%d).name", i + 1);
	// get name of field
	if (ctGetProperty(hObject, sObject, sName, sizeof(sName), NULL, DBTYPE_STR)) {
		// get value of field
		if (ctGetProperty(hObject, sName, sData, sizeof(sData),
		 NULL, DBTYPE_STR)) {
			printf("%8.8s ", sData);
		}
	}
}

Published June 2018