/MEng/System/CQC/Runtime/SimpleFldClient

ClassPath:	MEng.System.CQC.Runtime.SimpleFldClient
Parent ClassPath:	MEng.Object
Copyable:	No
Final:	Yes

MEng.System.CQC.Runtime.SimpleFieldClient provides field I/O services for control macros that don't need very elaborate field access, which is normally the bulk of them. Most invoked control macros read a few fields to find out the state of the state of whatever they are interested in, and then write to a few fields to achieve the desired result, and never look at any field more than once.

This class is appropriate for those types of macros, and provides that kind of access with the minimum of complexity and fuss. This means that it will be inefficient for more elaborate or repeated field access patterns, and other classes should be used for that kind of work.

This class provides typed field access, so there is a method to read and write each field data type. This is more efficient, but you must be sure to write a field as it's correct type of your operation will fail.

 

Nested Types:

Enum=SimpleFldErrors
    BadFldName   : "The name must be in moniker.field format";
    LookupFailed : "";
    QueryFailed  : "";
    ReadFailed   : "";
    WriteFailed  : "";
EndEnum;

This enumerated type is used to indicate a failure of a field read or write operation, respectively. The text is not provided here because it will actually be that text of the underlying CQC error that occurred. In most cases, there is no way for a macro to recover from such an error, because it means that either they have spelled a field name wrong, or that the device driver containing that field, or the CQCServer containing that device driver, or the PC running that CQCServer, is now unavailable. So it is usually best to just give up gracefully, perhaps after logging an error.

Enum=FldTokenResults
    Unchanged	: "";
    Failed	: "";
    Changed	: "";
EndEnum;

This enumerated type is used by the ReplaceFldTokens() method below, to indicate the results of the field token replacement process. The text is not provided here because it will actually be that text of the underlying CQC error that occurred.

VectorOf[String] StrList

A vector of strings used in some of the interfaces of this class. You can use any vector of strings, this is just defined in order to make this interface standalone.

VectorOf[CQCFldDef] FldDefList

A vector of field definition objects used in some of the interfaces of this class. You may use any vector of CQCFldDef objects, this is just defined to make this interface standalone.

 

Constructors:

Constructor();

There is only a default constructor since no information is required from the client code to prepare the object.

 

Final, Non-Const Methods:

QueryData
(
    [In] MEng.String Moniker
    , [In] MEng.Card4 QueryId
    , [In] MEng.String DataName
    , [Out] MEng.Card4 ByteCnt
    , [Out] MEng.System.Runtime.MemBuf ToFill
)   Returns MEng.Boolean;

This method allows you to call a 'backdoor' method on a driver, to get data directly from it, as apposed to the usual field interface. This is generally not used, but it is sometimes required. You must provide the moniker of the driver, and a query id and data name. The latter two are arbitrary and defined by the driver, allowing it to advertise what information it can make available. This method is for querying a binary buffer of data, whereas QueryTextVal is available for querying a string of data.

If the driver recognizes the passed id and data name, it will return True and fill in the buffer and byte count, else it will return False. If an error occurs, the QueryFailed exception will be thrown.

QueryDrivers([Out] StrList ToFill) Returns MEng.Card4;

This method will query a list of all of the currently loaded drivers in a vector of strings. It will return the number of drivers found.  You can use any vector of strings, StrList is just defined in order to have one to use in this class' interface. If an error occurs, the QueryFailed exception will be thrown.

QueryFields
(
    [In] MEng.String Moniker
    , [Out] FldDefList ToFill
    , [Out] MEng.Card4 FldListId
    , [Out] MEng.Card4 DriverId
    , [Out] MEng.Card4 DriverListId
)   Returns MEng.Card4;

This method will provide a list of all of the fields for a given driver. The driver must be loaded and functional or an error will occur. The last three parameters are not of much use to CML clients at this time, but will be in the future, so they are provided in the interface. You can use any vector of CQCFldDef objects, FldDefList is just defined to make this interface standalone.

QueryTextVal
(
    [In] MEng.String Moniker
    , [In] MEng.Card4 QueryId
    , [In] MEng.String DataName
    , [Out] MEng.String ToFill
)   Returns MEng.Boolean;

This method allows you to call a 'backdoor' method on a driver, to get data directly from it, as apposed to the usual field interface. This method allows you to query a string of text. Use QueryData to get a binary buffer of information. The query id and data name are arbitrary and defined by the driver, allowing it to advertise what information it can make available. If an error occurs, the QueryFailed exception will be thrown.

ReadBoolField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.Boolean;

ReadCardField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.Card4;

ReadFloatField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.Float8;

ReadIntField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.Int4;

ReadStringField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.String;

ReadTimeField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName
)   Returns MEng.Card8;


WriteBoolField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.Boolean ToWrite
);

WriteCardField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.Card4 ToWrite
);

WriteFloatField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.Float8 ToWrite
);

WriteIntField
(
     [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.Int4 ToWrite
);

WriteTimeField
(
     [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.Card8 ToWrite
);

WriteStringField
(
    [In] MEng.String Moniker, [In] MEng.String FieldName, [In] MEng.String ToWrite
);

These methods read or write fields based on their moniker and field name, and based on the data type of the field. You must write to a field in it's data type, and reads return data in the field's data type.

Though the Write methods do change something, that something is not part of this object's visible state, so they are Const methods as well. The change occurs in the back end CQCServer and the target device.

ReadField([In] MEng.String Moniker, [In] MEng.String Field) Returns MEng.String;
ReadField2([In] MEng.String MonikerFld) Returns MEng.String;

This method reads any field type generically as a string. This is often convenient when formatting out field values or dealing with fields generically. ReadField2 takes the field name in the 'moniker.field' format, and a BadFldName error will be thrown if it is not in the correct format.

WriteField([In] MEng.String Moniker, [In] MEng.String Field, [In] MEng.String ToWrite);
WriteField2([In] MEng.String MonikerFld, [In] MEng.String ToWrite);

This method writes to any field type generically as a string. This is often convenient when dealing dynamically with target fields. WriteField2 takes the field name in the 'moniker.field' format, and a BadFldName error will be thrown if it is not in the correct format.

 

Final, Const Methods:

ReplaceFldTokens
(
    [In] MEng.String SrcText
    , [Out] MEng.String ToFill
)   Returns FldTokenResults;

This method will take an input stream and scan it for replacements tokens in the form $(moniker.field) and replace those tokens with the actual values of the fields referenced. The return value indicates how you should deal with the result.

If the return is Unchanged, then ToFill was not filled in and the original text in SrcText is the actual resulting text. This avoids the overhead of copying the text when there were no tokens to replace (a common occurrence when scanning a block of text.) If the return is Changed, then ToFill has the updated text. Note that, the text still might be the same as SrcText, since a quick and dirty scan is made to see if any potential tokens are present and if so then ToFill is filled in even if the rough scan turned out to be mistaken.

If the return is Failed, then the results in ToFill are bad because either there were malformed tokens or one or more fields referenced could not be read to do the replacement. You can choose to give up or to just use the source text without replacement.