Check Spelling (QTWCHKSP) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Word list | Input | Char(*) |
| 5 | Length of word list | Input | Binary(4) |
| 6 | Input dictionaries | Input | Char(*) |
| 7 | Length of input dictionaries | Input | Binary(4) |
| 8 | Output dictionaries | Output | Char(*) |
| 9 | Length of output dictionaries | Input | Binary(4) |
| 10 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Check Spelling (QTWCHKSP) API accepts a list of one or more words in the word list parameter, and returns one word array entry in the receiver variable for every word with an indication if it is a valid word. To retrieve additional information about a specific word, see the Aid Spelling (QTWAIDSP) API.
The QTWCHKSP API can be used to do the following:
- Check the spelling of an individual word
- Find misspelled words in a character string
To perform the function, a user can specify a maximum of eight IBM® or user language dictionaries in the input dictionaries parameter.
Authorities and Locks
- Dictionary Authority
- *USE
- Dictionary Library Authority
- *USE
- Dictionary Lock Authority
- *SHRNUP
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information about each word in the word list. You can specify the size of this area to be smaller than necessary to hold information about each word as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. The minimum size of this area is eight bytes.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned in the receiver variable. For more information about the format, see CHKW0100 and CHKW0200 Formats. The following are possible format names:
CHKW0100 Word array entries for only the misspelled words should be returned in the receiver variable. CHKW0200 Word array entries for all words in the word list should be returned.
- Word list
- INPUT; CHAR(*)
A list of one or more words to be checked. The words must be separated by one or more word separators where the blank character is always considered a word separator. The CCSID of the current job determines what code page will be used and each code page defines what other characters can be used as word separators. See the i5/OS globalization topic collection for more information about CCSIDs. See Word Separator Tables for information about word separators.
- Length of word list
- INPUT; BINARY(4)
The length of the word list in bytes.
- Input dictionaries
- INPUT; CHAR(*)
A structure containing a list of up to eight dictionaries to be used to determine if the word or words in the word list are spelled correctly. For the format of this parameter, see Input Dictionaries Format.
- Length of input dictionaries
- INPUT; BINARY(4)
The length of the input dictionaries parameter. The only valid value is 172 bytes.
- Output dictionaries
- OUTPUT; CHAR(*)
A structure containing a list of up to eight dictionaries that were actually used. For the format of this parameter, see Output Dictionaries Format.
- Length of output dictionaries
- INPUT; BINARY(4)
The length of the output dictionaries parameter. The following are valid values:
0 No dictionaries are returned in the output dictionaries parameter. >0 The length of space available in the output dictionaries parameter. If this length is larger than the actual size of the output dictionaries parameter, the results may not be predictable.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
CHKW0100 and CHKW0200 Formats
The following information is returned for both the CHKW0100 and CHKW0200 formats. If the receiver variable is large enough to hold all the information, then it contains information about each word in the word list.
The receiver variable has three logical sections which contain:
- Fixed section
- Word information entry
- An array of the actual input words
For more detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| Note: Fixed section. | |||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of words returned |
| 12 | C | BINARY(4) | Number of words available |
| 16 | 10 | BINARY(4) | Offset to first word information entry |
| 20 | 14 | BINARY(4) | Length of word information entry |
| 24 | 18 | BINARY(4) | Reserved |
| Note: Format of a word information entry. The following four fields are repeated for each word returned. The first word information entry is found by using the offset to first word information entry in the fixed section. Each subsequent word information entry is found by adding the length of a word information entry to the offset of the previous word information entry. | |||
| BINARY(4) | Offset to word | ||
| BINARY(4) | Length of word | ||
| CHAR(1) | Misspelled | ||
| CHAR(*) | Reserved | ||
| Note: The following field is repeated for each word returned. Each word is located by the offset to word field and the length of the word is specified in the length of word field. | |||
| CHAR(*) | Word | ||
Input Dictionaries Format
The following list shows the format of the input dictionaries parameter. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to dictionary entries |
| 4 | 4 | BINARY(4) | Number of dictionary entries |
| 8 | 8 | BINARY(4) | Reserved (must be set to 0) |
| Note: Format of a dictionary entry. The following fields are repeated by the number of dictionary entries. The decimal and hexadecimal offsets depend on the number of dictionary entries. The first dictionary entry is found by using the offset to dictionary entries in the header section. | |||
| CHAR(10) | Dictionary name | ||
| CHAR(10) | Dictionary library name | ||
Output Dictionaries Format
The following shows the format of the output dictionaries parameter. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of dictionaries returned |
| 4 | 4 | BINARY(4) | Number of dictionaries available |
| Note: The following fields are repeated by the number of dictionaries returned. The decimal and hexadecimal offsets depend on the number of dictionaries returned. | |||
| CHAR(10) | Dictionary name | ||
| CHAR(10) | Dictionary library name | ||
Field Descriptions
Bytes available. The total length of all data available.
Bytes returned. The length of the data actually returned. If the receiver variable is not large enough to hold all of the data available, only the data that will fit in the space available is returned and this value will be less that the bytes available.
Dictionary library name. The library containing the language dictionary. The special values for the library name are *CURLIB and *LIBL.
Dictionary name. The name of the language dictionary.One special value for the name is *USERID.
| *USERID | The name of the dictionary is the same as the user ID for the current job. A library name must be specified with this value. |
Length of word. The length of the word in bytes.
Length of word information entry. The length of one item in the word information entry section.
Misspelled. Indicates if the word is misspelled.
| 0 | The word is spelled correctly. |
| 1 | The word is misspelled. |
Number of dictionaries available. The number of dictionaries that were actually used to determine if the word or words in the word list were spelled correctly.
Number of dictionaries returned. The number of dictionaries actually returned in the output dictionaries parameter. If this number is smaller than the number of dictionaries available, then all of the dictionaries could not fit in the space available.
Number of dictionary entries. The number of usable dictionaries to perform the function. Valid values are 1 through 8.
Number of words available. The number of words which are found in the word list.
Number of words returned. The number of words actually returned in the receiver variable. If this number is smaller than the number of words available, then all of the words could not fit in the receiver variable.
Offset to dictionary entries. The byte offset, from the beginning of the parameter, to the beginning of the dictionary entries.
Offset to first word information entry. The byte offset, from the beginning of the receiver variable, to the first item in the word information entry section.
Offset to word. The byte offset, from the beginning of the receiver variable, to the actual word.
Reserved. This field must be set to 0 on the input dictionaries parameter. Otherwise, this field is ignored.
Word. The word that was checked for spelling.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8751 E | Number of dictionaries is not valid. |
| CPF8752 E | No valid dictionaries were found. |
| CPF8753 E | Length of word list not valid. |
| CPF8755 E | Length of input dictionaries not valid. |
| CPF8756 E | Length of output dictionaries not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Office APIs | APIs by category ]