cniSqlCreateModifyablePathExpression

Use this function to create an SqlPathExpression object that represents the path that is specified by the path argument. When they are navigated, path elements are created 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* cniSqlCreateModifiablePathExpression( 
	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 that are 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. Call cciGetLastExceptionData to retrieve 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 NULL or an empty string, was passed in, returnCode is set to CCI_INV_ESQL_PATH_EXPR.
nodeObject (input): Specifies the message flow processing node that the ESQL Path Expression is owned by. This pointer is passed to the cniCreateNodeContext implementation function. This parameter must not be NULL.
dataSourceName (input): The ODBC data source name to be used if the statement references an external database. This parameter can be NULL.
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, except that 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

If you add the following code to the Transform node sample, you can create an element, and all necessary ancestor elements, with one function call.

Create the CciSQLPathExpression in the _Transform_createNodeContext function:

 {
        CciChar ucsPathExpressionString[32];
        char*   mbPathExpressionString =
                           "OutputRoot.XMLNS.Request.A.B.C.D.E";
        /* convert our path string to unicode*/
        cciMbsToUcs(NULL,
            mbPathExpressionString,
            ucsPathExpressionString,
            32,
            BIP_DEF_COMP_CCSID);
        
        p->pathExpression =
                     cniSqlCreateModifiablePathExpression(
                                 NULL,
                                 nodeObject,
                                 NULL,/* do not reference Database*/
                                 ucsPathExpressionString);
    }

Now use the CciSqlPathExpression later in the _Transform_evaluate function

{
      CciElement* newElement = 
               cniSqlNavigatePath(
                     NULL,
                    ((NODE_CONTEXT_ST *)context)->pathExpression,
                     message,
                     localEnvironment,
                     exceptionList,
                     outMsg,
                     NULL,/* do not reference OutputLocalEnvironment*/
                     NULL/* do not reference OutputLExceptionList*/);
}

Therefore passing in the input message PluginSample.change.xml:

<Request
type="change">
  <CustomerAccount>01234567</CustomerAccount>
  <CustomerPhone>555-0000</CustomerPhone>
</Request>

The following output message is generated:

<Request
type="modify">
  <CustomerAccount>01234567</CustomerAccount>
  <CustomerPhone>555-0000</CustomerPhone>
  <A>
    <B>
      <C>
        <D/>
      </C>
    </B>
  </A>
</Request>

This approach, rather than using functions such as cniCreateElementAsLastChild, has the following advantages:

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