X9Utilities Transcode
Transcode is used to apply a basic transformation to an existing x9.37 file and write those results to a new x9.37output file. Transcode is very different from Translate, in the sense that Transcode works at the record level while Translate works at the item level. Transcode essentially copies records from input to output, while Translate is a two step process that consists of a combination of Writex and Write.
By working at the record level, Transcode can do transformations such as converting a file from EBCDIC to ASCII, or adding/removing the 4-byte length prefix that exists at the front of each record. By working at the item level, Translate can do more complex operations such as adding an offsetting credit to a file that does not currently have one, or converting a file from x9.37 standard to another.
X9 Specification Conversions
In addition to character set transformations, Transcode is planned to have simple translation facilities from one x9.37 standard to another. An example would be converting from the DSTU to x9.100-187-2008 or x9.100-187-2013 to x9.100-187-2013-UCD. These translations become especially important when the input x9 file contains credits, and those credits must be converted to another format or record type as part of the transformation.
We have implemented a basic set of x9.37 conversion facilities, but it does not currently have “any-to-any” capabilities. We plan to implement additional conversions subject to user demand. In particular, we plan to enhance Transcode to support conversions between DSTU and x9.100-180, where these two standard are very different internally.
Please let us know what you need and we can quickly respond with the needed transformational capabilities.
Command line options
| Switch | Description |
| -config: | Use a specific an output x9 configuration. The input x9 configuration is determined automatically from inspection. |
| -ebcdic | Write output in EBCDIC. |
| -ascii | Write output in ASCII. |
| -nrl | Do not insert the 4-byte record length prefix on the output records. The default is to always insert these prefixes, even when they are not present on the input file. |
| -j | A summary JSON file will be created with a suffix of “_summary.json” in the same folder as the output x9 file. |
| -t | A summary text file will be created with a suffix of “_summary.txt” in the same folder as the output x9 file. |
| -x | A summary XML file will be created with a suffix of “_summary.xml” in the same folder as the output x9 file. |
| -l | Will list all csv lines to the system log. |
| -batch | Invokes batch (folder based processing; see that earlier topic for more information. |
| -workUnit: | Assigns command line parameters and files from an xml file that was previously created and saved by the X9Utilities facility within X9Assist. This allows you to easily repeat an X9Assist task directly in X9Utilities batch. |
X9Utilities Translate
Translate is used to transform an existing x9.37 file from one format to another. Internally within X9Utilities, -translate is implemented as a combination of our Writex and Write functions. By leveraging these two functions, you can read an existing x9.37 file and apply various manipulations, largely based on the headerXml file that is specified to construct the new file.
We should note that Translate is a new function that was added with X9Utilities R5.04, so you will need to be at this release (or higher) to be able to invoke this. Also, be advised that this function name itself was repurposed at that time, where the previous capability is now called Writex.
This is accomplished by reducing the input x9.37 file into generic items, which are then routed into x9utilities-write to construct a new x9.37 file. The items file is an intermediate CSV file that serves as the interface from -Writex to Write. As part of this process, all of the headers and trailers are removed from the input x9.37 file, allowing them to be reconstructed when the output (new) x9.37 file is created. This design leverages the combination of Writex and Write to build an entirely new x9.37 file, with a large number of options as to how the transformation is performed.
An important consideration for Translate processing is how the provided headerXml is used to tailor the conversion to meet your specific requirements. The headerXml file directs what x9.37 standard will be used to build the output x9.37 file, but also controls the attributes that are assigned to many header/trailer/record fields. This is because Writex reduces the input x9.37 file to generic items. The subsequent Write process then uses the headerXml and those items to build the final x9.37 file. This is reason why the headerXml file is so important to the process.
Every Translate run comes from one of two sources:
- You can provide the headerXml file that you want to use on the command line to Translate; please reference the sample command lines for the required format.
- Otherwise, you can tell Translate to use the headerXml file that is constructed by Writex, through an inspection process of the x9.37 file itself. This alternative is the default and automatically applied when the headerXml file is omitted from the command line. This automatically constructed headerXml file attempts to capture the spirit of the input x9.37 file by extracting various field level attributes into a headerXml file that will be written by Writex. You may decide to use this headerXml file as is, or you may instead use it at the basis to create a customized headerXml file that you provide on the command line in a subsequent run.
The following are some examples of the types of transformations that can be done:
- Convert a checks-only x9.37 file into a true Image Cash Letter (ICL) by adding an offsetting credit, where the credit amount is calculated automatically from the checks themselves. The credit can be in one of several formats and can be inserted at one of several positions within the new file.
- Repackage an existing x9.37 file by changing the number of items per bundle.
- Modify any or virtually all of the fields in the file header/trailer records with specific values that are defined in a customized headerXml file.
- Convert an existing x9.37 file from one standard to another. For example, from DSTU x9.37 to x9.100-187, or even x9.100-180.
Command line options
Translate allows all command line options that are made available by both Writex and Write.