Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Eclipse Titan » The binary RAW encoder of Titan : part III(Automatic generation of codec functions - Function prototypes)
The binary RAW encoder of Titan : part III [message #1712060] Wed, 21 October 2015 07:17
Elemer Lelik is currently offline Elemer LelikFriend
Messages: 1120
Registered: January 2015
Senior Member
As we have mentioned earlier, Titan will generate codec function automatically based on the declaration of the codec as an external function.
The encoder functions will have a TTCN-3 type as input and octetstring as output; the decoder , guess what, exactly the opposite.
To allow flexibility for different situations where the codec is used, several different prototypes can be used when generating the codec code.
Any TTCN-3 function, internal or external, can be declared with a prototype and the prototype to be used is indicated by an extension.

Simplest of them all is the prototype convert:

external function f_convert(in A param_ex) return B
  with { extension "prototype(convert)" }


Next , there is the prototype fast which avoids copying the result, passed in an out parameter:

external function f_fast(in A param_1, out B param_2)
  with { extension "prototype(fast)" }



Prototype backtrack has the same data input/output structure as prototype fast, but there is an additional integer value returned to indicate success or failure of the conversion process.
In case of conversion failure the contents of the output parameter is undefined.
Functions defined with such a prototype can only be used for decoding.
The following return values are defined to indicate the outcome of the decoding operation:
0 (OK). Decoding was successful; the result is stored in the out parameter.
1 (NOT_MY_TYPE). Decoding was unsuccessful because the input parameter does not contain a valid message of type B.
The content of the out parameter is undefined.

Example:
external function f_backtrack(in A param_1, out B param_2) return integer
  with { extension "prototype(backtrack)" }



Functions of prototype sliding have the same behavior as the one of prototype backtrack;
consequently, these functions can only be used for decoding.
The difference is that there is no need for the input parameter to contain exactly one message:
it may contain a fragment of a message or several concatenated messages stored in a FIFO buffer.
The first parameter of the function is an inout value parameter, which is a reference to a buffer of type octetstring or charstring.
The function attempts to recognize an entire message. It if succeeds, the message is removed from the beginning of the FIFO buffer,
hence the name of this prototype: sliding (buffer). In case of failure the contents of the buffer remains unchanged.
The return value indicates success or failure of the conversion process or insufficiency of input data as follows:

0 (OK). Decoding was successful; the result is stored in the out parameter.
The decoded message was removed from the beginning of the inout parameter which is used as a sliding buffer.

1 (NOT_MY_TYPE). Decoding was unsuccessful because the input parameter does not contain or start with a valid message of type B.
The buffer (inout parameter) remains unchanged. The content of out parameter is undefined.

2 (INCOMPLETE_MESSAGE). Decoding was unsuccessful because the input stream does not contain a complete message (i.e. the end of the message is missing).
The input buffer (inout parameter) remains unchanged. The content of out parameter is undefined.
Example:
external function f_sliding(inout A param_1, out B param_2) return integer
   with { extension "prototype(sliding)" }


The first portion of the input data received in the parameter param_1 of type A is converted.
The resulting data of type B is contained in the output parameter param_2 of type B.
The return value indicates the outcome of the conversion process.


OK ,as an example let's take the binary-encoded IUA protocol module from github:
(https://github.com/eclipse/titan.ProtocolModules.IUA ) :



//+++++++++++++++++++++++++++++++
//  External encoding/decoding functions
//+++++++++++++++++++++++++++++++
external function enc_PDU_IUA(in PDU_IUA pdu) return octetstring
 with { extension "prototype(convert) encode(RAW)" };
 
external function dec_PDU_IUA(in octetstring stream) return PDU_IUA
 with { extension "prototype(convert) decode(RAW)" };
 
external function dec_PDU_IUA_backtrack(in octetstring stream, out PDU_IUA pdu) return integer
 with { extension "prototype(backtrack) decode(RAW)" }



Next to the protoype declaration we can indicate the assumed codec.

(BTW, among the protocol modules published in github, one may find older ones, written before the concept of auto-generated functions
was implemented ; these will have handwritten codec functions, as we have seen no reason to change them;
but they may as well be rewritten for autogenerated codecs)

Ah yes , and one more thing , error handling:

The TITAN codec API has some well defined function calls that control the behavior of the codecs in various error situations during encoding and decoding. An error handling method is set for each possible error type. The default error handling method can be overridden by specifying the errorbehavior attribute:

"errorbehavior" "(" <error_type> ":" <error_handling>
              { "," <error_type> ":" <error_handling> } ")"
			  


Possible error types and error handlings are defined in APIGuide section "The common API".


The value of <error_type> shall be a value from the below list of generic types or one of the codec specific types listed with the codec:


UNDEF		Undefined/unknown error.
UNBOUND		Encoding of an unbound value.
REPR		Representation error (for example, internal representation of integral numbers).
ENC_ENUM	Encoding of an unknown enumerated value.
DEC_ENUM	Decoding of an unknown enumerated value.
INCOMPL_MSG	Decode error: incomplete message.
INVAL MSG	Decode error: invalid message.
CONSTRAINT	The value breaks some constraint.
INTERNAL	Internal error. Error behaviour cannot be set for this.
ALL 		All error type. Usable only when setting error behaviour.
NONE 		No error.



The value of <error_handling> shall be one of values listed below:

DEFAULT 	Sets the default error behaviour for the selected error type.
ERROR 		Raises an error if the selected error type occurs.
WARNING 	Gives a warning message but tries to continue the operation.
IGNORE 		Like warning but without the message.


Default error behaviour for codecs is preset to ERROR.


When using the backtrack or sliding decoding functions,
the default error behavior has to be changed in order to avoid a runtime error if the in or inout parameter does not contain a type we could decode.
With this change an integer value is returned carrying the fault code. Without this change a dynamic test case error is generated.

Example:
external function decode_PDU(in octetstring os, out PDU pdu) return integer 
with { 
  extension "prototype(backtrack)" 
  extension "decode(BER:BER_ACCEPT_LONG|BER_ACCEPT_INDEFINITE)" 
  extension "errorbehavior(ALL:WARNING)" 
} 

I know , this is not a RAW example, but you get the point.




Next, we will put all these pieces of information together and look into protocol design.


Best regards

Elemer
Previous Topic:The binary RAW encoder of Titan : part II
Next Topic:Using encode function of TTCN_Buffer
Goto Forum:
  


Current Time: Thu Aug 05 09:34:26 GMT 2021

Powered by FUDForum. Page generated in 0.01529 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top