Use a Parse Structured rule in conjunction with a Service File rule or the Apply-Parse-Structured method to import structured data to the clipboard. For example, you can import fixed-format flat files from various external sources and platforms.
If the source value to be parsed has a simple fixed-format structure where each field has a fixed length and is always present, you can use a map structured rule instead of a parse structured rule. Map Structured rules are simpler to debug and maintain. For more information, see Map Structured rules.
Service and connector forms might reference Parse Structured rules in data mapping. When evaluating the service or connector, the system evaluates the Parse Structured rule.
To execute a Parse Structured rule in an activity, use the Apply-Parse-Structured method.
Tabs on the Parse Structured form
Service and connector rules can reference parse structured rules, as part of the data mapping. For example, a Service File rule can use a parse structured rule to extract specific fields of interest from an input file. For more information, see Service File rules.
The Rule-Parse-Structured class is a child class of the Rule-Obj-Activity class. This class is not derived from the Rule-Parse- abstract class.
The parseState object and debugging
As it executes, a Parse Structured rule creates and maintains a Java object in memory named parseState. This corresponds to a method variable in the generated Java.
This object is not visible through the Tracer or the Clipboard tool, but you can use Public API functions to examine it. To do this, include a Java step containing the Public API call:
myStepPage.putString("debug3", Long.toString(parseState.getStreamOffset()) );
where debug3 is a Single Value property. This function places the byte offset position of the Java object into a clipboard value. You can review the clipboard value with the Tracer or Clipboard tool.
Four Pega Platform methods operate on the parseState object:
- Parse-Byte-Pos (for byte streams)
- Parse-Char-Pos (for character streams)
- Parse-Fixed-Binary (for byte streams)
- Parse-Packed-Decimal (for byte streams)
The result of each method is stored in parseState.lastToken (which can be accessed in a Java step) and is optionally stored as a property value.
The parseState object is defined in the PublicAPI Interface.
This facility is based on
java.io.* capabilities (not the newer
java.nio.* capabilities). The PublicAPI includes methods to query or
operate on the object.
Through changes to the
prconfig.xml file or dynamic system settings,
the system can alert you to unusually long Parse Structured executions as PEGA0011 alerts.
For more information, see Lengthy service operations.