Función escalar SUBSTR

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

El esquema es SYSIBM.

serie

La expresión de entrada, que especifica la serie desde la que se deriva la subserie. La expresión debe devolver un valor que sea una serie de caracteres incorporada, 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. Cualquier unidad de serie contigua numérica (cero o más) de esta expresión constituye una subserie de esta expresión.

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 SUBSTR('abcd',1,2) devuelve 'ab'.
La posición 2 es una posición a la derecha de la posición 1. La sentencia SUBSTR('abcd',2,2) devuelve 'bc'.

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.

longitud

Una expresión que especifica la longitud del resultado. Si se especifica, 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 entero debe estar en el rango comprendido entre 0 y n, donde n es igual (el atributo de longitud de la serie en unidades de serie) - inicio + 1 (SQLSTATE 22011, si está fuera de rango).

Si se especifica longitud explícitamente, la serie se rellena de forma efectiva en la parte derecha con el número necesario de caracteres en blanco (byte único para series de caracteres; bytes dobles para series gráficas) o caracteres cero hexadecimales (para series binarias), de modo que la subserie especificada exista. La longitud predeterminada es el número de unidades de serie de la unidad de serie especificada por el valor de inicio hasta la última unidad de serie de la serie. Sin embargo, si la serie es una serie de longitud variable con una longitud menor que el inicio, el valor por omisión es cero y el resultado es la serie vacía. Se debe especificar como número de unidades de serie en el contexto de la página de códigos de la base de datos, no de la página de códigos de la aplicación. (Por ejemplo, la columna NAME con un tipo de datos de VARCHAR(18) y un valor de 'MCKNIGHT' dará una serie vacía con SUBSTR(NAME,10).)

Si serie es:

Una serie de longitud fija, la longitud predeterminada es LENGTH(serie) - inicio + 1
Una serie de longitud variable, la longitud predeterminada es cero o LENGTH(serie) - inicio + 1, la que sea mayor.

Resultado

Si la serie es una serie de caracteres, el resultado es una serie de caracteres representada en la página de códigos y unidades de serie del primer argumento. Si es una serie binaria, el resultado es una serie binaria. Si es una serie gráfica, el resultado es una serie gráfica representada en la página de códigos y unidades de serie del primer argumento. Si el primer argumento es una variable del lenguaje principal que no es una serie binaria y no es una serie de caracteres FOR BIT DATA, la página de códigos del resultado es la página de códigos de la base de datos. Si cualquier argumento de la función SUBSTR puede ser nulo, el resultado puede ser nulo; si el argumento es nulo, el resultado es el valor nulo.

La Tabla 1 muestra que el tipo del resultado y la longitud de la función SUBSTR depende del tipo y los atributos de sus entradas.

Tabla 1. Tipo de datos y longitud del resultado de SUBSTR
Tipo de datos del argumento de la serie	Argumento de longitud	Tipo de datos del resultado
CHAR(A)	constante (l<n) Si las unidades de serie son: OCTETS, n=256 CODEUNITS32, n=64	CHAR(l)
CHAR(A)	no especificado pero el argumento inicio es una constante	CHAR(A-inicio+1)
CHAR(A)	no es una constante	VARCHAR(A)
VARCHAR(A)	constante (l<n) Si las unidades de serie son: OCTETS, n=256 CODEUNITS32, n=64	CHAR(l)
VARCHAR(A)	constante (m<l<n) Si las unidades de serie son: OCTETS, m=256 y n=32673 CODEUNITS32, m=63 y n=8169	VARCHAR(l)
VARCHAR(A)	no es una constante o no se especifica	VARCHAR(A)
CLOB(A)	constante (l)	CLOB(l)
CLOB(A)	no es una constante o no se especifica	CLOB(A)
GRAPHIC(A)	constante (l<n) Si las unidades de serie son: bytes dobles o CODEUNITS16, n=128 CODEUNITS32, n=64	GRAPHIC(l)
GRAPHIC(A)	no especificado pero el argumento inicio es una constante	GRAPHIC(A-inicio+1)
GRAPHIC(A)	no es una constante	VARGRAPHIC(A)
VARGRAPHIC(A)	constante (l<n) Si las unidades de serie son: bytes dobles o CODEUNITS16, n=128 CODEUNITS32, n=64	GRAPHIC(l)
VARGRAPHIC(A)	constante (m<l<n) Si las unidades de serie son: bytes dobles o CODEUNITS16, m=127 y n=16337 CODEUNITS32, m=63 y n=8169	VARGRAPHIC(l)
VARGRAPHIC(A)	no es una constante	VARGRAPHIC(A)
DBCLOB(A)	constante (l)	DBCLOB(l)
DBCLOB(A)	no es una constante o no se especifica	DBCLOB(A)
BINARY(A)	constante (l<256)	BINARY(l)
BINARY(A)	no especificado pero el argumento inicio es una constante	BINARY(A-start+1)
BINARY(A)	no es una constante	VARBINARY(A)
VARBINARY(A)	constante (l<256)	BINARY(l)
VARBINARY(A)	constante (255<l<32673)	VARBINARY(l)
VARBINARY(A)	no es una constante o no se especifica	VARBINARY(A)
BLOB(A)	constante (l)	BLOB(l)
BLOB(A)	no es una constante o no se especifica	BLOB(A)

Nota: Los tipos de datos LONG VARCHAR y LONG VARGRAPHIC siguen estando soportados pero han quedado obsoletos y no son recomendables.

Notas

En SQL dinámico, la serie, el inicio y la longitud pueden representarse mediante un marcador de parámetro. Si se utiliza un marcador de parámetro para la serie, el tipo de datos del operando será VARCHAR y el operando podrá contener nulos.
Aunque no se indica explícitamente en las definiciones de resultados indicadas anteriormente, la semántica implica que si la serie es una serie de caracteres que combina caracteres de un solo byte y de varios bytes, el resultado podría contener fragmentos de caracteres de varios bytes, en función de los valores de inicio y longitud. Por ejemplo, el resultado podría empezar con el segundo byte de un carácter de varios bytes o bien finalizar con el primer byte de un carácter de varios bytes. La función SUBSTR no detecta los fragmentos de este tipo, ni proporciona ningún proceso especial en caso de que se produzcan.

Ejemplos

Ejemplo 1: Presuponga que la variable de host NAME (VARCHAR(50)) tiene el valor 'BLUE JAY':
- La siguiente sentencia devuelve el valor 'BLUE':
```
   SUBSTR(:NAME,1,4)
```
- La siguiente sentencia devuelve el valor 'JAY':
```
   SUBSTR(:NAME,6)
```
- La siguiente sentencia devuelve el valor 'JA':
```
   SUBSTR(:NAME,6,2)
```
Ejemplo 2: seleccionar todas las filas de la tabla PROJECT para las que el nombre del proyecto (PROJNAME) empiece por la palabra 'OPERATION'.
```
   SELECT * FROM PROJECT
     WHERE SUBSTR(PROJNAME,1,10) = 'OPERATION '
```
El espacio al final de la constante es necesario para excluir palabras como 'OPERATIONAL'.