Función escalar LEFT

La función LEFT devuelve la serie situada más a la izquierda de expresión-serie de la longitud longitud, expresada en la unidad de serie especificada.

Leer el esquema de sintaxisOmitir el esquema de sintaxis visualLEFT(expresión-serie ,longitud ,CODEUNITS16CODEUNITS32OCTETS )

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

expresión-serie
Una expresión que especifica la serie de la que se deriva el resultado. La expresión debe devolver una serie incorporada, un valor numéricovalor booleano o valor de fecha y hora. Si el valor no es una serie, se convierte implícitamente a VARCHAR antes de que se evalúe la función. Una subserie de la serie consta de cero o más puntos de código contiguos de la serie.

La expresión-serie se rellena a la derecha con el número necesario de caracteres de relleno para que exista siempre la subserie especificada de expresión-serie. El carácter utilizado para el relleno es el mismo carácter que se utiliza para rellenar la serie en contextos donde se debe producir relleno. Para obtener más información acerca del relleno, consulte la sección Asignaciones de series en Asignaciones y comparaciones.

longitud

Una expresión que especifica la longitud del resultado. 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. longitud debe ser superior o igual a 0 (SQLSTATE 22011). Si se especifica OCTETS y el resultado son datos gráficos, el valor debe ser un número par (SQLSTATE 428GC).

Si longitud no es una constante y no se especifica una unidad de serie, longitud debe ser menor que o igual al atributo de longitud de expresión-serie (SQLSTATE 22011).

Si longitud no es una constante y se especifica una unidad de serie, longitud debe ser menor que o igual al valor correspondiente de la tabla siguiente (SQLSTATE 22011):

Tabla 1. Valor máximo de longitud cuando longitud no es una constante y se especifica una unidad de serie
Unidad de serie de expresión-serie Unidad de serie especificada Valor máximo de longitud

L = atributo de longitud de expresión-serie
OCTETS OCTETS L
OCTETS CODEUNITS16 L/2
OCTETS CODEUNITS32 L/4
CODEUNITS16 OCTETS L*2
CODEUNITS16 CODEUNITS16 L
CODEUNITS16 CODEUNITS32 L/2
CODEUNITS32 OCTETS L*4
CODEUNITS32 CODEUNITS16 L*2
CODEUNITS32 CODEUNITS32 L
Si longitud es una constante y el tipo de datos de expresión-serie es:
CHAR, VARCHAR, GRAPHIC o VARGRAPHIC
La longitud debe ser menor que o igual a 32.672 OCTETS, 16.336 CODEUNITS16 o 8168 CODEUNITS32 (SQLSTATE 22011).
CLOB o DBCLOB
La longitud debe ser menor que o igual a 2.147.483.647 OCTETS, 1.073.741.823 CODEUNITS16 o 53,6870,911 CODEUNITS32 (SQLSTATE 22011).
BLOB
La longitud debe ser menor que o igual a 2.147.483.647 OCTETS (SQLSTATE 22011).
CODEUNITS16, CODEUNITS32 u OCTETS
Especifica la unidad de serie de longitud.

CODEUNITS16 especifica que longitud se expresa en unidades de código UTF-16 de 16 bits. CODEUNITS32 especifica que longitud se expresa en unidades de código UTF-32 de 32 bits. OCTETS especifica que longitud se expresa en bytes.

Si la unidad de serie se especifica como CODEUNITS16 o CODEUNITS32 y expresión-serie es una serie binaria o datos de bit, se devuelve un error (SQLSTATE 428GC). Si la unidad de serie se especifica como OCTETS y expresión-serie es una serie gráfica, longitud debe ser un número par; de lo contrario, se devuelve un error (SQLSTATE 428GC). Si una unidad de serie no se especifica de forma explícita, la unidad de serie de serie-expresión determina la unidad que se utiliza. Para obtener más información sobre CODEUNITS16, CODEUNITS32 y OCTETS, consulte el apartado Unidades de serie en funciones incorporadas en Series de caracteres.

Resultado

El resultado de la función es una serie de longitud variable que depende del tipo de datos de expresión-serie:
  • VARCHAR si expresión-serie es CHAR o VARCHAR
  • CLOB si expresión-serie es CLOB
  • VARGRAPHIC si expresión-serie es GRAPHIC o VARGRAPHIC
  • DBCLOB si expresión-serie es DBCLOB
  • VARBINARY si expresión-serie es BINARY o VARBINARY
  • BLOB si serie-expresión es BLOB
La unidad de serie del resultado es la unidad de serie de expresión-serie.El atributo de longitud del resultado depende de cómo se especifiquen longitud y unidad de serie:
  • Si longitud no es una constante, el atributo de longitud del resultado es el mismo que el atributo de longitud de expresión-serie.
  • Si longitud es una constante y no se especifica una unidad de serie, el atributo de longitud del resultado es el máximo de longitud y el atributo de longitud de expresión-serie.
  • Si longitud es una constante y se especifica una unidad de serie, el atributo de longitud del resultado se muestra en la Tabla 2:
    Tabla 2. Atributo de longitud de resultado cuando longitud es una constante y se especifica una unidad de serie
    Unidad de serie de expresión-serie Unidad de serie especificada Valor máximo de longitud

    L = atributo de longitud de expresión-serie
    OCTETS OCTETS max(L, longitud)
    OCTETS CODEUNITS16 max(L, longitud * 2)
    OCTETS CODEUNITS32 max(L, longitud * 4)
    CODEUNITS16 OCTETS max(L, longitud / 2)
    CODEUNITS16 CODEUNITS16 max(L, longitud)
    CODEUNITS16 CODEUNITS32 max(L, longitud * 2)
    CODEUNITS32 OCTETS max(L, longitud / 4)
    CODEUNITS32 CODEUNITS16 max(L, longitud / 2)
    CODEUNITS32 CODEUNITS32 max(L, longitud)
La longitud real del resultado (en unidades de serie) es longitud.

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: Supongamos que la variable ALPHA tiene el valor ABCDEF. La siguiente sentencia:
       SELECT LEFT(ALPHA,3)
     FROM SYSIBM.SYSDUMMY1
    devuelve ABC, que son los tres caracteres situados más a la izquierda en ALPHA.
  • Ejemplo 2: supongamos que la variable NAME, que se define como VARCHAR(50), tiene el valor KATIE AUSTIN y que la variable de entero FIRSTNAME_LEN tiene el valor 5. La siguiente sentencia:
       SELECT LEFT(NAME,FIRSTNAME_LEN)
     FROM SYSIBM.SYSDUMMY1
    devuelve el valor KATIE.
  • Ejemplo 3: la sentencia siguiente devuelve una serie de longitud cero.
       SELECT LEFT('ABCABC',0)
     FROM SYSIBM.SYSDUMMY1
  • Ejemplo 4: la columna FIRSTNME de la tabla EMPLOYEE se define como VARCHAR(12). Busque el nombre de un empleado cuyo apellido es BROWN y devuelva el nombre en una serie de 10 bytes.
       SELECT LEFT(FIRSTNME, 10)
     FROM EMPLOYEE
     WHERE LASTNAME = 'BROWN'
    devuelve una serie VARCHAR(12) que tiene el valor DAVID seguido de cinco caracteres en blanco.
  • Ejemplo 5: en una base de datos Unicode, FIRSTNAME es una columna VARCHAR(12). Uno de sus valores es la serie de 6 caracteres Jürgen. Cuanto FIRSTNAME tiene este valor:
       Función...                        Devuelve...

   LEFT(FIRSTNAME,2,CODEUNITS32)   'Jü' -- x'4AC3BC'
   LEFT(FIRSTNAME,2,CODEUNITS16)   'Jü' -- x'4AC3BC'
   LEFT(FIRSTNAME,2,OCTETS)        'J'  -- x'4A20', una serie truncada
  • Ejemplo 6: 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'
    Suponga que la variable UTF8_VAR, con un atributo de longitud de 20 bytes, contiene la representación UTF-8 de la serie.
       SELECT LEFT(UTF8_VAR, 2, CODEUNITS16),
     LEFT(UTF8_VAR, 2, CODEUNITS32),
     LEFT(UTF8_VAR, 2, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &, &N y bb, respectivamente, donde b representa el carácter en blanco.
       SELECT LEFT(UTF8_VAR, 5, CODEUNITS16),
     LEFT(UTF8_VAR, 5, CODEUNITS32),
     LEFT(UTF8_VAR, 5, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &N~A, &N~AB y &N, respectivamente.
       SELECT LEFT(UTF8_VAR, 10, CODEUNITS16),
     LEFT(UTF8_VAR, 10, CODEUNITS32),
     LEFT(UTF8_VAR, 10, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &N~ABbbbb, &N~ABbbbbb y &N~ABb, respectivamente, donde b representa el carácter en blanco.
    Suponga que la variable UTF16_VAR, con un atributo de longitud de 20 unidades de código, contiene la representación UTF-16BE de la serie.
       SELECT LEFT(UTF16_VAR, 2, CODEUNITS16),
     LEFT(UTF16_VAR, 2, CODEUNITS32),
     HEX (LEFT(UTF16_VAR, 2, OCTETS))
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &, &N, y X'D834', respectivamente, donde X'D834' es un carácter de sustitución no coincidente.
       SELECT LEFT(UTF16_VAR, 5, CODEUNITS16),
     LEFT(UTF16_VAR, 5, CODEUNITS32),
     LEFT(UTF16_VAR, 6, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &N~A, &N~AB y &N, respectivamente.
       SELECT LEFT(UTF16_VAR, 10, CODEUNITS16),
     LEFT(UTF16_VAR, 10, CODEUNITS32),
     LEFT(UTF16_VAR, 10, OCTETS)
   FROM SYSIBM.SYSDUMMY1
    devuelve los valores &N~ABbbbb, &N~ABbbbbb y &N~A, respectivamente, donde b representa el carácter en blanco.