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.
Virtualizing fixed-length communication includes these high-level steps:
Create and configure a Service Virtualization agent.
- From the main menu, select Tools > Options.
- Click Agents.
- Select a supported agent and click Add to add a new configuration.
For user-interface details, see Agent user interfaces.
Build a service description for the fixed-length protocol. See below for detailed instructions.
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.
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
You can write CorrelationID to the Data column to aid in request-response correlation. For details, see CorrelationID.
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.
|HasError||14||1||Numeric||Has Error flag||0|
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.
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:
Responses have the following fields:
You can write
CorrelationID to the Data column of these four fields. During learning, the response with values
ResponseForSubType=A is matched with the last encountered request where
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:
Responses can be of the following 2 types:
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
In complex cases, you can combine both of the approaches described above, as in the example below.
Example: In the requests,
CorrelationID:004 are constants specified by the service description. In the response,
004 are the list of possible payload values.
Async Request 003:
Async Request 004:
|AckTypeNo||15||30||Acknowledge for type||Message Payload||CorrelationID|
Note: You can apply CorrelationID only in fields with a finite enumeration of possible values, or in fields with a constant value.
|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|
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.
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.-->-->-->
-->) 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.
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
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
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
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
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|