Funções de banco de dados no Jitterbit Studio
As funções de banco de dados fornecem acesso a interações 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 referência de caminho de string para uma conexão de Banco de Dados no projeto atualsql: O comando SQL a ser executado no banco de dados
Descrição
Esta função é igual a DBLookup, exceto que a primeira consulta armazena as informações em cache e as consultas subsequentes usam este cache em vez de consultar repetidamente o banco de dados. O cache é válido durante a cadeia de operações em que é chamado.
Se nenhuma linha for retornada para a consulta especificada em sql, a função retorna null.
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 conexão de Banco de Dados no projeto atual. Para mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Uma alternativa ao cache é usar as funções Set e Get.
Nota
Os endpoints criados com esta função são incluídos no relatório de uso de endpoints e contam para sua licença.
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: Uma referência de caminho de string para uma conexão de Banco de Dados no projeto atualspName: O procedimento armazenado a ser executado no servidor de banco de dadosresultSet: Uma variável global para manter o conjunto de resultados retornado pelo servidor de banco de dados, se aplicável. (Consulte as notas abaixo).
Parâmetros opcionais
inputOutputVariable: Um parâmetro de entrada ou saída a ser passado para o procedimento armazenado; estes 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 de Banco de Dados 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 usar um driver ODBC, este argumento é ignorado.
Para casos de uso não cobertos pela função CallStoredProcedure, use a função DBExecute.
Nota
Com bancos de dados Microsoft SQL Server, esta função chama procedimentos armazenados apenas no schema padrão do proprietário do banco de dados (dbo). Para chamar procedimentos armazenados em outros schemas, use a função DBExecute.
Cuidado
O parâmetro resultSet é suportado apenas por drivers de banco de dados JDBC no momento. Se usar ODBC, o resultSet sempre retornará null.
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 conterá 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 mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Para solução de problemas, consulte CallStoredProcedure: resultSet sempre null com drivers ODBC e CallStoredProcedure: "Stored proc or function could not be found" com PostgreSQL JDBC no guia de solução de problemas de operação.
Nota
Os endpoints criados com esta função estão incluídos em relatório de uso de endpoints e contam para sua licença.
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
Usar tipos de objeto e registro Oracle
O Jitterbit suporta tipos de objeto Oracle para trabalhar com bancos de dados Oracle ao usar o driver Oracle JDBC. Os tipos de objeto Oracle são semelhantes aos tipos de registro Oracle, que não são suportados no Jitterbit devido à falta de suporte do Oracle.
Aviso
Para usar tipos de objeto Oracle, você deve usar o driver Oracle JDBC. O driver Oracle ODBC não suporta tipos de objeto Oracle nem tipos de registro Oracle.
Para acessar tipos de registro Oracle usando o driver Oracle JDBC, você pode criar um procedimento armazenado "wrapper" no seu banco de dados Oracle que possa acessar e converter um tipo de registro Oracle. Em seguida, use a função CallStoredProcedure no Jitterbit para chamar o procedimento wrapper e fazer com que ele execute a conversão de e para um tipo de objeto Oracle.
Dica
Mais informações sobre as diferenças entre os tipos de registro Oracle e tipos de objeto Oracle podem ser encontradas na documentação do Oracle. Consulte Record Variable Declaration e Using PL/SQL With Object Types da documentação do Oracle Database Release 18 para mais informações.
O exemplo a seguir descreve como você pode usar objetos Oracle em uma função CallStoredProcedure 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 do exemplo
Etapa 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
);
Etapa 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;
Etapa 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;
Etapa 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 forma similar.
<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>
Nota
No exemplo, a função processcustomer no Oracle espera dois parâmetros: o objeto personalizado (example_customer_details) e um VARCHAR (new_account_number). No exemplo acima, o dicionário $cust representa o objeto personalizado, e NA0233 representa o VARCHAR.
Cuidado
Na saída, os nomes das propriedades do tipo de dados são sensíveis a maiúsculas e minúsculas e, portanto, estão em maiúsculas. Para objetos de entrada, os nomes das propriedades não são sensíveis a maiúsculas e minúsculas.
DBCloseConnection
Declaração
void DBCloseConnection(string databaseId)
Sintaxe
DBCloseConnection(<databaseId>)
Parâmetros obrigatórios
databaseId: Uma referência de caminho 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 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 mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
Exemplos
// Fechando uma conexão de Banco de Dados
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: Uma referência de caminho de string para uma conexão de Banco de Dados no projeto atualsql: O comando SQL a ser executado no banco de dadosoutputVariable: (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 formas de recuperar os dados:
-
Se você especificar apenas os dois parâmetros obrigatórios (primeira forma), a função retornará o conjunto de registros completo como um array de linhas.
Você pode então usar um loop
While()para iterar sobre as linhas e usarGet()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 sã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 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 retornado 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 em string hexadecimal.
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 mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
Variáveis Jitterbit Relacionadas
- Se este método for concluído com sucesso,
$jitterbit.scripting.db.rows_affectedconterá o número de linhas afetadas pela consulta. - Se usar um driver JDBC para conectar a um banco de dados, defina
jitterbit.scripting.db.search.rowsetcomotrueantes da função para fazer com que qualquer chamada a um procedimento armazenado que retorna 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=falsee$jitterbit.scripting.db.transaction=trueem um script antes da chamada. A transação será confirmada ao final de uma transformação bem-sucedida. Definir ambas as variáveis (auto_commitetransaction) comotrueresultará em um erro. - Defina
$jitterbit.scripting.db.max_rowspara limitar o número de registros a retornar. O padrão é 10.000 linhas.
Para solução de problemas, consulte DBExecute: Erro quando auto_commit e transaction são ambos true no guia de solução de problemas de operação, e Banco de Dados (JDBC): DBLookup ou DBExecute falha com erro de decodificação Base64 e Banco de Dados: DBLookup ou DBExecute falha com "Nenhum driver adequado encontrado" ao testar um script no guia de solução de problemas de conector.
Exemplos
Exemplo 1: Executar e recuperar valores em um array
// 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
Exemplo 4: Executar um procedimento armazenado
// An alternative to the CallStoredProcedure function.
// Configurable procedure definition as a variable:
$sql = "BEGIN
MyStoredProcedure;
END;";
DBExecute("<TAG>Sources/myDBTarget</TAG>", $sql);
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 referência de caminho de string para uma atividade associada a um endpoint do tipo arquivo no projeto atual que é um único arquivo em formato CSVtarget: Uma referência de caminho de string para uma atividade de Banco de Dados associada a um endpoint de Banco de Dados no projeto atualmode: Um inteiro; um de1(upsert),2(insert) ou3(update)tablename: A tabela no banco de dados de destinocolumnNames: Uma lista de nomes de colunas separados por vírgulacolumnKeynames: Uma lista de nomes de colunas separados por vírgula que formam a chave de atualização. Obrigatório se o modo não for2.
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 OracledatetimeFormat: Especifica o formato dos campos de data e hora, como "TimeStamp" em bancos de dados Oracle
Descrição
Utiliza uma origem (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 apenas inserir (mode=2) e pode ser omitido nesse caso.
Origem e destino
A origem utilizada nesta chamada de função deve ser definida como uma atividade associada a um endpoint do tipo arquivo no projeto atual. Isso inclui atividades de Compartilhamento de Arquivos, FTP, HTTP, Armazenamento Local e Armazenamento Temporário configuradas. O primeiro arquivo retornado dessa origem será utilizado.
O destino utilizado 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 mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Para solução de problemas, consulte DBLoad: Requer um driver de banco de dados JDBC no guia de solução de problemas de operações.
Aviso
A função DBLoad() funciona apenas em atividades de Banco de Dados associadas a um endpoint de Banco de Dados que utiliza um driver JDBC.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
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: Uma referência de caminho de string para uma conexão de Banco de Dados no projeto atualsql: 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 nenhuma linha for retornada 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, quando você deseja recuperar mais de um valor ou linha, utilize as funções DBLookupAll ou DBExecute.
Para solução de problemas, consulte Banco de Dados (JDBC): DBLookup ou DBExecute falha com erro de decodificação Base64 e Banco de Dados: DBLookup ou DBExecute falha com "Nenhum driver adequado encontrado" ao testar um script no guia de solução de problemas de conectores.
ID do banco de dados
O banco de dados utilizado nesta chamada de função deve ser definido como uma conexão de Banco de Dados no projeto atual. Para mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
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: Uma referência de caminho de string para uma conexão de Banco de Dados no projeto atualsql: 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 sempre são retornados como um array bidimensional de strings. Dados binários são retornados como sua representação em string hexadecimal. Se nenhuma linha for retornada 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 usado nesta chamada de função deve ser definido como uma conexão de Banco de Dados no projeto atual. Para mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Para consultas mais avançadas, quando você deseja recuperar diretamente em variáveis globais, use a função DBExecute.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
Exemplos
// Retorna o resultado da execução da consulta SQL
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: Uma referência de caminho 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 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 mais informações, consulte as instruções sobre inserção de endpoints na seção Endpoints em Jitterbit Script.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
Exemplos
// Reverte a transação atual
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. Consulte DBLoad para obter detalhes.
Nota
Os endpoints criados com esta função estão incluídos no relatório de uso de endpoints e contam para sua licença.
SetDBInsert
Declaração
void SetDBInsert()
Sintaxe
SetDBInsert()
Descrição
Substitui a configuração atual do modo inserir/atualizar para "inserir" no registro atual. O valor retornado é nulo.
Exemplos
// Define o modo inserir/atualizar como "inserir"
// para o registro atual
SetDBInsert();
SetDBUpdate
Declaração
void SetDBUpdate()
Sintaxe
SetDBUpdate()
Descrição
Substitui a configuração atual do modo inserir/atualizar para "atualizar" no registro atual. O valor retornado é nulo.
Exemplos
// Define o modo inserir/atualizar 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 SQL a ser escapada
Parâmetros opcionais
escapeBackslash: Sinalizador booleano 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 caracteres em uma instrução SQL usam uma aspas 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 aspas simples (') por duas aspas simples (''). Se 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 para ser tratado como não mapeado, removendo-o da saída. O valor retornado é nulo.
Mapear um valor de origem null não é o mesmo que chamar Unmap: um valor null ainda é gravado no campo de saída, enquanto Unmap omite o campo inteiramente. Use Unmap quando o campo em si deve estar ausente da saída, não apenas vazio.
Esta função tem efeito apenas quando é retornada diretamente da expressão de mapeamento do próprio campo de destino. Chamar Unmap de dentro de um script invocado por RunScript não tem efeito no campo, pois RunScript retorna o resultado do script chamado como uma string em vez de propagar o sinal de desmapeamento de volta para o mapeamento. Com agentes versão 12.9 e posterior, uma chamada RunScript anterior na expressão de mapeamento do próprio campo de destino não tem essa limitação. Em versões anteriores do agente, Unmap retorna null em vez de desmapar o campo neste caso.
O comportamento varia por tipo de destino:
- JSON e XML: O campo ou elemento é omitido inteiramente. Se todos os campos de um objeto JSON forem desmapeados, o objeto permanece na saída como um
{}vazio em vez de ser removido. - CSV: A coluna não é removida; o campo é gravado como um valor vazio em vez disso, pois uma linha CSV não pode omitir uma coluna posicional.
- XSD, ZIP e outros destinos XML definidos por esquema: O elemento é omitido. Se todos os filhos de um elemento pai forem desmapeados, o elemento pai também será omitido (um elemento raiz com todos os campos desmapeados se torna auto-fechado), e isso se propaga através de níveis aninhados de um esquema hierárquico.
- Banco de dados: O campo é excluído da instrução
INSERTgerada.
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 a tabela de destino contém tabelas vinculadas por uma relação de chave primária/chave estrangeira. Nesse caso, mapeie para as chaves primárias geradas pelo banco de dados Oracle.
Para bancos de dados diferentes do Oracle, use a função <SQLIDENTITY> em seu lugar.
Nota
Na sintaxe desta função, os símbolos menor que ("<") e maior que (">") fazem parte da sintaxe da função.
Exemplos
Se tags <trans> estiverem presentes, <SEQUENCE> deve ser colocada fora delas desta forma:
<trans>
</trans>
<SEQUENCE>
<SQLIDENTITY\>
Declaração
<SQLIDENTITY>
Sintaxe
<SQLIDENTITY>
Descrição
Para uso em mapeamentos com bancos de dados que não são Oracle, esta função é utilizada quando a tabela de destino contém tabelas vinculadas por uma relação de chave primária/chave estrangeira. Nesse caso, mapeie para as chaves primárias 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 seu lugar.
Nota
Na sintaxe desta função, os símbolos menor que ("<") e maior que (">") fazem parte da sintaxe da função.
Exemplos
Se tags <trans> estiverem presentes, <SQLIDENTITY> deve ser colocada fora delas desta forma:
<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 prefixo <UDF> é removido da expressão antes de ser passado adiante. Observe que tags de abertura e fechamento <trans> podem ser usadas para indicar partes da chamada de função que devem ser avaliadas pelo Jitterbit antes da expressão ser passada para um banco de dados.
Nota
Na sintaxe desta função, os símbolos menor que ("<") e maior que (">") ao redor de <UDF> fazem parte da sintaxe da função.
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>)