8 Understanding XML CallObject

This chapter contains the following topics:

8.1 XML CallObject

XML CallObject is XML-based interoperability that runs as a JD Edwards EnterpriseOne kernel process. You can also use XML CallObject with a messaging adapter. Some features of XML CallObject include:

  • The ability to make business function calls to JD Edwards EnterpriseOne using XML documents.

  • Business function templates and the ability to create your own templates.

  • The ability to call multiple business functions using a single XML document.

  • A simpler way of interfacing with JD Edwards EnterpriseOne as compared to using COM or Java APIs.

8.2 XML CallObject Templates

XML CallObject provides a blank template that you can complete to make CallObject requests for a given business function. You also have the option of creating your own custom XML documents.

To request an XML template for a given business function, you create an XML document that is a callMethod request type. When you make a CallObject template request, the response is the template that has information about all of the function parameters but is not populated with data values. The user, password, and session attribute values are blank so that you can cache the response for later use.

A CallObject template request is an exception to the convention that a jdeRequest returns a jdeResponse. Instead of data, you receive the template, which you use to make another callMethod request. When you request a CallObject template, the request for the template is the only request that can be made in the XML document. The XML document must include the business function.

This example illustrates a request for a CallObject template:

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' 
role="*ALL" session=''>
<callMethodTemplate name='myfunc' app='P42101'/>
</jdeRequest>

This example illustrates a response to a CallObject template request. This response can then be filled in with the appropriate information and sent back as a request.

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

See XML Format Examples (All Parameters).

8.3 XML CallObject Process

This diagram illustrates XML CallObject processing:

Figure 8-1 XML CallObject process flow

Description of Figure 8-1 follows
Description of "Figure 8-1 XML CallObject process flow"

In summary:

  • The JD Edwards EnterpriseOne server receives an XML document.

  • XML CallObject processes the message by parsing the XML document.

  • The session manager validates the user and password.

  • Each requested business function is called separately or within requested transaction boundaries until all calls are processed.

  • Output data and error messages are merged with the data from the input XML document and a new response document is created and sent to the originator.

8.4 XML CallObject Document Format

This section provides an overview for formatting XML CallObject documents and discusses these elements:

  • Call Object

  • OnError Handling

  • Call Object Error Handling

  • Error Text

  • Multiple Requests per Document

  • ID/IDREF Support

  • Return NULL Values

8.4.1 XML CallObject Formatting Documents

Your XML document must have these elements at the beginning of the document:

  • jdeRequest Type

  • Establish Session

  • Expire Session

Your XML document must end with Terminate Session.

Your XML CallObject document can also have these optional elements:

  • Call Object

  • On Error Handling

  • Call Object Error Handling

  • Error Text

  • Multiple Requests per Document

  • ID/IDREF Support

  • Return NULL Values

8.4.2 Call Object

Tags are used to call business functions on the server.

This sample code shows how to use callObject:

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' role='*ALL' 
environment='prod'>
<callMethod name='myfunc' app='P42101'>
<params>
<param name='CostCtr'>    1001</param>
<param name='ExpDate'>1999/10/31</param>
<param name='Quantity'>12</param>
</params>
</callMethod>
</jdeRequest>

The callMethod element details which function to call and in what context it is being called. The name attribute specifies which business function to call, and the application attribute enables the business function to know who is calling it.

The parameters and parameter elements define the data structure of the business function. Each parameter element describes one data structure member. The caller is only required to give the name attribute.

If no parameter element value is given for an input data structure member, then the value will be treated as if it were NULL or zero.

8.4.3 OnError Handling

You can add an onError element to the callMethod request to take a specific action if an error occurs. The onError tag can specify an abort attribute that specifies whether all subsequent requests should be skipped. The allowed values are yes or no. A global onError tag can be specified as a child of the jdeRequest tag, which will be executed if errors were encountered and no other onError tag with abort='yes' was executed. The global onError tag should be the last request in the document.

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

8.4.4 Call Object Error Handling

System errors on a call object are reported in the returnCode element. The numeric code is returned in the code attribute, and the corresponding text is returned as a child text node of the returnCode element. The standard jdeCallObject return codes are used for the code attribute.

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

8.4.5 Error Text

Business function error messages are returned in the errors element. Within the errors element, there can be zero or more error elements that contain a code attribute for the error code and a child text node that contains the error text. The name attribute describes the parameter element that is referred to by the error.

<?xml version='1.0' ?>
<jdeResponse type='callmethod' user='steve' pwd='xyz' role='*ALL' 
environment='prod' session=''>
<callMethod name='myfunc' app='P42101' trans='t1'>
<params>
<param name='CostCtr'>    1001</param>
</params>
<returnCode code='2'>Errors</returnCode>
<errors>
 <error code='192' name='CostCtr'>Cost Center not valid</error>
</errors>
</callMethod>
</jdeResponse>

8.4.6 Multiple Requests per Document

You can include multiple requests in the XML document. Requests are not run if there have been any errors on previous requests. If a request should be run, even if errors have occurred, then you can override the default behavior by using the runOnError attribute on the request with a value of yes.

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

8.4.7 ID/IDREF Support

ID type attributes uniquely identify, by a string value, elements in a XML document. IDREF attributes enable other elements to reference the specified element. An IDREF attribute must not be used in a document before the ID it references is defined.

A parameter element can specify an ID attribute so that its output value from the callMethod request will be saved and referred to later in another parameter element by an IDREF attribute. If a parameter element contains an IDREF attribute, the value of the given parameter is used as the input value for the parameter element. For example, the output value from referenced parameter is used instead of the value in the XML.

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='steve' pwd='xyz' role='*ALL' 
environment='prod' session=''>
<callMethod name='myfunc' app='P42101' trans='t1' runOnError='yes'>
<params>
<param name='CostCtr'>    1001</param>
<param name='Company1' id='c1'></param>
<param name='Company2' id='c2'></param>
</params>
</callMethod>
<callMethod name='myfunc2' app='P42101' trans='t1' runOnError='yes'>
<params>
<param name='Company1' idref='c1'></param>
</params>
<returnParams><param idref='c2'/></returnParams>
</callMethod>
</jdeRequest>

You can specify a special request tag called returnParams that can contain one or more parameter elements. If the parameter elements contain IDREF attributes, then the referenced values are copied into the response.

8.4.8 Return NULL Values

If a parameter was not specified in the request document, it will not be returned in the response document unless its value is non-blank or non-zero. This behavior can be modified by specifying the returnNullData attribute on the callMethod element with a value of yes.

<?xml version='1.0' ?>
<jdeRequest type='callmethod' user='' pwd='' role='*ALL' environment='prod' 
session=''>
<callMethod name='myfunc' app='P42101' returnNullData='yes'>
<params>
<param name='CostCtr'></param>
<param name='ExpDate'></param>
<param name='Quantity'></param>
</params>
</callMethod>
</jdeRequest>

8.5 XML CallObject jde.ini File Configuration

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

8.5.1 [JDENET_KERNEL_DEF6]

This examples illustrates settings for a Microsoft Windows platform:

krnlName=CALL OBJECT KERNEL
dispatchDLLName=XMLCallObj.dll
dispatchDLLFunction=_XMLCallObjectDispatch@28
maxNumberOfProcesses=1
numberOfAutoStartProcesses=1

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

Platform dispatchDLLName dispatchDLLFunction
IBM i XMLCALLOBJ XMLCallObjectDispatch
HP9000 libxmlcallobj.sl XMLCallObjectDispatch
SUN or RS6000 libxmlcallobj.so XMLCallObjectDispatch

8.5.2 Example: CallObject Request

This code sample shows a CallObject request:

<?xml version="1.0" encoding="utf-8" ?>
<jdeRequest pwd="JDE" type="callmethod" user="JDE" role="*ALL" 
 session="" environment="M7333NIS2" sessionidle="1800">
<callMethod app="XMLTest" name="AddressBookMasterMBF">
 <params>
  <param name="cActionCode">A</param>
  <param name="cUpdateMasterFile">1</param>
  <param name="mnAddressBookNumber" idref="ABNumber" />
  <param name="szSearchType">C</param>
  <param name="szAlphaName">bobs</param>
  <param name="szMailingName">Bob's Shrimp boats</param>
  <param name="szAddressLine1">One Technology Way</param>
  <param name="szPostalCode">80237</param>
  <param name="szCity">Denver</param>
  <param name="szCounty">Denver</param>
  <param name="szState">CO</param>
  <param name="szCountry">US</param>
  <param name="cPayablesYNM">N</param>
  <param name="cReceivablesYN">Y</param>
  <param name="cEmployeeYN">N</param>
  <param name="cUserCode">N</param>
  <param name="cARAPNettingY">N</param>
  <param name="jdDateEffective">01/23/2001</param>
  <param name="szProgramId">EP01012</param>
  <param name="mnAddNumParentOriginal">0</param>
  <param name="szVersionconsolidated" idref=Version />
  <param name="szCountryForPayroll">US</param>
 </params>
</callMethod>
</jdeRequest>

8.5.3 Example: CallObject Response

This code sample shows a CallObject response:

<?xml version="1.0" encoding="UTF-8" ?>
<jdeResponse pwd="JDE" role="*ALL" type="callmethod" user="JDE" 
session="2360.1049473980.6" environment="PDEVNIS2" sessionidle="1800">
<callMethod app="XMLTest" name="AddressBookMasterMBF">
<returnCode code="0" />
 <params>
  <param name="cActionCode">A</param>
  <param name="cUpdateMasterFile">1</param>
  <param name="mnAddressBookNumber">57322</param>
  <param name="szSearchType">C</param>
  <param name="szAlphaName">bobs</param>
  <param name="szMailingName">Bob's Shrimp boats</param>
  <param name="szBusinessUnit">1</param>
  <param name="szAddressLine1">One Technology Way</param>
  <param name="szPostalCode">80237</param>
  <param name="szCity">Denver</param>
  <param name="szState">CO</param>
  <param name="szCountry">US</param>
  <param name="cPayablesYNM">N</param>
  <param name="cReceivablesYN">Y</param>
  <param name="cEmployeeYN">N</param>
  <param name="cUserCode">N</param>
  <param name="cARAPNettingY">N</param>
  <param name="cAddressType3YN">N</param>
  <param name="cAddressType4YN">N</param>
  <param name="cAddressType5YN">N</param>
  <param name="jdDateEffective"/>
  <param name="szProgramId">EP01012</param>
  <param name="szVersionconsolidated">ZJDE0001</param>
  <param name="cEdiSuccessfullyProcess">0</param>
  <param name="szCountryForPayroll">US</param>
 </params>
</callMethod>
</jdeResponse>

8.6 XML CallObject Return Codes

This table provides XML CallObject return codes that can be returned from ThinNet APIs:

Code Description
0 XML request OK.
1 Root XML element is not a jdeRequest or jdeResponse.
2 The jdeRequest user identification is unknown. Check the user, password, and environment attributes.

or

A callmethod request is missing the session attribute.

3 An XML parse error exists at line.
4 A fatal XML parse exists error at line.
5 An error occurred during parser initialization; the server is not configured correctly.
6 There is an unknown parse error.
7 The request session attribute is invalid.
8 The request type attribute is invalid.
9 The request type attribute is not given.
10 The request session attribute is invalid; the referenced process 'processid' no longer exists.
11 The jdeRequest child element is invalid or unknown.
12 The environment 'Env name' could not be initialized for user. Check user, password, and environment attribute values.
13 The jdeXMLRequest parameter is invalid.
14 The connection to JD Edwards EnterpriseOne failed.
15 The jdeXMLRequest send failed.
16 The jdeXMLResponse receive failed.
17 The jdeXMLResponse memory allocation failed.
99 An invalid BSFN name exists.