Funções de Banco de Dados¶

As funções do banco de dados fornecem acesso às interações básicas do banco de dados.

CacheLookup¶

Declaração¶

string CacheLookup(string databaseId, string sql)

Sintaxe¶

CacheLookup(<databaseId>, <sql>)

Parâmetros Obrigatórios¶

• databaseId: Um caminho de referência de string para uma conexão de banco de dados no projeto atual
• sql: O comando SQL a ser executado no banco de dados

Descrição¶

Esta função é a mesma que DBLookup, exceto que a primeira pesquisa armazena em cache as informações e as pesquisas subsequentes usam esse cache em vez de consultar repetidamente o banco de dados. (Uma alternativa ao cache é usar as funções Set e Get.)

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

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

O banco de dados usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

// Looking up in a database using a SQL string
CacheLookup("<TAG>endpoint:database/My Database</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: Um caminho de referência de string para uma conexão de 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 exigido pela assinatura do procedimento armazenado

Descrição¶

Chama o procedimento armazenado spName usando as informações de conexão especificadas pela conexão do banco de dados identificada por databaseId.

Se aplicável, o retornado resultSet é uma matriz bidimensional de strings. Se o procedimento armazenado não retornar resultSet ou se estiver usando um driver ODBC, este argumento será 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 irá 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.

O banco de dados usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

Exemplo 1: Chamar um Procedimento Armazenado Sem Conjunto de Resultados¶

// 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>endpoint:database/My Oracle Database</TAG>",
    "MyStoredProcedure", 0, Input, $output);

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

Exemplo 2: Chamar um Procedimento Armazenado com um Conjunto de Resultados¶

// 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>endpoint:database/My Oracle Database</TAG>",
    "GetValues", $result, Input1, Input2);

Exemplo 3: Chamar um Procedimento Armazenado Que Acessa um Tipo de Objeto Oracle¶

Use Tipos de Objeto e Registro Oracle¶

O Jitterbit suporta Oracle Object Types para trabalhar com bancos de dados Oracle ao usar o driver Oracle JDBC. Oracle Object Types são semelhantes aos Oracle Record Types, que não são suportados no Jitterbit devido à falta de suporte do Oracle.

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

O exemplo a seguir descreve como você pode usar objetos Oracle em um CallStoredProcedure funcionam de forma 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
);

Etapas de Exemplo¶

Etapa 1: Crie o objeto Para usar os 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
);

Etapa 2: Crie 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;

Etapa 3: Crie 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;

Etapa 4: Chamar o procedimento armazenado no Jitterbit Agora você está pronto para chamar o procedimento armazenado processcustomer do Jitterbit usando o CallStoredProcedure função. Este script de exemplo mostra como passar um objeto para o CallStoredProcedure função. 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";
db = "<TAG>endpoint:database/My Oracle Database</TAG>";
$custout = CallStoredProcedure(db, "EXAMPLE.PROCESSCUSTOMER", "", $cust, "NA0233");
r = "Status: " + $custout["STATUS"] +
" Party ID: " + $custout["PARTY_ID"] +
" Account ID: " + $custout["ACCOUNT_ID"];
WriteToOperationLog("Resulting object: " + r);
</trans>

DBCloseConnection¶

Declaração¶

void DBCloseConnection(string databaseId)

Sintaxe¶

DBCloseConnection(<databaseId>)

Parâmetros Obrigatórios¶

• databaseId: Um caminho de referência de string para uma conexão de 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 usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

// Closing a Database connection
DBCloseConnection("<TAG>endpoint:database/My Database</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: Um caminho de referência de string para uma conexão de banco de dados no projeto atual
• sql: O comando SQL a ser executado no banco de dados
• outputVariable: (Segunda forma) Um parâmetro de saída que é correspondido 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, há duas maneiras de recuperar os dados:

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

  Você pode então usar um While() loop para iterar sobre as linhas e usar Get() para recuperar os dados. Se nenhuma linha for retornada, o método retornará uma matriz vazia (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 nomes de 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 para o quarto parâmetro, e assim por diante. Alternativamente, as variáveis globais podem ser passadas por referência precedendo-as com um sinal $, como $output.

  O valor de retorno neste caso é o número de registros retornados; 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 hexadecimal-string.

O banco de dados usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Variáveis Jitterbit relacionadas

• Se este método for concluído com sucesso, $jitterbit.scripting.db.rows_affected conterá o número de linhas afetadas pela consultar.
• Se estiver usando um driver JDBC para conectar a um banco de dados, defina jitterbit.scripting.db.search.rowset para true a acima na cadeia da função para fazer chamadas a um procedimento armazenado que retorna vários resultados para retornar 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 no final de uma transformação bem-sucedida. Definir ambas as variáveis (auto_commit e transaction) para true resultará em um erro.
• Definir $jitterbit.scripting.db.max_rows para limitar o número de registros a serem retornados. O padrão é 10.000 linhas.

Exemplos¶

Exemplo 1: Executar e Recuperar Valores em uma Matriz¶

// Results of the SQL select as an array

t = "<TAG>endpoint:database/My Database</TAG>";

rows = DBExecute(t, "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: Executar e Recuperar Valores em Variáveis Globais Referenciadas Passadas¶

// Results of the SQL select will be in the
// $custName and $custAddr global variables:

t = "<TAG>endpoint:database/My Database</TAG>";

DBExecute(t,
  "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: Executar e Recuperar Valores em Variáveis Globais Nomeadas Passadas¶

// Results of the SQL select will be in the
// OrderType and OrderAmount global variables:

t = "<TAG>endpoint:database/My Database</TAG>";

DBExecute(t, "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: Um caminho de referência de string para uma atividade associada a um endpoint do tipo arquivo no projeto atual que é um único arquivo no formato CSV
• target: Um caminho de referência de string para uma atividade de banco de dados associada a um endpoint de banco de dados no projeto atual
• mode: Um inteiro; um de 1(inserir acima), 2(inserir), ou 3 (atualizar)
• tablename: A tabela no banco de dados de destino
• columnNames: Uma lista delimitada por vírgulas de nomes de colunas
• columnKeynames: Uma lista delimitada por vírgulas de nomes de colunas que formam a chave de atualização. Obrigatório se o modo não for 2.

Parâmetros Opcionais¶

• skipLines: Número de linhas a ignorar 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¶

Pega 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 é usado quando apenas insere (mode=2) e pode ser omitido nesse caso.

Fonte e Alvo¶

A fonte usada nessa chamada de função deve ser definida como uma atividade associada a um endpoint do tipo arquivo no projeto atual. Isso inclui atividades configuradas de Compartilhamento de Arquivos, FTP, HTTP, Armazenamento Local e Armazenamento Temporário. O primeiro arquivo retornado dessa fonte será usado.

O alvo usado nesta chamada de função deve ser definido como uma atividade de banco de dados associada a um endpoint de banco de dados no projeto atual.

Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

// Using the file returned from the source
// "FTP Files", this example upserts (mode=1)
// into the table "MyTable" on the database
// target "myDatabase". "FTP Files" 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>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>",
    "<TAG>activity:database/Database Endpoint/database_insert/myDatabase</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: Um caminho de referência de string para uma conexão de banco 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 hexadecimal-string. Se não houver linhas retornadas para a consultar especificada, a função retornará nulo.

A variável global Jitterbit $jitterbit.scripting.db.rows_affected não é definido 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 usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

// Returns the first field of the first result
// from running the SQL query
result = DBLookup("<TAG>endpoint:database/My Database</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: Um caminho de referência de string para uma conexão de banco 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 retornados como uma matriz bidimensional de strings. Dados binários são retornados como sua representação hexadecimal de string. Se não houver linhas retornadas para a consultar especificada, a função retornará uma matriz vazia.

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

O banco de dados usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

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

Exemplos¶

// Returns the result from running the SQL query
result = DBLookupAll("<TAG>endpoint:database/My Database</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: Um caminho de referência de string para uma conexão de banco de dados no projeto atual

Descrição¶

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

O banco de dados usado nesta chamada de função deve ser definido como uma conexão de banco de dados no projeto atual. Para obter mais informações, consulte as instruções sobre como inserir endpoints em Endpoints seção em Jitterbit Script.

Exemplos¶

// Rolls back the current transaction
DBRollbackTransaction("<TAG>endpoint:database/My Database</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. Ver 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¶

// Sets the insert/update mode to "insert"
// for the current record
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¶

// Sets the insert/update mode to "update"
// for the current record
SetDBUpdate();

SQLEscape¶

Declaração¶

string SQLEscape(string unescapedSQL[, bool escapeBackslash])

Sintaxe¶

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

Parâmetros Obrigatórios¶

• unescapedSQL: Uma sequência de SQL que deve ser escapada

Parâmetros Opcionais¶

• escapeBackslash: Sinalizador booleano que indica se barras invertidas ("\") deve ser escapado por ser duplicado; o padrão é false

Descrição¶

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

Strings usadas como constantes de caracteres em uma instrução SQL usam uma aspa simples (') como um 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 (') com 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>endpoint:database/My Database</TAG>",
    "SELECT ORDER 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 é usada quando o destino contém tabelas que são vinculadas com 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 diferentes do Oracle, use a função <SQLIDENTITY> em vez de.

Exemplos¶

If <trans> as tags estão presentes, <SEQUENCE> deve ser colocado fora deles 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 é usada quando o alvo contém tabelas que são vinculadas com 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 de.

Exemplos¶

If <trans> as tags estão presentes, <SQLIDENTITY> deve ser colocado fora deles assim:

<trans>
</trans>
<SQLIDENTITY>

<UDF\>¶

Declaração¶

<UDF>string userDefinedFunction

Sintaxe¶

<UDF><userDefinedFunction>

Parâmetros obrigatórios¶

• userDefinedFunction: Uma string que define 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 <UDF> prefixo é retirado da expressão antes de ser passado adiante. Observe que a abertura e o fechamento <trans> tags podem ser usadas para indicar partes da chamada de 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>)