14.2 The war of 1426-1429 | Microsoft Office Automation with Visual FoxPro

The war of 1426 1429

No, we re not talking about a centuries-old battle here, we re talking about a series of error numbers. But we re certain you ll battle these four errors frequently while writing Automation code. These four errors are raised by the Automation server sending back an error code. Which one you get depends on how much information the server is willing to provide. This is the frustrating part: there isn t any categorical difference between these errors, and each error has a variety of meanings. These four errors return every possible problem from every Automation server; in contrast, FoxPro has hundreds of error messages!

Before you think that this is an awful design, remember that FoxPro is receiving the errors in a standard COM/Automation interface. There isn t any way to assign a unique error number to every possible error in every possible server even if we could ensure the errors are unique across servers, we d have error numbers larger than GUIDs, which would cause other problems.

So why is it so frustrating to work with these four errors? You can t tell the difference between a fatal error (the server has disconnected), a syntax error, and an error that can be fixed (like a divide by zero error) by the number. Yes, it is possible to keep a meticulous database of the text and number of each error for each server, but because of the volume of errors, it s very hard to track every error you come across and stay on-track with your development efforts.

Subtle differences

As we said before, the difference between these errors is in the quantity of information the server is willing to provide. Error 1426, "OLE error code 0x,"is the most simplistic. It returns only a character string containing the hexadecimal number and a short message, for example: "OLE error code 0x800706ba: The RPC server is unavailable." In your error handler, ERROR() returns 1426, and MESSAGE() returns "OLE error code 0x800706ba: The RPC server is unavailable."

Errors 1427, 1428, and 1429 all appear to return similar information: an exception code followed by the message. While FoxPro sees them as different errors, their messages seem eerily similar. The differences may lie in what is returned in the AERROR() function.

Visual FoxPro s AERROR() function returns more information for an error. It builds an array with seven columns containing various information, depending on whether it is a FoxPro, OLE, or ODBC error. Help indicates that most FoxPro errors return nulls for most of the entries, with the exception of OLE errors 1427 and 1429, and ODBC error 1526. In fact, OLE errors 1426 and 1428 also make good use of AERROR().

Table 2 lists the contents of the resulting AERROR() array. Error 1426 sets only the first three values; the remaining four are set to null values. Errors 1427, 1428, and 1429 use up to seven columns of the array.

Table 2. The contents of the AERROR() array, using a 1429 error generated by Excel. The described positions reflect those for OLE errors only; not general FoxPro errors or ODBC errors, which have different descriptions.

Position	Contents	Example
1	The error number. Same as ERROR().	1429
2	Text of the VFP error message. Same as MESSAGE(). Note that this is a concatenation of some of the other information in this array.	"OLE IDispatch exception code 0 from Microsoft Excel: Unable to set the Bold property of the Font class"
3	The text of the OLE message.	"Unable to set the Bold property of the Font class"
4	The application sending the message.	"Microsoft Excel"
5	The application s Help file, if available (.Null. if not).	"c:\Program Files\Microsoft Office\Office\1033\xlmain9.chm"
6	The Help context ID, if available (.Null. if not).	0
7	The OLE 2.0 exception number.	0

Error 1426 sets the first three columns. The first is the error number, which is the same as querying ERROR(). The second is the VFP error message the one that s displayed in the error dialog box, as in: "OLE error code 0x80020026: Unknown name." This is the same string that is returned from the MESSAGE() function. The third column contains only a portion of the text string; it is the string returned from the OLE server. VFP adds some standard text to clarify the message; in the case of 1426, it s "OLE error code 0x." While you can parse that out of the string, it s probably easier just to check the third column of the array, which contains the error code followed by the message: "80020026: Unknown name." Actually, it s even easier to check SYS(2018), the most recent error message parameter function. The remaining AERROR() array columns are .Null., like any other VFP error.

Errors 1427 1429 fill all columns of the array (if the Help file and Help Context ID are available). As you can see from Table 1, the VFP message is a concatenation of a standard message ("OLE IDispatch exception code "), the exception number (column 7), the application name (column 4), and finally the text of the OLE message (column 3). The text of the message (column 3) is also the value returned by SYS(2018), the most recent error message parameter, which is different from error 1426, which returns just the text (as in column 3). Actually, SYS(2018) returns only the first 255 characters of the message, which can be significant in longer messages, as we ll see later on.

As we wrote this chapter, it became evident that 1426 and 1429 are the most common errors. In fact, in our hunt for error examples, we couldn t even bag a live error 1427 or 1428. This does not mean that you will never see an error 1427 or 1428; instead, it means that we haven t encountered every Office Automation error (though it sure seems that we have!). While Office may not use these errors, other COM objects might, so we strongly recommend that you build your error handler to handle 1427 and 1428, just in case.
Some interesting error observations

To really see how frustrating handling these errors can be, a few examples are in order. The first example shows the range of how informative these errors can be. For example, imagine the following line of code (yes, it has a typo in it, to illustrate our point):

oChart.ChartWizrd(oExcel.Sheets(cSheetName).Range(cGraphRange), ;

xlColumn, 6, xlColumns, 1, 1, 1, "", "", "Assets", "")

The resulting error message is shown in Figure 1.

Figure 1. A sample error, 1426, obtained by a misspelled method name. While its conciseness is admirable, a bit of help on exactly what the unknown name is would be helpful.

Just a bit brief, no? Especially since our example has no fewer than five names in it: the references to oExcel, oChart, the ChartWizard method (which is the culprit here), the Sheets object, and the Range object. To be fair, VFP is reporting what it received from the server, so we can blame the server for its omission of one small, but very helpful, piece of information.

On the flip side, there s this error that comes from the following line of code. This line references a file that doesn t exist:

oWord.Documents.Open("Test.Doc")

This error, number 1429, is shown in Figure 2.

Figure 2. Another error, 1429, offers a lot of information. There s so much information, it even has a scroll bar!

This message is so unusually long and informative, the error message box actually has a scroll bar to allow you to read the full text of the message! The full text of the error message is as follows:

OLE IDispatch exception code 0 from Microsoft Word: This file could not be found.

Try one or more of the following:

* Check the spelling of the name of the document.

* Try a different file name.

(Test.Doc).

It was while testing this error that we found that SYS(2018) contains only the first 255 characters.

Another situation is that the same error number gives different kinds of errors that need to be handled differently. One kind of error is the syntax error, those pesky typos that the compiler usually catches, or the run-time notification that informs you that you ve reversed those two parameters. Another kind of error is when the user is notified that their system is improperly configured, or they ve made a mistake. Almost all FoxPro errors fall into one category or the other, so it s much easier to handle each individual error.

Errors 1426 1429 return errors in both of these categories (and any other category you can think of). To illustrate, let s pick on error 1426. We ve already talked about "OLE error code 0x80020026: Unknown name," shown in Figure 1, which generally means there s a misspelled method or property in the code and the developer needs to fix the code. The error handler can gracefully skip this line, shut down the module, or whatever action is appropriate (ideally, the developer fixes this before it gets to the user!). In contrast to that situation, Figure 3 shows a different error: "OLE error code 0x800706ba: The RPC server is unavailable." This error can show up on two occasions: when you re opening the server and it doesn t start up correctly (or doesn t start up all), or later, after your program opens the server, and the user closes it before your program is finished with it. Another 1426 classic is "OLE error code 0x80080005: Server execution failed." This means that the server is registered, but the actual EXE file isn t found (usually due to the user uninstalling by deleting the folder instead of using the Uninstall routine). These last two errors are handled a bit differently than a syntax error! Who knows how many other errors are returned as 1426.

Figure 3. Another error 1426, this one indicating the server is unavailable. Automation errors can return nearly any kind of error (including syntax errors, run-time errors, and configuration errors), which makes programming your error handler a bit tricky.