Legato
Legato

GoFiler Legato Script Reference

 

Legato v 1.6l

Application v 6.6b

  

 

Chapter Five — General Functions (continued)

5.23 Error Processing and Codes

5.23.1 Overview 

Many functions will return the result of success as an error code. ERROR_NONE (0x00000000) 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.

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.

The formatted error structure is used throughout Novaworks applications and carried into user developed Legato scripts. While programmers can adopt their own error reporting methods, using the formatted error code method specified here meshes best with the API scheme.

Finally, some functions will load a textual version or expansion of the error which can be retrieved with the GetLastErrorMessage function. This can be useful when debugging to aid in determining the type of failure through additional textual information. For example, if a function employs array key names to specify parameters, and an invalid or unknown key name is supplied, the textual error message may contain the offending name or index.

5.23.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.23.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 axes. Again, use GetLastError for expanded information.

5.23.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.23.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_32_MASK   0xFFFFFFFF   Formatted Error Code Mask (64-bit Signed Mask)  
    ERROR_MASK   0xFF000000   Error Code Mask  
    ERROR_CLASS_MASK   0xC0000000   Type Error Code Mask  
    ERROR_BIT   0x80000000   All Errors Must Have Bit Set  
  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 inter-window 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, Locking or Accessing 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  
  Combined Items          
  Explicit Local Error          
    ERROR_FATAL_LOCAL    0x80000000   Combined Fatal Error with a Local Code   
    ERROR_SOFT_LOCAL   0xC0000000   Combined Soft Error with a Local Code  
  Cancel Detail          
    ERROR_CANCEL_AUTO   0x00004000   Non-Elective Cancelled (Condition)   
    ERROR_CANCEL_CODE_MASK   0x0000F000   Mask (Avoid File Error Conflicts)  
    ERROR_CANCEL_NO_INFO   0x00000000   No Additional Information   
    ERROR_CANCEL_USER   0x00001000   User Stopped Process   
    ERROR_CANCEL_SELECT_MODE   0x00002000   Invalid Select State   
    ERROR_CANCEL_CONTEXT   0x00003000   Invalid Context or State   
    ERROR_CANCEL_PARAMETER   0x00004000   A Required Parameter is Missing   
  Local Error Detail          
    ERROR_LOCAL_NOT_DEFINED   0x00000001   No Local Code   
    ERROR_LOCAL_NO_RESOURCE   0x00000002   Resource Not Found  
    ERROR_LOCAL_BAD_DATA   0x00000003   Bad Internal Data  
    ERROR_LOCAL_SECURITY_VALIDATION   0x00000004   Error Validating Security   

 

An ambiguity exists with window messages in that when SendMessage fails, the result can be 0, or error none. The ERROR_MESSAGE_OK is used by many Novaworks window classes to provide an affirmative positive result for a call to a window via SendMessage.

The ERROR_REPORTED and ERROR_NOT_REPORTED bit can be used to indicate whether a message box was displayed or the error was added to a process’s log. This is used in specific areas (for example within the Legato script engine) to indicate that the returned error was added to the log. For API functions, it is not generally used.

The ERROR_FATAL_LOCAL and ERROR_SOFT_LOCAL only add semantic information to the returning function as opposed to ERROR_CT_WINDOWS which when added explicitly states the formatted error contains Windows SDK error data.

Certain API functions will return additional information that will be specified in the Return Value section of the function’s documentation.

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

Page revised 2026-11-16