Submitting Reports with The RUNUBEXML Program
Technology Demographic TableProduct / OneWorld, XE, ERP8, ERP9
Version / SP19 and higher
Platform/OS / Windows2000, UNIX
Industry
Application / Reports, Batches, UBEs
Database
Keywords / Batch jobs, reports, UBE, parallel batches
Date / May 20, 2003
Authors / Phil Kemp
Contents
Introduction 1
Features 1
Using runubexml 2
Necessary Basics 2
System, Bin32 Directory 2
Computer ID & Report ID 3
Editing & Errors in XML Documents 3
Runubexml & Runube Differences 4
Job ID 4
RUNUBE Interactive Mode 4
Security 5
Running RUNUBEXML 5
Runubexml Flow 7
Generate Base XML (Step 1) 8
Required Values 9
Optional Information 9
Build Request XML (Step 2) 10
Submit Report XML (Step 3) 11
JDE Business Views 11
JDE Printer Information 12
Data Selection 12
Data Sequencing 17
Appendix – Base XML File 19
Raw Base XML File 19
Edited Base XML File 19
Appendix – Request XML File 21
Appendix – Output XML File 23
Appendix - Windows2000 Path 26
Windows2000 Environment Paths 26
Checking Windows2000 Environment Paths 26
Setting directory paths 26
Appendix - Common Errors 29
Incorrect Report ID & Incorrect Password 29
Bad XML file 29
Invalid report name 29
Invalid report version 29
CREATE_XML Argument must be in CAPTIALS 30
Windows2000 Environment Path Not Set 30
First Argument Not “G” or “S” 30
No Arguments 31
Bad CREATE_XML Argument 31
Bad File Extensions 31
First XML File Doesn’t Exist 31
Process <runubexml> could not be registered 32
Introduction
The purpose of the paper is to provide documentation about how to run repots with the JDE ERP runubexml command. The paper explains the runubexml command, features, and give examples of how to use it. The information is intended for technical people who may have a need for command line execution of JDE reports or batches on an Enterprise Server. The command is also useful and important to customers who have the need to integrate JDE reporting with a production batch control system.
The runubexml program is another method for submitting batch jobs. It does not change or improve a reports performance. Existing jobs that work with the runube program should also work with runubexml.
The runubexml command was introduced with JDE OneWorld, SP17. However, there were issues found, and now with Service Pack 19 the command is reliable.
The paper’s focus is on the use of the command on UNIX and Windows based Enterprise Servers and UBE Servers. The runubexml command is also available on AS400 Enterprise Servers, but is not discussed in this paper.
Throughout the paper examples from the address book report, R014021 are used. This report was chosen because of its simplicity, and because it was a non-updating report. Demonstration data was used for the data set.
Features
The most unique, useful feature of runubexml is that XML documents are used to set report options and retrieve status information. This is a major advancement for JDE reporting. Before the command, this information was not easily accessible. Custom reports, programs and queries typically had to be developed to set report options and to get status information. Often these custom solutions are not flexible, and only work for a few specific reports. Runubexml offers a more general solution.
The runubexml XML documents can control or set the same common options that an interactive client does during a batch submission. The major controls that are now available are data selection and data sequencing. Data selection values can be directly manipulated in a XML document by an external program or an XML editor. This is the first time that this can be done outside of JDE ERP. Potentially, this means that reports can be dynamic in their data selection. For parallel or multi-threaded reports, this can mean better load balancing, or an even distribution data across the simultaneous reports.
The runubexml program also means there is production solution for parallelizing GL Post reports. The current approach requires either a manual interactive process, which is prone to errors, or custom development. One of the main data selections for the Post report is the GL Batch Number, which is a dynamic, changing, internally generated number. It is held in a database table. With a simple query along with runubexml, a production solution can be created.
Another feature that is available for the first time is the Job ID of the batch. A Job ID is critical for seeing the status of a report from an external program. It is also useful when a series of reports have dependencies. Many times a certain report must finish before other reports can be run. With a Job ID, a program can check if a specific report is still running or is finished and then proceed to the dependent batches.
For UNIX, another benefit of runubexml over runube is the user ID and password is in the XML file. With implementations that use runube, it is possible to see IDs and passwords with the UNIX “ps” command. The security risk goes away with runubexml.
In summary the main features and capabilities of the runubexml program are:
Ø External program control of data selection.
Ø Exposure of report Job ID.
Ø Hide report user ID and password.
Ø Direct manipulation of data sequencing values.
Ø Program control of UBE jde logging.
Ø Program control of UBE debug.
Using runubexml
The runubexml program or command submits a report to a batch or enterprise server just like any other batch submission process. The one exception is runube with “Interactive” switch options. Please see the section RunubeXML and Runube Differences for an explanation.
The runubexml program will use the same internal JDE processes as runube or an interactively submit job. It will use the UBE Kernel (Kernel 2). The status is kept in the Job Master table and can be seen in the Submitted Reports application. The same PDF output and the optional CSV output will be produced. It will also create Work Center messages, which are useful in checking the success of the batch. Finally, the report will be executed by the runbatch program at the operating system level.
While the internal processes and the system effects of running a batch with runubexml remain the same, the submission steps and setting report options are different.
Necessary Basics
The runubexml program is executed in a command window. The program is found on the server in the JDE system, bin32 directory.
System, Bin32 Directory
The best way to first test the command is to execute the command in the system, bin32 directory. Once you are satisfied that the command works, a Windows PATH or a UNIX ENV setting can be made, so the command can be executed in another directory. When executing runubexml program, the XML documents will be put in the directory or path that you execute the program in.
GOOD PRACTICE - It is a good practice not to put user files and user programs in the JDE system, bin32 directory. There are essential programs for JDE in this directory. Accidentally, if the standard files are corrupted, damaged or deleted, then the JDE ERP system will not work properly. To repair these inadvertent changes, the original file may have to be restored from the installation CDs.
To execute the runubexml program in another directory besides the bin32 directory, the Windows path or UNIX env setting may have to be changed. On the server, the Windows PATH or UNIX ENV must point to the JDE directories:
Ø bin32
Ø lib32
Ø libv32
All of the above directories are necessary to run the program in another directory besides the system, bin32 directory. The XML documents will be put in the directory where the runubexml program is executed. In Appendix – Windows2000 Path, there are instructions on how to set the Windows environment. In UNIX, the “.profile” or “.oneworld” file is modified to include the directory path for the env variable.
Computer ID & Report ID
Another simple but extremely important detail is the computer Login ID, and the JDE ERP ID. The computer Login ID runs the runubexml commands, while the JDE ERP ID is the one this used in the XML files.
The computer Login ID is usually the ID that starts JDE services. The reason for this is that the ID has all the permissions for the system and bin32 directories. If another computer ID is used, then the ID must have all the read, write, and execution permissions as the JDE ID. On UNIX, the computer ID will be something like jde7333 or jde7334.
The Report ID that is used in the base XML document is any valid JDE ERP ID. The report ID can be different from the computer login ID, but it does not have to be. Throughout the examples in the paper the JDE ID was used and the computer login ID was also JDE. If JDE ERP security has been setup for a report user ID, then it will still be in effect when using the runubexml program.
Editing & Errors in XML Documents
XML documents or files are text files. They are similar to HTML files in that there is a grammar with starting tag and ending tag, and have a specific structure. JD Edwards has created custom tags to work with the runubexml program.
When testing, a standard editor like vi or notepad can be carefully used to set values. However, in production it is strongly recommended that an XML editor or a programming language be used.
GOOD PRACTICE – In a production environment, use a XML editor or a programming language to change XML documents. Manual changes should only be done for testing purposes only. Manual changes for a production solution are prone to error and can produce inconsistent results.
Each of the runubexml execution steps parses the input XML file. If the XML file has been changed incorrectly or the syntax has been accidentally destroyed, then the runubexml program will not work.
For example, when a bad version name or wrong version name is entered in the base XML document, an error message will be in the request XML document. Many times the error can simply be corrected, and then repeat the execution step again. Some of the typical mistakes are described in Appendix – Common Errors.
GOOD PRACTICE - When using runubexml in a script, it good practice to manually scan each resulting XML file for error messages.
Runubexml & Runube Differences
Prior to runubexml, the command line program, runube, was used with batch schedulers and with custom script submission processes. Besides the tremendous benefit of externalizing report options in XML files, the runubexml has another major difference from the runube program. It externalizes the JDE JOB ID.
Job ID
This is an important difference, the JOB ID has to be use to see if the report has completed. The runube program does not have the functionality to return the JOB ID.
For developers adapting existing runube production scripts that use runube with its “Interactive” option, they will have to poll the Job Master table or the operating system to find the report’s status.
NOTE: Excessive polling of the F986110 table can affect overall batch performance and can cause a high number of database table locks.
RUNUBE Interactive Mode
In many controlling scripts, runube is used with the “Interactive” option. It has the effect of pausing in the script until the report has completed execution. It makes script development easy, since the script waits, and no testing has to be done for report completion.
While this is a useful feature for scripting, there is inherent risk with the “Interactive” option. The risk is that all the governing mechanisms, the limits setup up in the jde.ini file (Kernel 2 processes and Job Queues) are bypassed with the “Interactive” option. This means that if the runube command is submitted over and over again, the report will run as many times as it was submitted without any limitations. There is a potential that the Enterprise Server or batch server resource could be totally consumed.
The runubexml program does not have the equivalent “Interactive” feature. It processes report like runube does with the “Batch” option. This means that runubexml batch scripts must test for report or job completion. This difference will have an impact on scripts that chain multiple reports together.
However, runubexml does make it easy to test for report completion by giving the report JOB ID in the output XML file. With the runube command, there is not a way to get a specific reports ID without custom development. With runubexml, the JOB ID given in the output XML file, which then can be used to lookup the report’s specific computer process ID. A program can then be used to poll the Job Master table, F986110, for report completion.
Security
Another benefit of runubexml over runube is that JDE ERP IDs and passwords cannot be seen in the process information of UNIX. If the runube program is being used, a simple “ps” can show the ID and password. With runubexml the ID and password are not visible because they are in the base XML file.
Running RUNUBEXML
To execute the runubexml program is quite easy. There are only three steps. The XML documents details and settings are more complex. A few key elements in the XML documents need to be understood to be successful with the program. The main XML elements will be described in later sections.
There are three possible steps for the runubexml program executing in a command line window on the Enterprise Server or Batch Server. The first step creates a generic template or a base file. The file must be changed to specify a valid JDE ERP ID, password, environment, report name, and report version. Other informational options can also be set in the base file.
The second step generates a report request file. The request file also has optional steps like data selection and logging. The last step submits the request XML file and runs the report on the server, and also produces an output file that has the JOB ID.