5.20 Error Processing and Codes

GoFiler Legato Script Reference

Legato v 1.5b

Application v 5.24b

Table of Contents	< < Previous	Next >>

Chapter Five — General Functions (continued)

5.20 Error Processing and Codes

5.20.1 Overview

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.

5.20.2 Integer Return Values

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.

5.20.4 Handle Return Values

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:

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.

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

5.20.6 Get Last Error Data

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.

5.20.7 IsError Function

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 ...
  }

5.20.8 IsCancel Function

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.