cniSqlCreateReadOnlyPathExpression

Cria um objeto SqlPathExpression não modificável que representa o caminho especificado pelo argumento de caminho. Não modificável significa que o caminho navegado não criará elementos de caminho, se ainda não existirem. Essa função retorna um ponteiro para o objeto PathExpression o qual é utilizado como entrada para as funções que navegam o caminho, isto é, a família cniSqlNavigatePath.

Há um código extra envolvido na criação da expressão, portanto, se for necessário utilizar a mesma expressão de caminho para cada mensagem, essa função deve ser chamada uma vez e a CciSqlPathExpression* que é retornada deve ser utilizada em uma chamada para niSqlNavigatec para cada mensagem. É possível utilizar CciSqlPathExpression* em um encadeamento diferente do que ele foi criado.

Sintaxe

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

Parâmetros

returnCode (saída)
Uma entrada de ponteiro NULL significa que o nó definido pelo usuário não irá lidar com erros. Quaisquer exceções lançadas durante a execução desta chamada serão lançadas novamente para o próximo nó acima no fluxo. Se a entrada não for NULL, a saída significará o status de êxito da chamada. Se uma exceção ocorrer durante a execução, *returnCode será definido como CCI_EXCEPTION na saída. Uma chamada para cciGetLastExceptionData fornecerá detalhes da exceção. Se um parâmetro nodeObject inválido foi transmitido, o returnCode será configurado como CCI_INV_NODE_OBJECT. Se um parâmetro de caminho inválido, como por exemplo uma cadeia NULL ou vazia, foi transmitido, o returnCode será configurado como CCI_INV_ESQL_PATH_EXPR.
nodeObject (entrada)
Especifica o nó de processamento do fluxo de mensagens pertencente à Expressão de Caminho do ESQL. Esse ponteiro é transmitido à função de implementação cniCreateNodeContext. Esse parâmetro não deve ser NULL.
dataSourceName (entrada)
O nome da origem de dados ODBC a ser utilizado, se a instrução referenciar um banco de dados externo. NULL é permitido.
path (entrada)
Ponteiro para uma cadeia finalizada NULL de CciChars. Isso especifica a expressão de caminho ESQL a ser criada como definida pelo diagrama de sintaxe de referência de campo ESQL, exceto que ela não pode incluir variáveis ESQL locais, variáveis Referência de ESQL, funções definidas pelo usuário, constantes de Espaço de Nomes ESQL, porque não podem ser declaradas. No entanto, se uma puder ser executada em um caminho ESQL de uma linha em um nó calculado, então, isso será possível com esta API. Esse parâmetro não deve ser NULL.

Valores de Retorno

Se bem-sucedidos, o endereço do objeto SQLPathExpression será retornado. Se um erro ocorrer, CCI_NULL_ADDR será retornado e o parâmetro de código de retorno indica a razão do erro. Quando a SQLPathExpression não é mais necessária, (normalmente, quando o nó é excluído) ela deve ser excluída chamando cniSqlDeletePathExpression.

Exemplo

A amostra de nó de chave mostra como navegar para um elemento da sintaxe utilizando funções como cniFirstChild. O código a seguir pode ser utilizado para conseguir o mesmo resultado.

Na função _Switch_createNodeContext, criamos a CciSqlPathExpression para uso posterior.

 {
        CciChar ucsPathExpressionString[32];
        char*   mbPathExpressionString = "InputBody.Request.type";
        /* Converter a cadeia de caminho para unicode*/
        cciMbsToUcs(
                  NULL,
                  mbPathExpressionString,
                  ucsPathExpressionString,
                  32,
                  BIP_DEF_COMP_CCSID);
        
        p->pathExpression =
                    cniSqlCreateReadOnlyPathExpression(
                            NULL,
                            nodeObject,
                            NULL, /*não foi feita referência ao Banco de Dados*/
                            ucsPathExpressionString);
}
Nota: Isso assume uma alteração na estrutura NODE_CONTEXT_ST, na qual o campo CciSqlPathExpression* pathExpression foi incluído;

Em seguida, é possível utilizar essa CciSqlPathExpression na função _Switch_evaluate.

CciElement* targetElement = cniSqlNavigatePath(
                           NULL,
                          ((NODE_CONTEXT_ST *)context)->pathExpression,
                           message,
                           destinationList,
                           exceptionList,
                           NULL, /*não foi feita referência a nenhuma árvore de saída*/
                           NULL,
                           NULL);
Utilizar essa abordagem em oposição ao uso do cniFirstChild, cniNextSibling e assim por diante, tem as seguintes vantagens:
  • O caminho é mais dinâmico - a cadeia de caminhos poderia ser determinada no período de implementação, por ex., com base em um atributo de nó (poderíamos criar a CciSqlPathExpression na função de implementação cniSetAttribute).
  • Durante a navegação no elemento, foi feita uma chamada de função em vez de várias. Isso se torna mais evidente, quando o elemento de destino é intenso dentro da estrutura em árvore.
Avisos | Marcas Registradas | Downloads | Biblioteca | Suporte | Feedback
Direitos Autorais IBM Corporation 1999, 2006 Última Atualização: 1 Sep 2006
as08031_