D2000 OBJApi - Interface structures
From the version D2000 V9.02.034, there is available both 32 and 64-bit version with modified header file for using in the projects with interpretation of text strings in 8-bit form (ANSI) or 16-bit form (wide character UNICODE), according to the parameter of project "Character Set" in MS Visual Studio.
UniVal structure
UniVal contains all information about a value and status of given object of D2000 system.
Declaration in C language:
typedef struct _UniVal
{
GenValueType gvaltyp;
unsigned int status;
tLimitStatus limitStatus;
tProcAlarmType procAlarmStatus;
ValueType type;
double valtime;
double procAlarmTime;
unsigned int Flags;
VOBJ Indirect;
union
{
tBVal Boval;
int Intval;
double Realval;
StVal Stval;
struct
{
AlVal Alval;
double AlTimes[4];
} a;
PrVal Prval;
double TmAval;
double TmRval;
tQValue QVal;
char *TxtVal;
ArrayRecPtr ArrayValPtr;
struct
{
ArrayRecPtr recordValPtr;
HOBJ StructTypId;
int ColsNr;
} r;
} v;
} UniVal;
Description of individual structure parts:
- gvaltyp
It determines an object value type for the variable part of UniVal structure. - status
Value status, it gets a combination of the values :
Constant definition Description #define VAL_Valid 1U Object value is valid #define VAL_ProcAlarm 2U Object has an active process alarm #define VAL_NoAckPAlarm 4U Object had an active process alarm, that is not acknowledged #define VAL_PrAlSilent 8U Process alarms of the object are not evaluated #define VAL_Weak 16U Object value is suspicious – “weak” #define VAL_NoAckValue 32U Object value is changed and is not acknowledged #define VAL_Transient 64U Object value is in the transient status when is writing #define VAL_Default 128U Value is in the default status #define VAL_Manual 256U Object value modified manually #define VAL_PrAlCrit 512U Object has an active critical process alarm - limitStatus
Object value status in regard to configured value limits:
typedef enum {InLimit,VL_Limit,L_Limit,H_Limit,VH_Limit,LimitsProblem} tLimitStatus;
Value status Status description InLimit Object value is in limits L_Limit Object value is below the low limit VL_Limit Object value is below the lowest limit H_Limit Object value is above the high limit VH_Limit Object value is above the highest limit LimitsProblem A problem with the evaluation of the limits (unknown value of active limit, crossing the values of the active limits) - procAlarmStatus
Active process alarm type.
typedef enum {NoAlarm,ToOn,ToOff,On,Off,Err,Oscillate,ErrCmdOn,ErrCmdOff, SwToTrans,SwToOff,SwToOn,SwToErr,SwTrans,SwOff,SwOn,SwErr,ErrZalCmdOff, HL,VHL,LL,VLL,ToHL,ToVHL,ToLL,ToVLL,ErrWriteCmd,A28,A29,A30,A31,A32} tProcAlarmType; - type
D2000 system object type. - valtime
Time of the last object value change. - procAlarmTime
Time of the last object process alarm change. - Flags
Bit array: Object value flags (A up to P). - Indirect
If the value is a value of a structure of Object type, there is a value source (object id and row, col).
Variable part, holding an own object value:
- Boval
Value of an object of Boolean type (type : Bo, Di, Do, De, Li). - Intval
Value of an object of Integer type (type : Int, Ci, Co, Ce). - Realval
Value of an object of Real typee (type : Re, Ai, Ao, Ae). - Stval
Value of an object of Station type (type : St). - a.Alval
Value of an object of Alarm type (type : Al). - a.AlTimes
Indexed times if individual alarm states:
Alarm status Index Alarm 0 NoKvit 1 Kvit 2 Norm 3 - Prval
Value of an object of Process type (type : Pr). - TmAval
Value of an object of Absolute time types (type : TmA, TiA, ToA). - TmRval
Value of an object of Relative time types (type : TmR, TiR, ToR). - Qval
Value of an object of Quadrat input type (type : Qi). - TxtVal
Value of an object of Text type (type : Txt, TxtI, TxtO). - ArrayValPtr
Value of an object of Array type (type : Arr). - r.recordValPtr
Reference to an structure value (type : Rec). - r.StructTypId
Id of an object of Structure definition type, that defines the value type. - r.ColsNr
Number of columns in the structure.
!!! WARNING !!!
Since the D2000 version 7.0, the item a.AlTimes is not used and therefore has been renamed to a.AlTimes_Unused. The items of the array are filled with the value of 0.0.
Warning for some value types:
UniVal contains only references to values for objects of Text and Array types. Values are created dynamically and it is necessary to release them calling the function FreeData. Exceptions are asynchronous calling the function NewValueProc (ObjAPI releases the values after return from the callback) and the function ListOfObjects (values are released by calling the function FreeData that releases structures of ListObjData type).
Representation of arrays and structures
Arrays and structures are represented by a value array of UniVal type, before which there are low (lowIndex) and high (hiIndex) indexes. Array items are indexed from 1. Before hiIndex, there are following individual values in rows in successive steps.
typedef struct _ArrayRec
{
int lowIndex;
int hiIndex;
} ArrayRec;
typedef ArrayRec * ArrayRecPtr;
Access to a structure item (row, column) is represented by the following function:
UniValPtr GetRecordItem(UniVal value, int row, int col)
{
UniValPtr uni_Ptr;
int valueIdx;
valueIdx = (row-1)*value.v.r.ColsNr+col - 1;
// first value address
uni_Ptr = (UniValPtr)((char *)value.v.r.recordValPtr +
sizeof(*value.v.r.recordValPtr));
uni_Ptr = &(uni_Ptr[valueIdx]);
return uni_Ptr;
}
When calling interface procedures, it is important to correctly enter the indexes !!!
Pridať komentár