Share this page

# 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.

In this topic:

## 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. In version 5.4.1 and later: 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

Supported in versions: 5.4.1 and later

You can write CorrelationID to the Data column to aid in request-response correlation during asychronous 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:

- ResponseType

- ResponseSubtype

You can write `CorrelationID` to these four fields. During learning, the response with values `ResponseType=T1`, `ResponseSubType=A` is matched with the last encountered request where `RequestType=T1`, `RequestSubType=A`.

You can also create custom correlation values to group various request and response types.

Example: Requests have the following fields:

- TemperatureMeterRequest

- PressureMeterRequest

- WindMeterRequest

Responses have the following fields:

- 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: 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.

Sample files

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

https://admhelp.microfocus.com Service Virtualization 8942
Tips to improve your search results... Service Virtualization Help Center SV Help 5.4-5.4.1 All View Local Help Center View Online Help Center back Go back in browser history forward Go forward in browser history Remove search highlights next topic Go to next topic previous topic Go to previous topic Print the current topic Version: