  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
5.20 Error Processing and Codes
Many functions will return the result of success as an error code. ERROR_NONE (0) is the default return value for success. ERROR_NONE can be augmented with additional data.
Error codes provide a practical use. First, they can indicate whether or not a function succeeded as intended. Second, they can provide specific information on how a function failed, if it did. Error codes can contain general information specific the application, windows error codes and function specific error codes.
Legato provides a number of functions to aid in detecting and processing error codes. Many functions will return the same code as provided by the GetLastError function. However, in certain circumstances the return value of a function may be ambiguous with respect to differentiating an actual return value and an error, or the function does not return a simple int or dword and therefore cannot represent a formatted error code. In addition to GetLastError, IsError and IsNotError can be used to test for an error condition. Finally, some functions will load a textual version or expansion of the error which can be retrieved with the GetLastErrorMessage function.
Of course the return value of programmer created functions is up to the developer. However, the formatted error codes are a convenient method of passing error information.
Most functions that return a base integer type as an error will follow the above guidance and structure. If not, the function will specify the return value. For functions that are ambiguous or return an index, -1 will be used to indicate an error and the GetLastError function may be used to expand on the type of error.
5.20.3 String and Array Return Values
If a string is the expected return value, functions will return an empty string. Use GetLastError for expanded information.
In the event of an error where the function returns an array, table or cube, the variable will be zero elements in depth on all axis. Again, use GetLastError for expanded information.
Legato handles are always a non-zero value. NULL_HANDLE (0) is returned to indicate an error. For example, the OpenFile function will return 0 when the target file was not found. In this case, the GetLastError function must be used to retrieve the specific error.
Erroneous native Windows handles may be a either 0 or -1 depending on the underlying Windows handle type. Many native functions and handles consider 0 (or NULL_HANDLE) as an invalid handle value. However, some handle types can be zero, such as native file handles, and as such the value -1 is used to indicate an error or the Windows code as invalid handle (INVALID_HANDLE_VALUE). In general, when using handles for the Legato object, the window handles are managed by the script engine.
5.20.5 Formatted Error Code Structure
Formatted error code formatted in a specific bitwise structure (expressed here in hexadecimal):
0xTTFFCCCC
Where:
TT
The top 8 bits express the message type. Messages fall into three basic categories as expressed by the first 4 bits: fatal (0xC0000000), soft (0xC0000000), or no error (0xC0000000). The next four bits express additional error information such as overflow or end of data. Some fatal errors may cause the script to stop executing.
FF
The next 8 bits contain a series of flags to help clarify the error. The meaning of the bits can change depending on the type of error.
CCCC
The lower 16 bits can express an underlying error code. This is common when dealing with windows errors where the Windows SDK error code will be contained in this lower word. For example, the Windows error ERROR_FILE_NOT_FOUND (2) could possibly be contained in the formatted error code.
The following is an example of an error:
0x85000003
Which translates to ERROR_FILE (0x85000000) which is a soft error of the type file and ERROR_PATH_NOT_FOUND (3) the detailed Windows SDK error. This error could be translated into an English language version using either the TranslateWindowsError or ReportFileError functions.
Within the Legato SDK are the Legato structure error definitions as well as the Win32 SDK common errors up to and including error 200. There are additional codes which require the developer to research MSDN.
The Legato formatted error code definitions are as follows:
| Defined Code | Bitwise Code | Description | ||||
| Error Codes | ||||||
| Control | ||||||
| ERROR_MASK | 0xFF000000 | Error Code Mask | ||||
| ERROR_CLASS_MASK | 0xC0000000 | Type Error Code Mask | ||||
| Code Types | ||||||
| ERROR_CODE_TYPE_MASK | 0x00400000 | Error Code Type Mask | ||||
| ERROR_CT_LOCAL | 0x00000000 | Code is Local (default) | ||||
| ERROR_CT_WINDOWS | 0x00400000 | Code is Windows API Code | ||||
| Optional Report Information | ||||||
| ERROR_REPORTED | 0x00800000 | Error was Reported/Recorded (by default all fatal errors are reported at the point of the error) | ||||
| Data Types (apply to parameters) | ||||||
| ERROR_DATA_TYPE_MASK | 0x00300000 | Error Code Type Mask | ||||
| ERROR_DT_GENERAL | 0x00000000 | General Error (default) | ||||
| ERROR_DT_SOURCE | 0x00100000 | Applies to Source Data | ||||
| ERROR_DT_DESTINATION | 0x00200000 | Applies to Destination Data | ||||
| Cancel Expansion | ||||||
| ERROR_CANCEL_MASK | 0x00300000 | Mask for Cancel Type | ||||
| ERROR_CANCEL_ELECTIVE | 0x00000000 | Cancelled At Request of User | ||||
| ERROR_CANCEL_NON_ELECTIVE | 0x00100000 | Cancelled Because of Condition | ||||
| No Error | ||||||
| ERROR_NONE | 0x00000000 | No Error | ||||
| ERROR_NONE_MASK | 0x000FFFFF | No Error Return Value Mask | ||||
| ERROR_MESSAGE_OK | 0x20000000 | No Error (result for message – Windows interwindow messages can return 0 on error) | ||||
| ERROR_NO_REPORT | 0x00000000 | Error not Reported (semantic) | ||||
| Inter-Window Messages | ||||||
| ERROR_MESSAGE | 0x20000000 | Error/Result is Message | ||||
| Non-Fatal Class Errors | ||||||
| ERROR_SOFT | 0x80000000 | Class (soft error) | ||||
| ERROR_EOD | 0x81000000 | End of Data | ||||
| ERROR_CANCEL | 0x82000000 | Operation was Cancelled | ||||
| ERROR_OVERFLOW | 0x83000000 | Value or String Overflow | ||||
| ERROR_SYNTAX | 0x84000000 | Value or String Syntax Error | ||||
| ERROR_FILE | 0x85000000 | File Windows API Error (with type) | ||||
| ERROR_FUNCTION_NOT_SUPPORTED | 0x86000000 | Function Not Supported | ||||
| ERROR_RANGE | 0x87000000 | Parameter Out of Range | ||||
| ERROR_REMOTE | 0x88000000 | Error from Remote System (Cloud) | ||||
| ERROR_EXIT | 0x89000000 | Function Requests Exit/No error | ||||
| ERROR_CONTEXT | 0x8A000000 | The Context Was Not Correct | ||||
| ERROR_TIME_OUT | 0x8B000000 | A Time Out Occurred in a Routine | ||||
| Fatal Class Errors | ||||||
| ERROR_FATAL | 0xC0000000 | Class (non specified fatal error) | ||||
| ERROR_MEMORY | 0xC1000000 | Error Allocating or Locking Memory | ||||
| ERROR_FILE_IO | 0xC2000000 | File Error, Read/Write/Position | ||||
| ERROR_FILE_INTERNAL | 0xC3000000 | File Error, Internal File | ||||
| ERROR_FILE_EXTERNAL | 0xC4000000 | File Error, External File (user) | ||||
| ERROR_WINDOWS_API | 0xC5000000 | Windows API Error (with type) | ||||
| ERROR_PARAMETER | 0xC6000000 | An Invalid Parameter Was Passed | ||||
| ERROR_RESOURCE | 0xC7000000 | A Resource Could Not be Found | ||||
| ERROR_CONDITION | 0xC8000000 | Invalid Condition Existed in a Routine | ||||
| Error Details | ||||||
| ERROR_CODE_MASK | 0x0000FFFF | Error Code Mask | ||||
Aside from functions that return a formatted error code, there are two methods of retrieving basic error information: the GetLastError function and the GetLastErrorMessage function. The GetLastError function returns the error code. If the function succeeded, it will return ERROR_NONE. The last error is always set by the last called embedded Legato function and is always reset at the start of the next function call (except the GetLastError or GetLastErrorMessage functions).
The GetLastErrorMessage function can return additional information. Not every Legato function sets the value of the last error message. If additional information is not available, the function will translate the last error to a string using the same logic as the TranslateFormattedErrorCode function.
In additional to basic error information, some functions will return data logs. There are two types: an error log and the default output log. An example of a function that returns additional data is the RunScript function, It will return an error log for any program warnings or errors and a default log if the default log is used by the script. The GetLastErrorLog and GetLastDefaultLog functions to return a handle to each of the respective logs. If the log handles are not immediately retrieved, they are automatically closed on the next SDK function that sets error information.
The IsError function is an easy way to check for an error. It simply takes the resulting code and performs a bitwise AND operation with the error mask and then returns TRUE or FALSE depending on the result.
Syntax:
boolean = IsError ( int value );
Return Value
Returns TRUE if value is an error and FALSE if not. Note that -1 counts as an error.
Example:
result = ReadBlock(hFile, buffer);
if (IsError(result)) {
... do some stuff ...
}
The IsCancel function is an easy way to check if a result contains a cancel code. It takes the resulting code and checks for ERROR_CANCEL or ISCANCEL and then returns TRUE or FALSE depending on the result.
Syntax:
boolean = IsCancel ( int value );
Return Value:
Returns TRUE if value is an error and FALSE if not. Note that -1 counts as an error.
Example:
rc = ProgressUpdate(bytes, total);
if (IsCancel(result)) {
... do some stuff ...
}
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.