cniSqlNavigatePath

Use this function to run the SQLPathExpression that you have created by calling 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 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. A call to cciGetLastExceptionData provides details of the exception. If an invalid sqlPathExpression parameter was passed in, returnCode is set to CCI_INV_SQL_EXPR_OBJECT. If an invalid CciMessage* value is passed in, returnCode is set to CCI_INV_MESSAGE_OBJECT. If the element could not be navigated to or created, 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 cannot be NULL.
inputMessageRoot (input): The message representing the input message. This parameter cannot be NULL.
inputLocalEnvironment (input): The message representing the input local environment. This parameter cannot be NULL.
inputExceptionList (input): The message representing the input exception list. This parameter cannot 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 that is accessed.

Correlation name	Data accessed
Environment	The single Environment tree for the flow. This element is determined by the integration node and it is not necessary to specify it with 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 (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 that is compatible with earlier versions
OutputDestinationList	Synonym for OutputLocalEnvironment that is compatible with earlier versions

All other rules regarding the actual navigability and validity of paths are defined in Correlation names.

Return values

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

Example

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

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