Virtualize Fixed-Length Communication

This task describes how to virtualize fixed-length field based communication using a text-based service description. You can create a virtual service based on fixed-length service description files, enabling the virtual service to learn and understand the messages and message structure. After learning the new fixed-length messages, they are displayed in the data model, structured according to the service description files you provide.

A virtual service with a fixed-length service description supports the following:

  • TCP/IP, WebSphere MQ, and Filesystem/FTP protocols.
  • Multiple responses.
  • Multiple service description files can be used to create the virtual service. For more details, see Creating the text file.
  • Variable-length records/occurring structures are not supported.

Virtualize fixed-length communication

Virtualizing fixed-length communication includes these high-level steps:

  1. Create and configure a Service Virtualization agent.

    1. From the main menu, select Tools > Options.
    2. Click Agents.
    3. Select a supported agent and click Add to add a new configuration.

    For user-interface details, see Agent user interfaces.

  2. Build a service description for the fixed-length protocol. See below for detailed instructions.

  3. Create a new virtual service, and select the option to use a service description.

    • Select the .txt files you created to define the service description.
    • Select one of the supported fixed-length protocols.

    For more details on creating a virtual service, see Create a Virtual Service.

Back to top

Service description format

Define the service description in a text file, including the following information:

Name Custom, unique name of the field as it is displayed in the Data Model Editor.
Offset Binary offset, indicating the starting location of the field's data. For example, in a message that is 100 bytes in length with an offset of 5, the field starts at the 6th byte.
Length The number of bytes in the Data field. The field is read as a sub-array from the offset position to the offset + length position.
Type Service Virtualization internal data type. See Supported data types for details.
Description Custom text, used as a comment field. May not include a tab character.
Default value Default value for the field. Used as a value for enumeration fields, such as the Type and HasError fields in the example below.
Data

Used only for the Length field (the field marked as Attributes = '1'). The Data value adjusts the read message length value if the total message length differs by a constant value (+/-).

For example, suppose the Message length field value is 36, and the actual incoming message length is 40 bytes, but you have defined the Data value as +4. Service Virtualization will adjust the value to 40 (= 36 + 4), and will correctly parse the message.

You can write CorrelationID to the Data column to aid in request-response correlation. For details, see CorrelationID.
Attributes

  • Attributes - a 'flag' column, used by Service Virtualization to define special functionality for the field.

    • Attribute = 1: In the mandatory Message length field, set the Attributes column to '1'. The actual Message Length value (in the incoming message or in the Default Value column of Service Description) must be the size of the whole message—it must include the number of bytes indicating its length, type, and all fields. For example, suppose your payload is ABCDEFG_123456, the message type is one byte with the value ‘T’, and the message length is denoted in the first two bytes using a numeric data type. The whole message would be 16TABCDEFG_12345 with a length of 16.
      Note: If the length always deviates by a constant value, indicate this in the Data column (described above).
    • Attribute = 2: If using the Message type field, you must define Attributes = '2'.

Note: You must define how the message length can be determined in each of your Service description files. The length can be either present in the message payload or must be defined as a constant in the Service Description itself. If present in the payload, you must define Name, Offset, Length, Type and set Attributes to '1'. If it is a constant not present in the payload, provide that constant value to a Data field and Attributes to '1'.

For an example of when the message length is present in the payload, see the Sample data table. For an example of constant length which is not present in the payload, see Example of constant length which is not present in the payload.

Sample data:

Name Offset Length Type Description Default value Data Attributes
Length 0 4 IntBE Message length     1
Type 4 4 String Message type     2
        Request type REQ    
        Response type RESP    
MsgID 8 6 Numeric Message ID      
HasError 14 1 Numeric Has Error flag 0    
        No Error 0    
        Error 1    
Data 15 30 String Message payload      

Example of constant length which is not present in the payload:

Name Offset Length Type Description Default value Data Attributes
            4 1
Type 0 4 String Message type     2
        Request type REQ    
        Response type RESP    

Service Virtualization evaluates the table from the top down. If the Name field is not defined, then the value is treated as an enumeration value for the last evaluated field name. For example, Request type and Response type are enumerations of Message type in the table above.

Messages can be shorter than defined by the Length column. Unpopulated fields are set to the Not Present value in the Data Model.

CorrelationID

By default, incoming responses are time-based correlated to requests. This means that an incoming response is paired to the most recent request. If you need your requests and responses to be correlated differently, you can use the payload-based correlation described in this section. Note that correlation based on arbitrary values is not yet supported. You need to provide a pre-defined list of possible correlation values in your Service Description files.

You can write CorrelationID to the Data column to aid in request-response correlation during asynchronous communication. The value of this field in a request is used to match the request with its eventual response. If the correlation is complex, you can use CorrelationID in multiple fields.

Example: Requests and responses have the following fields:

  • RequestType

  • RequestSubType

Responses have the following fields:

  • ResponseForType

  • ResponseForSubtype

You can write CorrelationID to the Data column of these four fields. During learning, the response with values ResponseForType=T1, ResponseForSubType=A is matched with the last encountered request where RequestType=T1, RequestSubType=A. Note that you need to enumerate all possible values of the RequestType and RequestSubType fields in your Service Description.

You can also create custom correlation values to group various request and response types. Custom correlation values are not present in the payload and are used only in Service Description files.

Example: Requests can be of the following 3 types:

  • TemperatureMeterRequest

  • PressureMeterRequest

  • WindMeterRequest

Responses can be of the following 2 types:

  • MeterSuccessResponse

  • MeterErrorResponse

You can write CorrelationID:Meters to the Type field of these five messages. This causes any message with Meter*Response to be matched with the last encountered *MeterRequest.

In complex cases, you can combine both of the approaches described above, as in the example below.

Example: In the requests, CorrelationID:003 and CorrelationID:004 are constants specified by the service description. In the response, 003 and 004 are the list of possible payload values.

Async Request 003:

Name Offset Length Type Description Default Value Data Attributes
Length 0 4 Numeric Message Length     1
Type 4 4 String Message Type   CorrelationID:003 2
          003    
Data 15 30 String Message Payload      

Async Request 004:

Name Offset Length Type Description Default Value Data Attributes
Length 0 4 Numeric Message Length     1
Type 4 4 String Message Type   CorrelationID:004 2
          004    
Data 15 30 String Message Payload      

Async Response:

Name Offset Length Type Description Default Value Data Attributes
Length 0 4 Numeric Message Length     1
Type 4 4 String Message Type     2
          ACK    
AckTypeNo 15 30 Acknowledge for type Message Payload   CorrelationID  
          003    
          004    

Note: You can apply CorrelationID only in fields with a finite enumeration of possible values, or in fields with a constant value.

Back to top

Supported data types

Data format Service Virtualization data format (for Message type in service description) Note
ASCII, Alphanumeric, String String ASCII characters only
UTF-8, Unicode Binary Any non-ASCII charset
Numeric Numeric Numbers in ASCII, For example, “000010” or “-000020”.
Decimal Decimal Numbers in ASCII + decimal separator. For example, “0005.4” or “-005.4”.
Fixed decimal String Fixed decimal places. For example, for financial applications: “00100.00”.
Integer, Short (big-endian, network byte order) IntBE

Supported byte length is 4 bytes or less.

More information: http://en.wikipedia.org/wiki/Endianness
Integer, Short (little-endian, Intel x86) IntLE
Binary, other non-specified Binary

Back to top

Creating the text file

The text file must be structured as follows:

  • Use tab-separated files with .txt extension.

  • Each message type requires a separate file with .txt extension.
  • You can create separate files for requests and responses. See Service description file naming for details.

  • The structure of the message definition file must be as follows:

    The first line (header) is used to define columns for field definition.

    Example:  

    Name-->Offset-->Length-->Type-->Description-->Default Value-->Data-->Attributes

    Each additional line defines one field of the message. Define the field's column values using tab-separated columns.

    Example:  

    Message number-->12-->4-->Numeric-->Unique message identification number.-->-->-->

    where (-->) indicates a tab, and an extra tab marker (-->) indicates a column with no value. In this example:

    Name = Message number

    Offset = 12

    Length = 14

    Type = Numeric

    Description = Unique message identification number

    Default Value, Data, and Attributes are not defined.

error_rs.txt

Name	Offset	Length	Type	Description	Default Value	Data	Attributes
Length	0	4	IntBE	Message length			1
Type	4	6	String	Message type			2
					ERROR
ErrorCode	10	4	Numeric	Error code			
ErrorMessage	14	1000	String	Error message

plus_rq.txt

Name	Offset	Length	Type	Description	Default Value	Data	Attributes
Length	0	4	IntBE	Message length			1
Type	4	6	String	Message type			2
					PLUS
Base	10	2	Numeric	Base			
				Binary	2		
				Octal	8		
				Decimal	10		
				Hexadecimal	16		
Number1	12	10	String	Number 1			
Number2	22	10	String	Number 2

result_rs.txt

Name	Offset	Length	Type	Description	Default Value	Data	Attributes
Length	0	4	IntBE	Message length			1
Type	4	6	String	Message type			2
					RESULT
Base	10	2	Numeric	Base			
				Binary	2		
				Octal	8		
				Decimal	10		
				Hexadecimal	16		
Result	12	10	String	Result

sqrt_rq.txt

Name	Offset	Length	Type	Description	Default Value	Data	Attributes
Length	0	4	IntBE	Message length			1
Type	4	6	String	Message type			2
					SQRT
Number	10	10	Numeric	Number

Back to top

Service description file naming

Service description text files named in the format <message_name>.txt will be used for both requests and responses.

To use files for either requests or responses only, the filenames must be as follows:

Request filename pattern Response filename pattern
*_req.txt *_resp.txt
*_request.txt *_response.txt
*_rq.txt *_rs.txt
*-req.txt *_resp.txt
*-request.txt *-response.txt
*-rq.txt *-rs.txt
*.req.txt *.resp.txt
*.request.txt *.response.txt
*.rq.txt *.rs.txt

Back to top