SUBSTRING Função escalar

A função SUBSTRING retorna uma subsequência de uma sequência.

O esquema é SYSIBM.

expressão

Uma expressão que especifica a string a partir da qual o resultado é derivado. A expressão deve retornar uma sequência de caracteres embutida, valor numérico, valor booleanoou valor datetime. Se o valor não for uma string de caracteres, ele é implicitamente escalado para VARCHAR antes da função ser avaliada.

Uma subsequência da expressão de entrada compreende zero ou mais unidades de cadeia contíguas da expressão de entrada.

início

Uma expressão que especifica a posição, relativa ao início da expressão de entrada, a partir da qual a substring deve ser calculada. Por exemplo:

A posição 1 é a primeira unidade de cadeia da expressão de entrada. A instrução SUBSTRING('abc',1,2) retorna 'ab'.
A posição 2 é uma posição à direita da posição 1. A instrução SUBSTRING('abc',2,2) retorna 'bc'.
A posição 0 é uma posição à esquerda da posição 1. A instrução SUBSTRING('abc',0,2) retorna 'a'.
A posição -1 é duas posições à esquerda da posição 1. A instrução SUBSTRING('abc',-1,2) retorna uma sequência de comprimento zero.

A expressão deve retornar um valor numérico embutido, CHAR, VARCHAR, GRAPHIC ou VARGRAPHIC. Se o valor não for do tipo INTEGER, ele é implicitamente escalado para INTEGER antes de avaliar a função.

O valor de início pode ser positivo, negativo ou zero. Se OCTETS é especificado e a expressão de entrada contém dados gráficos, o valor de início deve ser estranho (SQLSTATE 428GC).

comprimento

Uma expressão que especifica o comprimento do resultado. A expressão deve retornar um valor numérico embutido, CHAR, VARCHAR, GRAPHIC ou VARGRAPHIC. Se o valor não for do tipo INTEGER, ele é implicitamente escalado para INTEGER antes de avaliar a função.

Se a expressão de entrada for:

Uma sequência de comprimento fixo, o comprimento padrão é CHARACTER_LENGTH(expression USING string-unit) - start + 1. Este é o número de unidades string (CODEUNITS16, CODEUNITS32ou OCTETS) desde a posição inicial até a posição final da expressão de entrada.
Uma sequência de comprimento variável, o comprimento padrão é zero ou CHARACTER_LENGTH(expression USING string-unit) - start + 1, consoante o que for maior.

Se o comprimento especificado for zero, o resultado será a sequência vazia.

Se o valor não for do tipo INTEGER, ele é implicitamente escalado para INTEGER antes de avaliar a função. O valor deve ser maior ou igual a zero. Se um valor maior do que n for especificado, onde n é o (atributo length of expression)- start + 1, então n é usado como o comprimento da substring resultante. O valor é expresso nas unidades de cadeia que são explicitamente especificadas. Se o OCTETS for especificado, e se a expressão de entrada contiver dados gráficos, o comprimento deve ser um número par (SQLSTATE 428GC).

CODEUNITS16, CODEUNITS32, ou OCTETS

Especifica as unidades string de start e length. CODEUNITS16 especifica que start e length devem ser expressos em 16-bit unidades de código UTF-16 . CODEUNITS32 especifica que start e length devem ser expressos em 32-bit unidades de código UTF-32 . OCTETS especifica que start e length devem ser expressos em bytes.

Se as unidades string forem especificadas como CODEUNITS16 ou CODEUNITS32, e expression é uma string binária ou uma string FOR BIT DATA, um erro é retornado (SQLSTATE 428GC).

Se um argumento de unidades string não for especificado e expression é uma string de caracteres que não é FOR BIT DATA ou é uma string gráfica, o padrão é CODEUNITS32. Caso contrário, o padrão é OCTETS.

Para obter mais informações sobre CODEUNITS16, CODEUNITS32, e OCTETS, consulte Unidades de cadeia em funções integradas em strings de caracteres.

Quando a função SUBSTRING é invocada usando OCTETS, e o source-string é codificado em uma página de código que requer mais de um byte por ponto de código (mixed ou MBCS), a operação SUBSTRING pode dividir um ponto de código multi-byte e a substring resultante pode começar ou terminar com um ponto de código parcial. Se isso ocorrer, a função substitui os bytes de pontos de código parciais iniciais ou finais com espaços em branco de uma maneira que não altere o comprimento de byte do resultado. (Veja um exemplo relacionado na seção Exemplos.)

Result

O tipo de dado do resultado depende do tipo de dados do primeiro argumento, conforme mostrado na tabela a seguir.

Tabela 1. Tipo de dado do resultado da SUBSTRING
Tipo de dados do primeiro argumento	Tipo de dado do resultado
Char ou Varchar	VARCHAR
CLOB	CLOB
GRÁFICO ou VARGRAPHIC	VARGRAPHIC
DBCLOB	DBCLOB
BINARY ou VARBINARY	VARBINARY
BLOB	BLOB

O atributo length do resultado é igual ao atributo comprimento da expressão de entrada. Se algum argumento da função puder ser nulo, o resultado pode ser nulo; se algum argumento for nulo, o resultado será o valor nulo. O resultado não é acolado com nenhum caractere. Se a expressão de entrada tiver um comprimento real de 0, o resultado também tem um comprimento real de 0.

Notas

O atributo length do resultado é igual ao atributo comprimento da expressão de entrada. Esse comportamento é diferente do comportamento da função SUBSTR, em que o atributo length é derivado do start e dos argumentos length da função.

Exemplos

Exemplo 1: FIRSTNAME é uma coluna VARCHAR (12) na tabela T1. Um de seus valores é a sequência de 6 caracteres 'Jürgen'. Quando FIRSTNAME tem este valor:

Function ...                          Returns ...
------------------------------------  ------------------------------------
SUBSTRING(FIRSTNAME,1,2,CODEUNITS32)  'Jü' -- x'4AC3BC'
SUBSTRING(FIRSTNAME,1,2,CODEUNITS16)  'Jü' -- x'4AC3BC'
SUBSTRING(FIRSTNAME,1,2,OCTETS)       'J ' -- x'4A20' (a truncated string)
SUBSTRING(FIRSTNAME,8,CODEUNITS16)    a zero-length string
SUBSTRING(FIRSTNAME,8,4,OCTETS)       a zero-length string
SUBSTRING(FIRSTNAME,0,2,CODEUNITS32)  'J' -- x'4AC3BC'

Exemplo 2: O exemplo a seguir ilustra como SUBSTRING substitui os bytes de pontos de código multi-byte parciais de liderança ou trailing com espaços em branco quando a unidade de comprimento de cadeia é OCTETS. Suponha que UTF8_VAR contenha a representação UTF-8 da string Unicode '& N ~ AB', onde '&' é o símbolo musical G clef e '~ ' é a personagem de tilde combinando.
```
   SUBSTRING(UTF8_VAR, 2, 5, OCTETS)
```
Três bytes em branco precedem o 'N', e um byte em branco segue o 'N'.