cniSqlCreateReadOnlyPathExpression

Use this function to create an SqlPathExpression object that represents the path that is specified by the path argument. The navigated path does not create path elements if they do not already exist. This function returns a pointer to the PathExpression object, which is used as input to the functions that navigate the path, namely the cniSqlNavigatePath family.

Because an overhead is incurred in creating the expression, if the same path expression is to be used for every message, call this function once, and use the CciSqlPathExpression* that is returned in a call to cniSqlNavigate for each message. You can use the CciSqlPathExpression* on threads other than the one on which it was created.

Syntax

CciSqlPathExpression* cniSqlCreateReadOnlyPathExpression( 
	   int*     returnCode,
     CciNode* nodeObject,
     CciChar* dataSourceName,
     CciChar* path );

Parameters

returnCode (output): A NULL pointer input signifies that the user-defined node does not handle errors. Any exceptions thrown during the execution of this call are re-thrown to the next upstream node in the flow. If input is not NULL, output signifies the success status of the call. If an exception occurs during execution, *returnCode is set to CCI_EXCEPTION on output. A call to cciGetLastExceptionData provides details of the exception. If an invalid nodeObject parameter was passed in, returnCode is set to CCI_INV_NODE_OBJECT. If an invalid path parameter, such as a NULL or empty string, was passed in, returnCode is set to CCI_INV_ESQL_PATH_EXPR.
nodeObject (input): Specifies the message flow processing node that owns the ESQL Path Expression. This pointer is passed to the cniCreateNodeContext implementation function. This parameter must not be NULL.
dataSourceName (input): The ODBC data source name that is used if the statement references an external database. NULL is allowed.
path (input): Pointer to a NULL terminated string of CciChars. This parameter specifies the ESQL path expression to be created, as defined by the ESQL field reference syntax diagram. It cannot include local ESQL variables, ESQL reference variables, user-defined functions, or ESQL namespace constants, because they cannot be declared. This parameter must not be NULL.

Return values

If successful, the address of the SQLPathExpression object is returned. If an error occurs, CCI_NULL_ADDR is returned and the return code parameter indicates the reason for the error. When the SQLPathExpression is no longer needed (typically when the node is deleted), call cniSqlDeletePathExpression to delete it.

Example

The switch node sample shows how to navigate to a syntax element using functions like cniFirstChild. The following code could be used to achieve the same result.

In _Switch_createNodeContext function, create the CciSqlPathExpression for use later.

 {
        CciChar ucsPathExpressionString[32];
        char*   mbPathExpressionString = "InputBody.Request.type";
        /* convert our path string to unicode*/
        cciMbsToUcs(
                  NULL,
                  mbPathExpressionString,
                  ucsPathExpressionString,
                  32,
                  BIP_DEF_COMP_CCSID);
        
        p->pathExpression = 
                    cniSqlCreateReadOnlyPathExpression(
                            NULL,
                            nodeObject,
                            NULL, /* do not reference Database*/
                            ucsPathExpressionString);
}

This code assumes the addition of the field CciSqlPathExpression* pathExpression to the NODE_CONTEXT_ST struct.

Now use the CciSqlPathExpression in the _Switch_evaluate function.

CciElement* targetElement = cniSqlNavigatePath(
                           NULL,
                          ((NODE_CONTEXT_ST *)context)->pathExpression,
                           message,
                           localEnvironment,
                           exceptionList,
                           NULL, /* do not reference any output trees*/
                           NULL,
                           NULL);

This approach, rather than using functions such as cniFirstChild and cniNextSibling, has the following advantages:

The path is more dynamic: the path string could be determined at deploy time based on a node property (you could create the CciSqlPathExpression in the cniSetAttribute implementation function).
While navigating to the element, only one function call is made. This technique is more apparent when the target element is deep within the tree structure.