cniSqlNavigatePath

Executes the SQLPathExpression previously created with the cniSqlCreateReadOnlyPathExpression or the cniSqlCreateModifiablePathExpression utility functions, as defined by the sqlPathExpression argument.

Syntax

CciElement* cniSqlNavigatePath( 
	int*                  returnCode,
	CciSqlPathExpression* sqlPathExpression,
	CciMessage*           inputMessageRoot,
	CciMessage*           inputLocalEnvironment,
	CciMessage*           inputExceptionList,       
	CciMessage*           outputMessageRoot
	CciMessage*           outputLocalEnvironment,
	CciMessage*           outputExceptionList);

Parameters

returnCode (output)
A NULL pointer input signifies that the user-defined node does not want to deal with errors. Any exceptions thrown during the execution of this call will be re-thrown to the next upstream node in the flow. If input is not NULL, output will signify the success status of the call. If an exception occurs during execution, *returnCode will be set to CCI_EXCEPTION on output. A call to cciGetLastExceptionData will provide details of the exception. If an invalid sqlPathExpression parameter was passed in, then returnCode will be set to CCI_INV_SQL_EXPR_OBJECT. If an invalid CciMessage* value is passed in then returnCode will be set to CCI_INV_MESSAGE_OBJECT. If the element could not be navigated to or created, then returnCode is set to CCI_PATH_NOT_NAVIGABLE.
sqlPathExpression (input)
Specifies the SQLPathExpression object to be executed as returned by either the cniCreateReadOnlyPathExpression or the cniCreateModifyablePathExpression function. This parameter can not be NULL.
inputMessageRoot (input)
The message representing the input message. This parameter can not be NULL.
inputLocalEnvironment (input)
The message representing the input local environment. This parameter can not be NULL.
inputExceptionList (input)
The message representing the input exception list. This parameter can not be NULL.
outputMessageRoot (input)
The message representing the output message. This parameter can be NULL.
outputLocalEnvironment (input)
The message representing the output local environment. This parameter can be NULL.
outputExceptionList (input)
The message representing the output exception list. This parameter can be NULL.

The following table shows the mapping between the correlation names accepted in the ESQL path expression and the data accessed.

Correlation name Data accessed
Environment The single Environment tree for the flow. This is determined by the broker and it is not necessary to specify it via this API.
InputLocalEnvironment inputLocalEnvironment parameter to cniSqlNavigatePath
OutputLocalEnvironment outputLocalEnvironment parameter to cniSqlNavigatePath
InputRoot inputMessageRoot parameter to cniSqlNavigatePath
InputBody Last child of InputRoot
InputProperties InputRoot.Properties
Note: InputRoot.Properties is the first child of InputRoot, named "Properties"
OutputRoot outputMessageRoot parameter to cniSqlNavigatePath
InputExceptionList inputExceptionList parameter to cniSqlNavigatePath
OutputExceptionList outputExceptionList parameter to cniSqlNavigatePath
Database ODBC datasource identified by dataSourceName parameter to cniCreateReadOnlyPathExpression or cniCreateModifyablePathExpression
InputDestinationList Synonym for InputLocalEnvironment
OutputDestinationList Synonym for OutputLocalEnvironment

All other rules regarding the actual navigability and validity of paths are as per the ESQL Field Reference documentation.

Return values

If the path is successfully navigated the address of the syntax element is returned. . However if the path is not navigable then a value of zero (CCI_NULL_ADDR) is returned and the returnCode parameter indicates the reason for the error.

Example

Assuming we have previously created a SQLPathExpression ( see the example for cniSqlCreateReadOnlyPathExpression or cniSqlCreateModifiablePathExpression), we could use the following code to navigate to the target element.

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