Nonstop Database, HiRDB Version 9 UAP Development Guide
![[Contents]](FIGURE/CONTENT.GIF)
![[Index]](FIGURE/INDEX.GIF)
![[Back]](FIGURE/FRONT.GIF)
Appendix H.2 Space conversion function
The space conversion function converts single-byte spaces in a character string to double-byte spaces, and vice versa. Because this function lets you know the conversion result without having to store character string data in a database, you can use the function for the following purposes:
- To evaluate whether the data to be stored will be partitioned equally when determining the partitioning key for partitioning a table by the key range
- To create an input data file for each RDAREA when loading data to a key-range-partitioned table in units of RDAREAs concurrently using the database load utility
- Prerequisites for using the space conversion function
- The prerequisites for using the space conversion function are the same as for the hash function for table partitioning. For details, see H.1(1) Prerequisites for using the hash function for table partitioning.
- Prerequisites for creating and executing a UAP using the space conversion function
- The prerequisites for creating and executing a UAP using the space conversion function are the same as for the hash function for table partitioning. For details, see H.1(2) Creating and executing UAPs that use the hash function for table partitioning.
- Organization of this subsection
- (1) Details about the space conversion function
(1) Details about the space conversion function
(a) Specification configuration
For details about the specification configuration, see H.1(3)(b) Specification configuration.
- Function
- The function converts spaces according to the specified conversion type as follows:
- Single-byte space
double-byte space:
- Converts two consecutive single-byte spaces in a character string to one double-byte space.
- Double-byte space
single-byte space:
- Converts each double-byte space in a character string to two single-byte spaces.
- The function converts spaces in the character string indicated by srcp and stores the conversion result in destp. The following table shows the combination of stype and flags arguments and the conversion type:
stype
(data type) |
flags (conversion type) |
Single-byte space double-byte space |
Double-byte space single-byte space |
NCHAR |
Checks two bytes at a time from the top and converts any two consecutive single-byte spaces to a double-byte space.#
The function does not convert any isolated single-byte space. |
Checks two bytes at a time from the top and converts any double-byte space# to two single-byte spaces. |
NVARCHAR |
MCHAR |
Results in an error. |
Checks each character code from the top and converts any double-byte space# to two single-byte spaces. |
MVARCHAR |
- #: The function treats the value specified in the ncspace argument as the character code for double-byte space.
- Header files
- #include<pdauxcnv.h>
- This header file is required to use the space conversion function.
- #include<pdbsqlda.h>
- This header file lets you use macros (with a name beginning with PDSQL_) to specify a data type code. If the data type code is to be retrieved from a data dictionary table, this header file is not necessary.
- Format
int p_rdb_conv_space(char *srcp,
unsigned char stype,
unsigned int srcl,
char *destp,
unsigned char ncspace[2],
int flags);
|
- Arguments
- srcp (input)
- Specifies the start address of the character string storage area.
- stype (input)
- Specifies the data type before conversion. Specifiable data types are as follows:
Macro name |
Data type |
PDSQL_NCHAR |
NCHAR |
PDSQL_NVARCHAR |
NVARCHAR |
PDSQL_MCHAR |
MCHAR |
PDSQL_MVARCHAR |
MVARCHAR |
- srcl (input)
- Specifies the length of the character string specified in srcp. For a variable-length character string, specify the length of the actual character string (in bytes) that is stored in the area indicated by srcp.
- destp (output)
- Sets the start address of the character string storage area after conversion. Allocate this area indicated by destp on the side that calls the space conversion function.
- ncspace (input)
- Specifies a two-byte area that contains the double-byte space character for the national character code used in the HiRDB server. For the double-byte space characters that can be specified in ncspace, see Table H-4 Double-byte space characters specified in ncspace.
- flags (input)
- Specifies the conversion type. Available conversion types are as follows:
Macro name |
Conversion type |
p_rdb_HALF_TO_FULL_SPACE |
Single-byte space double-byte space |
p_rdb_FULL_TO_HALF_SPACE |
Double-byte space single-byte space |
- Return values
- data type: int
- p_rdb_RC_RTRN(0)
- Normal termination.
- p_rdb_RC_ERRINVF(-8)
- Invalid flags argument
- p_rdb_RC_ERRTYPC(-9)
- Invalid data type
- Notes
- The National Language Support (NLS) facility provided by the OS is used to convert double-byte spaces into single-byte spaces. Therefore, before invoking the space conversion function, you must use the setlocale function to set an appropriate locale to the LC_CTYPE or LC_ALL category. Additionally, for a Windows UAP, a Linux UAP with a character code type of SJIS, or a UAP with a character code type of CHINESE, you must invoke the p_rdb_set_lang function before invoking the space conversion function. For details about the p_rdb_set_lang function, see H.4 Character code type specification function.
If the character code type of the character string indicated by the srcp argument contradicts the locale specified by the setlocale or p_rdb_set_lang function, the operation cannot be guaranteed.
- Operation is guaranteed if the data input area is the same as the data output area, or if the output area is located before the input area and the latter half of the output area overlaps the first half of the input area.
- Be sure to specify an appropriate value in srcl because the function does not check the length of a character string for any error.
- The function uses 0x20 as the character code for a single-byte space and the character code specified in the ncspace argument as the character code for a double-byte space.
- The data types that can be specified for input are NCHAR, NVARCHAR, MCHAR, and MVARCHAR.
- For a variable-length character string, the function references srcl to determine the length of character string to be converted. Specify the length without the real length section in the srcl argument.
- The real length section of a variable-length character string remains unchanged after space conversion.
- If the character code type is Unicode, the operation of this function cannot be guaranteed. If the character code type is Unicode, use the p_rdb_conv_space_utf8 function. For details on this function, see (c) Space conversion function (p_rdb_conv_space_utf8).
- Function
- This function converts double-byte spaces into single-byte spaces when the character code is Unicode (UTF-8). It converts each double-byte space inside a character string into two single-byte spaces.
- This function applies space conversion to the space characters inside the character string indicated by srcp. The conversion result is stored in destp and the character string length following the conversion is stored in destl.
- The following table shows the combinations of the stype and flags arguments, along with conversion details.
stype (data type) |
flags (conversion type) |
Single-byte spaces -> Double-byte spaces |
Double-byte spaces -> Single-byte spaces |
MCHAR |
An error occurs. |
Character codes are checked from the beginning, and any double-byte spaces# found are converted into single-byte spaces. |
MVARCHAR |
#: 0xE38080 is treated as a double-byte space character code.
- Header files
- #include <pdauxcnv.h>
- This header file is required to use the space conversion function.
- #include <pdbsqlda.h>
- This header file lets you use macros (with a name beginning with PDSQL_) to specify a data type code. If the data type code is to be retrieved from a data dictionary table, this header file is not necessary.
- Format
int p_rdb_conv_space_utf8(char *srcp,
unsigned char stype,
unsigned int srcl,
char *destp,
unsigned int *destl,
int flags) ;
|
- Arguments
- srcp (input)
- Specifies the start address of the character string storage area.
- stype (input)
- Specifies the data type before conversion. The following table shows the data types that can be specified:
Macro name |
Data type |
PDSQL_MCHAR |
MCHAR |
PDSQL_MVARCHAR |
MVARCHAR |
- srcl (input)
- Specifies the length of the character string specified by srcp. For a variable-length character string, this argument specifies the length (units: bytes) of the character string actually stored in the area indicated by srcp.
- destp (output)
- Specifies the start address of the character string storage area after conversion. The area indicated by destp must be allocated in the system that invokes the space conversion function.
- destl (output)
- Specifies the length of the character string specified by destp. For a variable-length character string, this argument specifies the length (units: bytes) of the character string actually stored in the area indicated by destp.
- flags (input)
- Specifies a conversion type. The following table shows the conversion types:
Macro name |
Conversion type |
p_rdb_FULL_TO_HALF_SPACE |
Double-byte spaces -> Single-byte spaces |
- Return values
- Data type: int
- p_rdb_RC_RTRN(0)
- Normal termination
- p_rdb_RC_ERRINVF(-8)
- Invalid flags argument
- p_rdb_RC_ERRTYPC(-9)
- Invalid data type
- Notes
- This space conversion function is used only for Unicode (UTF-8).
- Before invoking this function, you must set UTF8 for the lang argument and invoke the p_rdb_set_lang function. For details about the p_rdb_set_lang function, see H.4 Character code type specification function.
- If the data input area is the same as the data output area, or if the output area is located before the input area and the second half of the output area overlaps with the first half of the input area, the correct operation of the function is guaranteed.
- Because errors related to character string length are not checked, you must enter an appropriate value in srcl.
- The single- and double-byte space codes use 0x20 and 0xE38080, respectively.
- The data types that can be set for the input are MCHAR and MVARCHAR.
- When a character string has a variable length, srcl is referenced for the length of the character string to be converted. Specify for srcl a length that excludes the effective-length portion.
- Because space conversion converts each double-byte space (3 bytes) into two single-byte spaces (2 bytes), the length of the character string following conversion is shorter than that before the conversion.
- When a character string has a variable length, the effective-length portion of the area for storing character strings following conversion stores the data length following the conversion.
- The data inside the area for storing character strings following conversion is guaranteed only for the length specified in destl.
- If this function is invoked by a character code other than Unicode (UTF-8), the operation of this function cannot be guaranteed.
All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.