Funções de Instância¶
Essas funções destinam-se ao uso em mapeamentos de transformação (ou scripts chamados durante os mapeamentos), pois usam as instâncias de elementos de dados (origens e destinos) encontrados nos mapeamentos.
- Para obter detalhes sobre a sintaxe usada para descrever os caminhos de entidade dos elementos de dados, consulte a página Explicação da notação de caminho de entidade hierárquica.
- Para uso avançado das funções de instância, consulte as páginas sobre Mapeamento de instância.
Nota
O '#'
o símbolo, indicando uma instância, é inserido automaticamente em um caminho de elemento de dados quando um mapeamento que usa uma dessas funções é salvo. Como:
SumString(_Root$customer.contact#.Email, ",", true);
Uso avançado
As funções de instância podem, em geral, ser aninhadas umas dentro das outras. Como estão aninhados, os resultados subirão na hierarquia e abrangerão mais resultados. Essas funções podem retornar um único valor ou uma matriz de valores, dependendo do contexto em que são usadas.
Por exemplo: um Sum()
função que tem um Count()
dentro da função irá somar os resultados de cada invocação do Count()
função, e produzir um total:
Sum(Count(_Root$customer.sales#.items#.ID));
Count
¶
Declaração¶
int Count(type de)
int Count(array arr)
Sintaxe¶
Count(<de>)
Count(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Conta todas as instâncias de um elemento de dados em um determinado nível hierárquico em uma origem ou destino, onde esse elemento de dados contém um valor válido (e não é nulo).
A função retorna um número inteiro ou uma matriz de instâncias, dependendo do contexto em que é chamada.
Exemplos¶
Suponha que um banco de dados contenha um campo "Quantidade" em uma tabela "Itens" que seja filho de "POHeader" (uma ordem de compra) e que haja muitos itens dentro de um POHeader. Em seguida, esta instrução retorna o número de linhas de itens para um determinado POHeader que possui valores na coluna Quantity que não são nulos:
Count(POHeader.Items#.Quantity);
Nesse caso, suponha um arquivo de dados com várias instâncias nele, com clientes que tenham vendas que tenham itens; e cada item tem um campo ID. Esta declaração contará quantos itens diferentes há em cada venda e usará o Sum()
função para somar todos os itens devolvidos em cada venda; este será o número total de diferentes itens comprados:
Sum(Count(_Root$customer.sales#.items#.ID));
CountSourceRecords
¶
Declaração¶
int CountSourceRecords()
Sintaxe¶
CountSourceRecords()
Descrição¶
Retorna o número de instâncias de origem para um nó de destino, quando o nó de destino está se referindo a um pai de um campo de mapeamento.
Se o nó de destino não for um nó de loop, a função retorna 1. Consulte também o SourceInstanceCount
função.
Nota
O modo de streaming de uma transformação Flat-to-Flat não seria afetado pelo uso desta função, enquanto o modo de streaming seria desativado para uma transformação XML-to-Flat.
Exemplos¶
Suponha uma fonte com registros customer que tenham instâncias de sales com instâncias de items com um campo Type:
// This statement shows the instance count of a record compared
// to the total number of source records
"Record " + SourceInstanceCount() + " of " + CountSourceRecords();
Exist
¶
Declaração¶
bool Exist(type v, type de)
bool Exist(type v, array arr)
Sintaxe¶
Exist(<v>, <de>)
Exist(<v>, <arr>)
Parâmetros Necessários¶
v
: Um valor a ser encontradode:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos da matriz devem ser do mesmo tipo e ser do mesmo tipo quev
Descrição¶
Verifica a existência de um valor (v)
em instâncias de um elemento de dados (de)
ou uma matriz (arr
) e retorna verdadeiro (ou falso) dependendo se for encontrado.
A função retorna um booleano ou uma matriz de instâncias, dependendo do contexto em que é chamada.
Exemplos¶
Suponha uma fonte com registros customer que tenham instâncias de sales com instâncias de items com um campo Type:
// Returns if true if the value "subscription" is
// found in any instances of a field "customer.sales.items.Type"
// at the level of "sales":
Exist("subscription",_Root$customer.sales.items#.Type);
// To test this at the next highest level of the hierarchy,
// at the level of the customer,
// enclose this in a nested "Exist", testing for "true":
Exist(true, Exist("subscription",_Root$customer.sales#.items#.Type));
// The last statement answers, at the customer level, if a customer
// has any items in any sales with a Type field equal to "subscription"
FindByPos
¶
Declaração¶
type FindByPos(int pos, type de)
type FindByPos(int pos, array arr)
Sintaxe¶
FindByPos(<pos>, <de>)
FindByPos(<pos>, <arr>)
Parâmetros Necessários¶
pos
: O índice (de qual ocorrência; baseado em 1) para recuperar o valorde:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino; ouarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Retorna o valor de um elemento de dados de uma instância que ocorre várias vezes. Também pode ser usado para retornar um elemento de uma matriz, de maneira baseada em 1.
Se for especificado um número negativo para a ocorrência ou array, a contagem começará a partir da última linha ou elemento. Observe que o índice é baseado em 1.
Exemplos¶
// Assume a database has a child-parent relationship
// where for each parent the child occurs multiple times
// To retrieve the second child, use:
FindByPos(2, ParentTab.ChildTab#.Value$);
// To retrieve the last child, use:
FindByPos(-1, ParentTab.ChildTab#.Value$);
FindValue
¶
Declaração¶
type FindValue(type0 v, type1 de1, type2 de2)
Sintaxe¶
FindValue(<v>, <de1>, <de2>)
Parâmetros Necessários¶
v
: Um valor a ser pesquisadode1:
Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino, para ser usado como uma correspondênciade2:
Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino, a ser retornado se uma correspondência for encontrada
Descrição¶
Pesquisa várias instâncias de um elemento de dados (de1
) procurando o valor especificado em v
. Se a função encontrar o valor, ela retornará o valor no campo especificado no terceiro parâmetro (de2
) para essa instância encontrada. Se o valor não for encontrado, a função retornará null. Veja também o HasKey
função.
Exemplos¶
Esta instrução pesquisará as instâncias de B
sob A
e verifique o conteúdo de field1
. Ele selecionará a primeira instância de B
encontra onde field1
contém "ID
", e então retorne o valor de field2
dessa mesma instância:
FindValue("ID", A.B#.field1, A.B#.field2);
Essas instruções mostram como implementar um teste de uma matriz para inclusão de um valor. Ele procura um valor em uma matriz e retorna true se encontrado e false se não. É o array-equivalente ao dicionário HasKey
função. Observe que duas instâncias do mesmo array são passadas para a função:
arr = {1, 2, 3};
value = 1;
t = (FindValue(value, arr, arr) == value);
// t will be 1 (true)
value = 4;
t = (FindValue(value, arr, arr) == value);
// t will be 0 (false)
GetInstance
¶
Declaração¶
type GetInstance()
Sintaxe¶
GetInstance()
Descrição¶
Esta função retorna o elemento de dados da instância que foi definido chamando um SetInstances
função durante a geração do pai. Como alternativa a esta função, consulte o ArgumentList
função.
Exemplos¶
Suponha que um dos mapeamentos pai de uma transformação contenha estas instruções:
...
r1=DBLookupAll("<TAG>Sources/DB...</TAG>",
"SELECT key_name, key_value, key_type FROM key_values");
SetInstances("DETAILS", r1);
r2={"MS","HP"};
SetInstances("COMPANIES", r2);
...
No "DETAILS"
nó de destino, podemos criar uma condição de mapeamento usando:
<trans>
GetInstance()["key_value"] != "";
// Same as GetInstance()[0] != ""
</trans>
ou, em um dos atributos, o mapeamento pode conter:
<trans>
x=GetInstance();
x["key_name"] + "=" + x["key_value"];
// Same as x[0] + "=" + x[1]
</trans>
Em um dos atributos do "COMPANIES"
nó de destino, o mapeamento pode conter:
<trans>
GetInstance();
// This will return
// "MS" for the first instance
// "HP" for the second instance
</trans>
Max
¶
Declaração¶
type Max(type de)
type Max(array arr)
Sintaxe¶
Max(<de>)
Max(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Retorna o valor máximo de instâncias de um elemento de dados em um determinado nível na hierarquia de uma estrutura de dados. Ele verificará todas as instâncias naquele nível e retornará a maior. Também pode ser usado para retornar o valor máximo de uma matriz.
Exemplos¶
Suponha que um banco de dados contenha um campo "Quantity"
em uma mesa "Items"
isso é filho de "POHeader"
(uma ordem de compra) e que há muitos itens dentro de um POHeader. Em seguida, esta instrução retorna o valor máximo de Quantity para qualquer item para um determinado POHeader:
Max(POHeader.Items#.Quantity);
Min
¶
Declaração¶
type Min(type de)
type Min(array arr)
Sintaxe¶
Min(<de>)
Min(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Retorna o valor mínimo de instâncias de um elemento de dados em um determinado nível na hierarquia de uma estrutura de dados. Ele verificará todas as instâncias naquele nível e retornará a menor. Também pode ser usado para retornar o valor mínimo de uma matriz.
Exemplos¶
Suponha que um banco de dados contenha um campo "Quantity"
em uma mesa "Items"
isso é filho de "POHeader"
(uma ordem de compra) e que há muitos itens dentro de um POHeader. Em seguida, esta instrução retorna o valor mínimo de Quantity para qualquer item para um determinado POHeader:
Min(POHeader.Items#.Quantity);
ResolveOneOf
¶
Declaração¶
type ResolveOneOf(type de)
type ResolveOneOf(array arr)
Sintaxe¶
ResolveOneOf(<de>)
ResolveOneOf(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Retorna o primeiro valor não nulo de instâncias de um elemento de dados. Essa função geralmente é usada para recuperar o valor de um elemento de dados de origem "one-of". Também pode ser usado com arrays e retornará o primeiro elemento não nulo.
SetInstances
¶
Declaração¶
null SetInstances(string nodeName, array de)
Sintaxe¶
SetInstances(<nodeName>, <de>)
Parâmetros Necessários¶
nodeName
: O nome de um alvode:
Um caminho de entidade para instâncias de um elemento de dados no destino
Descrição¶
Define as instâncias de origem para um nó de loop de destino. Normalmente, uma instância de destino de loop é gerada a partir de uma instância de origem de loop. Às vezes, os dados podem vir de outras fontes. Esta função destina-se a casos em que os dados estão em vários conjuntos e cada conjunto gera um único elemento de destino.
A instância é um elemento de dados que pode ser um valor simples ou uma matriz de elementos de dados. Ao criar o destino, cada instância será usada para gerar uma instância de destino.
Para ver como usar um elemento de dados de instância, consulte o GetInstance
e ArgumentList
funções.
Esta função deve ser chamada nos mapeamentos do nó pai do destino pretendido. Se nenhum nó folha estiver disponível no pai, você poderá criar um nó de condição que chame essa função. A condição deve terminar com true
para que seja sempre aceito.
A função não deve ser chamada mais de uma vez com o mesmo nó de destino, pois a última chamada substitui as anteriores. Para evitar ser substituído, você pode criar várias pastas de mapeamento.
Um elemento de dados nulo é retornado dessa função e deve ser ignorado.
Exemplos¶
Assuma isso:
- Existe um pai comum para os nós de destino "DETALHES" e "EMPRESAS";
- Ambos são nós de loop; e
- Uma pasta de mapeamento múltiplo foi criada para o nó de destino "DETALHES".
...
r1 = DBLookupAll("<TAG>Sources/DB...</TAG>",
"SELECT key_name, key_value FROM key_values");
SetInstances("DETAILS", r1);
SetInstances("DETAILS#1", r1);
// DETAILS#1 is the name of the
// 1st multiple-mapping-folder for DETAILS
r2 = {"MS", "HP", "Apple"};
SetInstances("COMPANIES", r2);
// Note: Renaming the display name of a
// multiple-mapping-folder doesn't change
// the folder's actual name, which can be
// found by control-clicking the node and using
// "Copy node name to clipboard"
...
SortInstances
¶
Declaração¶
null SortInstances(string nodeName, array sourceDataElements1[, bool sortOrder, ..., array sourceDataElementsN, bool sortOrderN])
Sintaxe¶
SortInstances(<nodeName>, <sourceDataElements1>[, <sortOrder>, ..., <sourceDataElementsN>, <sortOrderN>])
Parâmetros Necessários¶
nodeName
: Nome dos elementos de loop de destino para classificarsourceDataElements:
Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
Parâmetros Opcionais¶
sourceDataElementsN:
Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinosortOrder
: Uma ordem de classificação opcional, padrão true para crescente. O argumento não é opcional se váriossourceDataElements
argumentos são fornecidos.
Descrição¶
Classifica a geração de elementos de dados de loop de destino com base em um ou mais elementos de dados na origem ou no destino.
Todas as instâncias de classificação devem ter o mesmo número de instâncias que o número de instâncias de destino.
Supõe-se que a ordem de classificação seja crescente e um argumento escalar opcional pode ser colocado ao lado de cada elemento de dados de classificação para substituir a ordem de classificação padrão. Se o sortOrder
for false, a ordem de classificação é decrescente.
Os elementos de dados do loop de destino serão classificados primeiro pelas instâncias dos primeiros elementos de dados de origem e, em seguida, classificados pelas instâncias dos segundos elementos de dados e assim por diante.
Esta função deve ser chamada nos mapeamentos do nó pai. Se não houver campo para mapear no nó pai, um script pode ser chamado com esta função ou uma condição adicionada para esse propósito.
Um valor nulo é retornado dessa função e deve ser ignorado.
Exemplos¶
// The target node "detail" will be ordered
// by "price" from high to low and,
// if the prices are the same for two items,
// the node will be ordered by "quantity" from low to high
SortInstances("detail", Invoice$Item#.price, false, Invoice$Item#.quantity);
Este próximo exemplo pode ser usado em uma condição em um mapeamento para classificar todas as vendas de cada cliente por data. Seria colocado ao nível do customer
nó. Observe a inclusão da declaração true
no final do bloco de código para que a condição seja sempre aceita:
<trans>
SortInstances("SalesOrders", _Root$customer.sales#.SalesDate);
true
</trans>
Sum
¶
Declaração¶
type Sum(type de)
type Sum(array arr)
Sintaxe¶
Sum(<de>)
Sum(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Toma o valor de cada instância de um elemento de dados em um determinado nível hierárquico e retorna a soma. O tipo de dados de ambos de
e arr
deve ser inteiro, longo, flutuante, duplo ou string. Os tipos de dados de todas as instâncias ou todos os elementos devem ser os mesmos.
Se a matriz estiver vazia, 0 (zero) é retornado. Embora valores nulos sejam ignorados em arrays com outro tipo de dados, um array com apenas nulos retornará um erro.
Exemplos¶
Suponha um banco de dados contendo um campo "Quantidade" em uma tabela "Itens" que seja filha de POHeader (existem muitos itens dentro de um POHeader).
// Returns the sum of the field "Quantity" for
// all items for a particular "POHeader"
Sum(POHeader.Items#.Quantity);
SumCSV
¶
Declaração¶
string SumCSV(type de)
string SumCSV(array arr)
Sintaxe¶
SumCSV(<de>)
SumCSV(<arr>)
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Descrição¶
Concatena cada instância de um campo de um elemento de dados ou cada elemento de uma matriz, com um delimitador de vírgula entre cada instância ou elemento.
Se o campo ou elemento de matriz contiver caracteres especiais, como avanços de linha ou vírgulas, o campo ou elemento de matriz será colocado entre aspas duplas. Nenhum delimitador é adicionado depois que a última instância ou elemento é concatenado.
Veja também o SumString
função para uma função semelhante, mas com opções adicionais.
Exemplos¶
// Concatenates all instances of a field of email addresses
// with a comma between each address
SumCSV(_Root$customer.contact#.Email);
SumString
¶
Declaração¶
string SumString(type de[, string delimiter, bool omitLast])
string SumString(array arr[, string delimiter, bool omitLast])
Sintaxe¶
SumString(<de>[, <delimiter>, <omitLast>])
SumString(<arr>[, <delimiter>, <omitLast>])
Parâmetros Necessários¶
de:
(Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destinoarr:
(Segunda forma) Uma matriz; todos os elementos do array devem ser do mesmo tipo
Parâmetros Opcionais¶
delimiter:
Uma string para delimitar os itens; o valor padrão é um ponto e vírgulaomitLast:
Um sinalizador indicando se deve incluir o delimitador após o último item; valor padrão é falso
Descrição¶
Concatena cada instância dos elementos de dados especificados ou cada elemento de uma matriz, com um delimitador anexado automaticamente ao final de cada string concatenada.
Se o parâmetro omitlast
for true, o delimitador após a última string será omitido.
Veja também o SumCSV
função.
Exemplos¶
// Concatenates all instances of a field of email addresses
// with a comma between each address,
// but does not place a delimiter after the last address
SumString(_Root$customer.contact#.Email, ",", true);