XML Request Manager

Overview

The XML Request Manager provides easy to use syntax for making XML requests with a local Basic installation. The method avoids the need to URL encode the XML request and manages all communication with the TS XML server process. Requests are made by CALLing the TS XML Request Manager OOXMLSRX directly from a Basic program.

CALL "OOXMLSRX", REQ$[ALL], XML$[ALL]

REQ$[1] Function:
        "e": Before posting to the remote server, url encode the query
        string. This is the default.

        note: When REQ$[1]="" the default function "e" will be applied

REQ$[2] The url address of the server running the Thoroughbred XML
        server process.

        Example: REQ$[2]="tweb.tbred.com"

REQ$[3] reserved for internal use

REQ$[4] reserved for internal use

REQ$[5] Optional time out value
        Example:  REQ$[5]="10"

REQ$[6] XMLRequest
        The XMLRequest varies depending upon the request type; READ
        (Link/XSchema), UPDATE, INSERT, DELETE, and METHOD.
        The XMLRequest strings are documented below.

NOTES

Multiple variables must be separated with the “&” character. For example: &User=tbred&Pwd=tbred
XML$[ALL] Contains the XML formatted response from the XML server.

READ Link XML Request Manager

The TS XML DataServer will attempt to read the definition as an XSchema. If a matching XSchema definition is found, the request will be processed as an XSchema. If a matching XSchema is not found, it will be processed as a Link. If the Link is not found an empty XML string will be returned.

SYNTAX

`REQ$[6]=READ link-name arguments`
`link-name`	is the name of the Link definition
`arguments`	are the READ arguments: USING KEY value, USING RANGE FROM value TO value, BY SORT n, DATANAME LIST data-names, and the SELECT WHEN conditional.

NOTES

XMLRequests do not have to be URL encoded; the XML Request Manager will construct a proper URL encoded query string.

Examples:

Read Link OELCUST for CUST-CODE 100101 and return all data in XML format:
REQ$[6]="READ OELCUST USING KEY 100101"

Read OELCUST for a range of records and return only the CUST-CODEs in XML
format:
REQ$[6]="READ OELCUST USING RANGE FROM 100000 TO 999999;DATANAME LIST
CUST-CODE"

Read OELCUST by Sort 3 for CUST-STATE NJ and return only the CUST-CODEs in
XML format:
REQ$[6]="READ OELCUST USING KEY NJ;BY SORT 3;DATANAME LIST CUST-CODE"

Read OELCUST for a range of records and only return XML data where SR-CODE
="HP":
REQ$[6]="READ OELCUST USING RANGE FROM 100101 TO 999999; DATANAME LIST
CUST-CODE;SELECT WHEN #OEFCUST.SR-CODE LIKE"+QUO+"A*"+QUO

EXAMPLES

On the local server the CALL is made to OOXMLSRX. On the remote server, the Link will be read using the supplied arguments and the data returned to the calling program in XML format.

In the following example the XML string will contain all the data elements for customer code 100101.

DIM REQ$[6], XML$[1];
* set the server address:
REQ$[2]="tweb.tbred.com",
* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="READ OELCUST USING KEY 100101";

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

* if no errors, save the xml string
IF REQ$[0]="."
   XML$=XML$[1]
FI

In the above example XML$[1] will contain:

<XMLSource_OELCUST>
<OELCUST>
<CUST_CODE>100100</CUST_CODE> <CUST_NAME>Toot-Your-Horn</CUST_NAME> <CUST_STATE>TX</CUST_STATE> <CUST_CITY>Port Lavaca</CUST_CITY> <CUST_PHONE>555-2341</CUST_PHONE> <SR_CODE>AF</SR_CODE>
</OELCUST>
</XMLSource_OELCUST>

In the following example the XML string will contain all the customer codes when the sales rep code contains “A*”.

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2]="tweb.tbred.com",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="READ OELCUST USING RANGE FROM 1000000 TO 999999;DATANAME LIST
CUST-CODE;SELECT WHEN #OEFCUST.SR-CODE LIKE "+QUO+"A*"+QUO

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

* if no errors, save the xml string
IF REQ$[0]="."
   XML$=XML$[1]
FI

In the above example XML$[1] will contain:

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELCUST>
  <OELCUST>
    <CUST_CODE>100100</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100109</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>101101</CUST_CODE>
  </OELCUST>
</XMLSource_OELCUST>

UPDATE Link XML Request Manager

SYNTAX

`REQ$[6]=UPDATE link-name xml-elements`
`link-name`	is the Link name.
`xml-elements`	is the xml string containing the key values and the data to update. The first set of xml-elements defines the key to the Link. The key value is always required and must be the first set of xml-elements. The order of non-key xml-elements is not significant.

NOTES

Before the Link is updated the TS XML DataServer will validate all data against the Format definition. This includes validation using LOOKUP VIEW.
If the Link contains an I/O Trigger, the trigger will be executed prior to the WRITE.
If the Link contains sort definitions all sorts will be updated.

A successful UPDATE XML reply will contain the “.” character indicating the process completed successfully:

<standard XML header>
<link name>
   <UPDATE>.</UPDATE>
</link name>

Example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OELCUST>
<UPDATE>.</UPDATE>
</OELCUST>

If an error occurs the XML reply will contain an error message:

<standard XML header>
<error>error-message</error>

Examples:

<?xml version="1.0" encoding="ISO-8859-1"?>
<ERROR>1) 102   : Can't find record for specified key  2) </ERROR>

EXAMPLE

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2]="tweb.tbred.com",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="UPDATE OELCUST <CUST-CODE>100104</CUST-CODE><SR-CODE>HP</SR-
CODE>",

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

UPDATEs Link OELCUST using a key value of 100104, changing the SR-CODE to “HP”.

INSERT Link XML Request Manager

SYNTAX

`REQ$[6]=INSERT link-name xml-elements`
`link-name`	is the Link name
`xml-elements`	is the xml string containing the key values and the data to added. The first set of xml-elements defines the key to the Link. The key is always required and must be the first set of xml-elements. The order of non-key xml-elements is not significant.

NOTES

Before the Link is updated the TS XML DataServer will validate all data against the Format definition. This includes validation using LOOKUP VIEW.
If the Link contains an I/O Trigger, the trigger will be executed prior to the WRITE.
If the Link contains sort definitions all sorts will be updated.

A successful INSERT XML reply will contain the “.” character indicating the process completed successfully:

<standard XML header>
<link name>
   <INSERT>.</INSERT>
</link name>

Example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OELCUST>
   <INSERT>.</INSERT>
</OELCUST>

If an error occurs the XML reply will contain an error message:

<standard XML header>
<error>error-message</error>

EXAMPLE

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2]="tweb.tbred.com",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="INSERT OELSLRP <SR-CODE>XX</SR-CODE><SR-NAME>JustinCase</SR-
NAME><SR-SALES>0</SR-SALES>",

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

WRITEs a new record to Link OELSLRP using a key value of “XX” for the new SR-CODE and “Justin Case” for SR-NAME and “0” for SR-SALES.

DELETE Link XML Request Manager

SYNTAX

`REQ$[6]=DELETE link-name xml elements`
`link-name`	is the Link name
`xml-elements`	is the xml string containing the key values of the record to be deleted.

NOTES

All xml-elements are assumed to be key fields.
If the Link contains an I/O Trigger, the trigger will be executed prior to the REMOVE.

A successful DELETE XML reply will contain the “.” character indicating the process completed successfully:

<standard XML header>
<link name>
   <DELETE>.</DELETE>
</link name>

Example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OELCUST>
   <DELETE>.</DELETE>
</OELCUST>

If an error occurs the XML reply will contain an error message:

<standard XML header>
<error>error-message</error>

EXAMPLE

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2=”tweb.tbred.com",

* set the xml server process path
REQ$[3]="/xml.tbred",

* set the tbredpost path
REQ$[4]="/opt/tbred/tbredpost/",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="DELETE OELCUST <CUST-CODE>100104</CUST-CODE>",

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

REMOVEs a record from Link OELCUST using key 100104.

READ XSchema XML Request Manager

SYNTAX

REQ$[6]=READ schema-name

schema-name: is the name of the XSchema definition

EXAMPLES

REQ$[6]="READ OEFSCM01"

The following XSchema definition will read Links OELCUST, OELSLRP, OELINVH, and OELINVH populating the specified data elements.

Schema: OEFSCM02 Sample System

OELCUST USING KEY “100100”;

        DATANAME LIST CUST-CODE CUST-NAME CUST-STATE CUST-CITY

                      CUST-PHONE XXX SR-CODE

OELSLRP USING #OEFCUST.SR-CODE; DATANAME LIST SR-NAME

  OELINVH USING #OEFCUST.CUST-CODE;

          BY SORT 1;

          DATANAME LIST INV-NUM INV-DATE INV-PRINTED-FLAG

                        INV-AMOUNT

    OELINVD USING #OEFINVH.INV-NUM

            DATANAME LIST INV-LNUM INV-QTY INV-LTAX INV-LEXTEN

                          ITEM-CODE INV-LPRICE INV-DISC;

            SELECT WHEN #OEFINVD.ITEM-CODE = "10-100-000”

    OELINVN USING #OEFINVD.ITEM-CODE;

The following XSchema request will post back to the calling program the data structure defined by XSchema OEFSCM02 in XML format.

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2]="tweb.tbred.com",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="READ OEFSCM02",

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];

* if no errors, save the xml string
IF REQ$[0]="."
   XML$=XML$[1]
FI

In the above example XML$[1] will contain:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <XMLSource_OEFSCM02>
    <OELCUST>
      <CUST_CODE>100100</CUST_CODE>
      <CUST_NAME>Toot-Your-Horn</CUST_NAME>
      <CUST_STATE>TX</CUST_STATE>
      <CUST_CITY>Port Lavaca</CUST_CITY>
      <CUST_PHONE>555-2341</CUST_PHONE>
      <SR_CODE>AF</SR_CODE>
    <OELSLRP>
      <SR_NAME>Albert Fisher</SR_NAME>
    </OELSLRP>
    <OELINVH>
      <INV_NUM>000001</INV_NUM>
      <INV_DATE>07/16/05</INV_DATE>
      <INV_AMOUNT>313.85</INV_AMOUNT>
    </OELINVH>
    <OELINVD>
      <INV_LNUM>02</INV_LNUM>
      <INV_QTY>1</INV_QTY>
      <INV_LTAX>.10</INV_LTAX>
      <INV_LEXTEN>1.40</INV_LEXTEN>
      <ITEM_CODE>10-100-000</ITEM_CODE>
      <INV_LPRICE>1.40</INV_LPRICE>
      <INV_DISC>30.00</INV_DISC>
    </OELINVD>
    <OELINVN>
       <ITEM_DESC>Little nails</ITEM_DESC>
    </OELINVN>
    <OELINVH>
       <INV_NUM>000016</INV_NUM>
       <INV_DATE>07/31/05</INV_DATE>
       <INV_AMOUNT>5021.29</INV_AMOUNT>
    </OELINVH>
    <OELINVD>
      <INV_LNUM>02</INV_LNUM>
      <INV_QTY>16</INV_QTY>
      <INV_LTAX>1.57</INV_LTAX>
      <INV_LEXTEN>22.40</INV_LEXTEN>
      <ITEM_CODE>10-100-000</ITEM_CODE>
      <INV_LPRICE>1.40</INV_LPRICE>
      <INV_DISC>30.00</INV_DISC>
    </OELINVD>
    <OELINVN>
      <ITEM_DESC>Little nails</ITEM_DESC>
    </OELINVN>
    <OELINVH>
      <INV_NUM>000031</INV_NUM>
      <INV_DATE>08/15/05</INV_DATE>
      <INV_AMOUNT>9728.78</INV_AMOUNT>
    </OELINVH>
    <OELINVD>
      <INV_LNUM>02</INV_LNUM>
      <INV_QTY>31</INV_QTY>
      <INV_LTAX>3.04</INV_LTAX>
      <INV_LEXTEN>43.40</INV_LEXTEN>
      <ITEM_CODE>10-100-000</ITEM_CODE>
      <INV_LPRICE>1.40</INV_LPRICE>
      <INV_DISC>30.00</INV_DISC>
    </OELINVD>
    <OELINVN>
      <ITEM_DESC>Little nails</ITEM_DESC>
    </OELINVN>
    </OELCUST>
  </XMLSource_OEFSCM02>

Method XML Request Manager

SYNTAX

`REQ$[6]=METHOD name [<msg>optional_method_msg</msg>]`
`name`	is the name of the method to be executed on the remote server.
`optional_method_msg`	is an optional message that can is passed to the method.

NOTES

The message returned by the XML Method must start with <method> and must terminate with </method>

<method>my-method-message-here</method>

EXAMPLE

The following example will execute method WBXML02 on the remote server passing the message “this is an example”. The method WBXML02 will then parse the message and construct a reply that is posted back to the calling program.

DIM REQ$[6], XML$[1];

* set the server address:
REQ$[2]="tweb.tbred.com",

* optional time out value
REQ$[5]="10"

* set the xmlrequest query string
REQ$[6]="METHOD WBQXML02<msg>this is an example</msg>"

* call the xml request manager to process the xmlrequest query string.
CALL "OOXMLSRX", REQ$[ALL], XML$[ALL];
IF REQ$[0]="."
   XML$=XML$[1]
FI;

The method WBXML02 is executed. When EXIT is executed the contents of XML$[1] is posted back to the calling program.

Method WBXML02

ENTER MSG1$[ALL],XML$[ALL];
PROCEDURE
      MSG$=MSG1$[1];
      P=POS(">"=MSG$),
      MSG$=MSG$(P+1),
      P=POS("</"=MSG$),
      MSG$=MSG$(1,P-1),
      XML$[1]="<method>WBQXML02 received: "+MSG$+"</method>";

The calling program receives the following message from the method WBXML02:

<?xml version="1.0" encoding="ISO-8859-1"?>
<method>WBQXML02 received: this is an example</method>

From the TS XML DataServer Reference, version 8.9.1. Open this page in the PDF