Skip to content
Thoroughbred Software InternationalThoroughbred Software InternationalThoroughbred DocumentationDocs

XML Request Query Strings

Overview

Section titled “Overview”

XML requests are posted as URL encoded HTTP query strings to the TS XML DataServer server process. All replies are posted back to the requestor in XML format.

SYNTAX

http|https://url_address/xml.tbred?[User=user_id][&Pwd=password]
&xmlrequest=argument
url_addressis the url address of the server running the Thoroughbred XML server process.
user_idis an optional global variable.
passwordis an optional global variable.
argumentis the XML request string. The contents vary depending upon the request type. See below for details.

NOTES

  • Both http and https are supported.
  • xml.tbred is the name of the server process on the TS XML DataServer.
  • Multiple variables must be separated with a space and must start with the “&” character. The first variable should not contain the “&” character. When the XML request is processed all supplied variables will be converted to CGV variables that can then be accessed within an XML Method. For example: LET USR$=CGV(“User”,ERC=49), P$=CGV(“Pwd”,ERC=49).

EXAMPLE

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELINVH+USING+KEY+%22100101%22

Reads Link OELCUST for Customer Code 100101.

https://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELINVH+USING+KEY+%22100101%22

Reads Link OELCUST for Customer Code 100101 over a SSL connection.

https://tweb.tbred.com/xml.tbred? User=tsi**&Pwd**=tsi&xmlrequest=METHOD+WBQXML02

Executes XML Method WBQXML02. The variables User and Pwd will be converted to CGV variables.

Section titled “READ Link Query Strings”

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

xmlrequest=argument

argument contains the READ link-name and read request parameters.

NOTES

  • The Thoroughbred key words normally separated with a space must be separated with the “+” character.

    Example:

    READ OELCUST USING KEY must be formatted as

    READ+OELCUST+USING+KEY

  • The query string must be URL encoded. Example:

    READ OLECUST USING KEY "100101" must be formatted as

    READ+OELCUST+USING+KEY+%22100101%22

  • It is required that key values be wrapped in quotes if the key contains embedded spaces or other special characters. Example:

    key value of "123 AB" must be encoded as

    %22123%20%20AB%20%22

EXAMPLES

Example 1

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELCUST+USING+KEY+%22100101%22

Posts a request to the remote sever to read Link OELCUST for Cust-Code 100101. The data will be posted back in XML format.

The requestor will receive:

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELCUST>
  <OELCUST>
    <CUST_CODE>100101</CUST_CODE>
    <CUST_CONTACT>David Kelly</CUST_CONTACT>
    <CUST_NAME>Fix-M-Up</CUST_NAME>
    <CUST_ADDRESS>Old Bay Shore Road</CUST_ADDRESS>
    <CUST_CITY>Seadrift</CUST_CITY>
    <CUST_STATE>TX</CUST_STATE>
    <CUST_ZIP>50250</CUST_ZIP>
    <CUST_PHONE>512 876-9070</CUST_PHONE>
    <CUST_DISC>32.00</CUST_DISC>
    <CUST_CRLMT>5010</CUST_CRLMT>
    <CUST_STC>TX</CUST_STC>
    <SR_CODE>HP</SR_CODE>
    <CUST_SALES>14530.92</CUST_SALES>
  </OELCUST>
</XMLSource_OELCUST>

Example 2

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELINVH+USING+KEY+%22100101%22+;
BY+SORT+1

Posts a request to the remote sever to read Link OELINVH using Sort 1 for Cust-Code 100101.

The requestor will receive:

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELINVH>
  <OELINVH>
    <INV_NUM>000002</INV_NUM>
    <INV_DATE>07/17/05</INV_DATE>
    <INV_AMOUNT>609.72</INV_AMOUNT>
    <CUST_CODE>100101</CUST_CODE>
    <SR_CODE>HP</SR_CODE>
  </OELINVH>
  <OELINVH>
    <INV_NUM>000017</INV_NUM>
    <INV_DATE>08/01/05</INV_DATE>
    <INV_AMOUNT>5182.71</INV_AMOUNT>
    <CUST_CODE>100101</CUST_CODE>
    <SR_CODE>HP</SR_CODE>
  </OELINVH>
  <OELINVH>
    <INV_NUM>000032</INV_NUM>
    <INV_DATE>08/16/05</INV_DATE>
    <INV_AMOUNT>9755.70</INV_AMOUNT>
    <CUST_CODE>100101</CUST_CODE>
    <SR_CODE>HP</SR_CODE>
  </OELINVH>
</XMLSource_OELINVH>

Example 3

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELCUST+
USING+RANGE+FROM+100101+TO+999999;DATANAME+LIST+CUST-CODE;
SELECT+WHEN+%23OEFCUST.SR-CODE=%22HP%22

The HTTP request has been split for readability.

Reads Link OELCUST using a range of keys from 100101 through 999999 and return the Cust-Code data element for those records where the SR-CODE = “HP”.

The requestor will receive:

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELCUST>
  <OELCUST>
    <CUST_CODE>100101</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100102</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100104</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100105</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>101103</CUST_CODE>
  </OELCUST>
 </XMLSource_OELCUST>

Example 4

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELCUST+
USING+RANGE+FROM+100101+TO+999999;
SELECT+WHEN+%23OEFCUST.CUST-CONTACT+LIKE+%22%2ASmith%2A%22

The HTTP request has been split for readability.

Reads Link OELCUST using a range of keys from 100101 through 999999 and return records where the CUST-NAME contains the characters “Smith”.

The requestor will receive:

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELCUST>
  <OELCUST>
    <CUST_CODE>100104</CUST_CODE>
    <CUST_CONTACT>Sarah Smith</CUST_CONTACT>
    <CUST_NAME>ACME Inc.</CUST_NAME>
    <CUST_ADDRESS>346 Elm Street</CUST_ADDRESS>
    <CUST_CITY>Dayton</CUST_CITY>
    <CUST_STATE>NJ</CUST_STATE>
    <CUST_ZIP>42523</CUST_ZIP>
    <CUST_PHONE>608 564-3200</CUST_PHONE>
    <CUST_DISC>38.00</CUST_DISC>
    <CUST_CRLMT>8010</CUST_CRLMT>
    <CUST_STC>NJ</CUST_STC>
    <SR_CODE>HP</SR_CODE>
    <CUST_SALES>14807.46</CUST_SALES>
  </OELCUST>
</XMLSource_OELCUST>

Example 5

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OELCUST+
USING+RANGE+FROM+100101+TO+999999;
DATANAME+LIST+CUST-CODE;
SELECT+WHEN+%23OEFCUST.CUST-SALES+%3E+15000

The HTTP request has been split for readability.

Reads Link OELCUST using a range of keys from 100101 through 999999 and return records where the CUST-SALES are > 1500. Only the CUST-CODE is returned in the XML string.

<?xml version="1.0" encoding="ISO-8859-1"?>
<XMLSource_OELCUST>
  <OELCUST>
    <CUST_CODE>100105</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100106</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100107</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100108</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100109</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>100110</CUST_CODE>
  </OELCUST>
  <OELCUST>
    <CUST_CODE>101104</CUST_CODE>
  </OELCUST>
</XMLSource_OELCUST>
Section titled “UPDATE Link Query Strings”

SYNTAX

UPDATE+name+xml-elements
nameis the Link name, XSchema names cannot be used with the UPDATE directive.
xml-elementsis 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>

    Example:

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

EXAMPLE

http://tweb.tbred.com/xml.tbred?xmlrequest=UPDATE+OELCUST+<CUST-
CODE>100104</CUST-CODE><SR-CODE>HP</SR-CODE>

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

Section titled “INSERT Link Query Strings”

SYNTAX

INSERT+name+xml-elements
nameis the Link name.
xml-elementsis 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

http://tweb.tbred.com/xml.tbred?xmlrequest=INSERT+OELSLRP+<SR-CODE>XX</SR-
CODE><SR-NAME>JustinCase</SR-NAME><SR-SALES>0</SR-SALES>

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.

Section titled “DELETE Link Query Strings”

SYNTAX

DELETE+name+xml-elements
nameis the Link name.
xml-elementsis 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

http://tweb.tbred.com/xml.tbred?xmlrequest=DELETE+OELCUST+<CUST-
CODE>100104</CUST-CODE>

REMOVEs a record from Link OELCUST using key 100104

Read XSchema Query Strings

Section titled “Read XSchema Query Strings”

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

xmlrequest=argument
argument
contains the READ schema-name.

NOTES

  • The Thoroughbred key words normally separated with a space must be separated with the “+” character.

    Example:

    READ OEFSCM02 must be formatted as
    READ+OEFSCM02

EXAMPLES

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-CODE
   OELINVH USING #OEFCUST.CUST SR-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.ITEMCODE;
              DATANAME LIST ITEM-DESC

Reads Links OELCUST, OELSLRP, OELINVH, and OELINVH populating the specified data elements and returns the data structure in XML format.

http://tweb.tbred.com/xml.tbred?xmlrequest=READ+OEFSCM02
<?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>
</OELCUST>
<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>
</XMLSource_OEFSCM02>

Method Query Strings

Section titled “Method Query Strings”

SYNTAX

http|https://url_address/xml.tbred?xmlrequest=METHOD+name+[<msg>optional_meth
od_msg</msg>]
url_addressis the url address of the server running the Thoroughbred XML server process.
nameis the name of the method to be executed on the remote server.
optional_method_msgis an optional message that can is passed to the method. The method message must be url encoded and wrapped in xml tags.

NOTES

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

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

EXAMPLE

Example 1

http://tweb.tbred.com/xml.tbred?xmlrequest=METHOD+WBQXML02

Executes method WBQXML02 on the remote server. No message is supplied to the method.

Example 2

http://tweb.tbred.com/xml.tbred?xmlrequest=METHOD+WBQXML02+%3Cmsg%3Ethis%20is
%20an%20example%3C/msg%3E

Executes 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 requestor.

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 method WBXML02 is executed. When EXIT is executed the contents of XML$[1] is posted back to the requestor.

The requestor 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