Saltar al contenido

Funciones de Instancia

Introducción

Estas funciones están diseñadas para usarse en asignaciones de transformación (o secuencias de comandos llamados durante las asignaciones), ya que utilizan las instancias de elementos de datos (fuentes y destinos) que se encuentran en las asignaciones.

Inserción de un Hash para Devolver una Matriz

En los casos en los que un parámetro de entrada requerido para una función de instancia es una matriz, un símbolo de almohadilla (#) se inserta automáticamente en la ruta de referencia de un elemento de datos para devolver una matriz de datos en lugar de un solo campo.

Por ejemplo:

SumString(_Root$customer.contact#.Email, ",", true);

En el ejemplo anterior, la ruta del elemento de datos (_Root$customer.contact#.Email) está construido para devolver una serie de direcciones de correo (.Email) dentro de una serie de contactos (.contact). El # se inserta antes de la matriz de direcciones de correo (#.Email) para indicar que en cada contacto podría haber una variedad de direcciones de correo. Esto da como resultado una asignación que recorre la matriz en los registros de contacto pero no recorre la matriz en los correos.

Para obtener una explicación más detallada de la sintaxis de las rutas de los elementos de datos, consulte Notación de ruta de referencia en Nodos y campos.

Uso Avanzado

Las funciones de instancia, en general, pueden anidarse unas dentro de otras. A medida que estén anidados, los resultados ascenderán en la jerarquía y abarcarán más resultados. Estas funciones pueden devolver un valor único o una matriz de valores, según el contexto en el que se utilizan.

Por ejemplo, un Sum función que tiene un Count la función interna sumará los resultados de cada invocación del Count función, y producir un total:

Sum(Count(_Root$customer.sales#.items#.ID));

Count

Declaración

int Count(type de)

int Count(array arr)

Sintaxis

Count(<de>)

Count(<arr>)

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Cuenta todas las instancias de un elemento de datos en un nivel jerárquico particular en un origen o destino, donde ese elemento de datos contiene un valor válido (y no es nulo).

La función devuelve un número entero o una matriz de instancias, según el contexto en el que se llama.

Ejemplos

Supongamos que una base de datos contiene un campo "Cantidad" en una tabla "Artículos" que es hijo de "POHeader" (una orden de compra) y que hay muchos artículos dentro de un POHeader. Luego, esta declaración devuelve el número de filas de elementos para un POHeader particular que tienen valores en la columna Cantidad que no son nulos:

Count(POHeader.Items#.Quantity);

En este caso, supongamos un archivo de datos con varias instancias, con clientes que tienen ventas que tienen artículos; y cada elemento tiene un campo ID. Esta declaración contará cuántos artículos diferentes hay en cada venta y utilizará el Sum función para sumar todos los artículos devueltos para cada venta; este será el número total de diferentes artículos comprados:

Sum(Count(_Root$customer.sales#.items#.ID));

CountSourceRecords

Declaración

int CountSourceRecords()

Sintaxis

CountSourceRecords()

Descripción

Devuelve el número de instancias de origen de un nodo de destino, cuando el nodo de destino hace referencia a un padre de un campo de asignación.

Si el nodo de destino no es un nodo de bucle, la función devuelve 1. Consulte también la SourceInstanceCount función.

Nota

El modo de transmisión de una transformación Flat-to-Flat no se vería afectado por el uso de esta función, mientras que el modo de transmisión se desactivaría para una transformación XML-to-Flat.

Ejemplos

Supongamos una fuente con registros de clientes que tienen instancias de ventas con instancias de artículos con un campo Tipo:

// This statement shows the instance count of a record compared
// to the total number of source records
"Record " + SourceInstanceCount() + " of " + CountSourceRecords();

Exist

Declaración

bool Exist(type v, type de)

bool Exist(type v, array arr)

Sintaxis

Exist(<v>, <de>)

Exist(<v>, <arr>)

Parámetros Requeridos

  • v: Un valor por encontrar
  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos de la matriz deben ser del mismo tipo y ser del mismo tipo que v

Descripción

Comprueba la existencia de un valor. (v) en casos de un elemento de datos (de) o una matriz (arr) y devuelve verdadero (o falso) dependiendo de si se encuentra.

La función devuelve un valor booleano o una matriz de instancias, según el contexto en el que se llama.

Ejemplos

Supongamos una fuente con registros de clientes que tienen instancias de ventas con instancias de artículos con un campo Tipo:

// 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

Declaración

type FindByPos(int pos, type de)

type FindByPos(int pos, array arr)

Sintaxis

FindByPos(<pos>, <de>)

FindByPos(<pos>, <arr>)

Parámetros Requeridos

  • pos: El índice (de qué ocurrencia; basado en 1) para recuperar el valor
  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o destino; o arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Devuelve el valor de un elemento de datos de una instancia que ocurre varias veces. También se puede utilizar para devolver un elemento de una matriz, basado en 1.

Si se especifica un número negativo para la ocurrencia o matriz, el conteo comenzará desde la última fila o elemento. Tenga en cuenta que el índice está basado en 1.

Ejemplos

// 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

Declaración

type FindValue(type0 v, type1 de1, type2 de2)

Sintaxis

FindValue(<v>, <de1>, <de2>)

Parámetros Requeridos

  • v: Un valor a buscar
  • de1: Una ruta de entidad a instancias de un elemento de datos en un origen o destino, que se utilizará como coincidencia
  • de2: Una ruta de entidad a instancias de un elemento de datos en un origen o destino, que se devolverá si se encuentra una coincidencia.

Descripción

Busca múltiples instancias de un elemento de datos (de1) buscando el valor especificado en v. Si la función encuentra el valor, devuelve el valor en el campo especificado en el tercer parámetro (de2) para esa instancia encontrada. Si no se encuentra el valor, la función devuelve nulo. Ver también el HasKey función.

Ejemplos

Esta declaración buscará las instancias de B bajo A y comprobar el contenido de field1. Seleccionará la primera instancia de B se encuentra donde field1 contiene "ID", y luego devolver el valor de field2 de esa misma instancia:

FindValue("ID", A.B#.field1, A.B#.field2);

Estas declaraciones muestran cómo desplegar una prueba de una matriz para la inclusión de un valor. Busca un valor en una matriz y devuelve verdadero si lo encuentra y falso si no. Es el array equivalente al diccionario. HasKey función. Tenga en cuenta que se pasan dos instancias de la misma matriz a la función:

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

Declaración

type GetInstance()

Sintaxis

GetInstance()

Descripción

Esta función devuelve el elemento de datos de instancia que se definió llamando a un SetInstances funcionar durante la generación del padre. Como alternativa a esta función, consulte la ArgumentList función.

Ejemplos

Supongamos que una de las asignaciones principales de una transformación contiene estas declaraciones:

...
r1=DBLookupAll("<TAG>endpoint:database/My Database</TAG>",
    "SELECT key_name, key_value, key_type FROM key_values");
SetInstances("DETAILS", r1);
r2={"MS","HP"};
SetInstances("COMPANIES", r2);
...

En el "DETAILS" nodo objetivo, podemos crear una condición de mapeo usando:

<trans>
GetInstance()["key_value"] != "";
// Same as GetInstance()[0] != ""
</trans>

o, en uno de los atributos, el mapeo puede contener:

<trans>
x=GetInstance();
x["key_name"] + "=" + x["key_value"];
// Same as x[0] + "=" + x[1]
</trans>

En uno de los atributos del "COMPANIES" nodo de destino, el mapeo puede contener:

<trans>
GetInstance();
// This will return
// "MS" for the first instance
// "HP" for the second instance
</trans>

Max

Declaración

type Max(type de)

type Max(array arr)

Sintaxis

Max(<de>)

Max(<arr>)

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Devuelve el valor máximo de instancias de un elemento de datos en un nivel particular en la jerarquía de una estructura de datos. Verificará todas las instancias en ese nivel y devolverá la más grande. También se puede utilizar para devolver el valor máximo de una matriz.

Ejemplos

Supongamos que una base de datos contiene un campo. "Quantity" en una mesa "Items" ese es un hijo de "POHeader" (una orden de compra), y que hay muchos artículos dentro de un POHeader. Luego, esta declaración devuelve el valor máximo de Cantidad para cualquier elemento para un POHeader particular:

Max(POHeader.Items#.Quantity);

Min

Declaración

type Min(type de)

type Min(array arr)

Sintaxis

Min(<de>)

Min(<arr>)

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Devuelve el valor mínimo de instancias de un elemento de datos en un nivel particular en la jerarquía de una estructura de datos. Verificará todas las instancias en ese nivel y devolverá la más pequeña. También se puede utilizar para devolver el valor mínimo de una matriz.

Ejemplos

Supongamos que una base de datos contiene un campo. "Quantity" en una mesa "Items" ese es un hijo de "POHeader" (una orden de compra), y que hay muchos artículos dentro de un POHeader. Luego, esta declaración devuelve el valor mínimo de Cantidad para cualquier elemento para un POHeader particular:

Min(POHeader.Items#.Quantity);

ResolveOneOf

Declaración

type ResolveOneOf(type de)

type ResolveOneOf(array arr)

Sintaxis

ResolveOneOf(<de>)

ResolveOneOf(<arr>)

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Devuelve el primer valor no nulo de instancias de un elemento de datos. Esta función se utiliza generalmente para recuperar el valor de un elemento de datos de origen "único". También se puede utilizar con matrices y devolverá el primer elemento no nulo.

SetInstances

Declaración

null SetInstances(string nodeName, array de)

Sintaxis

SetInstances(<nodeName>, <de>)

Parámetros Requeridos

  • nodeName: El nombre de un objetivo
  • de: Una ruta de entidad a instancias de un elemento de datos en el destino

Descripción

Define las instancias de origen para un nodo de bucle de destino. Normalmente, una instancia de destino del bucle se genera a partir de una instancia de origen del bucle. A veces los datos pueden provenir de otras fuentes. Esta función está destinada a casos en los que los datos se encuentran en varios conjuntos y cada conjunto genera un único elemento de destino.

La instancia es un elemento de datos que podría ser un valor simple o una matriz de elementos de datos. Al crear el objetivo, cada instancia se utilizará para generar una instancia de destino.

Para ver cómo utilizar un elemento de datos de instancia, consulte la GetInstance y ArgumentList funciones.

Esta función debe llamarse en las asignaciones del nodo principal del objetivo previsto. Si no hay ningún nodo hoja disponible en el padre, puede crear un nodo de condición que llame a esta función. La condición debe terminar con true para que siempre sea aceptado.

La función no debe llamarse más de una vez con el mismo nodo de destino, ya que la última llamada anula las anteriores. Para evitar ser anulado, puede crear varias carpetas de mapeo.

Esta función devuelve un elemento de datos nulo y debe ignorarse.

Ejemplos

Asumir que:

  • existe un padre común para los nodos de destino "DETALLES" y "EMPRESAS";
  • ambos son nodos de bucle; y
  • Se ha creado una carpeta de asignación múltiple para el nodo de destino "DETALLES".
...
r1 = DBLookupAll("<TAG>endpoint:database/My Database</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

Declaración

null SortInstances(string nodeName, array sourceDataElements1[, bool sortOrder, ..., array sourceDataElementsN, bool sortOrderN])

Sintaxis

SortInstances(<nodeName>, <sourceDataElements1>[, <sortOrder>, ..., <sourceDataElementsN>, <sortOrderN>])

Parámetros Requeridos

  • nodeName: Nombre de los elementos del bucle de destino a ordenar
  • sourceDataElements: Una ruta de entidad a instancias de un elemento de datos en un origen o un destino

Parámetros Opcionales

  • sourceDataElementsN: Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • sortOrder: Un orden de clasificación opcional, verdadero por defecto para ascendente. El argumento no es opcional si es múltiple sourceDataElements se proporcionan argumentos.

Descripción

Ordena la generación de elementos de datos del bucle de destino en función de uno o más elementos de datos en el origen o el destino.

Todas las instancias de clasificación deben tener la misma cantidad de instancias que la cantidad de instancias de destino.

Se supone que el orden de clasificación es ascendente y se puede colocar un argumento escalar opcional junto a cada elemento de datos de clasificación para anular el orden de clasificación predeterminado. Si el sortOrder es falso, el orden de clasificación es descendente.

Los elementos de datos del bucle de destino se ordenarán primero por las instancias de los primeros elementos de datos de origen y luego por las instancias de los segundos elementos de datos, y así sucesivamente.

Esta función debe llamarse en las asignaciones del nodo principal. Si no hay ningún campo para asignar en el nodo principal, se puede llamar a un secuencia de comandos con esta función o agregar una condición para ese propósito.

Esta función devuelve un valor nulo y debe ignorarse.

Ejemplos

// 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);

El siguiente ejemplo podría usarse en una condición en un mapeo para ordenar todas las ventas de cada cliente por fecha. Se colocaría al nivel del customer nodo. Tenga en cuenta la inclusión de la declaración true al final del bloque de código para que siempre se acepte la condición:

<trans>
SortInstances("SalesOrders", _Root$customer.sales#.SalesDate);
true
</trans>

Sum

Declaración

type Sum(type de)

type Sum(array arr)

Sintaxis

Sum(<de>)

Sum(<arr>)

Parámetros requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Toma el valor de cada instancia de un elemento de datos en un nivel jerárquico particular y devuelve la suma. El tipo de datos de ambos. de y arr debe ser uno de tipo entero, largo, flotante, doble o cadena. Los tipos de datos de todas las instancias o todos los elementos deben ser los mismos.

Si la matriz está vacía, se devuelve 0 (cero). Aunque los valores nulos se ignorarán en matrices con otro tipo de datos, una matriz con solo valores nulos devolverá un error.

Ejemplos

Supongamos una base de datos que contiene un campo "Cantidad" en una tabla "Elementos" que es secundaria de POHeader (hay muchos elementos dentro de un POHeader).

// Returns the sum of the field "Quantity" for
// all items for a particular "POHeader"
Sum(POHeader.Items#.Quantity);

SumCSV

Declaración

string SumCSV(type de)

string SumCSV(array arr)

Sintaxis

SumCSV(<de>)

SumCSV(<arr>)

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Descripción

Concatena cada instancia de un campo de un elemento de datos o cada elemento de una matriz, con un delimitador de coma entre cada instancia o elemento.

Si el campo o elemento de matriz contiene caracteres especiales como saltos de línea o comas, el campo o elemento de matriz se incluye entre comillas dobles. No se agrega ningún delimitador después de concatenar la última instancia o elemento.

Ver también el SumString función para una función similar pero con opciones adicionales.

Ejemplos

// Concatenates all instances of a field of email addresses
// with a comma between each address
SumCSV(_Root$customer.contact#.Email);

SumString

Declaración

string SumString(type de[, string delimiter, bool omitLast])

string SumString(array arr[, string delimiter, bool omitLast])

Sintaxis

SumString(<de>[, <delimiter>, <omitLast>])

SumString(<arr>[, <delimiter>, <omitLast>])

Parámetros Requeridos

  • de: (Primera forma) Una ruta de entidad a instancias de un elemento de datos en un origen o un destino
  • arr: (Segunda forma) Una matriz; todos los elementos del array deben ser del mismo tipo

Parámetros Opcionales

  • delimiter: Una cadena para delimitar los elementos; el valor predeterminado es un punto y coma
  • omitLast: Una bandera que indica si se debe incluir el delimitador después del último elemento; el valor predeterminado es falso

Descripción

Concatena cada instancia de los elementos de datos especificados o cada elemento de una matriz, con un delimitador agregado automáticamente al final de cada cadena concatenada.

Si el parámetro omitlast es verdadero, se omite el delimitador después de la última cadena.

Ver también el SumCSV función.

Ejemplos

// 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);