Understanding XML

This chapter discusses:

• XML and JD Edwards EnterpriseOne.

• XML document format.

• XML standards.

• System environment configuration.

• XML kernel troubleshooting.

XML and JD Edwards EnterpriseOne

Oracle's JD Edwards EnterpriseOne XML solution supports well-formed XML documents. The XML solution supports both UTF-8 and UTF-16 Unicode standards for receiving information into JD Edwards EnterpriseOne. The XML solution supports UTF-8 Unicode standard for sending information from JD Edwards EnterpriseOne. The JD Edwards EnterpriseOne XML solution includes:

Some of the benefits of using XML include:

• Scalable XML models that enable you to open multiple connections.

• Ability to use JD Edwards EnterpriseOne messaging adapters, providing a reliable connection and acknowledging operations.

• Exposure of business functions and interface tables.

• Ability to aggregate business function calls into one document, which reduces network traffic.

• Ability to manage session creation, validation, and tracking.

If you can create XML documents on the interoperability server, you can use XML for the interoperability solution.

See Also

World Wide Web Consortium (W3C) XML, http://www.w3.org/XML/

XML Document Format

This section provides an overview of formatting XML documents for JD Edwards EnterpriseOne and discusses these elements:

• Type Element

• Establish Session

• Expire Session

• Terminate Session

• Explicit Transaction

• Implicit Transaction

• Prepare/Commit/Rollback

• Terminate Session

Formatting XML Documents

When you send an XML document to JD Edwards EnterpriseOne for processing, the document must be in the XML format that is defined by JD Edwards EnterpriseOne. After the document reaches the JD Edwards EnterpriseOne server, the system processes the document based on the document type. All XML documents must contain these elements:

• One of these types:

  • jdeRequestType

  • jdeResponseType

• Establish Session

• Expire Session

• Terminate Session

In addition, you can use these optional elements:

• Explicit Transaction

• Implicit Transaction

• Prepare/Commit/Rollback

Type Element

The type element, which can be jdeRequest or jdeResponse, is the root element for all request documents coming into the XML infrastructure. This element contains basic information about the execution environment. These attributes form the jdeRequest and jdeResponse type element:

Establish Session

You establish a session by setting the session attribute of the standard jdeRequest element. When the session attribute is an empty string, a new session is started. On the server, the SessionManager singleton class creates a new instance of a session object given the user name, password, and environment name. The session can be reused before it expires to avoid the overhead of session initialization. You can specify the session ID in the session attribute for an already established session in an earlier request.

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='steve' pwd='xyz'
environment='prod' role='*ALL' session='' sessionidle='1800'>
</jdeRequest>

Note. If you do not want to start a new session, then remove the session=' ' tag. This example is for starting a new session.

Expire Session

Session expiration is addressed by the sessionidle attribute of the standard jdeRequest element. This attribute, when given on a session creation request, specifies the amount of time in seconds that this session is allowed to be idle. If the SessionManager determines that a session has not had any requests processed in this amount of time, it terminates the session and frees all associated resources. The session idle default value is 30 minutes. The session idle time is defined in the XML document.

<?xml version='1.0'?>
<jdeRequest type='callmethod' user='steve' pwd='xyz'
environment='prod' role='*ALL' session='' sessionidle='1800'>
</jdeRequest>

Explicit Transaction

Explicit database transactions are supported by another element, the startTransaction tag. The startTransaction tag specifies whether transactions are to be manually or automatically committed. The startTransaction tag element is an empty element, which means that all of the information is in the attributes.

<?xml version='1.0'?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' 
role='*ALL' session=''>
</jdeRequest>

Implicit Transaction

An XML request is included in a transaction set when the name of a transaction set is referenced in its trans attribute. Implicit start transactions can be included in the request by specifying the name of a transaction set that has not previously been created. For an implicit start, the transaction set will be a manual commit set.

<?xml version='1.0'?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' 
role='*ALL' session=''>
<callMethod name='myfunc' app='P42101' trans='t1'>
<params>
<param name='CostCtr'>   1001</param>
</params>
</callMethod>
</jdeRequest>

Prepare/Commit/Rollback

Manual transaction sets can be committed or rolled back. As part of a two-phase commit, they can be prepared to commit. Prepare, commit, and rollback requests to the database are made by using the endTransaction element. The transaction set is identified by the trans attribute. The action attribute indicates the action to take on the transaction set. The value can be prepare, commit, or rollback. This element is always an empty element, as indicated by the forward slash.

It is recommended that you manage the session ID when doing manual commits and terminate the session after the transaction is complete.

<?xml version='1.0'?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' 
role='*ALL' session=''
<endTransaction trans='t1' action='commit'/>
</jdeRequest>

Note. If startTransaction and endTransaction are in separate documents, one of these scenarios occurs:

The session attribute is not sent in the second document. In this case, the system uses the user ID, password, and environment to match the previous session.

The session number from the response of the first document is sent in the session attribute of the documents associated with the same transaction.

Terminate Session

Session termination is done by submitting an XML document to explicitly terminate the session. You must specify the session to be terminated in the jdeRequest element tag.

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' 
role='*ALL' session=5665.931961929.454'>
<endSession/>
</jdeRequest>

XML Standards

In addition to ensuring that your XML documents have the required format elements (jdeRequest or jdeResponse Type, Establish Session, Expire Session, and Terminate Session), JD Edwards EnterpriseOne has standards for XML documents that are different from industry standards. Also, some special characters are reserved for XML and can't be used directly.

This section discusses:

• Decimal and comma separators.

• Data usage.

• Industry standards for special characters.

Decimal and Comma Separators

JD Edwards EnterpriseOne uses the decimal and thousands separators differently than XML industry standards. The decimal and thousands separators do not depend on use profile settings, jde.ini settings, or regional settings for the computer. When you write XML documents to interface with JD Edwards EnterpriseOne, you must always use the decimal character (.) (period) as a decimal separator, and a comma (,) as a thousands separator. The purpose of the separator standards is to achieve consistent interoperability policy and to prevent data corruption.

Date Usage

Different components of the XML foundation use different format codes and APIs to format these dates:

• to XML date

• from XML date

• to JDEDATE

• from JDEDATE

This table explains the formats that are used by each XML component supported by JD Edwards EnterpriseOne:

* Component ignores the format code

Industry Standards for Special Characters

In XML, some special characters are reserved for internal use, and to use these characters in data, you must replace them with entity or numeric references. This table shows the special characters that are reserved for XML along with the entity and numeric references that enable you to use a special character in your XML documents:

Another way to use special characters in your XML documents is to use the CDATA section. Any text inside a CDATA section is ignored by the parser.

System Environment Configuration

Before you can use XML with JD Edwards EnterpriseOne, you must ensure that the ICU_DATA system environment variable is correctly defined on your JD Edwards EnterpriseOne system. If the ICU_DATA variable is not correctly defined, JD Edwards EnterpriseOne produces this error message:

The default Unicode converter could not be found within the jdenet_n.log on the OneWorld Enterprise Server.

For JD Edwards EnterpriseOne, the ICU conversion table, icu_data.dat, is generally located in system/locale/xml. Use the appropriate setting for your platform.

This section discusses:

• UNIX

• iSeries

• WIN32

UNIX

For UNIX systems, the ICU_DATA path is based on the ICU_DATA environment variable. The UNIX JD Edwards EnterpriseOne user login script sets the ICU_DATA environment variable to the directory location of the ICU resource file, incudata.dat. If the user login script does not set the ICU_DATA environment variable, you must define the ICU_DATA variable with a trailing slash, for example:

Export ICU_DATA=$SYSTEM/locale/xml/

Where $SYSTEM represents your JD Edwards EnterpriseOne install directory.

To support the loading of the JVM, verify the environment variable configuration for your platform.

HPUX

Verify these environment variable configurations for a HPUX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/PA_RISC/server:
$SYSTEM/jre/1.4/lib/PA_
RISC:${LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/PA_RISC/server:
$SYSTEM/jre/1.4/lib/PA_RISC:${SHLIB_PATH}

AIX

Verify these environment variable configurations for an AIX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/bin:
$SYSTEM/jre/1.4/lib/bin/classic:${LD_LIBRARY_PATH}
export LIBPATH=$SYSTEM/jre/1.4/lib/bin:$SYSTEM/jre/1.4/lib/bin/classic:
${LIBPATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/bin:
$SYSTEM/jre/1.4/lib/bin/classic:${SHLIB_PATH}

SUN

Verify these environment variable configurations for a SUN platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/sparc/server:
$SYSTEM/jre/1.4/lib/sparc:${LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/sparc/SERVER:
$SYSTEM/jre/1.4/lib/sparc:${SHLIB_PATH}

Note. Make sure that the server directory is first. The sparc directory has a libjvm.so just like the server directory, and the libjvm.so in the server directory is the directory you want to use.

LINUX

Verify these environment variable configurations for a LINUX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/i386/server:
$SYSTEM/jre/1.4/lib/i386L:{LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/i386/server:
$SYSTEM/jre/1.4/lib/i386:S{SHLIB_PATH}

iSeries

For iSeries systems, the ICU_DATA path is set when the ICU 1.6 conversion function is first called by the system. The system looks up Data Area BUILD_VER in the system library for the System Directory setting. For example:

System Directory: B9_S

The system appends locale/xml to the path specified in the BUILD_VER, and then uses this path as the ICU_DATA path. You must ensure the BUILD_VER data area is properly set to reflect the system directory setting.

WIN32

For WIN32 systems, the ICU_DATA path is set when the ICU 1.6 conversion function is first called. This logic is used on WIN32:

1. The system looks up the environment variable JDE_B9_ICU_DATA. If this environment is found, it becomes the path for the conversion files.

2. The system looks for this section in the jde.ini file:

   [XML]
   ICUPath=<<install>>/system/locale/xml

   If the ICUPath setting is found, it becomes the path for the conversion files.

3. If the system cannot find the ICUPath setting in the jde.ini file, the ICU_Path is:

   EXECUTABLE_DIRECTORY/./system/locale/xml

   The EXECUTABLE_DIRECTORY must be <<install>>/system/bin32.

Based on this logic, you usually do not need to set the JDE_B9_ICU_DATA ENVIRONMENT variable or the jde.ini file. You need to set the jde.ini ICUPath only when the location of the icudata.dat is different from system/locale/xml.

Note. The JD Edwards EnterpriseOne client install sets the environment variable JDE_B9_ICU_DATA.

XML Kernel Troubleshooting

If one or more XML kernels are not working properly, use these troubleshooting guidelines to ensure that your system is set up correctly:

• Check the kernel definition in the server jde.ini file.

  Also check that the library name is correct for the platform on which you are running. Check the entry function name.

• Check that the kernel is allowed to start.

  Check the maxNumberOfProcesses and numberOfAutoStartProcesses values for the kernel in the server jde.ini file. It is not necessary to auto start kernels. To work with a particular kernel, the allowed number of processes should be one or more.

• If you have a large number of simultaneous requests that are made to a particular kernel type, increase the number of allowed processes for that kernel.

  This will not only reduce the turnaround time for requests but will also eliminate any Queue Full errors.

• If you are using XMLList kernel, check that the LREngine section is correctly set up in the server jde.ini file and that the specified path exists.

  Also, check that the JD Edwards EnterpriseOne user has write permission to this location.

• Check that the XML document is a well-formed XML document.

  To do this, use any XML editor or open the document in Microsoft Internet Explorer and check for errors.

• Check that the root of the input XML document is jdeRequest.

  All input XML documents should have jdeRequest as their root element.

• Check that valid user ID, password, and environment are provided in the XML document.

• Check that the request type in the XML document is correct. The allowed request types are callmethod, list, and trans for XMLCallObject, XMLList, and XMLTransaction kernels, respectively.