A função USUPPLEMENTARY retorna um valor inteiro igual ao índice do primeiro caractere suplementar Unicode em um argumento de item de dados de caracteres codificado em UTF-8 ou UTF-16.

Um caractere suplementar Unicode é um caractere acima de U + FFFF, ou seja, um caractere fora do Plano Multilíngue Básico (BMP).
Esses caracteres são codificados em UTF-16 com um par substituto (duas unidades de código de 16 bits) ou são codificados em UTF-8 com uma representação de 4 bytes.

O tipo de função é inteiro.

argument-1

Deve ser da classe alfabética, alfanumérica ou nacional.
O argument-1 deve conter dados UTF-8 ou UTF-16 válidos com base em sua classe:

• Se o argument-1 for da classe alfabética ou alfanumérica, ele deverá conter dados UTF-8 válidos.
• Se o argument-1 for da classe nacional, ele deverá conter dados UTF-16 válidos.

O valor retornado é um número inteiro, que difere com base no valor do argumento 1 e tem 9 dígitos se LP (32) estiver em vigor ou 18 dígitos se LP (64) estiver em vigor:,/P.

• Se o conteúdo do argument-1 não for Unicode válido (UTF-8 ou UTF-16, dependendo da classe), o resultado retornado será imprevisível.
• Se o argument-1 não contiver caracteres suplementares, o valor retornado será zero.
• Se o argument-1 for da classe alfabética ou alfanumérica, o valor retornado será a posição de byte do primeiro caractere suplementar UTF-8 no argumento 1.
• Se o argument-1 for da classe nacional, o valor retornado será o índice, em unidades de codificação UTF-16, do primeiro caractere complementar UTF-16 no argument-1.

Exemplo 1

Por exemplo, o símbolo da clave de sol musical é representado no Unicode UTF-16 pelo par substituto nx'D834DD1E 'ou no Unicode UTF-8 por x'F09D849E'.
Portanto, para o seguinte fragmento de programa COBOL, a saída de ambas as instruções DISPLAY é o valor 3.

       01  N PIC N(4) VALUE NX'00200020D834DD1E'.
       01  X PIC X(6) VALUE X'2020F09D849E'.
       01  I PIC 9.
       ...
           COMPUTE I = FUNCTION USUPPLEMENTARY(N)
           DISPLAY I
           COMPUTE I = FUNCTION USUPPLEMENTARY(X)
           DISPLAY I

Exemplo 2

Se o argument-1 for um item codificado em UTF-8 e o argumento UTF-8 contiver caracteres compostos, os caracteres combinados serão contados individualmente.
Por exemplo, quando codificado em UTF-8, o caractere Unicode ä pode ser x'C3A4 'ou x'61CC88'.
Com um dos caracteres UTF-8 no argument-1, os valores retornados da função USUPPLEMENTARY são diferentes.

Veja a tabela a seguir para detalhes.

Valores Retornados da Função USUPPLEMENTARY