sendLispMessage
Prev DataHubConnector Methods Next

sendLispMessage

sendLispMessage — sends a message to the DataHub instance (C++ only).

Synopsis

For C++:
ST_STATUS sendLispMessage(force,  
 format,  
 ...); 
bool force;
char* format;
...;
 

Parameters

force

If a valid connection to the DataHub instance exists but the message is undeliverable immediately (due to the TCP buffer being full), then if the force parameter is TRUE, the message is queued and will be transmitted when possible.

format

The text formatting string (see below).

...

Parameters required by the specified format.

Returns

For C++:

  • ST_OK if the command was successfully sent to the DataHub instance. Since the command is sent asynchronously, the actual success or failure of the command must be determined through the onSuccess or onError message handlers.

  • ST_NO_TASK if no connection to the DataHub instance is established.

  • ST_TOO_LARGE if the message string exceeds the message buffer size.

  • ST_ERROR if the format contains an error or if the connection socket is unable to send the message.

Description

This method is used to format and send commands to the DataHub instance, and should only be used by those very familiar with the operation of the DataHub instance. The DataHub command set is described in the Using Commands chapter of the Cogent DataHub manual. To send a command to the the DataHub instance, it must be formatted such that strings and control characters are preserved through the message transfer and delivery process. The specialized format control specifiers of sendLispMessage make this easy to do.

[Note]

The writeCommand method gives a similar functionality for Java and C#.

The format control string is similar to that used by printf, with the following differences:

  • The %A field type specifier escapes all occurences of double quotes, i.e., substitutes \" for each occurence of ".

  • The %a field type specifier escapes all occurences of the following characters in addition to the double quote: \ CR LF FF TAB ( ).

  • The %s field type specifier escapes the same characters as %a, and also encloses the string in double quotes.

  • The %d (or %i) field type specifier assumes a parameter of type int, or of type long if preceeded by an 'l' type specifier (%ld). No other type length specifiers are supported.

  • The %f and %g field type specifiers assume a parameter of type double. No type length specifiers are supported.

  • Other field type specifiers such as %c, %p, %n, %o, %u, %x and %e are not supported.

  • The '*' field width specifier is not supported.

[Important]

The string parameters corresponding to the %s, %a or %A field type specifiers must be of type char *.

Example

void CSetpoint::BuildObjectHierarchy(LPCTSTR sDomain,
                                     LPCTSTR sAssembly)
{
    CT2A aDomain(sDomain);
    char *domain = aDomain;
    CT2A aAssembly(sAssembly);
    char *assembly = aAssembly;
    CT2A aName(sName);
    char *name = aName;

    // (assembly domain name)
    pCnx->sendLispMessage(TRUE, "(assembly %s CSetpoint)", domain);
    // (subassembly domain assemblyname subassemblyname instancename)
    pCnx->sendLispMessage(TRUE, "(subassembly %s %s CSetpoint %s)",
                                  domain, assembly, name);
    // (property domain attrname propid propname
    //  type rw dflt_value dflt_conf)
    pCnx->sendLispMessage(TRUE, "(property %s CSetpoint auto
                                  AutoMode int rw 0 100)", domain);
    pCnx->sendLispMessage(TRUE, "(property %s CSetpoint auto
                                  AutoTime r8 rw 0 100)", domain);
}
Prev Up Next
sendBinaryPointMessages  Home  sendLogin