Best Practice - SAPERION SQL Methods

Copyright © 2016 Lexmark. All rights reserved.

Lexmark is a trademark of Lexmark International, Inc., registered in the U.S. and/or other countries. All other trademarksare the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in anyform without the prior written permission of Lexmark.

Table of Contents

1 Rules and Functions ........................................................................................... 2

1.1 Queries ............................................................................................................. 2

1.2 Placeholder ...................................................................................................... 2

1.3 Multivalue-Fields ............................................................................................. 3

2 Examples .............................................................................................................. 3

2.1 Example 1 ......................................................................................................... 3

2.2 Example 2 ........................................................................................................ 3

3 Implementation of a Separate Search in SAPERION ........................................ 4

3.1 Functional Description of a Standard Search in the Rich Client ................... 4

3.2 Enhancement of the Standard Search of a Form by own Conditions ........... 4

2

Best Practice - SAPERION SQL Methods

The methods "Application.SelectSQL" and "Mask.SearchSQL" allow you to send queries directly to

the database in an application. SAPERION does not check the syntax, which can make the queries

susceptible to error – especially when the queries are based on user input.

In addition, the different syntax used by different database providers (e.g. ORACLE, SQL server) offer

further potential sources of error.

1 Rules and Functions

In order to counter these known problems, you should take the following SAPERION rules and functions

into consideration.

1.1 Queries

A query in SAPERION consists of the elements:

SELECT <columns> FROM <tables> WHERE <conditions> ORDER BY <columns>

1.2 Placeholder

With "SelectSQL" and "SearchSQL" you can influence the element "< conditions> ORDER BY

<columns>. Please use the following placeholders for the conditions:

Placeholder

Placeholder Description

[@<ddc column name>] Is replaced by the actual column name in the table in the respective DB syntax, for example

the correct name for XHDOC is $HDOC, i.e. [@$HDOC].

[$yyyy-mm-dd$hh:mm:ss] Queries the value of a time stamp.

[$yyyy-mm-dd$] Queries the value of a date.

[$$hh:mm:ss] Queries the value of a time.

[SYSDATE] Is replaced by the current date.

[SYSTIME] Is replaced by the current time.

[SYSDATETIME] Is replaced by the current time stamp.

[§U] Is replaced by the UPPER conversion function if it is defined.

[§)] Is replaced by the if UPPER conversion function if it is defined.

2 Examples 3

1.3 Multivalue-Fields

Multivalue-fields may only be used in the conditions as subqueries or in conjunction with EXISTS. A

query that is preceded by a JOIN is not possible. Automatic field replacements are not functional here.

Example

[@$HDOC] = (SELECT HDOC FROM <DDC> SYSACLUSERLIST WHERE (MULTIVAL = 0)

Using "Application.SelectSQL" on a multivalue-field the following statement must not be used:

Set oCursor = Application.SelectSQL("<DDCNAME","<MultivalueField> = 1")

Instead, use the following statement:

Set oCursor = Application.SelectSQL("<DDCNAME>"," (EXISTS (SELECT HDOC FROM <DDCNAME><Multivaluefield>

WHERE HDOC = XHDOC AND MULTIVAL = '1')) order by zeichen desc")

i Please keep in mind that you have to add SYSINDEXSTATE and SYSOUTLINERDATA by yourself

in case of using it. SYSACLUSERLIST will automatically added.

2 Examples

2.1 Example 1

selectSQL( "exampleszenario", "[§U(][@DOCNAME][§)] = 'TEST' AND [@ARCHIVINGDATE] = [$2009-01-20$] AND

[@SYSTIMESTAMP] >= [SYSDATETIME]" )

For SQL server this becomes:

[DOCNAME] = 'TEST' AND [ARCHIVINGDATE] = '2009/20/01' AND [SYSTIMESTAMP] >= '2009/01/01 12:00'

Or for Oracle:

Upper("DOCNAME") = 'TEST' AND ...

2.2 Example 2

Query form with two query fields directed to one date field:

The first defines the upper limit, the other the lower limit of the search criteria.

Create a macro button with a macro that invokes the criteria above.

4

Query = "(([@InvoiceDate] >= [$ " & Format(mask.field("InvoiceDate",1), "yyyy-mm-dd") &"$]) AND ([@InvoiceDate] <=

[$" & Format(mask.field("InvoiceDate",2), "yyyy-mm-dd") &"$]))"

Mask.SearchSQL sQuery

The macro call does the following in detail:

+ "mask.field("InvoiceDate",1)”retrieves the date field defined for the lower limit (e.g. "01.02.2011")

+ "mask.field("InvoiceDate",2)” retrieves the date field defined for the upper limit (e.g. "01.04.2011")

+ "Format(<retrieved field contents>, "yyyy-mm-dd")” converts the retrieved contents to the given

format (in this case "2011-02-01" and "2011-04-01")

+ Use of the leading and following [$...$] creates a search format independent of database type (in

this case "[$2011-02-01$]" and "[$2011-04-01$]").

+ If for example the string in the query form field contains "InvoiceDate" "01.02.2011" the conversion

turns the date into "[$2011-02-01$]" or "[$2011-04-01$]") in our example..

+ "Mask.SearchSQL" sends the SQL string stored in sQuery to the database "(([@InvoiceDate] >=

[$2011-02-01$] AND ([@InvoiceDate] <= [$2011-04-01$] ))"

3 Implementation of a Separate Search in SAPERION

3.1 Functional Description of a Standard Search in the Rich Client

When an application is activated via the navigation SAPERION opens or activates the form and sends

the "Instant search" command to the results list. If the "Instant search" option of the results list is

enabled, SAPERION executes a standard search by sending the "Execute" command to the [Result]

button (BUTTON CLICK). This implies the evaluation of the OnButtonClick-event by SAPERION.

In cases the "Instant search" option of the results list is deactivated the application developer resp.

the user is responsible for the execution of a search. A search can be executed by clicking on the

[Result] button resp. the [Refresh] button in the ribbon or via the COM-API methods of Masks.Search.

In all these cases SAPERION sends the "Execute" command to the [Result] button and evaluates the

OnButtonClick-event.

3.2 Enhancement of the Standard Search of a Form by own Conditions

For the enhancement of the standard search the "Mask.SearchSQL" command can be used:

Example

Mask.SearchSQL "<column>=<value> AND …", True

3 Implementation of a Separate Search in SAPERION 5

Parameters of Mask.SearchSQL

Parameter Description

Mask.SearchSQL "<column>=<value> AND …" TRUE: SAPERION filters data by the SQL condition and considers also all filled fields of the

form.

FALSE: SAPERION ignores the fields in the form; conditions can be written completely in

scripts.

In order to ensure the execution of the enhanced search as soon as the search for a form is invoked

(independent whether it is called via navigation, script, button in the ribbon or in the mask), you can

attach the following script to the OnButtonClick-event of the [Result]-button and activate the "Instant

search" option:

Function Search_OnButtonClick( controlId As Long ) As Boolean

Mask.SearchSQL "<column>=<value> AND …", True

Search_OnButtonClick = FALSE ' set to False if event is handled by you

End Function

Because the function returns FALSE SAPERION does not execute the standard search so that you have

successfully implemented your search for this form.

i Commonly, also the OnInitDialog-event is used to perform a search in forms. This does only work

in version 7 when the "Instant search" option is deactivated.

When you wish to reduce the system load it is recommended to work without the "Instant search" option

and also to provide appropriate scripts to the OnIntDialog-event and OnButtonClick-event. The required

search will then be executed only once when opening the form or when the user is explicitly requesting

a refresh, but not when the form is focused via the navigation.