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 Agents Page.

  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.

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.

  • 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 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 a field called Length with the IntBE data type, and Attributes = '1'.

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      

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.

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:

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.


    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.


    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.

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