XML Document Format for the Message Protocol XML SQL Format

 You can modify one or more database tables by means of a message. Depending on the content of the message, you can either insert (INSERT), update (UPDATE), or delete (DELETE) the data. Results from queries (SELECT) can also be included in the response in XML format for synchronous messages. The XML document must have the following schema in this case:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <StatementName1>
    <dbTableName action=”UPDATE” | “UPDATE_INSERT”>
      <table>
        realDbTableName
      </table>
      <access>
        <col1>val1</col1>
        <col2>val2new</col2>
      </access>
      <key1>
        <col2>val2old</col2>
        <col4>val4</col4>
      </key1>
      <key2>
        <col2>val2old2</col2>
      </key2>
    </dbTableName>
  </StatementName1>
  <StatementName2>
    <dbTableName action=”INSERT”>
      <table>
        realDbTableName
      </table>
      <access>
        <col1>val1</col1>
        <col2>val2</col2>
      </access>
      <access>
        <col1>val11</col1>
      </access>
    </dbTableName>
  </StatementName2>
  <StatementName3>
    <dbTableName action=”DELETE”>
      <key1>
        <col2>val2old</col2>
        <col4>val4</col4>
      </key1>
      <key2>
        <col2>val2old2</col2>
      </key2>
    </dbTableName>
  </StatementName3>
  <StatementName4>
    <dbTableName action=”SELECT”>
      <table>
        realDbTableName
      </table>
      <access>
        <col1/>
        <col2/>
        <col3/>
      </access>
      <key1>
        <col2>val2old</col2>
        <col4>val4</col4>
      </key1>
      <key2>
        <col2>val2old2</col2>
      </key2>
    </dbTableName>
  </StatementName4>
  <StatementName5>
    <storedProcedureName action=” EXECUTE”>
      <table>
        realStoredProcedureeName
      </table>
      <param1 [isInput=”true”] [isOutput=true] type=SQLDatatype>val1</param1>
    </storedProcedureName >
  </StatementName5>
  <StatementName6>
    <anyName action=” SQL_QUERY” | “SQL_DML”>
      <access>SQL-String with optional placeholder(s)</access>
      <key>
        <placeholder1>value1</placeholder1>
        <placeholder2>
        value2
        <placeholder2>
      </key>
    </anyName >
  </StatementName6>
</root>

Comments

The document contains a tag with the arbitrary name<root>. Within this tag there are one or more statement elements that also have arbitrary names. Each of these statements contains the description of a database action. With the exception of the execute description for a stored procedure (shown in the example under the element<StatementName5>), all statements have the same structure:

The name of the element beneath the statement element specifies the name of the database table and contains the attributeactionwith the valueINSERTUPDATEUPDATE_INSERTDELETE, orSELECT. If you use the optional<table>element, the value specified is used as a database table name. This enables you, for example, to define table names containing non-XML-compatible characters or characters that prevent them from being used in interface definitions in the Integration Builder. If specified,<table>must be the first element in the block within<dbTableName>

Within this element there is (except for in theDELETEaction) an element with the nameaccessand one or more elements with arbitrary names. In the above example, these elements are calledkeyN. Theaccesselement contains the table columns which are to be accessed. It must be specified as the first element. Thekeyelements describe a condition for access. If no such elements are specified, access proceeds without any conditions. In the case ofUPDATEandDELETE, this can lead to the entire table being updated or deleted respectively.

If you want to ensure this does not happen, select Key Tags Mandatory in the adapter configuration.

The response documents described below can only be evaluated by the Integration Server/PCK if the call is synchronous because the content of the response document is not accessible if the call is asynchronous. The response is put in a separate element< StatementName_response>for each statement element.

action= UPDATE

Statements with this action cause existing table values to be updated. Therefore, the statement corresponds to an SQL UPDATE statement.

The<access>block contains the new column values and a<key>element contains the columns whose values must be identical with the specified value to get the new column values. The name of the<key>element is arbitrary. Column values within a<key>element are combined with a logical AND; different<key>elements are combined with a logical OR.

A statement with the actionUPDATEmust have exactly one<access>element. The number of<key>elements with arbitrary names is not restricted.

The corresponding SQL statement forStatementName1in the example above is as follows:

“

UPDATE dbTableName SET col1=’val1’, col2=’val2new’ WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

As in the other examples, the column typeStringis used for all columns. The character“may be missing in other column types.

The response document contains the following element as well as the number of updated table lines, including 0.

<update_count>count</update_count>

If there is no<key>element, or if there is a<key>element but it is empty, then no condition is specified and the entire table is to be updated. This may not be permitted by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message.

action= INSERT

Statements with this action cause table values to be inserted. Therefore, the statement corresponds to an SQL INSERT statement.

The<access>block contains the new column values.

A statement with the actionINSERTmust have at least one<access>element. It cannot have a<key>element.

The corresponding SQL statement forStatementName2in the example above is as follows:

“

INSERT INTO dbTableName (col1, col2) VALUES(‘val1’, ‘val2’)

INSERT INTO dbTableName (col1) VALUES(‘val11’)

“

The response document contains the following element as well as the number of inserted table lines, including 0.

<insert_count>count</insert_count>

action= UPDATE_INSERT

The statement has the same format as for theUPDATEaction. Initially, the same action is executed as forUPDATE. If no update to the database table can be made for this action (the condition does not apply to any table entry), values of the table described in the <access> element are inserted in accordance with the description of the actionINSERT<key>elements are ignored in this case.

The response document has the following format; one of the two values is always 0 because either anUPDATEor anINSERTaction is always executed:

<update_count>count</update_count>

<insert_count>count</insert_count>

action= DELETE

Statements with this action cause existing table values to be deleted. One or more<key>elements formulate the condition for which table values are deleted. The names of<key>elements are arbitrary. Column values within a<key>element are combined with a logical AND; different<key>elements are combined with a logical OR.

The corresponding SQL statement forStatementName3in the example above is as follows:

“

DELETE FROM dbTableName WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

The response document contains the following element:

<delete_count>count</delete_count>

If there is no<key>element, or if there is a<key>element but it is empty, then no condition is specified and the entire table is to be deleted. This may not be permitted by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message.

action= SELECT

Statements with this action cause existing table values to be selected. Therefore, the statement corresponds to an SQL SELECT statement.

The<access>block contains the column names to be selected, a<key>element contains the columns whose values must be identical with the specified value to get the new column values. The name of the<key>element is arbitrary. Column values within a<key>element are combined with a logical AND; different<key>elements are combined with a logical OR.

A statement with the actionSELECTmust have exactly one<access>element. The number of<key>elements with arbitrary names is not restricted.

The corresponding SQL statement forStatementName4in the example above is as follows:

“

SELECT col1,col2,col3 FROM dbTableName WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

If there is no<key>element, or if there is a<key>element but it is empty, then no condition is specified and the entire table is to be selected. This may not be permitted by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message.

The response document contains the result of the action in XML format as follows:

“

<row>

<column1>value11</column1>

<column2>value12</column2>

</row>

<row>

<column1>valueN1</column1>

<column2>valueN2</column2>

</row>

“

action= EXECUTE

Statements with this action result in a stored procedure being executed. The name of the element is interpreted as the name of the stored procedure in the database. If you use the optional <table> element, the value specified here is used as the stored procedure name. This enables you, for example, to define stored procedure names containing non-XML-compatible characters or characters that prevent them from being used in interface definitions in the Integration Builder/PCK. If specified, <table> must be the first element in the block within <dbTableName>.

The elements within the stored procedure are interpreted as parameters. They can optionally have the attribute isInput=“1“ (input parameter) or isOutput=“1“ (output parameter) or both (INOUT parameter). If both attributes are missing, the element is interpreted as an input parameter. The parameter names must be identical to those of the stored procedure definition.

The attributetype=<SQL-Datatype>, which describes the valid SQL data type, is mandatory for all parameter types (IN, OUT, INOUT).

The following SQL data types are supported:

INTEGER, BIT, TINYINT, SMALLINT, BIGINT, FLOAT,REAL, DOUBLE, NUMERIC, DECIMAL,CHAR, VARCHAR, STRING, LONGVARCHAR, DATE, TIME, TIMESTAMP, BINARY, VARBINARY, LONGVARBINARY, BLOB (input and output),CLOB (input and output), CURSOR (output; only in conjunction with the Oracle JDBC driver)