Función escalar INSERT

La función INSERT devuelve una secuencia en la que, a partir de inicio en fuente-secuencia, longitud de las unidades de código especificadas se han eliminado y se ha introducido insertar-secuencia.

El esquema es SYSIBM. La versión SYSFUN de la función INSERT continúa estando disponible.

La función INSERT es idéntica a la función OVERLAY, excepto en que el argumento de longitud es obligatorio.

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.

inicio

Expresión que devuelve un valor entero. El valor entero especifica el punto de partida en la serie fuente donde debe empezar la supresión de unidades de código y la inserción de otra serie. 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 fuente-serie en las unidades de serie implícitas o explícitas más uno (SQLSTATE 22001). 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).

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.

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 datos de bit, 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 una unidad de serie no se especifica de forma explícita, la unidad de serie de la fuente-serie determina la unidad que se utiliza. Para obtener más información sobre CODEUNITS16, CODEUNITS32, y OCTETS, consulte Unidades de serie en las funciones integradas 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 la fuente-serie o insertar-serie se define como FOR BIT DATA el otro argumento no se puede definir con las unidades de serie de CODEUNITS32.La segunda tabla aplica solamente a las 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	BINARY, VARBINARY o BLOB	BLOB
BINARY o VARBINARY	BLOB	BLOB

Nota: Si serie-origen o serie-inserción es un tipo de datos binario y el otro es una 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 para inicio descritos anteriormente) 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 `fuente-serie` y `insertar-serie` (casos especiales)
`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
Serie de caracteres con atributo de longitud A	OCTETS	serie gráfica con atributo de longitud B	CODEUNITS32	A+4*B	OCTETS
Serie de caracteres con atributo de longitud A	OCTETS	carácter con atributo de longitud B	CODEUNITS32	A+4*B	OCTETS
serie gráfica con atributo de longitud A	CODEUNITS16	carácter con atributo de longitud B	OCTETS	A+B	CODEUNITS16
serie gráfica con atributo de longitud A	CODEUNITS16	carácter con atributo de longitud B	CODEUNITS32	A+2*B	CODEUNITS16
serie gráfica con atributo de longitud A	CODEUNITS16	serie gráfica con atributo de longitud B	CODEUNITS32	A+2*B	CODEUNITS16

La longitud real del resultado depende de la longitud real de la fuente-serie, la longitud real de la serie eliminada, la longitud real de insertar-serie 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 y INSTING a partir de la serie INSERTING insertando texto en la mitad del texto existente.

   SELECT INSERT('INSERTING',4,2,'IS'),
     INSERT('INSERTING',4,0,'IS'),
     INSERT('INSERTING',4,2,'')
     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 INSERT('INSERTING',1,0,'XX'),
     INSERT('INSERTING',1,1,'XX'),
     INSERT('INSERTING',1,2,'XX'),
     INSERT('INSERTING',1,3,'XX')
     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 INSERT('ABCABC',7,0,'XX')
     FROM SYSIBM.SYSDUMMY1
```

Ejemplo 4: Cambie la serie Hegelstraße a Hegelstrasse.

   SELECT INSERT('Hegelstraße',10,1,'ss',CODEUNITS16)
     FROM SYSIBM.SYSDUMMY1

Ejemplo 5: El ejemplo siguiente funciona con la serie Unicode &N~AB, donde & 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 INSERT para insertar una C en la serie Unicode &N~AB.

   SELECT INSERT(UTF8_VAR, 1, 4, 'C', CODEUNITS16),
     INSERT(UTF8_VAR, 1, 4, 'C', CODEUNITS32),
     INSERT(UTF8_VAR, 1, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1

devuelve los valores CAB, CB y CN~AB, respectivamente.

   SELECT INSERT(UTF8_VAR, 5, 1, 'C', CODEUNITS16),
     INSERT(UTF8_VAR, 5, 1, 'C', CODEUNITS32),
     INSERT(UTF8_VAR, 5, 1, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1

devuelve los valores &N~CB, &N~AC y &C~AB, respectivamente.

   SELECT INSERT(UTF16_VAR, 1, 4, 'C', CODEUNITS16),
     INSERT(UTF16_VAR, 1, 4, 'C', CODEUNITS32),
     INSERT(UTF16_VAR, 1, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1

devuelve los valores CAB, CB y CN~AB, respectivamente.

   SELECT INSERT(UTF16_VAR, 5, 2, 'C', CODEUNITS16),
     INSERT(UTF16_VAR, 5, 1, 'C', CODEUNITS32),
     INSERT(UTF16_VAR, 5, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1

devuelve los valores &N~C, &N~AC y &CAB, respectivamente.