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
] 
Search
Help
Register
Login
Home
