DosQueryCollate

Description

Obtains a collating sequence table that resides in the country file.

Syntax

#define INCL_DOSNLS
#include <os2.h>

ULONG         cb;    /* The length, in bytes, of the data area (pch) provided by the caller. */
PCOUNTRYCODE  pcc;   /* Pointer to the COUNTRYCODE structure in which the country code 
                        and code page are identified. */
PCHAR         pch;   /* The data area where the collating sequence table is returned. */
PULONG        pcch;  /* The length, in bytes, of the collating sequence table returned. */
APIRET        ulrc;  /* Return Code. */

ulrc = DosQueryCollate(cb, pcc, pch, pcch);

Parameters

cb (ULONG) - input

The length, in bytes, of the data area (pch) provided by the caller.

A length value of 256 bytes is sufficient.

pcc (PCOUNTRYCODE) - input

Pointer to the COUNTRYCODE structure in which the country code and code page are identified.

If country is set to 0, the collate table for the default system country code is returned.

If codepage is set to 0, the collate table for the current process code page of the caller is returned.

Refer to the COUNTRYCODE for a table of values for country code and code page identifier.

pch (PCHAR) - output

The data area where the collating sequence table is returned.

The caller provides this data area. The input parameter cb specifies the length of this area.

If this area is too small to hold all of the available information, then as much information as possible is provided in the available space (in the order in which the data would appear). If the amount of data returned is not enough to fill the memory area provided by the caller, then the memory that is unaltered by the available data is zeroed out. The format of the information returned in this buffer is as follows:

1 Byte  Sort weight of ASCII (0)
1 Byte  Sort weight of ASCII (1)
...     (additional values in collating order)
1 Byte  Sort weight of ASCII (255)

pcch (PULONG) - output

The length, in bytes, of the collating sequence table returned.

Return Code

ulrc (APIRET) - returns

DosQueryCollate returns one of the following values:

• 0 NO_ERROR
• 397 ERROR_NLS_OPEN_FAILED
• 398 ERROR_NLS_NO_CTRY_CODE
• 399 ERROR_NLS_TABLE_TRUNCATED
• 401 ERROR_NLS_TYPE_NOT_FOUND
• 476 ERROR_CODE_PAGE_NOT_FOUND

Remarks

DosQueryCollate obtains a collating sequence table (for characters 0x00 through 0xFF) that resides in the country file (the default name is COUNTRY.SYS). It is used by the SORT utility to sort text according to the collating sequence.

The collating table returned corresponds to the system country code or selected country code, and to the process code page or selected code page.

Example Code

This example gets the collating sequence table for the current country and code page.

 #define INCL_DOSNLS     /* National Language Support values */
 #define INCL_DOSERRORS  /* DOS error values                */
 #include <os2.h>
 #include <stdio.h>

 int main(VOID) {
 COUNTRYCODE UserInfo       = {0};       /* Country and code page requested */
 UCHAR       achColSeq[256] = {0};       /* Collating sequence              */
 ULONG       ulSeqLen       = 0;         /* Length of sequence returned     */
 ULONG       i              = 0,         /* Two loop indices                */
             j              = 0;
 APIRET      rc             = NO_ERROR;  /* Return code                     */

    UserInfo.country = 0;      /* Request information about current country */
    UserInfo.codepage = 0;     /* ... and current code page                 */

    rc = DosQueryCollate(sizeof(achColSeq),   /* Length of output area      */
                         &UserInfo,           /* Country and codepage info  */
                         achColSeq,           /* Area for collating sequence*/
                         &ulSeqLen);          /* Length of data returned    */

    if (rc != NO_ERROR) {
        printf("DosQueryCollate error: return code = %u\n",rc);
        return 1;
    }
         /* Show the order of the first 128 characters in the sequence */

   if (ulSeqLen >= 8*16) {
     for (i = 0; i < 8; i++) {
       for (j = 0; j < 16; j++) {
          printf("%3u ", achColSeq[i*16+j]);
          } /* endfor (j) */
       printf("\n");
       } /* endfor (i) */
   } else {
      printf("Unable to show first 128 characters... only %u were returned.\n",
              ulSeqLen);
      return 1;
   }  /* endif */

   return NO_ERROR;
}

Related Functions

• DosMapCase
• DosQueryCp
• DosQueryCtryInfo
• DosQueryDBCSEnv
• DosSetProcessCp