/MEng/System/CQC/Runtime/CMLBinBase

Class Information:

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

MEng.System.CQC.Runtime.CMLBinBase is used by the CQC Web Server. The web server provides the ability for you to write CML macros that can generate web dynamic web content. Those macros must derive from this base class, so that the web server can interface to them generically, and so that some common functionality can be provided in the base class and be available for all such macros. These types of macros are called 'CMLBin' macros, in reference to the CGI-Bin scheme that is used in some web servers to achieve the same results.

The primary purpose of this class is to define the ProcessReq() method, which is the method called by the web server to ask your derived class to generate page content. This method is given access to any Key/Value pairs that were part of the GET query or the POST body, which can be used by the client browser to control how the content gets generated.

Nested Types:

Enum=CMLBinErrors
    ErrReplyErr    : "";
    EscapeErr      : "";
    ReqValErr      : "";
EndEnum;

These are the errors that this class throws. Some have no text because they are just given the text of an underlying C++ exception that occurred.

 

Constructors:

Constructor();

There is just a default constructor available.

 

Required, Non-Const Methods:

ProcessReq
(
    [Out]   MemBuf      ToFill
    , [Out] MEng.Card4  ContLen
    , [Out] MEng.String ContType
    , [Out] MemBuf      RepText
)   Returns MEng.Card4;

This the primary method of this class. You must provide an override of this class and generate either the requested page contents, or an error reply. The page content should be put into ToFill, and the format of that data indicated in ContType, using the standard MIME indicators such as "text/html;charset=utf-8" and so forth. If the format is Latin1 (aka iso-8859-1), then you don't need to indicate a charset= value, since that is the defined default.

The return value should be one of the standard HTTP result codes, such as 200 for OK, 404 for Not Found and so forth. If the return is 200, then you don' t need to fill in RepText, else set RepText to the short text description of the meaning of the returned code. This will not be seen by the user directly, but goes into the HTTP status line.

Generally, you will create a  StringOutStream and format your page contents into it. At the end, you will then transcode it into the ToFill buffer, like this, where m_Body is the string output stream used to format the text.

ContLen := m_Body.XcodeTo(ToFill, "iso-8859-1");
ContType := "text/html;charset=iso-8859-1";
Return 200;

The actual encoding name will vary of course, according to what you want/need to use. You might prefer utf-8 if you are using a Latin1 based language. See the TextCoder class documentation for a list of available transcoders in CQC.

The reason that the output is a binary buffer is because you can also return binary data, such as an image or whatever other type of data your application needs. Be sure to set the correct ContType for whatever you return.

 

Final, Const Methods:

BuildErrReply
(
    [In]    MEng.Card4  ErrCode
    , [In]  MEng.String ErrMsg
    , [Out] MEng.String ContType
    , [Out] MemBuf      ToFill
)   Returns MEng.Card4;

If your ProcessReq() method encounters an error, this helper method will build an attractive error reply page for you. It will effectively do what ProcessReq() normally does, but it generates a fixed page with error information inserted into it, instead of the requested page. The ToFill buffer is filled with the page contents, and ContType is filed with the content type information. The return value is the number of bytes puts into the ToFill buffer.

EscapeText(In] MEng.String SrcText, [Out] TextOutStream TarStrm);

When building HTML body text, which is what your ProcessReq() method is doing, there are certain magic characters that cannot be used directly, they must be escaped. This method will do that escaping process for you. Generally you will use an output text stream to build your output content, so this method conveniently takes an output text stream and dumps the escaped contents directly into the stream.

Be sure to use this anywhere that your generated content is not under your control (such as when using content from an external source, such a string oriented device fields) and you cannot guarantee it won't generate illegal characters.

FindReqValue(In] MEng.String Key, [Out] MEng.String ToFill) Returns MEng.Boolean;

Your ProcessReq() method has access to any key/value pairs that came in the query part of a GET URL or the body of a POST URL. You can access these values via this method. If the key was found, ToFill is filled with its value and the return value is True. Else, the return is False and the value of ToFill is not changed.

 

Final, Non-Const Methods:

AddReqValue([In] MEng.String Key, [In] MEng.String Value) Returns MEng.Boolean;

This method is mainly for testing purposes. It allows you to force a key/value pair in the list so that your ProcessReq() method will see it. It is often used in the Start() method so that a CMLBin macro can be tested outside of the web server environment before committing to its use.

The return indicates whether the new key was added (True) or just updated with the passed value (False.)