10 Understanding XML List

This chapter contains the following topics:

Section 10.1, "XML List"
Section 10.2, "List-Retrieval Engine Table Conversion Wrapper"
Section 10.3, "XML List Process"
Section 10.4, "XML List Requests"
Section 10.5, "List-Retrieval Engine jde.ini File Configuration"
Section 10.6, "XML List jde.ini File Configuration"

10.1 XML List

XML List is XML-based interoperability that runs as a JD Edwards EnterpriseOne kernel process. XML List provides List/GetNext functionality that enables you to collect a list of records from JD Edwards EnterpriseOne. XML List is built on the JD Edwards EnterpriseOne table conversion (TC) engine. XML List takes an XML document as a request and returns an XML document with the requested data. A list can represent data in a table, a business view, or data from a table conversion. Using data from a table conversion enables you to use multiple tables. By sending an XML document, you can retrieve metadata for a list, create a list, retrieve a chunk of data from a list, or delete a list. You can send the request through JDENet or third-party software to perform any of these operations:

CreateList
GetTemplate
GetGroup
DeleteList

XML List provides both trivial and non-trivial List/GetNext APIs. A trivial List/GetNext API performs simple gets such as selecting data from a single table. A non-trivial API uses additional functionality such as event rules. Each non-trivial List/GetNextBPAPI must have a table conversion designed for it. The data selection and data sequencing can be defined in an XML request at runtime.

XML List provides a list-retrieval engine that enables you to create an XML data file in the system repository and then retrieve the data in small chunks.

10.2 List-Retrieval Engine Table Conversion Wrapper

A list-retrieval engine is an optimized database engine that provides and manages access to XML repository files. Each XML list repository file is a pair of index and data files with *.idb and *.ddb extensions. The .idb file keeps an index that is generated on a data file, and the .ddb file keeps data that is generated by the table conversion engine. TCWrapper is a system module that aggregates list-retrieval and list-processing APIs from TCEngine and list-retrieval engine and provides a uniform access to the data for XML List.

10.3 XML List Process

This illustration shows the XML List process for both a trivial and non-trivial XML List request:

Figure 10-1 XML List process flow

Description of "Figure 10-1 XML List process flow"

In summary:

JDENet receives the XML document.
JDENet passes the XML document to the XML List kernel.
If the request is for CreateList or GetTemplate, XML List creates a session.
If the request is a trivial request, XML List retrieves the data and creates a response message to send to the requestor.
If the request is a non-trivial request, XML List kernel passes the request to the appropriate API:
- GetTemplate
- CreateList
- GetGroup
- DeleteList
A table conversion wrapper processes data retrieved as a result of a non-trivial request. The table conversion wrapper aggregates list-retrieval and list-processing APIs from the table conversion engine and the list-retrieval engine to provide a uniform access to the data.

10.4 XML List Requests

You can make any of these requests using XML List:

XML List Request	Description
GetTemplate	Send a request to retrieve metadata information for a list so that you can add data selection and data sequencing to the CreateList request.
CreateList	Send a request with TC/Table name along with data selection and sequencing. The response is an XML document that has a handle and size that is associated with the created list in the repository.
GetGroup	Send a request to retrieve data from the generated list by the previous CreateList request. GetGroup passes the handle value and range of records to be retrieved.
DeleteList	Send a request to delete a list from the repository.

This illustration shows the various components in list operations:

Figure 10-2 XML List operations components

Description of "Figure 10-2 XML List operations components"

10.4.1 Creating a List

This code example illustrates using CreateList for an XML request with the TC Name/Table Name and data selection and sequencing. The system returns an XML response with a handle that is associated with the created list:

<?xml version="1.0"?>
<jdeRequest type="list" user="JDE" pwd="JDE" environment="PRODHP01"
role='*ALL' session="" sessionidle="">
 <ACTION TYPE="CreateList">
  <TC_NAME VALUE=""/>
  <TC_VERSION VALUE=""/>
  <FORMAT VALUE="UT"/>
    <RUNTIME_OPTIONS>
    <DATA_SELECTION>
     <CLAUSE TYPE="WHERE">
       <COLUMN NAME="" TABLE="" INSTANCE="" ALIAS=""/>
       <OPERATOR TYPE="EQ"/>
       <OPERAND>
        <COLUMN NAME="" TABLE="" INSTANCE="" ALIAS=""/>
        <LITERAL VALUE=""/>
        <LIST>
          <LITERAL VALUE=""/>
        </LIST>
        <RANGE>
          <LITERAL_FROM VALUE=""/>
          <LITERAL_TO VALUE=""/>
        </RANGE>
       </OPERAND>
     </CLAUSE>
<CLAUSE TYPE="OR">
       <COLUMN NAME="" TABLE="" INSTANCE="" ALIAS=""/>
       <OPERATOR TYPE="EQ"/>
       <OPERAND>
        <COLUMN NAME="" TABLE="" INSTANCE="" ALIAS=""/>
        <LITERAL VALUE=""/>
        <LIST>
          <LITERAL VALUE=""/>
        </LIST>
        <RANGE>
          <LITERAL_FROM VALUE=""/>
          <LITERAL_TO VALUE=""/>
        </RANGE>
       </OPERAND>
     </CLAUSE>
    </DATA_SELECTION>
    <DATA_SEQUENCING>
     <DATA SORT="ASCENDING">
       <COLUMN NAME="Product Code" TABLE="F0004" INSTANCE="" ALIAS=""/>
     </DATA>
    </DATA_SEQUENCING>
  </RUNTIME_OPTIONS>
 </ACTION>
</jdeRequest>

Either TC_NAME and TC_VERSION or TABLE_NAME and TABLE_TYPE must be defined in the request. TABLE_TYPE can be one of these:

OWTABLE
OWVIEW
FOREIGN_TABLE

FORMAT VALUE is an optional attribute of the FORMAT element that enables full mode or concise mode formatting in the response message. UT is the only FORMAT value that is supported. If you do not set the VALUE="UT" attribute on the FORMAT element, the response message uses concise formatting, which is illustrated in this sample response:

<F0005>
   <SY>00</SY>
   <RT>03</RT>
   <KY>   DIR</KY>
   <DL01>Direct Manufacturing</DL01>
   <DL02> </DL02>
   <SPHD> </SPHD>
   <UDCO> </UDCO>
   <HRDC> </HRDC>
   <USER>DEMO</USER>
   <PID>P00051</PID>
   <UPMJ>2055/05/12</UPMJ>
   <JOBN>V3477JG51</JOBN>
   <UPMT>175301</UPMT>
</F0005>

If you do not use the <FORMAT VALUE> element or you do not set the attribute to UT in the request, the response message uses full formatting, which is illustrated in this sample response:

<FORMAT NAME='F0005'>
    <COLUMN ALIAS='SY'>00</COLUMN>
    <COLUMN ALIAS='RT'>03</COLUMN>
    <COLUMN ALIAS='KY'>       DIR</COLUMN>
    <COLUMN ALIAS='DL01'>Direct Manufacturing</COLUMN>
    <COLUMN ALIAS='DL02'>        </COLUMN>
    <COLUMN ALIAS='SPHD'> </COLUMN>
    <COLUMN ALIAS='UDCO'> </COLUMN>
    <COLUMN ALIAS='HRDC'> </COLUMN>
    <COLUMN ALIAS='USER'>DEMO</COLUMN>
    <COLUMN ALIAS='PID'>P00051</COLUMN>
    <COLUMN ALIAS='UPMJ'>2055/05/12</COLUMN>
    <COLUMN ALIAS='JOBN'>V3477JG51</COLUMN>
    <COLUMN ALIAS='UPMT'>175301</COLUMN>
</FORMAT>

The CLAUSE can be WHERE, OR, or AND to simulate an SQL statement.

You can specify the COLUMN NAME with any meaningful name to help recognize the real column name in the table, which should be defined in ALIAS. The values of TABLE, INSTANCE, and ALIAS should be the same as those in the XML response that is returned by a GetTemplate request. For example, if Column X is in the data selection, it should be <COLUMN NAME=My column TABLE=F9999 INSTANCE=0 ALIAS=X/> because information is returned by a GetTemplate request and is similar to this example:

<COLUMN NAME="X" ALIAS="X" TYPE="String" LENGTH="32" TABLE="F9999" INSTANCE="0">

The OPERATOR uses values of EQ, NE, LT, GT, LE, GE, IN, NI, BW (between) or NB.

The OPERAND node can contain one of the these supported element types:

Column
Literal
List
Range

This XML node, which is a template fragment that should be used with only one of the supported elements, shows the supported elements in the OPERAND node:

<CLAUSE TYPE="WHERE">
 <COLUMN NAME="UserDefinedCodes" TABLE="F0005" INSTANCE="" ALIAS="RT"/>
 <OPERATOR TYPE="EQ"/>
 <OPERAND>
    <COLUMN NAME="" TABLE="" INSTANCE="" ALIAS="null"/>
    <LITERAL VALUE="P4"/>
    <RANGE>
    </RANGE>
 </OPERAND>
</CLAUSE>

These sample XML nodes show the operator type and the operand using the different supported elements.

If the operand is a COLUMN, populate the COLUMN element. For example:

<CLAUSE TYPE="WHERE">
 <COLUMN NAME="DRSY" TABLE="F0005" INSTANCE="0" ALIAS="SY"/>
 <OPERATOR TYPE="EQ"/>
 <OPERAND>
    <COLUMN NAME="DRRT" TABLE="F0005" INSTANCE="0" ALIAS="RT"/>
 </OPERAND>
</CLAUSE>

If the operand is a LITERAL, populate the LITERAL element. For example:

<CLAUSE TYPE="WHERE">
 <COLUMN NAME="DRSY" TABLE="F0005" INSTANCE="0" ALIAS="SY"/>
 <OPERATOR TYPE="EQ"/>
 <OPERAND>
    <LITERAL VALUE="08"/>
 </OPERAND>
</CLAUSE>

If the operand is a LIST, populate the element LIST. LIST should be used with IN or NI. For example:

<CLAUSE TYPE="WHERE">
 <COLUMN NAME="DRSY" TABLE="F0005" INSTANCE="0" ALIAS="SY"/>
 <OPERATOR TYPE="IN"/>
 <OPERAND>
    <LIST>
        <LITERAL VALUE="08"/>
        <LITERAL VALUE="09"/>
    </LIST>
 </OPERAND>
</CLAUSE>

If the operand is a RANGE, populate the element RANGE. RANGE should be used with BW or NB. For example:

<CLAUSE TYPE="WHERE">
 <COLUMN NAME="DRSY" TABLE="F0005" INSTANCE="0" ALIAS="SY"/>
 <OPERATOR TYPE="BW"/>
 <OPERAND>
    <RANGE>
        <LITERAL_FROM VALUE="08"/>
        <LITERAL_TO VALUE="10"/>
    </RANGE>
 </OPERAND>
</CLAUSE>

The XML response for a CreateList request is similar to this:

<?xml version="1.0"?>
<jdeResponse type="list" session="5665.931961929.454">
<returnCode code="0">XMLRequest OK</returnCode>
 <ACTION TYPE="CreateList">
           <TABLE_NAME VALUE="F0005">
    <HANDLE>"1r4670001"</HANDLE>
    <SIZE>773</SIZE>
 </ACTION>
</jdeResponse>

The value of HANDLE can be published and referenced in a GetGroup or DeleteList request.

10.4.2 Retrieving Data from a List

You can retrieve data from a list generated by a previous CreateList request by using a GetGroup request. The HANDLE, FROM VALUE, and TO VALUE can be defined in the request:

<?xml version="1.0"?>
<jdeRequest type="list" user="JDE" pwd="JDE" role="*ALL" environment="PRODHP01">
 <ACTION TYPE="GetGroup">
  <HANDLE VALUE="lr4670001"/>
  <FROM VALUE="10"/>
  <TO VALUE="50"/>
 </ACTION>
</jdeRequest>

The XML response lists records falling into the range specified. The default FROM value is the first record and the default TO value is the last record in the list. For a GetGroup request for the whole list, no FROM and TO values need to be specified. In this sample code, the response returns the records in the list from #10 to #50:

<?xml version="1.0"?>
<jdeResponse type="list">
<returnCode code="0">XMLRequest OK</returnCode>
<ACTION TYPE="GetGroup">
<HANDLE VALUE="lr4670001"/>
   <FROM VALUE="10"/>
   <TO VALUE="50"/>
 <Format name="Standard"><Column name="X">abc</Column><Column name="Y">
edf</Column></Format>
 00
 </ACTION>
</jdeResponse>

10.4.3 Deleting a List

A list can be deleted if all GetGroup requests are done:

<?xml version="1.0"?>
<jdeRequest type="list" user="JDE" pwd="JDE" role="*ALL" environment="PRODHP01">
 <ACTION TYPE="DeleteList">
   <HANDLE VALUE="lr4670001"/>
 </ACTION>
</jdeRequest>

The list result defined in the HANDLE is deleted from the storage and a response with the status is returned to the caller:

<?xml version="1.0"?>
<jdeResponse type="list">
<returnCode code="0">XMLRequest OK</returnCode>
 <ACTION TYPE="DeleteList">
<HANDLE VALUE="lr4670001"/>
   <STATUS>OK</STATUS>
 </ACTION>
</jdeResponse>

10.4.4 Getting Column Information for a List

You can send a GetTemplate request to get the column information for a list so that data selection and sequencing can be added to the CreateList request. If OUTPUT is defined in the TEMPLATE_TYPE, the response is only for those columns in the XML output generated by a CreateList request based on the table conversion. For a trivial table conversion, both templates should be the same. The default template type is INPUT if no tag is specified.

<?xml version="1.0"?>
<jdeRequest type="list" user="JDE" pwd="JDE" role="*ALL" 
environment="PRODHP01" session="" sessionidle=""> 
 <ACTION TYPE="GetTemplate">
  <TABLE_NAME VALUE="F0004"/>
  <TABLE_TYPE VALUE="OWTABLE"/>
  <TEMPLATE_TYPE VALUE="OUTPUT"/>
 </ACTION>
</jdeRequest>

The response for the input template lists all of the columns with alias name, type and the length of the data type, even though the length is only meaningful for the string type.

<?xml version="1.0"?>
<jdeResponse type="list" session="5665.931961929.454">
<returnCode code="0">XMLRequest OK</returnCode>
 <ACTION TYPE="GetTemplate">
  <TABLE_NAME VALUE="F0004"/>
  <TABLE_TYPE VALUE="OWTABLE"/>
  <TEMPLATE_TYPE VALUE="INPUT"/>
  <COLUMN Name="Address" Alias="X" TYPE="String" LENGTH="32" TABLE="F9999" 
INSTANCE="0">
 </ACTION>
</jdeResponse>

10.5 List-Retrieval Engine jde.ini File Configuration

The list-retrieval engine uses a predefined folder as its system directory to keep and manage repository files. This system directory should be configured in jde.ini file as follows:

[LREngine]
System=C:\output
Repository_Size=20 (allocates percentage of disk free space for XML list 
repository)
Disk_Monitor=Yes (monitors free space on the disk)

Note:

The engine uses the IFS file system on IBM i, so a corresponding system subsection must be set up.

Caution:

For data privacy, be sure to remove the global read access rights for the specified directory.

The [SECURITY] section of the jde.ini file should also be configured. The default environment, password, and user settings should be filled in for the engine to validate the default user and to initialize the default environment.

10.6 XML List jde.ini File Configuration

The XML List kernel must be defined in the jde.ini file.

10.6.1 [JDENET_KERNEL_DEF16]

Use these settings for a Microsoft Windows platform:

krnlName=XML LIST
dispatchDLLName=xmllist.dll
dispatchDLLFunction=_XMLListDispatch@28
maxNumberOfProcesses=3
beginningMsgTypeRange=5257
endingMsgTypeRange=5512
newProcessThresholdRequest=0
numberOfAutoStartProcesses=1

This table provides the different .dll extensions for other platforms:

Platform	dispatchDLLName	dispatchDLLFunction
IBM i	XMLLIST	XMLListDispatch
Solaris, Linux, AIX, or HP-UX	libxmllist.so	XMLListDispatch