The X9Utilities Console is an interactive tool that is available within both X9Utilities and X9Assist. The console is a powerful facility that allows command line parameters to be entered, validated, and then submitted for execution. It serves as a good demonstration of the overall capabilities of X9Utilities, since it allows the command line to be constructed visually, with validation of files and command line switches as they are entered. The console allow X9Utilities to be run on demand. It intercepts and displays the system log as x9utilities is executing. It then displays the final exit status that is posted by the x9uti.exe.
The console is an integral part of X9Utilities itself, and launched using the “-console” switch on the command line. By using this approach, it is not a separate program but instead embedded within the standard x9utilities runtime. The console can serve as a workbench for your testing. It provides an illustration of x9utilities capabilities and operation.
The console allows allows a set of parameters can be save to xml as a “run unit” that can be subsequently loaded an executed again. This is a provided as a productivity tool, since it allows a given set of parameters to be saved and executed again in the future, as needed.
The console is made available as part of X9Assist since that product is a desktop tool, is designed with a UI (User Interface) for human interaction, and is our full-function desktop product. X9Assist customers can use the console to actually run X9Utilities interactively in their environment. An X9Utilities license must be purchased if you subsequently decide that you would like to run the tool on batch basis.
This documentation describes how to use the X9Utilities Console. However, it does not provide detailed information on each of the functions that are available via that batch (command line) utility. Please reference the X9Utilities User Guide (which is available in its entirety via help) for complete information regarding functions, capabilities, and command line options.
X9Utilities Evaluations
The console can be used during an X9Utilities evaluation, to both simplify and expedite the review process. Product evaluations are normally performed within a limited time frame and hence productivity factors are important. The console helps greatly during this process, since you can run any X9Utilites function from start to end within minutes, without the need to develop a batch script. You can also repeat the same test using a variety of input files, and can save the work unit for further repeated testing at a later time. All of these capabilities can add a lot of value during an evaluation of our X9Utilities product, so it represents a great way to get started. Once you have determined that your evaluation is favorable, X9Ware can then provide an evaluation copy of X9Utilities, which will allow you to perform the same operations on a command line basis.
Console Fields
The X9Utilities Console contains the following fields which allow you to identify the function to be performed along with their associated parameters:
- “Function” is a drop down box which allows the X9Utilities task to be selected.
- “Command Switches” is a list of switch values which are to be applied to the selected task. The entered switches must begin with a dash and must be valid for the selected function to be performed. Refer to the X9Utilities User Guide for more information.
- “Rules Specification” is used to select the x9.37 specification to be associated with the selected task. For example, the specification is critical for the “-write” since it identifies the x9 rules to be utilized, which identifies key information such as fields and field alignments.
- “Command line as executed” is a display box which summarizes the command line that will be executed for the selected task. The command line will be updated interactively as changes are made to the above fields (function, switches, rules, etc).
Input and Output Files
The X9Utilities Console includes a facility which must be used to define the input and output files that are processed. There are various files that can be specified, with certain files required based on the function being performed. These files are selected via a file chooser and the fully qualified file name is then displayed in the text box immediately to the right of each selection box. The chosen input and output files will be passed to X9Utilities via the command line. It is also informative to take a look at the command line box to see how input and output files are provided to X9Utilties via the constructed command line.
The following input and output files can be specified:
| Function | Input File | Image Folder | Secondary Input File | Output File | Results File |
| Translate | Mandatory | Optional; will default to “_IMAGES” when not specified | Optional; is assigned based on the input file name when not specified | ||
| Write | Mandatory | Optional; defines the HeaderXml file to be used when not provided as the first row within the input csv file | Optional; is assigned based on the input file name when not specified | ||
| Import | Mandatory | Optional; defines the image folder when image file names are relative | Optional; is assigned based on the input file name when not specified | ||
| Export | Mandatory | Optional; defines the image folder when image files are written | Optional; is assigned based on the input file name when not specified | ||
| ExportCsv | Mandatory | Optional; defines the image folder when image files are written | Optional; is assigned based on the input file name when not specified | ||
| Validate | Mandatory | Optional; is assigned based on the input file name when not specified | |||
| Scrub | Mandatory | Mandatory; defines the scrub xml parameters file to be used | Optional; is assigned based on the input file name when not specified | ||
| Update | Mandatory | Mandatory; defines xml file which is used to identify the field level update parameters | Optional; is assigned based on the input file name when not specified | Optional output csv file name | |
| Split | Mandatory | Mandatory; defines xml file which is used to identify the field level split parameters | Not allowed; it is defined within the xml file. | Optional output csv file name | |
| Merge | Mandatory; defines the input folder that contains the files to be merged. | Mandatory; defines the output file to be created. | |||
| Make | Mandatory; defines the input use case file. Along with the input file, you must specify the “-reformatter” and “-generator” switches to define those xml files, which are mandatory as well. | Optional; defines the routing list file when it is not defined within the generator xml file. | Mandatory; defines the output file to be created. | ||
| Compare | Mandatory | Mandatory; defines the secondary input file to be compared against | Optional output text file name | ||
| ImagePull | Mandatory | Optional; defines the image folder when image file names are relative | Mandatory; defines csv file which is used to identify the item images to be pulled |
Work Units
A work unit is a combination of all entered fields which describe the X9Utilities task to be performed. A work unit can be saved to xml and then subsequently loaded at a future time, allowing the work unit to be performed again. The load and save buttons on the right side panel are used for this purpose. Work units are stored in folder / documents / x9_assist / xml / x9utilities /. The ability to save and subsequently reuse work units allows task to be performed repetitively as needed. This might be used to perform a user periodic task and eliminates the need to create a batch script for that same purpose. Work units can not only be stored, but can also organized into subfolders within / documents / x9_assist / xml / x9utilities /.
X9Utilities Console
The console is used to display system log information for each new task that is executed. The console is initialized at the start of each new task and will be updated with log snapshots as the task is run. There are limits as to how much information can be shown within the log, which requires some truncation when the logging becomes excessive. In these situations, logging will be suspended. The console will still contain the very last lines from the log, which is important since these lines may contain output file names, totals, error messages, etc. Console content can be scrolled (using the scroll bar on the right) and can be copied to the clipboard (using CTRL A and then CTRL C). Once copied to the clipboard, the text can be pasted into other external applications as needed for specific purposes.
JDK Requirements
The console requires JDK 11 or higher for execution.
Function Execution
User input is edited interactively and errors and shown when identified. Once a valid work unit has been entered, it can be optionally saved and ultimately executed using the run button on the action line. Many tasks will run very quickly. Depending on the function performed, the number of files involved, and the relative size of those files, the run may take an extended period of time. The console has several indicators to inform you that a utility task is running:
- The background of the X9Utility console is changed from gray to cyan while the task is in a running state, and will be changed back to gray on completion.
- Exit status on the action line will be changed to “running” while the task is in a running state, and will be changed to the numeric exit status on completion.
- The status icon on the action line will be changed to a “runner” image while the task is in a running state, and will be changed back to a green/red icon on completion.
A popup message will displayed on completion that provides the exit status and the name/size of the output file. The elapsed time (in seconds) will also be displayed on the action line.
Command Line as Executed
The console includes a display box which shows the command line as executed. This is provided for several reasons:
- First is that it provides details on how the command line is formulated and thus is very helpful for exposure into the technical workings of the utility. You can compare the content of the formulated command line against the X9Utilities User Guide to fully review the command formats.
- Second is that the command line can be used as the basis for developing batch scripts. This would be done by fully testing the function to be performed, and then by creating a batch script from the command line. The new batch script may have certain parameters or file names turned into symbolic parameters, increasing both flexibility and usability.
Demonstrations
The following are examples of using the utilities console through a series of sequential operations:
| ## | Function | Steps needed to run the demonstration |
| (1) | Export x9.37 data + images into fixed column CSV format. | Select the EXPORT function using the drop down box. You will first need an x9.37 file to be exported. A good example would be to copy our sample file “Test ICL with 10 checks.x9” to your documents folder. You will find this x9 file in the program installation folder; for example in C:\Program Files\X9Ware LLC\X9Utilities R4.11\samples\files\. The file needs to be copied, because export will (by default) put the output CSV file and image folder next to the input file, so you need to use a folder where you have write privileges. You will notice a series of file selection rows that are used to identify the input and output files for the current function that is to be executed. These rows select files that are automatically populated into the command line. The first of these rows is for the input file. Once you have copied your sample x9 file to your documents folder, you then need to use the SELECT button to browse and select this as the input file. Take a look at the switches; you can change these as desired. You will need to look at the X9Utilities User Guide for more information on the switches that are available. A good first test would be to export into fixed CSV columns with images and create a summary JSON file totals. The switches for this would be entered as: -xf -i -j Look at the box which contains the command line as it will be executed. This shows exactly how the command line has been constructed based on your input file and entered switch values. Hit the RUN button in the lower right to execute X9Utilities. The X9Utilities system log will scroll as the command executes, and will eventually show as “finished” when complete. A popup box will be displayed and you can click OK. When the export has completed, you will find the exported CSV file and the associated images located in your input folder. Open the exported CSV file (for example, with a text viewer) and take a look at the export contents. You can use the documentation provided in the X9Utilities User Guide for a definition of the fixed format columns that have been created. This example has assigned defaults for the image folder (secondary file) and the output file. You can alternatively assign these using SELECT. When you do that, you will also see these file names populated into the command line box. |
| (2) | Export x9.37 data + images into variable column CSV format. | This is just a variation on the above example (1). The difference is that we will export into a variable number of CSV columns instead of into fixed columns. The variable column format follows the record and field definitions per the x9.37 standards. You will need to refer to the x9.37 standards themselves (eg, the 2003 DSTU) for a definition of this CSV format. Follow the above example, but change the command line switches to indicate that variable columns should be created: -xc -i -j Look at the box which contains the command line as it will be executed. This shows exactly how the command line has been constructed based on your input file and entered switch values. Hit the RUN button in the lower right to execute X9Utilities. Review output as described in the above export example. |
| (3) | Import x9.37 from an exported file, or a CSV of your creation. | This example builds on the above example (2), where the output file is in variable column CSV format. For the purposes of import, this format is mandatory, since import requires that the input file be constructed using the variable (records and fields) layout. This provides a very strict definition of the x9.37 file to be created. Select the IMPORT function using the drop down box. Set command line switches to write a JSON summary file and to also include additional logging: -j -l Use the input file SELECT button to select the variable columns CSV file that was created by example (2) above. Use the output file SELECT button to identify the output file that is to be written. For example, you can create the output file in the same folder where your input file exists. Following the example, we suggest that you create the output file as “Test ICL with 10 checks imported.x9”. Review the selected files to ensure that they are correct. Review the “command line” box for insight into how the import command has been constructed. Hit the RUN button in the lower right to execute X9Utilities. Review the created x9.37 file. You will see that it is has the exact same content as the x9.37 file that was originally exported. |
| (4) | Compare two x9.37 files. | This example builds on the above examples (2) and (3), where example (2) exported a file to data+images, and example (3) then imported the data+images to create a new x9.37 file. Given the simplistic flow of those two processes, we would expect the original x9.37 file to be equal to imported x9.37 file, which was constructed from a combined export-import process. Select the COMPARE function using the drop down box. Use the input file SELECT button to select the x9.37 that was input to example (2), which was the original file exported into variable column format. Use the secondary file SELECT button to select the x9.37 file that was created by example (3), which was an import of the CSV file in variable column format. Hit the RUN button in the lower right to execute X9Utilities. Review the created “_output.txt” and “_output.csv” files, which will contain all identified differences. Also take a look at the exit status that was posted by X9Utilities, which should be zero. |
Reusing a Saved Work Unit
The console can be used to save a work unit to xml for subsequent reuse. This work unit can be used to the batch version of X9Utilities to rerun this command in a batch environment. This can be useful when a function needs to be performed in a batch environment and can be repeated exactly as originally performed via the console. In some situations, this may eliminate the need to develop and test a batch script to perform the same function. The work unit is provided to X9Utilities using the -workUnit:”fully Qualified File Name” command line parameter. No other parameters or switches are required. You can review the created xml file for more insight into the work unit xml definition and embedded content.