Brief: Now you can give your users the ability to check text fields for spelling errors. This article offers you a utility that makes it easy to implement this capability for your own applications.

Computerized spelling aids are an important feature of word processing software. They allow the user to quickly locate and correct misspelled words in a document. OfficeVision/400 offers this capability, but only from within its own environment. With V2R3 of OS/400, two new application program interfaces (APIs) allow you to put spell-checking capabilities into your own applications. To make it easy, I have created the Spell Check Text (SPLCHKTXT) command which you can use to perform this function.

You usually find spell-checking capabilities only in word processing software. However, any application which allows the user to enter free-form text (e.g., descriptions, comments, notes, instructions) can benefit from this capability. For example, an inventory application which allows a user to create a purchase order may contain a field for special instructions to the vendor. By implementing spell-checking capabilities, the user can ensure that the instructions printed on the purchase order do not contain any spelling errors. This presents a more professional image for your company and eliminates misunderstandings caused by a misspelled word.

I'll begin by showing you what the Spell Check Text utility does; then I'll explain how to add it to your applications. I'll discuss how this utility uses two new APIs to perform the actual check for spelling errors, and I'll also show you how to create your own dictionaries.

Introducing the Spell Check Text Utility

The Spell Check Text utility analyzes words in a text string. Each word in the string is looked up in a spelling aid dictionary (more on this in a moment). When a word is not found in a dictionary, you are presented with a window as illustrated in 1. The window shows the word in question and allows you to type in a correction. It also contains a list of suggested words from which you can make a selection. Using this window, you can accept the original word, type in a correction to the word or select a word from the list. When you press Enter, the Spell Check Text utility continues to check the spelling of the remaining words in the text string. Pressing F3 or F12 at the window cancels the spell-checking process for the remaining words in the string.

The Spell Check Text utility analyzes words in a text string. Each word in the string is looked up in a spelling aid dictionary (more on this in a moment). When a word is not found in a dictionary, you are presented with a window as illustrated in Figure 1. The window shows the word in question and allows you to type in a correction. It also contains a list of suggested words from which you can make a selection. Using this window, you can accept the original word, type in a correction to the word or select a word from the list. When you press Enter, the Spell Check Text utility continues to check the spelling of the remaining words in the text string. Pressing F3 or F12 at the window cancels the spell-checking process for the remaining words in the string.

A spelling aid dictionary is an object (type *SPADCT) which contains a list of words used to correct spelling errors when a spell-check function is requested. There are two types of spelling aid dictionaries. Those supplied by IBM are called IBM language dictionaries. Those which you create on your own are called user dictionaries.

If you have the OfficeVision/400 licensed program, you should find one or more IBM language dictionaries on your system. IBM language dictionaries are available for most major languages including English, French, Italian, German and Spanish, as well as many others. The English language dictionary is called US in library QDCT. The utility, by default, uses this dictionary, but you can easily change it to the dictionary of your choice. Use the Work with Spelling Aid Dictionaries (WRKSPADCT) command to verify that you have an IBM language dictionary on your system before implementing the Spell Check Text utility. If you don't find an IBM language dictionary on your system, you can purchase one as a separately chargeable licensed program (5738DCT).

You may never need a spelling aid dictionary other than the IBM language dictionary. However, you can supplement the IBM language dictionary by creating your own user dictionary. You can put into your user dictionary words that are not found in the IBM language dictionary. These additions could include names and addresses or words that are specific to your business. You can then request that the Spell Check Text utility verify spelling against words in your user dictionary as well as the IBM language dictionary. This prevents the utility from prompting you for words which you know are spelled correctly but are outside the mainstream language. For information on how to create a user dictionary, see the accompanying sidebar.

Implementing the Spell Check Text Utility

The Spell Check Text (SPLCHKTXT) command is designed to be incorporated into one of your application programs. Basically, your program passes the command a text string and the command passes back the text with any corrections made by the user.

Look at the prompt for the SPLCHKTXT command in 2. This command contains four parameters. The TEXT parameter allows you to pass up to 256 bytes of text to the command. Although you can specify a constant in this parameter, you would normally specify a character variable loaded from a screen field. The RTNVAR parameter returns the corrected text to your program in another 256-byte character variable. For screen fields longer than 256 bytes, you must run the SPLCHKTXT command repeatedly.

Look at the prompt for the SPLCHKTXT command in Figure 2. This command contains four parameters. The TEXT parameter allows you to pass up to 256 bytes of text to the command. Although you can specify a constant in this parameter, you would normally specify a character variable loaded from a screen field. The RTNVAR parameter returns the corrected text to your program in another 256-byte character variable. For screen fields longer than 256 bytes, you must run the SPLCHKTXT command repeatedly.

The last two parameters specify spelling aid dictionaries. The LNGDCT parameter defaults to QDCT/US, which is the English version of the IBM language dictionary. The USRDCT parameter, which defaults to *NONE, allows you to specify a user dictionary should you decide to use one.

Commands such as SPLCHKTXT, which return information in a program variable, can only be executed from within a CL program. This means that you can't run this command from a command line. It also means that you can't use QCMDEXC to run SPLCHKTXT from within RPG or COBOL programs, which are strong candidates for spell-checking assistance. In this case, I recommend that you call the command- processing program (CPP) directly. Pass the program the same parameters that you would pass to the command and it will run just as if the command had been executed.

How the Spell Check Text Utility Works

The source code for the SPLCHKTXT command is shown in 3. The CPP, TXT003CL, is shown in 4. TXT003CL checks for the existence of the IBM language dictionary and the user dictionary (if specified) and then calls an RPG program to check for misspelled words.

The source code for the SPLCHKTXT command is shown in Figure 3. The CPP, TXT003CL, is shown in Figure 4. TXT003CL checks for the existence of the IBM language dictionary and the user dictionary (if specified) and then calls an RPG program to check for misspelled words.

The TXT003RG program, shown in 5, calls the two APIs that actually perform the spell-checking operation. The program receives the parameters from the TXT003CL program and loads the dictionary names into a data structure so that they can be passed to the APIs. The real work of the program is done in the CHKSPL (check spelling) subroutine.

The TXT003RG program, shown in Figure 5, calls the two APIs that actually perform the spell-checking operation. The program receives the parameters from the TXT003CL program and loads the dictionary names into a data structure so that they can be passed to the APIs. The real work of the program is done in the CHKSPL (check spelling) subroutine.

The CHKSPL subroutine calls the Check Spelling (QTWCHKSP) API. This API accepts a text string containing a list of words and the names of the dictionaries to be used as spelling references. The API returns any words in the text string which are not found in the dictionaries. These words are considered misspelled. A counter is also returned, specifying the number of misspelled words. For each misspelled word, TXT003RG executes the AIDSPL (aid spelling) subroutine.

The AIDSPL subroutine calls the Aid Spelling (QTWAIDSP) API which has parameters almost identical to those used for the Check Spelling API. The difference is that instead of accepting a string of words, this API accepts only one word at a time. For each word, the Aid Spelling API returns a list of suggested spellings to the program. These suggestions are loaded into a subfile and displayed in a window on the screen. The display file for the window, TXT003DF, is shown in 6. The results from the screen are analyzed to determine if the user has changed the word or made a selection. If the user changes the misspelled word, the RPLWRD (replace word) subroutine is executed.

The AIDSPL subroutine calls the Aid Spelling (QTWAIDSP) API which has parameters almost identical to those used for the Check Spelling API. The difference is that instead of accepting a string of words, this API accepts only one word at a time. For each word, the Aid Spelling API returns a list of suggested spellings to the program. These suggestions are loaded into a subfile and displayed in a window on the screen. The display file for the window, TXT003DF, is shown in Figure 6. The results from the screen are analyzed to determine if the user has changed the word or made a selection. If the user changes the misspelled word, the RPLWRD (replace word) subroutine is executed.

The RPLWRD subroutine puts the new word in place of the old one. It accomplishes this by retrieving the text to the left and right of the old word within the text string. It then pieces together the left-hand text, the new word and the right-hand text to create the new text string. This new text string is ultimately passed back to your application program.

Poor Spellers, Help Has Arrived

Like most people, I'm not a perfect speller. But you wouldn't know it by reading this article. That's because my word processor let me check this article for spelling errors before you had a chance to read it. Now you can give your users this same capability from within your AS/400 applications.

Not only do spelling errors make your users look bad; if errors are seen by customers, they tarnish the image of your whole organization. Implement the Spell Check Text utility to give your users online, spell-checking capabilities. You'll be saving them the time they would spend manually looking up questionable words in a dictionary. You'll also give them confidence that the data they entered into the AS/400 is correctly spelled

Robin Klima is a senior technical editor at Midrange Computing.

Creating a User Dictionary

A user dictionary is a specialized spelling aid dictionary (object type *SPADCT) which you can create on your system. Your user dictionary should contain any frequently used words in your industry that the IBM language dictionaries do not contain. You can specify a user dictionary in the USRDCT parameter of the Spell Check Text (SPLCHKTXT) command. The SPLCHKTXT utility will then consider those words to be correctly spelled when it encounters them in a text string. Although OfficeVision/400 provides a method of creating a user dictionary, you can also accomplish the task without using OfficeVision. The following instructions describe how to perform this task.

Use SEU command to create a source member in a source physical file, and specify SPADCT for the source type (TYPE) parameter.

Enter the words you want to add to your user dictionary. Words can be entered in any order. More than one word can be entered on the same line as long as you leave at least one space between words. Words entered in uppercase, lowercase or mixed case are treated the same. Since single hyphens are ignored (e.g., mother-in-law = motherinlaw), you must use double hyphens to represent a single hyphen (e.g., father--in--law = father-in-law).

Use the Create Spelling Aid Dictionary (CRTSPADCT) command to create the dictionary. You can use option 14 in PDM as long as the member type is SPADCT. Although you can take most of the default values on the CRTSPADCT command, you might want to consider changing some parameters.

The Base Dictionary (BASEDCT) parameter is optional. If specified, words for the dictionary being created come from two sources: the source member and the user dictionary specified in this parameter. This allows you to combine words from another user dictionary with your new list. (An IBM language dictionary cannot be specified in this parameter.)

The Verify Dictionary (VFYDCT) parameter specifies the name of a dictionary that is checked for each word in the source member. Only those words not found in the verification dictionary are added to the dictionary being created. The verification dictionary can be another user dictionary or an IBM language dictionary. This allows you to avoid words already included in another dictionary.

The Language Attribute (LNGATR) parameter specifies the extended attribute for the dictionary object being created, as well as the processing rules which apply to that dictionary when it is used. Because each language has its own structure, specifying the language attribute allows the system to create and store the dictionary more efficiently. The default is *NONE, but you can to change it to *ENGLISH or a number of other languages such as *ESPANA, *FRANCAIS or *ITALIANO.

The CRTSPADCT command creates a spool file which you can view to determine the number of words that were processed and the number of words added to your dictionary. Once you have created a user dictionary, you can then use it in the USRDCT parameter of the SPLCHKTXT command.

The Spell Check Text (SPLCHKTXT) Command

Figure 1 The Spell-check Window

 .................................. : Spell Check : : : : Word MISPELED : : : : Correct word or make selection : : 1=Select : : : : Opt Suggested spelling : : _ MISSPELLED : : _ MISPLAYED : : _ MISPLACED : : _ MISRULED : : _ MISFILED : : _ MISLABELED : : Bottom : : : : F3=Exit F12=Cancel : :................................: 
 
 The Spell Check Text (SPLCHKTXT) Command
 
 Figure 2 Prompting the SPLCHKTXT Command
 
 Spell Check Text (SPLCHKTXT) Type choices, press Enter. Text to spell check . . . . . . TEXT _______________________________ _______________________________________________________________________________ _ _______________________________________________________________________________ _ _________________________________________________________________ CL variable for returned text . RTNVAR ___________ Language dictionary . . . . . . LNGDCT US Library . . . . . . . . . . . QDCT User dictionary . . . . . . . . USRDCT *NONE Library . . . . . . . . . . . *LIBL Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys 
 
 The Spell Check Text (SPLCHKTXT) Command
 
 Figure 3 The SPLCHKTXT Command
 
 /*================================================================*/ /* To compile: */ /* */ /* CRTCMD CMD(XXX/SPLCHKTXT) PGM(XXX/TXT003CL) + */ /* SRCFILE(XXX/QCMDSRC) ALLOW(*IPGM) */ /* */ /*================================================================*/ SPLCHKTXT: CMD PROMPT('Spell Check Text') PARM KWD(TEXT) TYPE(*CHAR) LEN(256) MIN(1) + PROMPT('Text to spell check') PARM KWD(RTNVAR) TYPE(*CHAR) LEN(256) + RTNVAL(*YES) MIN(1) PROMPT('CL variable + for returned text') PARM KWD(LNGDCT) TYPE(QUAL1) PROMPT('Language + dictionary') PARM KWD(USRDCT) TYPE(QUAL2) PROMPT('User + dictionary') QUAL1: QUAL TYPE(*NAME) DFT(US) QUAL TYPE(*NAME) DFT(QDCT) SPCVAL((*LIBL)) + PROMPT('Library') QUAL2: QUAL TYPE(*NAME) DFT(*NONE) SPCVAL((*NONE)) QUAL TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL)) + PROMPT('Library') 
 
 The Spell Check Text (SPLCHKTXT) Command
 
 Figure 4 CL Program TXT003CL
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/TXT003CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ TXT003CL: + PGM PARM(&TEXT &RTNVAR &LNGDCT &USRDCT) DCL VAR(&TEXT) TYPE(*CHAR) LEN(256) DCL VAR(&RTNVAR) TYPE(*CHAR) LEN(256) DCL VAR(&LNGDCT) TYPE(*CHAR) LEN(20) DCL VAR(&USRDCT) TYPE(*CHAR) LEN(20) DCL VAR(&MSGID) TYPE(*CHAR) LEN(7) DCL VAR(&MSGF) TYPE(*CHAR) LEN(10) DCL VAR(&MSGFLIB) TYPE(*CHAR) LEN(10) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(80) /* Send all errors to error handling routine */ MONMSG MSGID(CPF0000 IWS0000) EXEC(GOTO CMDLBL(ERROR)) /* Check for existence of language dictionary */ CHKOBJ OBJ(%SST(&LNGDCT 11 10)/%SST(&LNGDCT 1 10)) OBJTYPE(*SPADCT) /* Check for existence of user dictionary */ IF COND(%SST(&USRDCT 1 10) *NE '*NONE') THEN(CHKOBJ + OBJ(%SST(&USRDCT 11 10)/%SST(&USRDCT 1 10)) OBJTYPE(*SPADCT)) ELSE CMD(CHGVAR VAR(&USRDCT) VALUE(' ')) /* Call program to spell check text */ CALL PGM(TXT003RG) PARM(&TEXT &RTNVAR &LNGDCT &USRDCT) /* Branch around error handling routine */ GOTO CMDLBL(ENDPGM) /* Error handling routine */ ERROR: + RCVMSG MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) MSGF(&MSGF) + MSGFLIB(&MSGFLIB) SNDPGMMSG MSGID(&MSGID) MSGF(&MSGFLIB/&MSGF) MSGDTA(&MSGDTA) + MSGTYPE(*ESCAPE) ENDPGM: + ENDPGM 
 
 The Spell Check Text (SPLCHKTXT) Command
 
 Figure 5 RPG Program TXT003RG
 
 *=============================================================== * To compile: * * CRTRPGPGM PGM(XXX/TXT003RG) SRCFILE(XXX/QRPGSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 FTXT003DFCF E WORKSTN F RN KSFILE WDWSFL E RTN 256 1 ICHKVAR DS 512 I B 13 160CHKAVL I B 17 200CHKOFF I B 21 240CHKLEN IAIDVAR DS 512 I B 13 160AIDAVL I B 29 320AIDOFF I B 33 360AIDLEN IINPDCT IDS 172 I I 12 B 1 40DCTOFF I I 1 B 5 80DCTNUM I I 0 B 9 120DCTRSV I 13 32 INPDC1 I 33 52 INPDC2 IWKFLDS IDS I I 512 B 1 40RCVLEN I I 172 B 5 80INPLEN I B 9 120WRDLEN I B 13 160OUTDCT I B 17 200OUTLEN I B 21 240OFFBIN I 21 24 OFFCHR I B 25 280LENBIN I 25 28 LENCHR IERROR IDS I B 1 40BYTPRV * C *ENTRY PLIST C PARM TEXT 256 C PARM RTNVAR256 C PARM LNGDCT 20 C PARM USRDCT 20 * * Load input dictionary data structure C MOVELLNGDCT INPDC1 C USRDCT IFNE *BLANKS C MOVELUSRDCT INPDC2 C Z-ADD2 DCTNUM C ENDIF * * Check spelling of input string C EXSR CHKSPL * C MOVE *ON *INLR ***************************************************************** C CHKSPL BEGSR * C MOVELTEXT RTNVAR C ' ' CHEKRTEXT WRDLEN C Z-ADD0 COUNT 30 C Z-ADD1 ST 30 * * Call "Check Spelling" API to retrieve misspelled words C CALL 'QTWCHKSP' C PARM CHKVAR C PARM RCVLEN C PARM 'CHKW0100'FMTNAM 8 C PARM TEXT C PARM WRDLEN C PARM INPDCT C PARM INPLEN C PARM OUTDCT C PARM OUTLEN C PARM ERROR * * Process misspelled words until no more or user cancels C COUNT DOWLTCHKAVL C *IN03 ANDEQ*OFF C CHKOFF ADD 1 X 40 C 4 SUBSTCHKVAR:X OFFCHR C ADD 4 X C 4 SUBSTCHKVAR:X LENCHR C ADD CHKLEN CHKOFF C OFFBIN ADD 1 X C LENBIN SUBSTCHKVAR:X WRD 25 P C Z-ADDLENBIN LENWRD 30 C EXSR AIDSPL C END * C ENDSR ***************************************************************** C AIDSPL BEGSR * * Clear subfile C MOVE *OFF *IN90 C MOVE *ON *IN91 C WRITEWDWCTL C MOVE *OFF *IN91 C Z-ADD0 RN 40 * C ' ' CHEKRWRD WRDLEN C Z-ADDWRDLEN WL 30 C WRD:WL SCAN RTNVAR:ST ST * * Call "Aid Spelling" API to retrieve suggested spellings C CALL 'QTWAIDSP' C PARM AIDVAR C PARM RCVLEN C PARM 'AIDW0100'FMTNAM C PARM WRD C PARM WRDLEN C PARM INPDCT C PARM INPLEN C PARM OUTDCT C PARM OUTLEN C PARM ERROR * * Load suggested spellings into subfile C AIDAVL IFGT 0 C DO AIDAVL C AIDOFF ADD 1 X 40 C 4 SUBSTAIDVAR:X OFFCHR C ADD 4 X C 4 SUBSTAIDVAR:X LENCHR C ADD AIDLEN AIDOFF C OFFBIN ADD 1 X C MOVE *BLANKS SFOPTN C LENBIN SUBSTAIDVAR:X SFWORD P C MOVE *ON *IN90 C ADD 1 RN C WRITEWDWSFL C END C END * * Display window containing suggested spellings C ADD 1 COUNT C MOVELWRD CTWORD C WRITEWDWFTR C EXFMTWDWCTL C MOVE 'N' REPLCD 1 * * Check to see if user changed the word C WRD IFNE CTWORD C MOVELCTWORD RPWORD 25 C EXSR RPLWRD C ENDIF * * Check to see if a selection was made C *IN90 IFEQ *ON C READCWDWSFL 99 C *IN99 DOWEQ*OFF C SFOPTN IFEQ '1' C MOVELSFWORD RPWORD C EXSR RPLWRD C MOVE *ON *IN99 C ELSE C READCWDWSFL 99 C ENDIF C ENDDO C ENDIF * C REPLCD IFEQ 'N' C ADD WL ST C ENDIF * C ENDSR ***************************************************************** C RPLWRD BEGSR * C MOVE 'Y' REPLCD C MOVE *BLANKS LEFT 256 C MOVE *BLANKS RIGHT 256 C ST SUB 1 X * C X IFGT 0 C X SUBSTRTNVAR LEFT C ENDIF * C 257 SUB ST Y 30 C SUB WRDLEN Y C WRDLEN ADD ST X * C Y IFGT 0 C Y SUBSTRTNVAR:X RIGHT C ENDIF * C MOVEALEFT RTN C MOVEARPWORD RTN,ST C ' ' CHEKRRPWORD RPWDLN 30 C ST ADD RPWDLN X C MOVEARIGHT RTN,X C MOVEARTN RTNVAR C ADD RPWDLN ST * C ENDSR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
 
 The Spell Check Text (SPLCHKTXT) Command
 
 Figure 6 Display File TXT003DF
 
 *=============================================================== * To compile: * * CRTDSPF FILE(XXX/TXT003DF) SRCFILE(XXX/QDDSSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 A DSPSIZ(24 80 *DS3) A CA03(03) A CA12(03) A R WDWSFL SFL A SFOPTN 1A B 9 2VALUES(' ' '1') A SFWORD 25A O 9 6 A R WDWCTL SFLCTL(WDWSFL) A SFLSIZ(0007) A SFLPAG(0006) A WINDOW(WDWFTR) A KEEP A OVERLAY A 90 SFLDSP A N91 SFLDSPCTL A 91 SFLCLR A N03 SFLEND(*MORE) A 1 11'Spell Check' A DSPATR(HI) A 3 1'Word' A DSPATR(HI) A CTWORD 25A B 3 6CHECK(LC) A 5 1'Correct word or make selection' A COLOR(BLU) A 6 3'1=Select' A COLOR(BLU) A 8 1'Opt' A DSPATR(HI) A 8 6'Suggested spelling' A DSPATR(HI) A R WDWFTR A WINDOW(3 25 17 30 *NOMSGLIN) A WDWBORDER((*DSPATR HI)) A 17 1'F3=Exit' A COLOR(BLU) A 17 11'F12=Cancel' A COLOR(BLU) A R DUMMY ASSUME A 1 2' ' *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7