This topic introduces the Fixed Length Message Responder and explains configuration options that are unique to this type of Message Responder.
Fixed Length Message Responder is a Message Responder that is designed to simplify the use of fixed length by allowing you to utilize XML. You can model your fixed length response payload as an XML document; the responder then automatically converts the XML to fixed length before sending the message. If the responder receives a fixed length message, the responder can convert the message to XML so that you can define message correlations using XPaths or attach tools. Message Responders are protocol agnostic. The transport protocol or API to access a responder is defined in the deployment configuration of the PVA.
Fixed length is a data format for which there is no standard definition. In general, fixed length data formats consist of a number of records. Each record has one or more fields, each of which is of a fixed length (hence the name "fixed length format"). These fields typically do not have separators between them.
For a simple example, consider a message where each record is on a different line and simply contains two fields:
Each field is 10 characters long, is right-aligned, and is padded by spaces.
A record in a fixed length format may have nested sections that also have records with fixed length formats. These nested sections could have a variable number of records. Consider a second fixed length format that is based on the first example. Assume that for each person, we want to specify a variable number of pets owned by that person. We will start with the data format we used above, but for each record we will add the following:
Here is an example of such data.
Doe Jane02 Cat Fluffy Dog Spot
The first person record has 0 pets, and the second person record has 2 pets. The pets sub-section has pet records that can appear a variable number of times.
Since many different fixed length formats exist (and there is no single standard), Parasoft Virtualize is easily configured to recognize any fixed length message format that the organization uses. In order to configure and validate fixed length messages in Virtualize, you need to perform the following one-time configuration:
There are two main steps required to define a data model that describes your fixed length data format:
The first step in working with fixed length messages in Virtualize is to define a data model that describes your fixed length data format.
To create a new data model:
The wizard will create a file with the extension .datamodel in the workspace location that was selected. The file does not appear within the Virtual Asset Explorer. You can find it by switching to Navigator view and looking within the project where it was saved.
The next step is to use the data model editor to tell Virtualize how your fixed length messages are structured. Virtualize will use this information to convert these messages to and from XML.
The data model editor opens after a new data model definition is created. You can also access it by double-clicking the Navigator node that represents the data definition file.
This name will be used to identify your message format in applicable tools.
Next, enter the general details about the section as a whole: its name, the name of its records, how these records are separated, and the criteria for next record.
Specify the name of the section. This name appears in message configuration interfaces and is used as the XML tag name in the converted XML (illegal XML characters get stripped out in the XML). It can be set to anything.
Specify the name of each record within the section. This name appears in message configuration interfaces and is used as the XML tag name in the converted XML (illegal XML characters get stripped out in the XML). It can be set to anything.
Indicate what separator should be used between different records within the section. You can either select one of the available options (double-click the field to open a drop-down), or enter a custom separator.
Available options are:
Specify criteria that will enable the parser to know that it is done reading this section when the parser is converting from fixed length to XML. This is important when there is additional content that appears after this section that should not be confused as being part of this section. The parser needs to know how many records appear within this section before it moves on from this section.
Valid values are:
The xpath option specifies the condition under which the parser continues applying content to this section. The parser considers that it is still in this section as long as this condition is true; once the condition becomes false, the parser moves on from this section. The condition gets applied at the beginning of reading a record in order to determine whether or not the following content is a new record in this section.
When this option is chosen, a new descriptor named XPath appears. You can enter an xpath expression that describes the condition under which the content should still be applied to this document.
When the condition is evaluated, the XPath gets applied to the XML document that is being created from the fixed length document.
The default XPath is "count($section/*) < 1". Let's examine what this means. $section is a special XPath variable that applies only in this context. It refers to the XML element that represents this section. "$section/*" gets the collection of all XML elements that are children of the section element. Basically, it gets all the XML elements that represent the records in this section. "count()" is a normal XPath function that counts the number of nodes in the nodeset that is passed to it. So "count($section/*)" ends up returning the number of records that have been added to the XML document so far. The full expression then essentially means "keep adding records to this section as long as the number of records that have already been added to this document is less than 1" - meaning by default to only add one record.
However, in many cases, the number of records to read is specified in some other field in the document. In this case, you would use an XPath that references the field within the document that specifies the number of records. Remember that the XPath gets evaluated against the XML document that is being created, so it references an XML element within the XML document. If a document has a field that has been named "NumberOfPets", then a corresponding XPath to locate that element might be "$section/../NumberOfPets". This means "start at the XML element representing this section, go up one element to the parent, and then get the NumberOfPets element". This would find a "NumberOfPets" element that is a sibling of the current section. In this case, the full XPath expression might be
"count($section/*) < $section/../NumberOfPets".
There are two available XPath functions that are unique to this context: fixedlen:peek() and fixedlen:peek-starts-with()
This function takes a single integer as an argument. It peeks at the upcoming content within the fixed length document that has not yet been read and converted to XML. This is used in cases where the determination of whether there are more records to read for this section is based on some content that appears later in the file. For example, consider a case where the record starts with a "<" character:
Doe Jane< Cat Fluffy>< Dog Spot>
In this case, your XPath expression would be "fixedlen:peek(1) = '<'".
This function takes a single string as an argument. It peeks at the upcoming content within the fixed length document that has not yet been read and converted to XML. This is used in cases where the determination of whether there are more records to read for this section is based on some kind of delimiter that signals the start of the record. For example, consider a case where the record starts with a "<" character:
Doe Jane< Cat Fluffy>< Dog Spot>
In this case your XPath expression would be "fixedlen:peek-starts-with('<')".
The fixedlen:peek-starts-with() function is the equivalent of the XPath expression "starts-with(fixedlen:peek(1), '<')".
The default option is greedy. This is the option that you will typically use—unless you are working within a nested sub-section and it is not the last content in the document.
Use the Components section to provide details about what fields and/or sub-sections are contained by the section. Multiple fields and/or sub-sections can be added here.
To add a field:
For each field, specify the following settings:
To add a subsection:
For details on completing general section details, see 2. Specify general information about the section.
The initial view for the data model editor shows the data model in a tree-based table. The tree format allows you to easily see the hierarchy and structure of the data model. It is in a table format so that you can edit values within the context of the data model structure.
In this tree-table view, the fields that can be edited fall into the following categories:
When you’re entering data for a large number of fields, you might want to switch from the tree format to the table format, which is designed to provide a fast and easy way to enter field descriptors for a single section.
To switch to table view:
The table view resembles a spreadsheet. Each field in the section is a single row in the table, and each column in the table corresponds to one of the field descriptors. You can add more fields in this view by simply modifying the last row in the table and pressing an arrow key or the Enter key.
You can also use the following buttons:
To return to the main view for the data model, click the Return to Full Data Model button.
There may be cases where you have a number of fields and sections defined in your data model, and you realize that you need to add a new field in the middle of those you already have defined.
To achieve this:
As the data model is being defined, it you probably will want to test it to ensure that it is accurately reflecting your fixed length data format.
To do this:
Each data model that you have defined needs to be registered in Virtualize before the associated formats can be used. This registration has to be performed on every Virtualize installation that you want to access your fixed length format(s). If you have both Virtualize and SOAtest installed, you can register the model once, then use it for both products.
There are two ways to register a data model:
Once registered, the data model can be used in the Fixed Length Message Responder as well as in the XML Converter. You can create a Fixed Length Message Responder tool directly from the Add Responder wizards.
In order to perform fixed length message configuration or validation, you must select your data model in the Message type combo box in each of those tools.
You can now configure the Fixed Length Message Responder as you could configure any other Message Responder. For details on configuring standard Message Responder behavior (e.g., correlations, performance profiles, etc.), see Message Responder Overview.
When you select a message type as shown above, Virtualize fills the Form Input view with sample XML that can be converted to fixed length data without requiring modification.
The data model definition for the fixed length message type determines the content of the generated XML. The XML contains the sections and fields specified in the definition.
An XML element is added for each section. Each section element contains elements for records. The section’s Criteria for next record setting determines how many records are added to the section:
|fixedCount||The "Record count" option determines the number of records.|
|greedy||Exactly one record is added.|
|xpath||The XPath is evaluated when generating the XML. Another record is added if the XPath evaluates to true. Virtualize always adds at least one record, and—in the unlikely event that the XPath evaluates to true many times—never adds more than 1000 records. (Because of these restrictions on the number of records added, there is the small chance that using XPath criteria will result in sample XML that will not convert to fixed length data without modification.)|
Fields are filled with default values. Integer and decimal fields are set to the number 1. String fields are set to the value a. Virtualize uses this arbitrary value rather than no value (the empty string) to clarify where each field begins and ends if you convert the sample XML to fixed length format.