FlatFile Module 10.7 | Flat File Built-in Services Referrence Guide | wmFlatFile Package | Flat File Folder | Summary of Elements in the Flat File Folder | pub.flatFile:convertToValues
 
pub.flatFile:convertToValues
WmFlatFile. Converts a flat file document to an IS document (IData object) based on the input flat file schema.
Input Variables
ffData
Object. The flat file input with type of String, InputStream, or ByteArray.
ffSchema
String. The full name of the flat file schema object used to parse the ffData object.
ffIterator
Object. Optional. An object that encapsulates and keeps track of the input data during processing. It is used only when the iterate variable has been set to true.
encoding
String. Optional. The encoding of the InputStream passed in to ffData. The default encoding is UTF–8.
Note:
If the flat file document contains multi-byte encodings, you must install the Extended Character Set using the Software AG Installer. For more information about installing the Extended Character Set, see the “Configuring the flat file byte count parser" section of the Flat File Schema Developer’s Guide.
delimiters
Document. Optional. An IData object that contains the segment terminator and the field and subfield separators. If the delimiter is null, it will be located using the information defined in the flat file schema. To specify a delimiter, you can specify:
*One character or character representation (for example, *, \n for line terminator, \t for tab)
*Hexadecimal value with prefix “0X” (for example, 0X09, 0X13)
*Octal value with prefix “0” or decimal value (for example, 011, 023)
*Unicode characters (for example, \u XXXX where XXXX represents the Unicode value of the character)
*The space character.
Important:
If you specify one delimiter value, you must specify all values. Specifying one of these values will override any information set in the flat file schema.
Variable
Description
record
String. Character used to separate records. If you want to specify the two–character carriage return line feed (CRLF) characters, specify \r\n.
field
String. Character used to separate fields.
subfield
String. Character used to separate subfields.
release
String. Character used to ignore a record, field, or subfield delimiter in a field. If a release character occurs in a field or subfield before the delimiter, it will be prefixed with the release before being written to the output ffValues.
quotedRelease
String. Character to use to ignore a record, field, or subfield delimiter in a field. If a quoted release character occurs in a field or subfield before the delimiter, it will be prefixed with quotedRelease before being written to the output string. The string is pre- and appended with the quoted release character.
For example, if * is a delimiter, the field value is a*b, and the quoted release character is “, the string appears as “a*b”.
FormatInfo
Document. Any values mapped to the FormatInfo variable will be passed unmodified to all format services invoked by convertToString and convertToValues.
iterate
String. Optional. Whether you want to process the input all at one time.
batchsize
String Optional. Whether you want to process the specified number of records. The input value of this field is a positive integer. This field is applicable only when the iterate field value is set to true. If you do not specify this field value, default value is set to 1.
Value
Description
true
Processes top-level records (children of the document root) in the flat file schema one at a time. After all child records of the top-level record are processed, the iterator moves to the top-level of the next record in the flat file schema, until all records are processed.
false
Processes all input data at one time. This is the default.
createIfNull
String Optional. Whether to create the IData object if all the fields are null.
Value
Description
true
No IS document (IData object) will be created if all the fields are null. This is the default.
false
Always create IS document even though all the fields are null.
skipWhiteSpace
String. Optional. Whether white space at the beginning of records will be ignored.
Note:
The fixed length record parser ignores skipWhiteSpace; it preserves white space.
Value
Description
true
Ignore white spaces at the beginning of a record. This is the default.
false
Record is used as it is identified (useful for positional data record).
keepResults
String. Optional. Whether to return the parsed data in the ffValues output parameter.
Value
Description
true
The parsed ffData will be returned in the output ffValues. This is the default.
false
ffValues will not return data. Use this option when validating the structure of the ffData against the given flat file schema.
validate
String. Optional. Whether to return error messages that describe how ffData differs from the flat file schema.
Value
Description
true
Do not return error messages describing how ffData differs from the specified flat file schema. This is the default.
false
Return errors describing how the given ffData violates the constraints described in the flat file schema.
returnErrors
String. Optional. Whether to return the validation errors. Validation errors are returned only if validate is set to true.
Value
Description
asArray
Return any validation errors with the ffData in an array called errors. This is the default.
inResults
Return validation errors in the ffValues object.
both
Return validation errors in both errors and ffValues.
maxErrors
String. Optional. The maximum number of errors that can be returned from one record. When the flat file parser encounters more than the maximum number of errors within a record, the parser will stop parsing and return the parsed data and errors processed up until that point. Validation errors are returned only if validate is set to true.
flags
String. Optional. Flags that you can set to govern convertToValues options.
Variable
Description
addRecordCount
String. Whether you want the service to add an additional field (@record–count) to each parsed record in the resulting IData object (ffValues). The @record–count field is used to identify the record number of each parsed record.
Value
Description
true
The @record–count field is added to each parsed record. This field contains the number of the parsed record. The first parsed record is 1, the second is 2, etc. If there are records that are undefined data, the count of the next defined record will reflect the undefined data. For example, if the @record–count field for a record is 2 and that record contains 5 undefined records, the @record–count field for the next defined record will be 8.
false
The @record–count field is not added to each parsed record. This is the default.
detailedErrors
String. Whether you want detailed conditional validation error information. This flag is only used when validate is true.
Value
Description
true
When a conditional validation error occurs, the output errors variable will contain detail information about all the conditions that were violated. For more information, see Flat File Schema Developer’s Guide.
false
When a conditional validation error occurs, the service does not provide detail error information. Conditional validators report only whether a condition failed validation with no additional information about the conditions that were violated. This is the default.
skipToFirstRecord
String. Whether you want the service to wait until it finds the first valid record before reporting invalid records as errors.
Value
Description
true
The service will wait until it finds the first valid record before reporting invalid records as errors. This is the default.
false
The service will report invalid records as errors prior to locating the first valid record.
trimWhitespace
String. Whether you want the service to delete any blank spaces at the beginning of fields, at the end of fields, or both.
Value
Description
none
The service will not delete any blank spaces from fields. This is the default.
left
The service will delete all blank spaces at the beginning of all fields.
right
The service will delete all blank spaces at the end of all fields.
both
The service will delete all blank spaces at the beginning and end of all fields.
resultAsArray
String. Whether you want the service to return the ffValues output parameter as an IData[] that can be mapped to the document types generated from the schema. An IData[] is a document List. The resultAsArray parameter is used only when the iterate input parameter is set to true.
Value
Description
false
The service returns the ffValues output parameter as an IData[] that can be mapped to the document types generated from the schema. This is the default.
true
The service returns the ffValues output parameter as an IData object and not as an IData[].
Output Variables
ffValues
Document. The IData object that represents the input flat file data.
ffIterator
Object. Optional. An object that encapsulates and keeps track of the input records during processing. It is used only when the iterate variable has been set to true. When all input data has been processed, the object becomes null. When the ffIterator variable is null, you should exit the LOOP to discontinue processing.
isValid
String Whether flat file contains validation errors.
Value
Description
true
The validate input variable was set to true and no errors were found.
false
The validate input variable was set to true and errors were found, or the validate input variable was set to false.
errors
String. Optional. An array containing the validation errors, if any, that were found in ffData. For more information about validation error codes see Flat File Schema Developer’s Guide.
Usage Note
If you specified a default record definition by which the pub.flatFile:convertToValues service parses the IS document (IData object), the service displays the resulting recordWithNoID document as a child of the document above it, in an array.
To display the recordWithNoID record as a child of the root, change the value of the recWithNoIDLike46 to true in the Integration Server_directory \instances\instance_name\packages\WmFlatFile\config\ff file and reload the WmFlatFile package so that this configuration setting will take effect. For more information, see the Flat File Schema Developer’s Guide.
If some or all of the flat files that you process encounter problems because of memory constraints, set the iterator variable in the pub.flatFile:convertToValues service to true to process top-level records (children of the document root) in the flat file schema one at a time. After all child records of the top-level record are parsed, the pub.flatFile:convertToValues service returns and the iterator moves to the top-level of the next record in the schema, until all records are parsed. This parsing should be done in a flow service using a REPEAT step where each time the pub.flatFile:convertToValues service returns, the results are mapped and dropped from the pipeline to conserve memory. If the results were kept in the pipeline, out–of–memory errors might occur.