![]() |
![]() |
![]() |
![]() |
![]() |
Error Management System
The coder solution contains error management functions. The error management consists of fault detection, error handling and error output. The error management is optional and can be removed from the application.
The fault detection consists of monitoring code that checks for all kinds of faults when encoding and decoding. When a problem is detected the fault detection part will start the error handler. The monitoring code is controlled by C macros and can be removed by defining macros, see Error checking configuration. The user defined error handling functionality is described in User defined Error Handling.
SDL Suite error output functionality has several error output implementations for the different types of kernels. The behavior is different for simulation and for application. It is possible to register a different error output function. See User defined Error Output.
There are several types of error output functions which can be used to perform error output:
- SDL Suite error output as default
- Coder library error output
- user defined application specific error output functions.
The type of error output to be invoked upon error detection is configured when compiling coder library by compile switches, see Error output configuration.
Error Management Interface
Encode and decode functions return a status code, which is equal to a success code, or one of the error codes in case of failure. Error codes are visible in both SDL and C functional interfaces. If an error occurs, its code is returned by the encoding or decoding function, and is written into the buffer at the same time.
The behavior of the fault detection can be controlled by compilation switches, that are described in Error checking configuration. For instance, it is possible to remove all fault detection by defining a corresponding switch.
Detailed error messages
Error messages contain a type name with a path to the field where an error has occurred. The path contains a sequence of SET/CHOICE/SEQUENCE fields and open type objects from the root type up to the field where an error has occurred.
There are two possible representations for the path:
- Path fields are represented by their names. This representation is available only if one of the following compile switches are present, CODER_TI_NAMES (see Error output configuration) or CODER_VMS_PRINT (see Printing configuration). For example:
ERROR 21 No more data for read at BOOLEAN, type: BOOLEAN, path: yASN1_Type1.field2.comp1- Path fields are represented by their indexes - in this case root type is named "undef" and path contains indexes of SEQUENCE/SET components, CHOICE alternatives and open type objects, for example:
ERROR 21 No more data for read at BOOLEAN, type: undef, path: SEQUENCE.2.1By default the second representation with indexes is used.
If an error occurs within the encoding/decoding then you can unambiguously understand the exact place of the error. For example if we have a complex type with the several nested sequences:
Type1 ::= SEQUENCE {field1 Type2,field2 Type2}Type2 ::= SEQUENCE {comp1 [0] Bool,comp2 [1] Int}Bool ::= [0] BOOLEANInt ::= [1] INTEGERERROR 21 No more data for read at BOOLEAN, type: BOOLEAN, path: yASN1_Type1.field2.comp1
- (in the first representation)
ERROR 21 No more data for read at BOOLEAN, type: undef, path: SEQUENCE.2.1
- (in the second representation)
Then the exact place of the error is known. The error occurred in Bool type in the second nested sequence by the path Type1.field2.comp2 .
The benefits of this feature become significant in a huge ASN.1 specifications with the long nested fields, like UMTS. This is an example of a real error message from the RRC specification (subpart of UMTS):
ERROR 22: Wrong TAGGED identifier octet, type: CPCH_SetInfo_INLINE_3, path: yASN1_DL_DCCH_Message.message.radioBearerSetup.modeSpecificPhysChInfo.fdd.cpch_SetInfo.ap_AICH_ScramblingCode
Detailed error messages (type and path) is used in the ec_VAL_ and ec_DEC_ errors.
The default configuration includes detailed error messages. Detailed messages require extra resources from the speed and from the Type Info size (if names information is enabled). The encoding/decoding speed becomes a bit slower because the feature requires extra manipulations with the stack to store the temporary path. If you do not need to use this feature then you should use CODER_REMOVE_PATH compile switch (see Error handling configuration). Error messages in this case will look like:
ERROR 21 No more data for read at BOOLEAN, type: undef, path: undefSDL error interface
In SDL, error codes are represented by integer values and are defined as Integer synonyms. Names of synonyms are the same as error codes described in Error codes. The file codererrors.sdl contains a complete list of Integer synonyms for coder error codes. This file must be included to the SDL system that is going to check coder error codes after encoding and decoding.
C error interface
In the C error interface, error codes are literals of one big enumerated type, and they can be treated as C integer values. All possible error codes are listed in the file errors.h in the `ems' folder of the library installation (see Files and File Descriptions). For detailed description of error codes see Error codes.
Error codes
If the decode or encode succeeded, ec_SUCCESS is returned.
In case of failure, an error code is returned that helps to understand the reason of the failure. All possible error codes with short descriptions are listed below.
Memory access errors
ec_MEM_NotEnoughMemory
The application has run out of memory and one of the coder library functions can not allocate memory.
Buffer errors
ec_BUF_DifferentBufferTypes
This is a buffer copying error. The BufCopyBuf function belongs to the general buffer interface which supports different buffer types. The error occurs when the source and destination buffers in the copying function are of different buffer types.
ec_BUF_WrongBufferType
The message is reported when the buffer initialize function has been called with the buffer type which has been excluded from the application by compile switches (see Buffers configuration).
ec_BUF_CloseNotInitialized
The message is reported when BufCloseBuf is called on a buffer that has not been initialized.
ec_BUF_WorkWithNotInitialized
One of the two buffer modes, read or write, has to be initialized before accessing the buffer with reading or writing procedures. If a read or write procedure has been applied to a buffer that has not been initialized, the ec_BUF_WorkWithNoneInitialized error is reported.
ec_BUF_NullPtrToUserMemory
BufInitBufWithMemory or BufCloseBufToMemory is called with NULL pointer to user memory.
ec_BUF_NotEnoughUserMemory
This error is specific for buffers that are initialized by the user memory, and it denotes that the size of the user memory assigned to the buffer is not enough for storing data.
ec_BUF_OpenOpened
This error is reported when trying to reopen the buffer which has already has been opened for write or read mode, and has not been closed afterwards.
ec_BUF_IllegalClose
This error is reported when BufCloseBuf is called on the buffer for which one of the modes, reading or writing, has not been closed.
ec_BUF_CloseWrongMode
This error is returned when trying to close the buffer for a mode different from the opened one. This situation can happen, for example, when BufCloseWriteMode follows the function BufInitReadMode, or when BufCloseReadMode is called to the buffer which mode has been initialized by the function BufInitWriteMode.
ec_BUF_OperationWrongMode
This error denotes that you are trying to perform an incorrect operation for the current buffer mode. For example, you are trying to read data from the buffer which has been opened for writing by function BufInitWriteMode.
ec_BUF_NoMoreDataForRead
This error is returned when you are trying to read data from a buffer which is already empty.
ec_BUF_TooBigNumberOfBits
The error is returned when you are trying to put or get more bits from the buffer than it is possible to pass to the bit buffer interface function. The operations BufGetBits and BufPutBits operate with bits stored in the value of type long and can not process more then sizeof(long) number of bits. So when they are called with a number of bits more then sizeof(long), an error message is reported.
ec_BUF_InvalidEncodingRules
This error code is returned when the combination of bit masks passed as the second parameter to the function BufSetRule does not form a valid encoding rule. For example, BufSetRule( buffer, er_BER | er_Aligned ) will return this error code because er_Aligned is an alternative of PER and does not have any sense together with BER.
Value errors
ec_VAL_IllegalRealBase
The real value received for encoding is represented with a base that cannot be handled by the encoder function.
ec_VAL_WrongConstrainedValue
The value passed to the coder function does not satisfy constraints specified for the corresponding type.
ec_VAL_WrongConstrainedLength
The size of the value passed to the coder function does not satisfy the size constraint specified for the corresponding type.
ec_VAL_WrongConstrainedAlphabet
Characters in the string value passed to the coder function do not satisfy the permitted alphabet constraint specified for the corresponding type.
Decoding errors
ec_DEC_NoMoreDataForRead
This error is returned when you are trying to read data from a buffer which is already empty. There is a difference in the formats between ec_DEC_NoMoreDataForRead and ec_DEC_NoMoreDataForRead. ec_DEC_NoMoreDataForRead uses the detailed error message approach (with type and path) but ec_BUF_NoMoreDataForRead does not.
ec_DEC_WrongIdentifierOctet
This is a BER specific error, based on BER encoding TLV (Type-Length-Value) structure. The type information from TLV is stored in a so called identifier octet. If the data in the identifier octet for the sequence of bits to be decoded is wrong (for example, ASN.1 type is defined to be INTEGER, but the identifier octet for the value of that type claims that value to be decoded if of type BOOLEAN), an error is returned.
ec_DEC_WrongLength
For some ASN.1 types, the range of the encoded value length is restricted. When length is out of range, the wrong length error is returned.
ec_DEC_TooBigTagNumber
Tag numbers are stored in the variable of type unsigned long, so the value of a tag is restricted. When the tag number occupies more then 32 bits, restriction is violated and this error message is returned.
ec_DEC_WrongConstructedLengthPrefix
When constructed encoding is used, each group of bytes from the encoding is prefixed by the group information. For example, if it is the last group in the constructed encoding or not, and similar. Constructed encoding prefix occupies 8 bits, but not all bit combinations are meaningful. When the combination is wrong, this error is returned.
ec_DEC_WrongUnusedBits
This is a BER specific error. BIT STRING values in BER are encoded into a sequence of bytes, although they cannot contain exactly an integer number of 8 bits. For correct value encoding, the number of unused bits in the last byte is also encoded. When this number is not in the range between 0 and 7, an error is returned.
ec_DEC_TooBigSubIdent
This object identifier decoding error is reported when the sub-identifier is too big and cannot be stored in the variable of type long (4 bytes).
ec_DEC_WrongRealPrefix
The real value encoding contains a prefix denoting the type of real value that has been encoded, plus infinity and minus infinity real values, zero real value, other common real value (mantissa + base + exponent). The real prefix is encoded into 8 bits but not all of them have meaning. If the real encoding contains a bad prefix, this error is reported.
ec_DEC_UnsupportedRealBase
Trying to decode a real value which has been encoded with a base that is not supported in the coding library.
ec_DEC_UnsupportedRealDecimalEncoding
Decimal encoding of real values is not supported. If real value has been encoded according to decimal real encoding algorithm, the decoder will not be able to decode it and it will return this error code.
ec_DEC_RequiredComponentIsAbsent
This error can be reported when decoding SEQUENCE or SET type values and it denotes that not all required components are present in the value encoding.
ec_DEC_ExtRequiredComponentIsAbsent
This is SEQUENCE and SET decoding specific error. It points out that not all required components from extension addition group are present in the value encoding, although the group itself is encoded as present.
ec_DEC_AbsentComponentIsPresent
This error can appear while decoding a value of sequence or set type with the ABSENT constraint applied. When the component constrained to be absent is present in the encoded value, this error message is reported.
ec_DEC_AbsentAlternativeIsPresent
This error can appear while decoding a value of choice type with the ABSENT constraint applied. When the alternative constrained to be absent is present in the encoded value, this error message is reported.
ec_DEC_UnknownComponent
This is SEQUENCE and SET specific decoding error, and it is reported when the encoded field tag is not a known tag from the type fields of SEQUENCE or SET type.
ec_DEC_UnknownAlternative
This is CHOICE specific error, and it is returned when the encoded choice alternative has got a tag which does not belong to the set of possible tags for the decoded choice type.
ec_DEC_NoOpenId
This is open type specific error. It is reported when open type value can not be decoded because open type identifier field is absent for some reason in the encoding.
ec_DEC_UnknownObject
This is open type specific error. It is reported when decoded open type identifier is not equal to any of identifier in the open type restricting table.
ASCII decoding errors
Each ASCII decoding error refer to a particular type and denotes that there are problems or errors when decoding value of that type, for example, ec_ERROR_DECODING_PARSTART is reported when there are errors when decoding start of signal parameter or variable from the buffer.
All possible ASCII decoding errors are listed below.
ec_ERROR_DECODING_INTEGER ec_ERROR_DECODING_REAL ec_ERROR_DECODING_BOOLEAN ec_ERROR_DECODING_TIME ec_ERROR_DECODING_CHARSTRING ec_ERROR_DECODING_BIT ec_ERROR_DECODING_BITSTRING ec_ERROR_DECODING_OCTET ec_ERROR_DECODING_OCTETSTRING ec_ERROR_DECODING_SIGNALID ec_ERROR_DECODING_STRUCT ec_ERROR_DECODING_CHOICE ec_ERROR_DECODING_POWERSET ec_ERROR_DECODING_BAG ec_ERROR_DECODING_STRING ec_ERROR_DECODING_ARRAY ec_ERROR_DECODING_REF ec_ERROR_DECODING_USERDEF ec_ERROR_UNKNOWN_TYPE_NODE ec_ERROR_DECODING_PARSTART ec_ERROR_DECODING_PAREND
Internal errors
ec_INT_InternalError
This is coder library internal error. If coder function returns this error, please, contact IBM Rational Customer Support. Internal error will never be reported if CODER_CHECK_NONE_INNER compile switch is set up (see Error checking configuration), in this case all internal error checks are removed from the library code.
ec_INT_UnsupportedType
This is also coder library internal error. It is reported when the type specified for the encode or decode function in the ASN.1 type info structure is not supported by the coder library. Internal error will never be reported if CODER_CHECK_NONE_INNER compile switch is set up (see Error checking configuration), in this case all internal error checks are removed from the library code.
Definition of your own error codes
It is possible to specify your own error codes. It might be useful for user encoding rules or user memory management implementation.
If you want to use your own error codes, perform the following steps:
CUCF_ERROR(ec_<error identifier>, "Error message")
Example 482 : File errors_user.h
CUCF_ERROR(ec_MY_ERROR_ONE, "My error one")CUCF_ERROR(ec_ME_ERROR_TWO, "My error two")
- Compile the coder library with the CODER_EC_USER="errors_user.h".
- Add include path for the file errors_user.h to the compilation settings.
User defined Error Handling
This functionality allows to call a user defined error handling function inside the decoding procedure. If an error occurs this function will be called. Combined with the BufGetErrorPath( buffer ) buffer interface (see Buffer Management Functions), error handling function gives an opportunity to insert a default value to the field for which the decoding failed.
An error handler function must be written by the user according to the following format:
typedef void (*tBufErrInitFunc)(tBuffer Buffer);There is an interface in the buffer functionality BufSetErrInitFunc( buffer, func ) that allows to set user error handling by reference into the buffer and it will be used by the decoder. BufGetErrInitFunc( buffer ) returns a reference to an error handling function. By default there is no error handler and it returns NULL. Below there is an example with the user defined error handling.
These two checks between ErrorPath and TypeInfo help to determine the exact place where an error has occurred:
#define EQ_TI(field, ti) \((tASN1TypeInfo*)(field)==(tASN1TypeInfo*)&ti)#define EQ_CMP(field, ti) \(((tASN1Component*)(field))->TypeInfo==(tASN1TypeInfo*)&ti)void TinyErrorHandling(tBuffer b){int res = BufGetErrorCode(b);tErrorPath *ep = BufGetErrorPath(b);LineB* lineB = (LineB *)BufGetMainVal(b);if ( res == ec_VAL_WrongConstrainedValue &&ep->NumOfFields == 2 &&EQ_TI(ep->Fields[0], yASN1_LineB) &&EQ_CMP(ep->Fields[1], yASN1_PointB_INLINE_0)){lineB.point1.x = 40;return;}if ( res == ec_VAL_WrongConstrainedValue &&ep->NumOfFields == 2 &&EQ_TI(ep->Fields[0], yASN1_LineB) &&EQ_CMP(ep->Fields[1], yASN1_PointB_INLINE_1)){lineB.point2.y = 25;return;}}Tiny DEFINITIONS AUTOMATIC TAGS ::=BEGINPointA ::= SEQUENCE {x INTEGER (0..42),y INTEGER (0..26)}PointB ::= SEQUENCE {x INTEGER (0..40), -- lineA.point2.x = 42y INTEGER (0..25) -- lineB.point1.y = 26}LineA ::= SEQUENCE {point1 PointA,point2 PointA}LineB ::= SEQUENCE {point1 PointB,point2 PointB}lineA LineA ::= { point1 { x 11, y 26 }, point2 { x 42, y 24 } }lineB LineB ::= { point1 { x 11, y 25 }, point2 { x 40, y 24 } }ENDThe code example with the encoding of LineA type and LineB as the type for the decoding. The encoded lineA value does not satisfy the LineB constraint and that is why there are two constraint errors:
ERROR 18 Wrong INTEGER constrained value, type: PointB_INLINE_0, path: yASN1_LineB.point1.xERROR 18 Wrong INTEGER constrained value, type: PointB_INLINE_1, path: yASN1_LineB.point2.yThe TinyErrorHandling function catches these errors with a corresponding assignment to the correct values.
BufInitBuf(b, bms_SmallBuffer);BufSetErrInitFunc(b, TinyErrorHandling); /* set TinyErrorHandling as decodingBufInitWriteMode(b);res = ASN1_ENCODE(b, (tASN1TypeInfo *)&yASN1_LineA, lineA);BufCloseWriteMode(b);BufInitReadMode(b);res = ASN1_DECODE(b, (tASN1TypeInfo *)&yASN1_LineB, dec_lineB); /*BufCloseReadMode(b);BufCloseBuf(b);User error handling requires the same resources as for detailed error messages (see Detailed error messages). The encoding/decoding speed becomes slower because of some extra manipulations with the stack. CODER_REMOVE_PATH compile switch (see Error handling configuration) should be defined to disable the error handling.
User defined Error Output
It is possible to write your own error output function, which will be invoked when a fault is detected.
If you want to use your own error output, perform the following steps:
- Implement a C-procedure for error output with the prototype void USERErrorOutputFunc(FILE* File, tEMSErrorCode Code, va_list MessageArguments). tEMSErrorCode is an enumerated type containing all possible error codes returned by coder library functions, see Error codes. You can also find a list of the different error codes in errors.h from /cucf/ems folder.
- Compile the coder library with CODER_EO_USER compile switch, see Error output configuration,
- Compile and link the user error output function to the application.
The USERErrorOutputFunc function takes error message arguments as the third parameter which corresponds to the message string defined in the coder library. The error management system provides a function that allows you to get the coder library message string for the error code: char* CUCFGetErrorMessage(tEMSErrorCode Code). Example 483 illustrates one possible way of defining a user error output function.
void USERErrorOutputFunc( FILE* File,int Code,va_list MessageArguments ){/* user error output with the code and message */fprintf(File, "USER ERROR %d ", Code);vfprintf(File, ErrorMessageArray[Code], MessageArguments);fputc('\n', File);}
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |