E Error Handling

 E.1 The STATUS Argument and Error Reporting
 E.2 Error Codes

E.1 The STATUS Argument and Error Reporting

All TRANSFORM routines carry a final integer STATUS argument and adhere to the ADAM inherited error handling strategy. Unless otherwise indicated, a routine which finds that STATUS is not set to SAI__OK11 on entry will assume an error has occurred in a previous routine and will return immediately without action and without accessing other arguments (which may not be defined under error conditions). The value of the STATUS argument will not be changed. This behaviour usually allows tests of the STATUS value to be deferred until after several routine calls have been made.

If a TRANSFORM routine is called with STATUS set to SAI__OK, then it will attempt to execute. If it subsequently encounters an error, it will first perform any “cleaning up” which is possible and will then exit with its STATUS argument set to one of the error codes described in the next Section. When a STATUS value is set by a TRANSFORM routine, an associated error report will always be made by calling the ERR routine ERR_REP. The report will normally contain additional information about the circumstances of the error. Transmission of the report to the user will be deferred by the ERR facility pending action by the caller of the TRANSFORM routine (such as a call to ERR_FLUSH to output the error, or ERR_ANNUL to ignore it). The documentation for the ERR facility should be consulted for further details. Exceptions to the rule.  The routines TRN_ANNUL and TRN_CLOSE are exceptions to the above rules. Both of these perform “cleaning up” operations and will therefore attempt to execute regardless of the STATUS value set on entry. If either of these routines fail, they will only set a new STATUS value and make an error report if the value of STATUS was SAI__OK on entry. If STATUS was not set to SAI__OK when they were called, then these two routines will assume that a previous error has occurred and will fail “silently” so that the initial STATUS value and error report are preserved.

E.2 Error Codes

The value returned via the STATUS argument of TRANSFORM routines under error conditions may be:

If it is necessary to test for specific error conditions, then symbolic names (defined by Fortran PARAMETER statements) should be used to identify the associated error codes. Symbolic names for the TRANSFORM error codes are defined in the include file TRN_ERR and may be incorporated into an application with the statement:

  INCLUDE ’TRN_ERR’

The following list gives the names of these error codes, the associated error messages and an explanation of each error condition:

TRN__CLSIN, classification information invalid
The classification information associated with a transformation is invalid. This may be because conflicting classification properties are being specified (e.g. POSITIVE_DET and NEGATIVE_DET) or because a property is being specified in circumstances where it cannot be adequately defined (because the numbers of input and output variables are unequal, for instance).
TRN__CMPER, compilation error
An error has been detected during compilation of the right hand side of a transformation function. The associated error report will give further diagnostic information.
TRN__CMTOF, compiled mapping table overflow
The maximum number of simultaneously active compiled mappings has been exceeded. This error should not be encountered because the permitted number of compiled mappings is very large.
TRN__CONIN, constant syntax invalid
The right hand side of a transformation function contains a numerical constant whose syntax is invalid.
TRN__DELIN, delimiting comma invalid
The right hand side of a transformation function contains an invalid comma (commas are only used to separate the arguments of built-in functions).
TRN__DIMIN, dimensions invalid
An HDS object has inappropriate dimensions for its purpose.
TRN__DSTIN, definition status invalid
The FORWARD or INVERSE component of an HDS transformation structure contains an invalid value. Only the values ‘DEFINED’ and ‘UNDEFINED’ (case insensitive) are allowed.
TRN__DUVAR, duplicate variable name
A variable name is defined (i.e. appears on the left hand side of a transformation function) more than once.
TRN__EXPUD, expression undefined
The expression on the right hand side of a transformation function is missing.
TRN__ICDIR, incompatible transformation directions
An attempt to concatenate two transformations has failed because only the forward mapping was defined within one of them and only the inverse mapping was defined within the other.
TRN__MAPUD, mapping undefined
The mapping requested from a transformation (either forward or inverse) has not been defined.
TRN__MIDIN, compiled mapping identifier invalid
A compiled mapping identifier is not valid (i.e. it is not currently associated with a compiled mapping).
TRN__MIOPA, missing or invalid operand
During compilation of the right hand side of a transformation function, an operand (i.e. a constant, variable or expression) was expected but was not found.
TRN__MIOPR, missing or invalid operator
During compilation of the right hand side of a transformation function, an operator (or delimiter) was expected but was not found.
TRN__MISVN, missing variable name
The variable name is missing from the left hand side of a transformation function.
TRN__MLPAR, missing left parenthesis
The right hand side of a transformation function has a left parenthesis missing.
TRN__MRPAR, missing right parenthesis
The right hand side of a transformation function has a right parenthesis missing.
TRN__NDCMM, number of data coordinates mis-matched
The number of input or output coordinates specified for a set of data points does not match the corresponding number of variables associated with the compiled mapping being used to transform the points.
TRN__NMVMM, number of module variables mis-matched
Two adjacent transformation modules in the MODULE_ARRAY component of an HDS transformation structure are mis-matched because the number of output variables from one module is not equal to the number of input variables for the one which follows.
TRN__NTVMM, number of transformation variables mis-matched
The number of output variables from the first of two transformations being concatenated is not equal to the number of input variables to the second transformation.
TRN__NVRIN, number of variables invalid
The number of variables specified in the NVAR_IN or NVAR_OUT component of an HDS transformation module (TRN_MODULE) structure is invalid (i.e. it is not positive).
TRN__OPCIN, operation code invalid
An invalid internal arithmetic operation code has been encountered while evaluating a transformation function which is part of a compiled mapping. This is a serious error indicating internal inconsistency within the TRANSFORM software. It should be reported immediately.
TRN__PRCIN, precision invalid
An invalid precision specification has been supplied when creating a new transformation.
TRN__TOKIN, token name invalid
An attempt to substitute a value for a token in a character string has failed because an invalid token name has been specified.
TRN__TRNUD, transformation undefined
A set of transformation functions is incomplete or is otherwise insufficient to fully define a transformation.
TRN__TRUNC, character string truncated
A character string has been truncated because the CHARACTER variable supplied is not of sufficient length to accommodate it.
TRN__TYPIN, type invalid
An HDS object has a type inappropriate for its purpose.
TRN__VARIN, variable name invalid
A variable used in a transformation function has an invalid name.
TRN__VARUD, variable name undefined
A variable used on the right hand side of a transformation function is undefined because it does not appear on the left hand side of one of the transformation functions which define the complementary mapping.
TRN__VERMM, software version mis-match
The version number of the TRANSFORM software used to create or last modify an HDS transformation structure exceeds the version number of the software with which the current application is linked.
TRN__WRNFA, wrong number of function arguments
An invalid number of arguments has been supplied for a built-in function invoked from the right hand side of a transformation function.

11SAI__OK is a symbolic constant defined in the include file SAE_PAR.