DosQueryDBCSEnv

Description

Obtains a DBCS (double-byte character set) environmental vector that resides in the country file.

Syntax

#define INCL_DOSNLS
#include <os2.h>

ULONG        cb;    /* The length, in bytes, of the data area (pBuf) provided by the caller. */
PCOUNTRYCODE pcc;   /* A pointer to the COUNTRYCODE structure in which the country code
                       and code page are identified. */
PCHAR        pBuf;  /* The data area where the country-dependent information for the 
                       DBCS environmental vector is returned. */
APIRET       ulrc;  /* Return Code. */

ulrc = DosQueryDBCSEnv(cb, pcc, pBuf);

Parameters

cb (ULONG) - input

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

A length value of 12 bytes is sufficient. The caller can always determine if all of the information has been obtained, because it ends with four bytes of 0s. A length of 4 is sufficient for information returned from non-DBCS-related countries.

pcc (PCOUNTRYCODE) - input

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

If country is set to 0, the DBCS information for the default system country code is returned.

If codepage is set to 0, the DBCS information 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.

pBuf (PCHAR) - output

The data area where the country-dependent information for the DBCS environmental vector is returned.

The caller provides this memory area. The size of the area is specified by the input parameter cb.

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). Assuming that the data area is large enough, the valid information is terminated by two bytes of 0. The format of the information returned in this buffer is as follows:

2 Bytes        First range definition for DBCS lead byte values:
               Byte 1            binary start value (inclusive) for range one 
               Byte 2            binary stop value (inclusive) for range one 

2 Bytes        Second range definition:
               Byte 1            binary start value for range two 
               Byte 2            binary stop value for range two 

2 Bytes        Nth range definition:
               Byte 1            binary start value for Nth range 
               Byte 2            binary stop value for Nth range 

2 Bytes        Two bytes of binary 0 end the list.

                   For example: DB   81H,9FH
                                DB   E0H,FCH
                                DB   0,0

Return Code

ulrc (APIRET) - returns

DosQueryDBCSEnv 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

DosQueryDBCSEnv obtains a double-byte character set environmental vector that resides in the country file (the default name is COUNTRY.SYS).

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

A double-byte character set is for a code page that contains more than 256 characters. A DBCS data string may contain both SBCS (single-byte character set) and DBCS (double-byte character set) characters.

A DBCS character is two bytes in length. It contains a lead byte and a trail byte. A lead byte is in the range returned by DosQueryDBCSEnv. A trail byte is not restricted to any range. The trail byte always follows the lead byte in a DBCS character.

Example Code

This example shows how to get the double-byte character set vector from the country file, and displays the first and second range definition values.

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

int main(VOID) {
COUNTRYCODE  ctrycodeInfo      = {0};        /* Country code information */
UCHAR        uchDBCSInfo[12]   = {0};        /* DBCS information buffer */
APIRET       rc                = NO_ERROR;   /* A return code */

ctrycodeInfo.country = 0;    /* Current country */
ctrycodeInfo.codepage = 0;   /* Current codepage */

rc = DosQueryDBCSEnv(sizeof(uchDBCSInfo),   /* Size of buffer */
                     &ctrycodeInfo,         /* Country code information */
                     uchDBCSInfo);          /* DBCS information buffer */

if (rc != NO_ERROR) {
   printf("DosQueryDBCSEnv error: return code = %u\n", rc);
   return 1;
 } else {
      /* For non-DBCS countries, these will be 4 bytes of 0 */
   printf("DBCS 1st range definition: %2.2x %2.2x\n",
                            uchDBCSInfo[0], uchDBCSInfo[1]);
   printf("     2nd range definition: %2.2x %2.2x\n",
                            uchDBCSInfo[2], uchDBCSInfo[3]);
 } /* endif */


return NO_ERROR;
}

Related Functions

• DosMapCase
• DosQueryCollate
• DosQueryCp
• DosQueryCtryInfo
• DosSetProcessCp