Función escalar LOCATE

La función LOCATE devuelve la posición inicial de la primera aparición de una serie (denominada serie-búsqueda) dentro de otra serie (denominada serie-fuente).

El esquema es SYSIBM. La versión SYSFUN de la función LOCATE continúa estando disponible, pero no es sensible a la clasificación de base de datos.

Si el argumento serie-búsqueda no se encuentra y ningún argumento es nulo, el resultado es cero. Si el argumento serie-búsqueda se encuentra, el resultado es un número de 1 la longitud real del argumento serie-fuente. La búsqueda se realiza utilizando la ordenación de la base de datos, a menos que serie-búsqueda o serie-fuente se defina como una serie binaria o como FOR BIT DATA, en cuyo caso la búsqueda se realiza utilizando una comparación binaria.

Si se especifica el argumento opcional inicio, éste indica la posición del carácter en el argumento serie-fuente en el que debe iniciarse la búsqueda. Puede especificarse una unidad de la serie opcional para indicar en qué unidades se expresan el argumento inicio y el resultado de la función.

Si serie-búsqueda tiene una longitud de cero, el resultado devuelto por la función es 1. En caso contrario, si la serie-fuente es de longitud cero, el resultado devuelto por la función será 0. En otro caso:

Si el valor del argumento serie-búsqueda es igual a una longitud idéntica de subserie de posiciones contiguas dentro del valor de serie-búsqueda, el resultado que devuelve la función es la posición inicial de la subserie de este tipo dentro del valor serie-fuente.
De lo contrario, el resultado que devuelve la función es 0.

serie-búsqueda: Expresión que especifica la serie que es objeto de la búsqueda. La expresión debe devolver un valor que sea un tipo de datos incorporado CHAR, VARCHAR, GRAPHIC, VARGRAPHIC, serie binaria, numérico, booleanoo de fecha y hora. Si el valor no es un tipo de datos CHAR, VARCHAR, GRAPHIC, VARGRAPHIC o binario, se convierte implícitamente a VARCHAR antes de evaluar la función. La expresión no se puede especificar mediante una variable de referencia de archivo de archivo LOB.

serie-origen: Expresión que especifica la serie en la que debe realizarse la búsqueda. La expresión debe devolver un valor que sea un tipo de datos de serie incorporada, numérico, booleanoo 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.

iniciar

Expresión que especifica la posición entro de serie-fuente en la que debe iniciarse la búsqueda. 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 ser mayor o igual que cero. Si se especifica inicio, la función LOCATE es parecida a la siguiente:

   POSITION(search-string,
     SUBSTRING(source-string, start, string-unit),
     string-unit) + start - 1

donde unidad-serie es CODEUNITS16, CODEUNITS32u OCTETS.

Si no se especifica inicio, la búsqueda empieza en la primera posición de la serie fuente, y la función LOCATE es parecida a la siguiente:

   POSITION(search-string, source-string, string-unit)

Si se especifica OCTETS y serie-fuente corresponde a datos gráficos, el valor del entero debe ser impar (SQLSTATE 428GC).

CODEUNITS16, CODEUNITS32, o OCTETS

Especifica la unidad de la serie de inicio y del resultado. CODEUNITS16 especifica que inicio y el resultado deben expresarse en unidades de código UTF-16 de 16 bits. CODEUNITS32 especifica que inicio y el resultado deben expresarse en unidades de código UTF-32 de 32 bits. OCTETS especifica que inicio y el resultado deben expresarse en bytes.

Si se especifica una unidad de serie como CODEUNITS16 o CODEUNITS32, y serie-búsqueda o serie-fuente es una serie binaria o 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 serie-fuente son CODEUNITS32, se devolverá un error (SQLSTATE 428GC).

Si no se especifica de forma explícita una unidad de serie y si fuente-serie es una serie gráfica o serie de caracteres, las unidades de serie de fuente-serie determinan la unidad que se utiliza para el resultado y para inicio (si se especifica). De lo contrario, se expresan en bytes.

Si se utiliza una clasificación basada en la UCA sensible a la configuración local para esta función, la opción CODEUNITS16 ofrece las mejores características de rendimiento.

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

El primer y segundo argumento deben tener tipos de serie compatibles. Para obtener más información sobre la compatibilidad, consulte la sección Normas para la conversión de series. En una base de datos Unicode, si un argumento de serie es de tipo carácter (no FOR BIT DATA) y el otro argumento de serie es gráfico, la serie-búsqueda se convierte al tipo de datos de la serie-fuente para el proceso. Si un argumento es de tipo carácter FOR BIT DATA, el otro argumento no debe ser gráfico (SQLSTATE 42846).

El resultado de la función es un entero grande. 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: Busque la ubicación de la primera aparición del carácter N en la serie DINING.
```
   SELECT LOCATE('N', 'DINING')
   FROM SYSIBM.SYSDUMMY1
```
El resultado es el valor 3.
Ejemplo 2: Para todas las filas de la tabla denominada IN_TRAY, seleccionar la columna RECEIVED, la columna SUBJECT y la posición de inicio de la serie GOOD dentro de la columna NOTE_TEXT.
```
   SELECT RECEIVED, SUBJECT, LOCATE('GOOD', NOTE_TEXT)
   FROM IN_TRAY
   WHERE LOCATE('GOOD', NOTE_TEXT) <> 0
```
Ejemplo 3: Localice el carácter ß en la serie Jürgen lives on Hegelstraßey establezca la variable del lenguaje principal LOCATION con la posición, medida en unidades CODEUNITS32 , dentro de la serie.
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, CODEUNITS32)
```
El valor de la variable del lenguaje principal LOCATION se establece en 26.
Ejemplo 4: Localice el carácter 'ß en la serie Jürgen lives on Hegelstraßey establezca la variable del lenguaje principal LOCATION con la posición, medida en unidades CODEUNITS16 , dentro de la serie.
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, CODEUNITS16)
```
El valor de la variable del lenguaje principal LOCATION se establece en 26.
Ejemplo 5: localizar el carácter ß en la serie Jürgen lives on Hegelstraße, y definir la variable host LOCATION con la posición, según se mide en OCTETS, dentro de la serie.
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, OCTETS)
```
El valor de la variable del lenguaje principal LOCATION se establece en 27.
Ejemplo 6: Los ejemplos siguientes funcionan con la serie Unicode &N~AB, donde & es el carácter de clave de símbolo musical G y ~ es el carácter de tilde de combinación sin espaciado. En el ejemplo siguiente se muestra esta serie en distintos formatos de codificación Unicode:

& N ~ A P

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 la variable UTF8_VAR contiene la representación UTF-8 de la serie.
```
   SELECT LOCATE('~', UTF8_VAR, CODEUNITS16),
     LOCATE('~', UTF8_VAR, CODEUNITS32),
     LOCATE('~', UTF8_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
devuelve los valores 4, 3 y 6, respectivamente.
Supongamos que la variable UTF16_VAR contiene la representación UTF-16BE de la serie.
```
   SELECT LOCATE('~', UTF16_VAR, CODEUNITS16),
      LOCATE('~', UTF16_VAR, CODEUNITS32),
      LOCATE('~', UTF16_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
devuelve los valores 4, 3 y 7, respectivamente.
Ejemplo 7: En una base de datos Unicode creada con la clasificación no sensible a las mayúsculas y minúsculas y CLDR181_LEN_S1, buscar la posición de la palabra Brown en la frase The quick brown fox.
```
SET :LOCATION = LOCATE('Brown', 'The quick brown fox', CODEUNITS16)
```
El valor de la variable del lenguaje principal LOCATION se establece en 11.

	&	N	~	A	P
UTF-8	X'F09D849E'	X'4E'	X'CC83'	X'41'	X'42'
UTF-16BE	X'D834DD1E'	X'004E'	X'0303'	X'0041'	X'0042'