Función escalar SUBSTRING

La función SUBSTRING devuelve una subserie de una serie.

El esquema es SYSIBM.

expresión

Una expresión que especifica la serie de la que se deriva el resultado. La expresión debe devolver una serie de caracteres incluida, valor numérico,valor booleano o valor de fecha y hora. Si el valor no es una serie de caracteres, se convierte implícitamente a VARCHAR antes de evaluar la función.

Una subserie de la expresión de entrada consta de cero o más unidades de serie contiguas de la expresión de entrada.

inicio

Una expresión que especifica la posición, en relación con el inicio de la expresión de entrada, desde la que se ha de calcular la subserie. Por ejemplo:

La posición 1 es la primera unidad de serie de la expresión de entrada. La sentencia SUBSTRING('abc',1,2) devuelve 'ab'.
La posición 2 es una posición a la derecha de la posición 1. La sentencia SUBSTRING('abc',2,2) devuelve 'bc'.
La posición 0 es una posición a la izquierda de la posición 1. La sentencia SUBSTRING('abc',0,2) devuelve 'a'.
La posición -1 son dos posiciones a la izquierda de la posición 1. La sentencia SUBSTRING('abc',-1,2) devuelve una serie de longitud cero.

La expresión debe devover un valor 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 de inicio puede ser positivo, negativo o cero. Si se especifica OCTETS y la entrada contiene datos gráficos, el valor de inicio debe ser un número impar (SQLSTATE 428GC).

longitud

Una expresión que especifica la longitud del resultado. La expresión debe devover un valor 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.

Si la expresión de entrada es:

Una serie de longitud fija, la longitud predeterminada es CHARACTER_LENGTH(expresión USING unidad-serie) - inicio + 1. Este es el número de unidades de serie (CODEUNITS16, CODEUNITS32, u OCTETS) desde la posición de inicio a la posición final de la expresión de entrada.
Una serie de longitud variable, la longitud predeterminada es cero o CHARACTER_LENGTH(expresión USING unidad-serie) - inicio + 1, la que sea mayor.

Si la longitud requerida es cero, el resultado es la serie vacía.

Si el valor no es del tipo INTEGER, se convierte implícitamente en INTEGER antes de evaluar esta función. El valor debe ser igual o mayor que cero. Si se especifica un valor superior a n, donde n sea (atributo de longitud de expresión) - inicio + 1, n se utilizará como longitud de la subserie resultante. El valor se expresa en las unidades de serie que se especifican explícitamente. Si se especifica OCTETS y si la expresión contiene datos gráficos, la longitud debe ser un número par (SQLSTATE 428GC).

CODEUNITS16, CODEUNITS32 u OCTETS

Especifica las unidades de serie de inicio y longitud. CODEUNITS16 especifica que inicio y longitud deben expresarse en unidades de código UFT-16 de 16 bits. CODEUNITS32 especifica que el inicio y la longitud se han de expresar en unidades de código UTF-32 de 32 bits. OCTETS especifica que inicio y longitud deben expresarse en bytes.

Si las unidades de serie se especifican como CODEUNITS16 o CODEUNITS32 y la expresión es una serie binaria o una serie FOR BIT DATA, se devuelve un error (SQLSTATE 428GC).

Si no se especifica un argumento de unidades de serie y expresión es 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.

Cuando se invoca la función SUBSTRING utilizando OCTETS, y la serie-fuente se codifica en una página de códigos que requiere más de un byte por elemento de código (combinados o MBCS), la operación SUBSTRING debe dividir un elemento de código de varios bytes y la subserie resultante puede comenzar o finalizar con un elemento de código parcial. Si sucede esto, la función sustituye los bytes de los elementos de código parciales iniciales o finales por espacios en blanco de modo que no se modifique la longitud de bytes del resultado. Consulte un ejemplo relacionado en la sección Ejemplos.

Resultado

El tipo de datos del resultado depende del tipo de datos del primer argumento, como se muestra en la tabla siguiente.

Tabla 1. Tipo de datos del resultado de SUBSTRING
Tipo de datos del primer argumento	Tipo de datos del resultado
CHAR o VARCHAR	VARCHAR
CLOB	CLOB
GRAPHIC o VARGRAPHIC	VARGRAPHIC
DBCLOB	DBCLOB
BINARY o VARBINARY	VARBINARY
BLOB	BLOB

El atributo de longitud del resultado es igual al atributo de longitud de la expresión de entrada. Si cualquier argumento de la función puede ser nulo, el resultado puede ser nulo; si el argumento es nulo, el resultado es el valor nulo. El resultado no se rellena con ningún carácter. Si la expresión de entrada tiene una longitud real de 0, el resultado también tiene una longitud real de 0.

Notas

El atributo de longitud del resultado es igual al atributo de longitud de la expresión de entrada. Este comportamiento es diferente del comportamiento de la función SUBSTR, donde el atributo de longitud se obtiene a partir de los argumentos inicio y longitud de la función.

Ejemplos

Ejemplo 1: FIRSTNAME es una columna VARCHAR(12) de la tabla T1. Uno de sus valores es la serie de 6 caracteres 'Jürgen'. Cuanto FIRSTNAME tiene este valor:

Función ...                           Devuelve ...
------------------------------------  ------------------------------------
SUBSTRING(FIRSTNAME,1,2,CODEUNITS32)  'Jü' -- x'4AC3BC'
SUBSTRING(FIRSTNAME,1,2,CODEUNITS16)  'Jü' -- x'4AC3BC'
SUBSTRING(FIRSTNAME,1,2,OCTETS)       'J ' -- x'4A20' (una serie truncada)
SUBSTRING(FIRSTNAME,8,CODEUNITS16)    una serie de longitud cero
SUBSTRING(FIRSTNAME,8,4,OCTETS)       una serie de longitud cero
SUBSTRING(FIRSTNAME,0,2,CODEUNITS32)  'J' -- x'4AC3BC'

Ejemplo 2: el ejemplo siguiente ilustra cómo SUBSTRING sustituye los bytes de los elementos de código de múltiples bytes parciales iniciales o finales por espacios en blanco cuando la unidad de longitud de la serie de caracteres es OCTETS. Presupone que UTF8_VAR contiene la representación UTF-8 de la serie Unicode '&N~AB', donde '&' es el símbolo musical de la clave de sol y '~' es el carácter de tilde de combinación.
```
   SUBSTRING(UTF8_VAR, 2, 5, OCTETS)
```
Tres bytes en blanco preceden la 'N' y un byte en blanco sigue a la 'N'.