Funções de banco de dados no Jitterbit Design Studio

As funções de banco de dados fornecem acesso a atividades básicas de banco de dados.

CacheLookup

Declaração

string CacheLookup(string databaseId, string sql)

Sintaxe

CacheLookup(<databaseId>, <sql>)

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte de banco de dados no projeto atual
• sql: O comando SQL a ser executado contra o banco de dados

Descrição

Esta função é a mesma que DBLookup, exceto que a primeira busca armazena em cache as informações e as buscas subsequentes usam esse cache em vez de consultar repetidamente o banco de dados. O cache é válido durante a duração da cadeia de operações em que é chamado.

Se não houver linhas retornadas para a consulta especificada em sql, a função retorna nulo.

A variável global do Jitterbit $jitterbit.scripting.db.rows_affected não é definida por este método.

O banco de dados usado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserir itens do projeto.

Uma alternativa ao cache é usar as funções Set e Get.

Exemplos

// Buscando em um banco de dados usando uma string SQL
CacheLookup("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE FROM PO_HEADER WHERE PO_NUMBER=1");

CallStoredProcedure

Declaração

type CallStoredProcedure(string databaseId, string spName, type resultSet[, string inputOutputVariable,...])

Sintaxe

CallStoredProcedure(<databaseId>, <spName>, <resultSet>[, <inputOutputVariable>,...])

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte do banco de dados no projeto atual
• spName: O procedimento armazenado a ser executado no servidor de banco de dados
• resultSet: Uma variável global para armazenar o conjunto de resultados retornado pelo servidor de banco de dados, se aplicável. (Veja as notas abaixo).

Parâmetros opcionais

• inputOutputVariable: Um parâmetro de entrada ou saída a ser passado para o procedimento armazenado; esses parâmetros são adicionados conforme necessário pela assinatura do procedimento armazenado

Descrição

Chama o procedimento armazenado spName usando as informações de conexão especificadas pela fonte/destino identificada por databaseId.

Se aplicável, o resultSet retornado é um array bidimensional de strings. Se o procedimento armazenado não retornar um resultSet ou se estiver usando um driver ODBC, este argumento é ignorado.

Os parâmetros opcionais restantes são usados para passar argumentos de entrada e saída para o procedimento armazenado. O número de argumentos necessários depende da assinatura do procedimento armazenado.

Os argumentos de entrada podem ser um valor codificado, o valor de uma fonte ou o valor de um cálculo ou fórmula. Os argumentos de saída (incluindo o resultSet) são especificados por referência como "$name", onde "name" é o nome da variável global que armazenará o valor de saída. O valor de retorno e o tipo da função são o valor de retorno e o tipo do procedimento armazenado.

$sql = "BEGIN
MyStoredProcedure;
END;";

$result = DBExecute("<TAG>Sources/Oracle</TAG>",$sql);

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserindo itens do projeto.

Examples

Example 1: Calling a stored procedure with no result set

// Calls a stored procedure "MyStoredProcedure",
// which takes one input variable, one output variable,
// and ignores the result set.
// "Input" is the name of the source global variable
// that provides the input and
// "output" is the name of the global variable
// used to store the output:

CallStoredProcedure("<TAG>Sources/myDBTarget</TAG>",
  "MyStoredProcedure", 0, Input, $output);

// The value of the output parameter can be accessed
// by using either $output or Get("output")

Example 2: Calling a stored procedure with a result set

// Calls a stored procedure "GetValues",
// which takes two input variables and returns a result set.
// The result set is returned as the two-dimensional array $result.
// The result can be accessed by using either $result or Get("result"):

CallStoredProcedure("<TAG>Sources/myDBTarget</TAG>", "GetValues", $result, Input1, Input2);

Example 3: Calling a stored procedure that accesses an Oracle object type

Using Oracle object and record types

Jitterbit suporta Tipos de Objetos Oracle para trabalhar com bancos de dados Oracle ao usar o driver JDBC do Oracle. Tipos de Objetos Oracle são semelhantes aos Tipos de Registros Oracle, que não são suportados no Jitterbit devido à falta de suporte por parte da Oracle.

Para acessar Tipos de Registros Oracle usando o driver JDBC do Oracle, você pode criar um procedimento armazenado "wrapper" em seu banco de dados Oracle que pode acessar e converter um Tipo de Registro Oracle. Em seguida, use a função CallStoredProcedure no Jitterbit para chamar o procedimento wrapper e fazer a conversão para e de um Tipo de Objeto Oracle.

O exemplo a seguir descreve como você pode usar Objetos Oracle em uma função CallStoredProcedure de maneira simplificada.

Definições de tipo Oracle

Uma definição de Tipo de Objeto Oracle segue este padrão:

CREATE OR REPLACE TYPE example_customer_details AS OBJECT
(status NUMBER
,party_id NUMBER
,account_id VARCHAR
);

Uma definição de Tipo de Registro Oracle segue este padrão:

CREATE TYPE example_customer_details IS RECORD
(status NUMBER
,party_id NUMBER
,account_id VARCHAR
);

Passos do exemplo

Passo 1: Criar o Objeto
Para usar Tipos de Objeto Oracle, primeiro crie o objeto no banco de dados Oracle:

CREATE OR REPLACE TYPE example_customer_details AS OBJECT
(status                    NUMBER
,party_id                  NUMBER
,account_id                VARCHAR
);

Passo 2: Criar o Pacote
Em seguida, crie o pacote como uma função no banco de dados Oracle:

CREATE OR REPLACE PACKAGE example AS
  FUNCTION processcustomer(custin IN example_customer_details, new_account_number IN VARCHAR) RETURN example_customer_details;
END example;

Passo 3: Criar o Corpo do Pacote
Em seguida, crie o corpo do pacote como uma função no banco de dados Oracle:

CREATE OR REPLACE PACKAGE BODY example AS
FUNCTION processcustomer(custin IN example_customer_details, new_account_number IN varchar) RETURN example_customer_details
  IS
  custout example_customer_details;
  BEGIN
     custout := example_customer_details(
     custin.status + 1,
     custin.party_id,
     new_account_number
     );
     return custout;
END;
END example;

Passo 4: Chamar o Procedimento Armazenado no Jitterbit
Agora você está pronto para chamar o procedimento armazenado processcustomer do Jitterbit usando a função CallStoredProcedure. Este script de exemplo mostra como passar um objeto para a função CallStoredProcedure. Você também pode passar objetos de um procedimento armazenado como parâmetros de retorno ou saída de maneira semelhante.

<trans>
$cust = dict();
$cust["status"] = 1;
$cust["party_id"] = 10;
$cust["account_id"] = "2341";

$custout = CallStoredProcedure("<TAG>Sources/OracleDatabase</TAG>",
    "EXAMPLE.PROCESSCUSTOMER", "", $cust,"NA0233");

$result = "Status: " + $custout["STATUS"] +
  "  Party ID: " + $custout["PARTY_ID"] +
  "  Account ID:  " + $custout["ACCOUNT_ID"];

WriteToOperationLog("Resulting object: " + $result);
</trans>

DBCloseConnection

Declaração

void DBCloseConnection(string databaseId)

Sintaxe

DBCloseConnection(<databaseId>)

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte do banco de dados no projeto atual.

Descrição

Confirma a transação atual e fecha a conexão com o banco de dados.

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserir itens de projeto.

Exemplos

// Fechando uma conexão com o banco de dados
DBCloseConnection("<TAG>Sources/myDBTarget</TAG>");

DBExecute

Declaração

array DBExecute(string databaseId, string sql)

int DBExecute(string databaseId, string sql, string outputVariable,...)

Sintaxe

DBExecute(<databaseId>, <sql>)

DBExecute(<databaseId>, <sql>, <outputVariable>,...)

Parâmetros obrigatórios

• databaseId: Uma string Fonte de banco de dados no projeto atual
• sql: O comando SQL a ser executado contra o banco de dados
• outputVariable: (Segunda forma) Um parâmetro de saída que corresponde aos campos retornados no comando SQL. Argumentos adicionais podem ser especificados conforme necessário.

Descrição

Executa uma instrução SQL em um banco de dados e retorna os resultados.

Se a instrução SQL produzir um conjunto de resultados, existem duas maneiras de recuperar os dados:

• Se você especificar apenas os dois parâmetros obrigatórios (primeira forma), a função retornará o conjunto completo de registros como um array de linhas.

  Você pode então usar um loop While() para iterar sobre as linhas e usar Get() para recuperar os dados. Se nenhuma linha for retornada, o método retorna um array vazio (Length($arr) == 0).

• Se você especificar variáveis de saída além dos dois parâmetros obrigatórios (segunda forma), os valores dos campos da primeira linha serão retornados.

  Passe os nomes das variáveis globais entre aspas como parâmetros após os dois primeiros parâmetros. O valor do primeiro campo da primeira linha será escrito na variável global passada como o terceiro parâmetro, o segundo campo da primeira linha no quarto parâmetro, e assim por diante. Alternativamente, as variáveis globais podem ser passadas por referência, precedendo-as com um sinal de $ , como $output.

  O valor de retorno neste caso é o número de registros retornados; seja 1 (se registros foram encontrados) ou 0 (se nenhum foi retornado).

Os valores de dados retornados são sempre strings. Dados binários são retornados como sua representação em string hexadecimal.

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserindo itens do projeto.

Variáveis Relacionadas do Jitterbit

• Se este método for concluído com sucesso, $jitterbit.scripting.db.rows_affected conterá o número de linhas afetadas pela consulta.
• Se estiver usando um driver JDBC para se conectar a um banco de dados, defina jitterbit.scripting.db.search.rowset como true antes da função para que qualquer chamada a um procedimento armazenado que retorne múltiplos resultados retorne o primeiro conjunto de registros não vazio em vez de retornar um conjunto vazio.
• Para executar a instrução em uma transação, defina as variáveis $jitterbit.scripting.db.auto_commit=false e $jitterbit.scripting.db.transaction=true em um script antes da chamada. A transação será confirmada ao final de uma transformação bem-sucedida. Definir ambas as variáveis (auto_commit e transaction) como true resultará em um erro.
• Defina $jitterbit.scripting.db.max_rows para limitar o número de registros a serem retornados. O padrão é 10.000 linhas.

Exemplos

Exemplo 1: Executando e recuperando valores em um array

// Results of the SQL select as an array
rows = DBExecute("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE, ORDER_AMOUNT FROM PO_HEADER WHERE PO_NUMBER = 1");

// The value of the database column ORDER_TYPE can then be accessed with
// Get($rows, $i, 0) where $i is the 0-based count of the row you want retrieved.

Exemplo 2: Executando e recuperando valores em variáveis globais de referência passadas

// Results of the SQL select will be in the $custName and $custAddr global variables:
DBExecute("<TAG>Sources/myDBTarget</TAG>",
    "SELECT CustomerName, CustomerAddress FROM Customers WHERE CustomerId = " + $custId,
    $custName,
    $custAddr);

// The value of the database column CustomerName can then
// be accessed with either Get("custName") or $custName.

Exemplo 3: Executando e recuperando valores em variáveis globais nomeadas passadas

// Results of the SQL select will be in the OrderType and OrderAmount global variables:
DBExecute("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE, ORDER_AMOUNT FROM PO_HEADER WHERE PO_NUMBER = 1",
    "OrderType", "OrderAmount");

// The value of the database column ORDER_TYPE can then
// be accessed with either Get("OrderType") or $OrderType.

DBLoad

Declaração

void DBLoad(string source, string target, int mode, string tablename, string columnNames[, string columnKeynames, int skipLines, string dateFormat, string datetimeFormat])

Sintaxe

DBLoad(<source>, <target>, <mode>, <tablename>, <columnNames>[, <columnKeynames>, <skipLines>, <dateFormat>, <datetimeFormat>])

Parâmetros obrigatórios

• source: Uma fonte de string no projeto atual que é um único arquivo em formato CSV
• target: Um alvo de string Database no projeto atual
• mode: Um inteiro; um dos 1 (upsert), 2 (inserir) ou 3 (atualizar)
• tablename: A tabela no banco de dados de destino
• columnNames: Uma lista de nomes de colunas delimitada por vírgulas
• columnKeynames: Uma lista de nomes de colunas delimitada por vírgulas que formam a chave de atualização. Necessário se o modo não for 2.

Parâmetros opcionais

• skipLines: Número de linhas a serem ignoradas no início do arquivo (usado para pular cabeçalhos)
• dateFormat: Especifica o formato dos campos de data, como "Date" em bancos de dados Oracle
• datetimeFormat: Especifica o formato dos campos de data e hora, como "TimeStamp" em bancos de dados Oracle

Descrição

Recebe uma fonte (um único arquivo em formato CSV) e carrega os dados em uma tabela especificada em um banco de dados de destino.

O parâmetro columnKeynames não é utilizado ao inserir apenas (mode=2) e pode ser omitido nesse caso.

Fonte

A fonte utilizada nesta chamada de função deve ser definida como uma fonte de arquivo do projeto atual. O primeiro arquivo retornado dessa fonte será utilizado. Veja as instruções sobre inserindo itens do projeto.

Exemplos

// Using the file returned from the source "MyCSVData",
// this example upserts (mode=1) into the table "MyTable"
// on the Database target "SQL Server JDBC". "MyCSVData"
// is expected to be a CSV file that contains data for
// the columns "ID,Col1,Col2,Col3". The update key (used
// to decide whether to update or insert) will be on the
// column "ID". The first line of the CSV file will be
// ignored as it is a header:

DBLoad("<TAG>Sources/MyCSVData</TAG>",
    "<TAG>Targets/SQL Server JDBC</TAG>", 1,
    "MyTable", "ID,Col1,Col2,Col3", "ID", 1);

DBLookup

Declaração

string DBLookup(string databaseId, string sql)

Sintaxe

DBLookup(<databaseId>, <sql>)

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte de dados no projeto atual
• sql: O comando SQL a ser executado no banco de dados

Descrição

Executa uma instrução SQL em um banco de dados e retorna o primeiro campo do primeiro resultado que corresponde aos critérios especificados.

O valor de dados retornado é sempre uma string. Dados binários são retornados como sua representação em string hexadecimal. Se não houver linhas retornadas para a consulta especificada, a função retorna null.

A variável global do Jitterbit $jitterbit.scripting.db.rows_affected não é definida por este método.

Para consultas mais avançadas, onde você deseja recuperar mais de um valor ou linha, use as funções DBLookupAll ou DBExecute.

ID do banco de dados

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserir itens do projeto.

Exemplos

// Returns the first field of the first result from
// running the SQL query
result = DBLookup("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE FROM PO_HEADER WHERE PO_NUMBER=1");

DBLookupAll

Declaração

array DBLookupAll(string databaseId, string sql)

Sintaxe

DBLookupAll(<databaseId>, <sql>)

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte de dados no projeto atual
• sql: O comando SQL a ser executado no banco de dados

Descrição

Executa uma instrução SQL em um banco de dados e retorna os resultados que correspondem aos critérios especificados.

Os dados retornados são sempre apresentados como um array bidimensional de strings. Dados binários são retornados como sua representação em string hexadecimal. Se não houver linhas retornadas para a consulta especificada, a função retorna um array vazio.

A variável global do Jitterbit $jitterbit.scripting.db.rows_affected não é definida por este método.

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserir itens do projeto.

Para consultas mais avançadas, onde você deseja recuperar diretamente em variáveis globais, use a função DBExecute.

Exemplos

// Retorna o resultado da execução da consulta SQL
result = DBLookupAll("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE FROM PO_HEADER WHERE PO_NUMBER=1");

DBRollbackTransaction

Declaração

void DBRollbackTransaction(string databaseId)

Sintaxe

DBRollbackTransaction(<databaseId>)

Parâmetros obrigatórios

• databaseId: Uma string que representa a fonte de banco de dados no projeto atual

Descrição

Desfaz a transação atual e fecha a conexão com o banco de dados.

O banco de dados utilizado nesta chamada de função deve ser definido como uma fonte ou um destino do projeto atual. Veja as instruções sobre inserir itens do projeto.

Exemplos

// Desfaz a transação atual
DBRollbackTransaction("<TAG>Sources/myDBTarget</TAG>");

DBWrite

Declaração

void DBWrite(string source, string target, int mode, string tablename, string columnNames[, string columnKeynames, int skipLines, string dateFormat, string datetimeFormat])

Sintaxe

DBWrite(<source>, <target>, <mode>, <tablename>, <columnNames>[, <columnKeynames>, <skipLines>, <dateFormat>, <datetimeFormat>])

Descrição

Um alias para a função DBLoad. Veja DBLoad para detalhes.

SetDBInsert

Declaração

void SetDBInsert()

Sintaxe

SetDBInsert()

Descrição

Substitui a configuração atual do modo de inserção/atualização para "inserir" para o registro atual. O valor de retorno é nulo.

Exemplos

// Define o modo de inserção/atualização como "inserir"
// para o registro atual
SetDBInsert();

SetDBUpdate

Declaração

void SetDBUpdate()

Sintaxe

SetDBUpdate()

Descrição

Substitui a configuração atual do modo de inserção/atualização para "atualizar" para o registro atual. O valor de retorno é nulo.

Exemplos

// Define o modo de inserção/atualização como "atualizar"
// para o registro atual
SetDBUpdate();

SQLEscape

Declaração

string SQLEscape(string unescapedSQL[, bool escapeBackslash])

Sintaxe

SQLEscape(<unescapedSQL>[, <escapeBackslash>])

Parâmetros obrigatórios

• unescapedSQL: Uma string de SQL que deve ser escapada

Parâmetros opcionais

• escapeBackslash: Flag booleana que indica se barras invertidas ("\") devem ser escapadas sendo duplicadas; o padrão é false

Descrição

Realiza o escape necessário de strings literais usadas em uma instrução SQL.

Strings usadas como constantes de caractere em uma instrução SQL utilizam uma aspa simples (') como delimitador; se os dados reais contiverem aspas simples, elas precisam ser escapadas especificando-as duas vezes. Este método escapa aspas simples seguindo o padrão SQL, substituindo cada aspa simples (') por duas aspas simples (''). Se os caracteres de barra invertida também devem ser escapados, forneça e defina o segundo parâmetro como true.

Exemplos

// In this example, the variable GUID needs to have
// any single quotes in it escaped (doubled); the
// resulting string is then enclosed in single quotes
// by the Quote function before being used in a
// DBLookup function:


DBLookup("<TAG>Sources/myDBTarget</TAG>",
    "SELECT ORDER_TYPE FROM PO_HEADER WHERE PO_ID=" +
    Quote(SQLEscape(GUID)));

Unmap

Declaração

void Unmap()

Sintaxe

Unmap()

Descrição

Para uso em mapeamentos, esta função define um campo de destino do banco de dados para ser tratado como não mapeado. O valor de retorno é nulo.

Exemplos

valueToInsert = DBLookup(....);
// If valueToInsert returned by a DBLookup is null, we want to treat
// this field as unmapped and we do not want to include it in the INSERT statement
// that is being generated for the DB target for this record:
If (valueToInsert == Null(), Unmap(), valueToInsert);

<SEQUENCE>

Declaração

<SEQUENCE>

Sintaxe

<SEQUENCE>

Descrição

Para uso em mapeamentos com bancos de dados Oracle, esta função é utilizada quando o destino contém tabelas que estão vinculadas por um relacionamento de chave primária/chave estrangeira. Nesse caso, mapeie isso para as chaves primárias que são geradas pelo banco de dados Oracle.

Para bancos de dados que não sejam Oracle, use a função <SQLIDENTITY> em vez disso.

Exemplos

Se as tags <trans> estiverem presentes, <SEQUENCE> deve ser colocado fora delas assim:

<trans>
</trans>
<SEQUENCE>

<SQLIDENTITY>

Declaração

<SQLIDENTITY>

Sintaxe

<SQLIDENTITY>

Descrição

Para uso em mapeamentos com bancos de dados não Oracle, esta função é utilizada quando o destino contém tabelas que estão vinculadas por um relacionamento de chave primária/chave estrangeira. Nesse caso, mapeie isso para as chaves primárias que são geradas pelo banco de dados, como Identity no SQL Server ou Serial no PostgreSQL. Para bancos de dados Oracle, use a função <SEQUENCE> em vez disso.

Exemplos

Se as tags <trans> estiverem presentes, <SQLIDENTITY> deve ser colocado fora delas assim:

<trans>
</trans>
<SQLIDENTITY>

<UDF>

Declaração

<UDF>string userDefinedFunction

Sintaxe

<UDF><userDefinedFunction>

Parâmetros obrigatórios

• userDefinedFunction: Uma string definindo uma chamada de função definida pelo usuário

Descrição

Adiciona uma função de banco de dados definida pelo usuário ao início de uma fórmula. O prefixo <UDF> é removido da expressão antes de ser passado adiante. Observe que as tags <trans> de abertura e fechamento podem ser usadas para indicar partes da chamada da função que devem ser avaliadas pelo Jitterbit antes que a expressão seja passada para um banco de dados.

Exemplos

// The user-defined function geography::Point()
// is being called with parameters created by evaluating
// the Jitterbit Script enclosed by <trans> tags:

<UDF>geography::Point(<trans>json$Incidents$item.Latitude$ + ","
  + json$Incidents$item.Longitude$ + ",4326";</trans>)