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 use in the projects with the interpretation of text strings in 8-bit form (ANSI) or 16-bit form (wide character UNICODE), according to the parameter of the project "Character Set" in MS Visual Studio.

UniVal structure

UniVal contains all information about the value and status of a given object of the 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 the UniVal structure.

    • status
      Value status, gets a combination of the values :

      Constant definitionDescription
      #define VAL_Valid 1UObject value is valid
      #define VAL_ProcAlarm 2UObject has an active process alarm
      #define VAL_NoAckPAlarm 4UObject had an active process alarm, that is not acknowledged
      #define VAL_PrAlSilent 8UProcess alarms of the object are not evaluated
      #define VAL_Weak 16UObject value is suspicious – “weak”
      #define VAL_NoAckValue 32UObject value is changed and is not acknowledged
      #define VAL_Transient 64UObject value is in the transient status when is writing
      #define VAL_Default 128UValue is in the default status
      #define VAL_Manual 256UObject value modified manually
      #define VAL_PrAlCrit 512UObject 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 statusStatus Description
      InLimitObject value is in limits
      L_LimitObject value is below the low limit
      VL_LimitObject value is below the lowest limit
      H_LimitObject value is above the high limit
      VH_LimitObject value is above the highest limit
      LimitsProblemA 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).

The variable part, holding its 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 statusIndex
      Alarm0
      NoKvit1
      Kvit2
      Norm3


!!! 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.

  • 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 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 is low (lowIndex) and high (hiIndex) indexes. Array items are indexed from 1. Before hiIndex, there are the 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 !!!

Napíšte komentár