Call SQL B1if PDF

Integration Framework
Processing Atom
Call SQL
Last Modified: April 22, 2015
Table of Contents
1 Parameters ............................................................................................................................. 2
1.1 Options for Providing SQL Statements .............................................................................. 5
1.2 Filtering Invalid XML Characters from Database Fields ..................................................... 6
2 Functions ................................................................................................................................ 6
3 Single Processing ................................................................................................................... 8
4 Blocked Processing in Compatibility Mode .............................................................................. 9
5 Blocked Processing in Batch Mode ......................................................................................... 9
6 Optimizing SQL Call for Large SQL Statements .....................................................................11
7 Preventing SQL Injection .......................................................................................................12
Copyrights, Trademarks, and Disclaimers .................................................................................13
Call SQL
In the process flow, use the atom to make SQL calls to a database system.
The Call SQL atom is of simple call type. You do not need a predecessor transformation atom,
if you directly enter statement or statements in the user interface. However, the call SQL atom
provides additional options to define SQL statements in a predecessor transformation atom and
point to the place in the atom either using an XPath statement or a reference to an atom
identifier. For more information, see the 1.1 Options for Providing SQL Statements section.
Use a predecessor atom, for example, to handle large SQL statements.
1 Parameters
Scenario Step Identifier
This is a read-only field. It displays the name of the scenario step for which you develop the
process flow.
Public
2015 SAP SE or an SAP affiliate company.
All rights reserved
Atom Identifier
This is a read-only field. It displays identifier of the atom. The identifier is unique and has the
atom<no> pattern. <no> is a number. The atom identifier enables subsequent atoms to
access data produced by the atom using an XPath expression, for example,
/vpf:Msg/vpf:Body/vpf:Payload[./@id=atom2]/*.
Description
When creating the atom, the integration framework generates a default description. The
description serves as a comment about the task that the atom performs. In the graphical flow
designer, the integration framework displays the text as mouse over. You can change the
default description.
Additionally, you can use the description field to change the default label of the atom displayed
in the graphical flow designer. To provide an individual label, add the label in brackets at the
end of the description. The maximum length of an individual label is ten characters.
Example
The integration framework displays the this is my comment[my Label] string as my
Label for the atom in the graphical flow designer.
SysId
Select the system you want call using SQL. A leading # indicates an explicit value, for example,
#0010000105 calls the system that has the 0010000105 SysId in SLD. If you use an explicit
SysId from SLD, make sure that the system you want to call is identical with the one in SLD at
runtime. Using an explicit value with a leading #, you can use variables and properties.
For more information, click the
button to open the documentation.
Additionally, you have the following options:
B1 System, based on User
Only use the option for scenario steps triggered by HTTP calls or Web services that run in a
session. The HTTP or Web service channel must be associated to a SAP Business One
system through the associatedSrvIP. SLD parameter.
Sender System
Perform the SQL call to the sender system that you have defined in the inbound definition of
the scenario step.
List of database systems in SLD
To calculate the SysId at runtime, do not enter an explicit value, but use an XPath expression
instead. With the XPath expression, you can retrieve a value from the payload generated by the
predecessor transformation atom.
Example
/vpf:Msg/vpf:Body/vpf:Payload[./@id=atom2]/@sysid.
Stop processing if fails
Set the parameter to control the behavior of the integration framework, if an exception occurs
during the SQL call. The default value is false.
Public
All rights reserved
If you set the value to false, processing continues, if an exception occurs. You have the
option to introduce an individual error handling in the following XSL transformation atom or
atoms.
If you set the value to true, an exception causes the scenario step processing to fail.
You can display the message in the message log error section with the complete call stack
of the internal processing.
The default error handling of the integration framework restarts the scenario step after one
minute.
The integration framework allows you to provide an individual error handler scenario step in
the scenario package. The scenario step must have the internal queue inbound type. In the
processing phase, define the individual error handling. You can send, for example, an e-mail
to an administrator, or a SAP Business One message to a specific user, insert a message to
a table, and so on. To enable individual error handling for the scenario package, choose
Scenarios Package Design [Definitions] Error Handling and select the error handling
step.
The parameter does not support XPath, variables and properties.
Method
Select the method how the integration framework identifies the SQL method. The following
options are available:
Automatic detection by key word
The integration framework detects the method by the first statement that you enter in the
Default SQL Statement or in the HANA SQL Statement field.
Query statement
If you want to send a query or queries in your SQL call, select Query statement. The
integration framework sets the Processing Mode to Single Processing and the Blocked
Processing Delimiter to a semicolon. You cannot change the settings.
Update statement
If you want to make an update or updates in the database, select Update statement. The
integration framework sets the Processing Mode to Single Processing and the Blocked
Processing Delimiter to a semicolon. You cannot change the settings.
Processing Mode
Select the method how you want to submit the SQL statements to the database. You have the
following options:
Single Processing
Single processing allows you to submit SQL statements call by call to the database. The
integration framework guaranties the order of SQL statements that it submits to the
database.
Blocked Processing in compatibility mode
This option is available to be compatible with older versions of the SQL Call atom. In older
versions, the Blocked Processing checkbox is available. If you select the checkbox, the
integration framework offers same behavior like choosing the Blocked Processing in
compatibility mode option.
NOTE
Do not use this option for new developments.
Public
All rights reserved
Blocked Processing in batch mode

With this option, you can group related SQL statements into a batch and submit them in one
call to the database. This option reduces communication overhead and can have a positive
impact on the overall performance.
Blocked Processing Delimiter

Enter the delimiter you use to separate the SQL statements for batch processing. You cannot
use characters that define regular expressions such as <([{\^-=$!|]})?*+.>.
1.1 Options for Providing SQL Statements

To provide the SQL statement or statements in the Default SQL Statement field, you have the
following options:
Directly Entering the SQL Statement
Directly enter the SQL statement or statements in the input field.
Enter, for example, #select ItemCode, ItemName as 'Name' from OITM
where ItemCode = 'A00003'
If a value in an SQL statement contains a (single quote), for example, 235, the SQL
statement does not interpret it correctly and only considers 23. The SQL call fails. To hand
over the correct value, double the single quote: 235
Alternatively, use the utils2:handleSQLString(string()) function when providing the
SQL statement in an XSL transformation atom. For more information about handling single
quotes, see section 7 Preventing SQL Injections
If a database contains special characters in tables that are not Latin, but for example Hebrew,
use the N character in the WHERE clause of an SQL statement to include the special characters.
Enter, for example:
SELECT T2.E_MAIL as FromEmail FROM OUSR as T2 WHERE
T2.USER_CODE=N'$userid'
Entering an Atom Identifier
Enter the name of an XSL transformation atom that contains the SQL statement or statements.
Enter, for example, #atom4.
In atom4, provide the SQL statement in the <sql> tag, for example:
<sql xmlns="">select ItemCode, ItemName as 'Name' from OITM
where ItemCode = 'A00001'</sql>
The procedure also supports you in processing large SQL statements. For more information,
see section 6 of the document
Entering an XPath Statement
Enter an XPath that points to the SQL statement in the XSL transformation atom.
Enter, for example,
/vpf:Msg/vpf:Body/vpf:Payload[./@id='atom4']/xpath
Public
All rights reserved
The XPath points to the <xpath> tag in atom4 that contains the SQL statement. atom4 is an
XSL transformation atom.
In atom4, enter the SQL statement in the following way:
<xpath xmlns="">select ItemCode, ItemName as 'Name' from OITM
where ItemCode = 'A00002'</xpath>
If values in an XPath statement contain a string that starts with ! (exclamation mark) and ends
with _ (underscore), the integration platform (B1iP) interprets it as a variable and the SQL
statement does not work. To avoid errors at runtime, do not enter the XPath statement in the
input field. Instead, enter the transformation atom identifier, for example, #atom4. In the XSL
transformation atom, enter the statement in the <sql> </sql> tag.
To avoid out of memory errors at integration framework runtime, the integration framework in
general reduces SQL statements to 1000 characters in the return payload.
1.2 Filtering Invalid XML Characters from Database Fields

Invalid XML characters in database fields cause exceptions at integration framework runtime.
To avoid such errors, do not enter the SQL statement in the input field, but use an XSL
transformation atom. In the XSL transformation atom, you can use the
filterInvalXMLChar=true attribute to filter invalid XML characters.
Procedure
1. Create an XSL Transformation atom in front of the Call SQL atom.
2. in the XSL document, provide the attribute in the following way:
<sql filterInvalXMLChar=true occ="1">select * from table</sql>
3. In the SQL call atom, in the Default SQL Statement field, enter #atom<number> to
reference the XSL transformation atom.
<number> is the number of the XSL transformation atom that contains the SQL statement.
2 Functions
To open documentation, describing the concepts of variables and properties and how to use
them in the context of the process development, click this button.
The integration framework provides context-based documentation. If documentation is available,

the integration framework displays the documentation icon. The greyed out icon indicates still
missing documentation. To open documentation, click the icon.
To save the current parameter definitions of the processing atom, click the button. The
integration framework stores all settings directly in the process flow definition document
(vBIU.bfd). To open the document, click the
icon on the start atom of your flow.
Public
All rights reserved
[VarL]
To add, change or delete local variables, click the button. Local variables are valid for the
scenario step for wgich you define them. You can use them in all atoms of the scenario step.
You can assign fixed literals or an XPath that runs against the incoming message at runtime
before the system calls the process flow. In the process flow the value is fixed and you cannot
change it. You can use local variables in XSL coding or in the parameter definition for atoms.
button
[VarG]
To add, change or delete global variables, click the button. Global variables are valid for the
scenario steps of a scenario package. You can use them in all atoms of the scenario step. You
can assign fixed literals or an XPath that runs against the incoming message at runtime before
the system calls the process flow. Inside the process flow the value is fixed and you cannot
change it. You can use global variables in XSL coding or in the parameter definition for atoms.
button
[HANA]
To perform a call to the SAP HANA database, click the button.
HANA SQL Statement
Enter the SQL statement or statements for the SAP HANA database.
Note that if a HANA SQL statement contains the table field name, and the table field name
contains lower case characters, enclose the table field name in double quotation marks.
Example
Default SQL Statement: SELECT ItemName FROM OITM WHERE ItemCode=A0001
HANA SQL Statement: SELECT ItemName FROM OITM WHERE ItemCode=A0001
If a database contains special characters that are not Latin, but for example Hebrew in tables,
use the N character in the WHERE clause of an SQL statement to include the special
characters.
Example
SELECT T2.E_MAIL as FromEmail FROM OUSR as T2 WHERE
T2.USER_CODE=N'$userid'
For more information about SAP HANA, in the internet select http://help.sap.com/hana.
[Close]
To close the user interface of the atom, click the button.
Public
All rights reserved
3 Single Processing
If you select Single Processing, the integration framework submits each SQL statement in
a transaction to the JDBC adapter. The adapter hands over the statements call by call to the
database. The integration framework guarantees that it hands over the SQL statements and
submits them to the database in the same order as you have entered them. Each call has a
separate payload.
Example
SQL statements:
#select * from tbl1 where [key]='1';select * from tblA;select * from
tblB;update tbl1 set F1='X' where [key]='1';update tbl set F1='Y'
where [key]='2'
The fifth statement leads to an error. <Payload
Role="C" id="atom5_5" system="
Result:
<?xml version="1.0" encoding="UTF-8"?>
<Msg>
<Header> ...</Header>
<Body>
...
<Payload Role="C" id="atom5_1" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="select * from tbl1 where [key]='1'" disableoutput-escaping="false">
<ResultSet xmlns="urn:com.sap.b1i.adapter:jdbcadapter" rowCount="1">
...
</ResultSet>
</Payload>
compatibilityMode="true" delimiter=";" sql="select * from tblA" disable-outputescaping="false">
...
</ResultSet>
</Payload>
compatibilityMode="true" delimiter=";" sql="select * from tblB" disable-outputescaping="false">
...
</ResultSet>
</Payload>
compatibilityMode="true" delimiter=";" sql="update tbl1 set F1='X' where [key]='1'"
disable-output-escaping="false">
<UpdateCount xmlns="urn:com.sap.b1i.adapter:jdbcadapter">1</UpdateCount>
</Payload>
compatibilityMode="true" delimiter=";" sql="update tbl set F1='Y' where [key]='2'" disableoutput-escaping="false">
<SqlExceptions xmlns="urn:com.sap.b1i.adapter:jdbcadapter">
<SqlException>
<ErrorCode>208</ErrorCode>
<Message>Invalid object name 'tbl'.</Message>
Public
All rights reserved
<SqlState>S0002</SqlState>
</SqlException>
</SqlExceptions>
</Payload>
</Body>
</Msg>
The single processing mode is identical with previous Call SQL atom versions where you have
not selected the Blocked Processing checkbox.
4 Blocked Processing in Compatibility Mode

In previous versions of the SQL Call atom, you could select the Blocked Processing checkbox.
Blocked Processing in compatibility mode provides the same system behavior.
If you define only select or only update or only delete statements, this option hands over the
statements to the database that processes them in batch mode. However if you define different
statement types, for example, select and update statements for the batch, it does not work.
Additionally, the error handling of the integration framework gives you wrong or incomplete
information about processing. If the database correctly performs the first SQL statement, but
cannot process the following statements, the integration framework always provides information,
that the processing of all SQL statements has been correct.
NOTE
SAP recommends no longer using the mode for new developments.
5 Blocked Processing in Batch Mode

The Blocked Processing in Batch Mode uses the batch mode that databases provide.
Define the delimiter separating the SQL statements in the Blocked Processing Delimiter field.
The JDBC adapter that handles SQL call in the integration framework separates the SQL
statements that you enter, writes them to an array, and sends the array to the database batch
processing. The database batch processing analyses the array and possibly changes the
processing order of SQL statements for internal optimization. Therefore the integration
framework cannot guarantee the in-order processing of SQL statements.
Note that Blocked Processing in Batch Mode always comprises one transaction. If any
SQL statement in the batch fails, the transaction completely rolls back.
There are databases that cannot handle read and write operations in one batch. The integration
framework provides a mechanism to overcome this. If the integration framework finds at least
one select statement in the SQL statements you enter, the integration framework internally
switches to single processing mode and hands over the SQL statements one by one to the
database. But even then the processing comprises one transaction. In this case, the integration
framework guarantees the in-order processing of SQL statements.
The result is part of one payload.
Public
All rights reserved
Example for Successful Processing

SQL statements:
tblB;update tbl1 set F1='X' where [key]='1';update tbl 1set F1='Y'
where [key]='2'
Result:
<?xml version="1.0" encoding="UTF-8"?>
<Msg>
<Header> ...</Header>
<Body>
...
<Payload Role="C" id="atom5" system="0010000108" mode="blocked" plr="1"
dbtype="SQL" blockExecution="true" compatibilityMode="false"
delimiter=";" sql="select * from tbl1 where [key]='1';select * from
tblA;select * from tblB;update tbl1 set F1='X' where [key]='1';update
tbl1 set F1='Y' where [key]='2'" disable-output-escaping="false">
<ResultSets xmlns="urn:com.sap.b1i.adapter:jdbcadapter">
<ResultSet rowCount="1">
...
</ResultSet>
...
</ResultSet>
...
</ResultSet>
<UpdateCount>1</UpdateCount>
<UpdateCount>1</UpdateCount>
</ResultSets>
</Payload>
</Body>
</Msg>
Example for an Exception

SQL statements:
tblB;update tbl1 set F1='X' where [key]='1';update tbl set F1='Y'
where [key]='2'
Result:
The integration framework does not process any of the SQL statements. It raises an error and
hands over error handling.
The error message displays the SQL error:
com.sap.b1i.bizprocessor.BizProcException: BPE001 Nested exception:
com.sap.b1i.xcellerator.XcelleratorException: XCE001 Nested exception:
com.microsoft.sqlserver.jdbc.SQLServerException: Invalid object name
'tbl'.
Public
All rights reserved
10
6 Optimizing SQL Call for Large SQL Statements

In the Default SQL Statement field, you directly enter your SQL statement or statements, or you
enter an XPath that points to the SQL statement. Alternatively, you can enter the name of a
transformation atom that contains the SQL statements.
Enter the information in the following way: #atom<number of atom>. Enter, for example,
#atom2
NOTE
Use the procedure above to handle large SQL statements that can cause memory
problems at runtime, for example, a stack overflow.
In the transformation atom, provide an <sql> tag and place your SQL statement or statements
inside the tag.
You can use the following attributes in the <sql> tag:
removeinbound
In the removeinbound attribute, provide the transformation atom name that contains the
SQL statement or statements definition. At runtime, the integration framework removes the
SQL statement from the payload tag of the predecessor transformation atom. Instead, it
includes the following information: removed by sqlcall
occ
In the occ (occurrence) attribute, provide how many semicolons you use in your SQL
statements definition. If you have, for example, one SQL statement, occ=0.
This way, the integration framework does not have need to calculate the number of SQL
statements at runtime. This improves the performance.
result
Using this attribute does not improve the performance. Use it, if database fields contain
invalid characters according to the XML specification. It is the default that the integration
framework uses database table field names as tags to create the result structure of the SQL
call. If the field names contain invalid characters according to the XML specification, such as
#, for example, this leads to an error at runtime. Use the result attribute to avoid such a
situation.
Example for default processing
<ResultSet xmlns=urn:com:sap:b1i:adapter:jdbcadapter rowCount=3>
<Row>
<MenueId>01</MenueId>
<Text>This is a text</Text>
</Row>
<Row>
<MenueId>02</MenueId>
<Text>This is also a text</Text>
</Row>
.
.
.
Public
All rights reserved
11
Set result=Field
<ResultSet
<Row>
<Field
<Field
</Row>
<Row>
<Field
<Field
</Row>
.
.
.
xmlns=urn:com:sap:b1i:adapter:jdbcadapter rowCount=3>
label=MenuId name=MenuID>01</Field>
label=Text name=Text>This is a text</Field>
label=MenuId name=MenuID>02</Field>
label=Text name=Text>This is also a text</Field>
7 Preventing SQL Injection

SQL injection is a technique that exploits a potential security vulnerability occurring in the
scenario layer of your integration scenario. Whereas the integration framework takes care in all
cases when the framework generates SQL statements, you have to explicitly prevent SQL
injection in case you generate an SQL statement based on incoming data.
To prevent intrusion from outside, the integration framework provides you with two functions to
wrap the variable, or value before inserting it into the SQL string.
The utils2:handleSQLString(string()) function duplicates the (single quote)
character. This guarantees that the system does not process the drop statement but inserts it as
string value into the database field. An additional positive effect is that it allows handling normal
strings containing a (single quote) character.
The function utils2:handleSQLNumber(string()) type-casts the incoming value explicitly
to a number. In case of an intrusion the result is a NaN that leads to an SQL syntax error.
CAUTION
We strongly recommend using the above functions. We strongly recommend replacing
only values by outside data. Do never design the scenario to accept complete SQL
statements or parts of SQL statements from outside. You cannot control such a
situation.
Public
All rights reserved
12
Copyrights, Trademarks, and Disclaimers

Copyright 2015 SAP SE. All rights reserved.
The current version of the copyrights, trademarks, and disclaimers at
http://service.sap.com/smb/sbocustomer/documentation is valid for this document.
Public
All rights reserved
13

Call SQL B1if PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Call SQL B1if PDF

Uploaded by

Copyright:

Available Formats

Integration Framework

Last Modified: April 22, 2015

Blocked Processing in batch mode

Blocked Processing Delimiter

1.1 Options for Providing SQL Statements

1.2 Filtering Invalid XML Characters from Database Fields

The integration framework provides context-based documentation. If documentation is available,

Role="C" id="atom5_5" system="

4 Blocked Processing in Compatibility Mode

5 Blocked Processing in Batch Mode

Example for Successful Processing

Example for an Exception

6 Optimizing SQL Call for Large SQL Statements

7 Preventing SQL Injection

Copyrights, Trademarks, and Disclaimers

You might also like