Función escalar OVERLAY

La función OVERLAY devuelve una serie en la que, a partir de inicio en la serie-fuente, se ha suprimido la longitud de las unidades de código especificadas y se ha insertado una serie-inserción.

Leer el esquema de sintaxisOmitir el esquema de sintaxis visualOVERLAY(serie-origen PLACINGserie-inserciónFROMinicioFORlongitudUSINGCODEUNITS16CODEUNITS32OCTETS,serie-inserción,inicio,longitud,CODEUNITS16CODEUNITS32OCTETS )

El esquema es SYSIBM.

serie-fuente
Expresión que especifica la serie fuente. La expresión debe devolver un valor que sea de un tipo de datos de serie incorporada, numérico, booleano o de fecha y hora. Si el valor no es un tipo de datos de serie, se convierte implícitamente a VARCHAR antes de evaluar la función.
serie-inserción
Expresión que especifica la serie que se debe insertar en serie-fuente, a partir de la posición identificada por inicio. La expresión debe devolver un valor que sea de un tipo de datos de serie incorporada, numérico, booleano o de fecha y hora. Si el valor no es un tipo de datos de serie, se convierte implícitamente a VARCHAR antes de evaluar la función. Si la página de códigos de la serie-inserción difiere de la página de códigos de la serie-fuente, serie-inserción se convierte a la página de códigos de la serie-fuente.
inicio
Expresión que devuelve un valor entero. El valor de número entero especifica el punto de inicio dentro de la serie de origen en donde la eliminación y la inserción de otra serie va a comenzar. La expresión debe devolver un valor que sea un tipo de datos incorporado numérico, CHAR, VARCHAR, GRAPHIC o VARGRAPHIC. Si el valor no es del tipo INTEGER, se convierte de forma implícita en INTEGER antes de evaluar la función. El valor del número entero es el punto de inicio en las unidades de código mediante el uso de las unidades de serie especificadas. El valor de número entero debe estar entre 1 y la longitud real de origen-serie en las unidades de serie especificada más uno (SQLSTATE 42815). Si se especifica OCTETS y el resultado son datos gráficos, el valor debe ser un número impar entre 1 y la longitud de octetos real de fuente-serie más uno (SQLSTATE 428GC o 22011).
longitud
Expresión que especifica el número de unidades de código (en las unidades de serie especificadas) que se deben suprimir de la serie fuente, a partir de la posición identificada por inicio. La expresión debe devolver un valor que sea un tipo de datos incorporado numérico, CHAR, VARCHAR, GRAPHIC o VARGRAPHIC. Si el valor no es del tipo INTEGER, se convierte de forma implícita en INTEGER antes de evaluar la función. El valor debe ser un entero positivo o cero (SQLSTATE 22011). Si se especifica OCTETS y el resultado son datos gráficos, el valor tiene que ser un número par o cero (SQLSTATE 428GC).

El hecho de no especificar longitud equivale a especificar un valor de 1, excepto cuando se especifica OCTETS y el resultado son datos gráficos, en cuyo caso el hecho de no especificar longitud equivale a especificar un valor de 2.

CODEUNITS16, CODEUNITS32 u OCTETS
Especifica la unidad de la serie de inicio y longitud.

CODEUNITS16 especifica que inicio y longitud se expresan en unidades de código UTF-16 de 16 bits. CODEUNITS32 especifica que inicio y longitud se expresan en unidades de código UTF-32 de 32 bits. OCTETS especifica que inicio y longitud se expresan en bytes.

Si la unidad de serie se especifica como CODEUNITS16 o CODEUNITS32 y el resultado es una serie binaria o una serie FOR BIT DATA, se devuelve un error (SQLSTATE 428GC). Si la unidad de serie se especifica como CODEUNITS16 o OCTETS, y las unidades de serie de fuente-serie es CODEUNITS32, se devuelve un error (SQLSTATE 428GC). Si la unidad de serie se especifica como OCTETS, la operación se realiza en la página de códigos de la serie-fuente.

Si no se especifica un argumento de unidades de serie y serie-fuente y serie-inserción son una serie de caracteres que no es FOR BIT DATA o es una serie gráfica, el valor predeterminado es CODEUNITS32. De lo contrario, el valor predeterminado es OCTETS.

Para obtener más información sobre CODEUNITS16, CODEUNITS32 y OCTETS, consulte el apartado Unidades de serie en funciones incorporadas en Series de caracteres.

El tipo de datos del resultado depende de los tipos de datos de serie-fuente y serie-inserción, como se muestra en las tablas siguientes de combinaciones de tipos soportadas. La unidad de serie del resultado es la unidad de serie de fuente-serie. Si origen-serie o insertar-serie se define como FOR BIT DATA el otro argumento no se puede definir con unidades de serie de CODEUNITS32. La segunda tabla aplica solamente a bases de datos Unicode.

Tabla 1. Tipo de datos del resultado como función de los tipos de datos de serie-fuente y serie-inserción
serie-fuente serie-inserción Resultado
CHAR o VARCHAR CHAR o VARCHAR VARCHAR
GRAPHIC o VARGRAPHIC GRAPHIC o VARGRAPHIC VARGRAPHIC
CLOB CHAR, VARCHAR o CLOB CLOB
CHAR o VARCHAR CLOB CLOB
DBCLOB GRAPHIC, VARGRAPHIC o DBCLOB DBCLOB
GRAPHIC o VARGRAPHIC DBCLOB DBCLOB
CHAR o VARCHAR CHAR FOR BIT DATA o VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
CHAR FOR BIT DATA o VARCHAR FOR BIT DATA CHAR, VARCHAR, CHAR FOR BIT DATA o VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
BINARY o VARBINARY BINARY o VARBINARY VARBINARY
BLOB BLOB BLOB
BINARY o VARBINARY BLOB BLOB
Nota: Si los tipos de datos para serie-fuente y serie-inserción son una combinación de serie binaria y serie FOR BIT DATA, el argumento que no es un tipo de datos binario se gestiona como si fuera a convertirse en el tipo de datos binario correspondiente.
Tabla 2. Tipo de datos del resultado como función de los tipos de datos de serie-fuente y serie-inserción (bases de datos Unicode únicamente)
serie-fuente serie-inserción Resultado
CHAR o VARCHAR GRAPHIC o VARGRAPHIC VARCHAR
GRAPHIC o VARGRAPHIC CHAR o VARCHAR VARGRAPHIC
CLOB GRAPHIC, VARGRAPHIC o DBCLOB CLOB
DBCLOB CHAR, VARCHAR o CLOB DBCLOB

Una serie-fuente puede tener una longitud de 0; en este caso, inicio debe ser 1 (como lo implican los vínculos que se indican en la descripción de inicio) y el resultado de la función es una copia de la serie-inserción.

Una serie-inserción también puede tener una longitud de 0. Esto tiene el efecto de suprimir las unidades de código identificadas en inicio y longitud de la serie-fuente.

El atributo de longitud del resultado es el atributo de longitud de fuente-serie más el atributo de longitud de insertar-serie cuando las unidades de serie de la fuente-serie y insertar-serie son las mismas o las unidades de la serie del resultado son CODEUNITS32. En la siguiente tabla se mencionan casos especiales.
Tabla 3. Tipo de datos del resultado como una función de los tipos de datos de origen-serie y insertar-serie (casos especiales, solo en bases de datos Unicode)
serie-fuente serie-inserción Resultado
Tipo de datos unidades de serie Tipo de datos unidades de serie atributo de longitud unidades de serie
Serie de caracteres con atributo de longitud A OCTETS serie gráfica con atributo de longitud B CODEUNITS16 A+3*B OCTETS
      CODEUNITS32 A+4*B  
    carácter con atributo de longitud B CODEUNITS32 A+4*B  
serie gráfica con atributo de longitud A CODEUNITS16 carácter con atributo de longitud B OCTETS A+B CODEUNITS16
      CODEUNITS32 A+2*B  
    serie gráfica con atributo de longitud B CODEUNITS32 A+2*B  
La longitud real del resultado depende de la longitud real de la serie-fuente, la longitud real de la serie eliminada, la longitud real de serie-inserción y las unidades de serie utilizadas para los argumentos iniciar y longitud. Por ejemplo, si los argumentos de serie son series de caracteres en OCTETS y se utiliza OCTETS como el cuarto argumento, la longitud real del resultado es A1 - MIN((A1 - V2 + 1), V3) + A4, donde:
  • A1 es la longitud real de serie-fuente
  • V2 es el valor de inicio
  • V3 es el valor de longitud
  • A4 es la longitud real de serie-inserción
Si la longitud real de la serie de resultado excede el máximo del tipo de datos de retorno, se devuelve un error (SQLSTATE 54006).

Si cualquiera de los argumentos puede ser nulo, el resultado puede ser nulo; si alguno de los argumentos es nulo, el resultado es el valor NULL.

Ejemplos

  • Ejemplo 1: crear las series 'INSISTING', 'INSISERTING' e 'INSTING' a partir de la serie 'INSERTING' insertando texto en medio del texto existente.
       SELECT OVERLAY('INSERTING','IS',4,2,OCTETS),
     OVERLAY('INSERTING','IS',4,0,OCTETS),
     OVERLAY('INSERTING','',4,2,OCTETS)
     FROM SYSIBM.SYSDUMMY1
  • Ejemplo 2: crear las series 'XXINSERTING', 'XXNSERTING', 'XXSERTING' y 'XXERTING' a partir de la serie 'INSERTING' insertando texto antes del texto existente, utilizando 1 como punto de partida.
       SELECT OVERLAY('INSERTING','XX',1,0,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,1,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,2,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,3,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1
  • Ejemplo 3: crear la serie 'ABCABCXX' a partir de la serie 'ABCABC' insertando texto después del texto existente. Dado que la serie fuente tiene una longitud de 6 caracteres, establezca la posición inicial en 7 (uno más la longitud de la serie fuente).
       SELECT OVERLAY('ABCABC','XX',7,0,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1
  • Ejemplo 4: Cambie la serie 'Hegelstraße' a 'Hegelstrasse'.
       SELECT OVERLAY('Hegelstraße','ss',10,1,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1
  • Ejemplo 5: el ejemplo siguiente funciona con la serie Unicode '&N~AB', siendo '&' el carácter de clave G de símbolo musical y '~' el carácter de tilde de combinación. En el ejemplo siguiente se muestra esta serie en distintos formatos de codificación Unicode:
      '&' 'N' '~' 'A' 'B'
    UTF-8 X'F09D849E' X'4E' X'CC83' X'41' X'42'
    UTF-16BE X'D834DD1E' X'004E' X'0303' X'0041' X'0042'
    Supongamos que las variables UTF8_VAR y UTF16_VAR contienen las representaciones de la serie en UTF-8 y UTF-16BE respectivamente. Utilice la función OVERLAY para insertar una 'C' en la serie Unicode '&N~AB'.
       SELECT OVERLAY(UTF8_VAR, 'C', 1, CODEUNITS16),
     OVERLAY(UTF8_VAR, 'C', 1, CODEUNITS32),
     OVERLAY(UTF8_VAR, 'C', 1, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores 'C?N~AB', 'CN~AB' y 'CbbbN~AB', respectivamente, donde '?' representa X'EDB49E', que corresponde a X'DD1E' en el formato UTF-16 intermedio, y 'bbb' sustituye los caracteres UTF-8 incompletos X'9D849E'.
       SELECT OVERLAY(UTF8_VAR, 'C', 5, CODEUNITS16),
     OVERLAY(UTF8_VAR, 'C', 5, CODEUNITS32),
     OVERLAY(UTF8_VAR, 'C', 5, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores '&N~CB', '&N~AC' y '&N~AB', respectivamente.
       SELECT OVERLAY(UTF16_VAR, 'C', 1, CODEUNITS16),
     OVERLAY(UTF16_VAR, 'C', 1, CODEUNITS32)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores 'C?N~AB' y 'CN~AB', respectivamente, donde '?' representa el carácter de sustitución bajo no coincidente U+DD1E.
       SELECT OVERLAY(UTF16_VAR, 'C', 5, CODEUNITS16),
     OVERLAY(UTF16_VAR, 'C', 5, CODEUNITS32)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores '&N~CB' y '&N~AC', respectivamente.