sqlLiteralSubstitution (Eigenschaft)

Wenn Ihre Anwendung viele SQL-Anweisungen ausführt, die dieselbe Syntax verwenden und sich lediglich bei den Literalwerten unterscheiden, die sie enthalten, können Sie diese Anweisungen erfassen und konsolidieren, indem pureQuery die Literalwerte durch Parametermarken ersetzt. Ihre Anwendung kann dann diese SQL-Anweisungen statisch ausführen und von der Sicherheit und Geschwindigkeit des statischen SQL profitieren.

Ihre Anwendung könnte beispielsweise INSERT-Anweisungen generieren, die syntaktisch identisch sind, aber Literalwerte enthalten, die von Benutzern in den Feldern eines Formulars bereitgestellt werden.

Normalerweise könnten Sie diese Anweisungen nicht statisch ausführen, da sie während der Ausführung generiert werden. Die pureQuery-Clientoptimierung kann solche Anweisungen jedoch erfassen, indem es die Literalwerte durch Parametermarken ersetzt und erkennt, wenn die Syntax einer SQL-Anweisung mit der einer bereits erfassten Anweisung identisch ist. Sie können diese SQL-Anweisungen deshalb in DB2-Paketen binden.

Wenn Sie Ihre Anwendung ausführen und die Clientoptimierungseigenschaft executionMode auf STATIC gesetzt ist, kann pureQuery SQL-Anweisungen mit den von ihm erfassten, parametrisierten SQL-Anweisungen abgleichen. Übereinstimmende Anweisungen werden statisch ausgeführt. Die übereinstimmenden Anweisungen werden in der Datenbank ausgeführt.

Wenn Ihre Anwendung SQL-Anweisungen dynamisch ausführt, profitieren Sie von der Sicherheit, dass nur die erfassten Anweisungen ausgeführt werden, wobei die Literale durch Parametermarken ersetzt werden. Sie setzen den Wert der pureQuery Runtime-Eigenschaft capturedOnly auf TRUE.

Abschnitte in diesem Thema

Beispiel

Wenn Sie die Clientoptimierungseigenschaften vor der Erfassung von SQL-Anweisungen definieren, setzen Sie die Eigenschaft sqlLiteralSubstitution auf ENABLE, wie im folgenden Beispiel gezeigt:

pdqProperties=captureMode (ON), executionMode (DYNAMIC), 
pureQueryXml	(C:/workspace/capture_file.pdqxml), 
sqlLiteralSubstitution (ENABLE)

Wenn Ihre Anwendung eine Anweisung INSERT wie die erste Anweisung im nächsten Beispiel ausführt, erfasst pureQuery sie im Format der zweiten Anweisung:

insert into EMPLOYEES/*inserting new row into EMPLOYEES table*/values('Dong','Margaret',NULL,60000,12)

insert into EMPLOYEES values(?,?,?,?,?)
Anmerkung: In der CLI-Anwendungsumgebung wird NULL nicht durch eine Parametermarke ersetzt und die Kommentare in der SQL-Anweisung werden nicht entfernt.

Nachdem die Erfassung von Anweisungen beendet ist, können Sie das Dienstprogramm Configure für die Datei capture_file.pdqxml ausführen und danach das Dienstprogramm StaticBinder, um die Anweisungen in DB2-Paketen zu binden.

Wenn bei der Anwendungsausführung die Eigenschaft executionMode auf STATIC gesetzt ist und die Anwendung die Anweisung insert into EMPLOYEES values('Hinkis','Tali','R',68000,20) absetzt, gleicht pureQuery die Anweisung mit der parametrisierten Version in der pureQueryXML-Datei ab und führt sie statisch aus.

Sie können pureQuery jedoch anweisen, SQL-Anweisungen nicht mit parametrisierten Anweisungen in der Datei capture_file.pdqxml abzugleichen. Wenn Sie executionMode vor dem Ausführen der Anwendung auf STATIC setzen, können Sie gleichzeitig auch sqlLiteralSubstitution auf DISABLE setzen. Wenn Sie die Anwendung ausführen und diese die Anweisung INSERT aus dem vorherigen Absatz ausgibt, hängt es von den Werten der Clientoptimierungseigenschaften capturedOnly und allowDynamicSQL ab, ob pureQuery die Anweisung ausführt.

Werte für der Eigenschaft sqlLiteralSubstitution festlegen

In der folgenden Tabelle werden die drei Werte der Eigenschaft sqlLiteralSubstitution und die entsprechenden Auswirkungen bei der Erfassung von SQL-Anweisung aufgelistet. In der Tabelle wird außerdem gezeigt, was passiert, wenn Sie keinen Wert für diese Eigenschaft festlegen.

Tabelle 1. Auswirkungen des Festlegens bzw. Nichtfestlegens eines Wert für die Eigenschaft sqlLiteralSubstitution
Wert Auswirkungen, wenn Sie Anweisungen zum ersten Mal erfassen Auswirkungen der inkrementellen Erfassung Auswirkungen der Ausführung der Anwendung im Modus STATIC oder DYNAMIC
ENABLE pureQuery ersetzt Literalwerte durch Parametermarken.

pureQuery erfasst außerdem den Stack-Trace für die ursprünglichen SQL-Anweisungen. Wenn pureQuery Stack-Traces für alle ursprünglichen SQL-Anweisungen erfassen soll, müssen Sie möglicherweise den Wert der Eigenschaft maxStackTracesCaptured erhöhen.1

pureQuery berücksichtigt im Hinblick auf den Wert der Eigenschaft maxNonParmSQLciki nicht die Anzahl der ursprünglichen SQL-Anweisungen.

Wenn pureQuery eine SQL-Anweisung nicht parametrisieren kann und als Protokollebene FINE oder FINER angegeben ist, protokolliert es eine Warnung. Informationen zu protokollierten Warnungen finden Sie in SQL-Literalersetzung.
Die Auswirkungen sind mit denen identisch, die beim erstmaligen Erfassen von SQL-Anweisungen auftreten. pureQuery versucht, SQL-Anweisungen, die die Anwendung versucht auszuführen, mit parametrisierten SQL-Anweisungen in einer pureQueryXML-Datei abzugleichen. 2
DISABLE pureQuery ersetzt Literalwerte nicht durch Parametermarken. pureQuery ersetzt Literalwerte nicht durch Parametermarken. pureQuery versucht nicht, SQL-Anweisungen, die die Anwendung versucht auszuführen, mit parametrisierten SQL-Anweisungen in einer pureQueryXML-Datei abzugleichen.
NOT_SET (oder nicht angegeben) pureQuery ersetzt Literalwerte nicht durch Parametermarken. Wenn der Wert ENABLE lautete, als pureQuery zuletzt Anweisungen in der angegebenen pureQueryXML-Datei erfasst hat, ersetzt pureQuery Literalwerte soweit möglich durch Parametermarken.

Wenn der Wert DISABLE oder NOT_SET lautete, ersetzt pureQuery Literalwerte nicht durch Parametermarken.
Wenn der Wert ENABLE lautete, als pureQuery zuletzt Anweisungen in der angegebenen pureQueryXML-Datei erfasst hat, versucht pureQuery SQL-Anweisungen, die die Anwendung versucht auszuführen, mit parametrisierten SQL-Anweisungen in einer pureQueryXML-Datei abzugleichen.

Wenn der Wert DISABLE oder NOT_SET lautete, versucht pureQuery nicht, SQL-Anweisungen, die die Anwendung versucht auszuführen, mit parametrisierten SQL-Anweisungen in einer pureQueryXML-Datei abzugleichen.
Anmerkung:
  1. Die Eigenschaft maxStackTracesCaptured und Stack-Traces werden in einer CLI-Anwendungsumgebung nicht unterstützt.
  2. Wenn pureQuery Runtime eine parametrisierte SQL-Anweisung nicht mit der pureQueryXML-Datei abgleichen kann, hängt das Verhalten von pureQuery Runtime vom Wert der Eigenschaft captureMode ab:
    • Wenn captureMode auf ON gesetzt ist und pureQuery Runtime feststellt, dass die Literalersetzung für die SQL-Anweisung unterstützt wird, führt pureQuery die parametrisierte SQL-Anweisung aus und erfasst sie.
    • Wenn captureMode auf OFF gesetzt ist, sucht pureQuery Runtime nach der (nicht parametrisierten) SQL-Originalanweisung in der pureQueryXML-Datei. pureQuery Runtime führt dann die Anweisung aus oder löst eine Ausnahmebedingung aus. Die pureQuery-Aktion hängt davon ab, ob es die Anweisung in der Datei findet, sowie von den Werten der pureQuery Runtime-Eigenschaften allowDynamicSQL und capturedOnly.

    Wenn Sie die Literalersetzung für SQL-Anweisungen angeben, ohne eine pureQueryXML-Datei anzugeben, ersetzt pureQuery Runtime Literalwerte in SQL-Anweisungen vor der Ausführung der Anweisung durch Parametermarken. Es ist nicht erforderlich, SQL-Anweisungen zu erfassen und eine pureQueryXML-Datei zu erstellen. Die Anweisungen werden dynamisch ausgeführt. Es ist nicht erforderlich, sie statisch auszuführen. Sie können jedoch keine anderen pureQuery Runtime-Optionen aktivieren, die eine pureQueryXML-Datei erfordern, wie z. B. capturedOnly und executionMode.

Casting

Ab Version 2.2.0.1 unterstützt pureQuery Runtime zwei Castingtypen beim Ersetzen von Literalwerten durch Parametermarken.

Die SQL-Literalersetzung für einen beliebigen Parameter in CAST-Funktionen wird in einer CLI-Anwendungsumgebung nicht unterstützt.

Funktion CAST
Wenn eine SQL-Anweisung die Funktion CAST verwendet, um einen Literalwert in einen Datentyp umzusetzen, ersetzt pureQuery diesen Wert durch eine Parametermarke.

Beispiel: Wenn eine Anweisung die Klausel WHERE mySMALLINTcolumn=CAST(99 as INTEGER) enthält, wird der Wert 99 beim Erfassen der Anweisung zu einer Parametermarke.

Ein anderes Beispiel: Wenn Sie die CAST-Funktion CAST(6 as DECIMAL(7,3)) verwenden, wird bei Erfassen der Anweisung nur die '6' zu einer Parametermarke.

Benutzerdefinierte externe Skalarfunktionen, die CAST genannt werden, werden nicht unterstützt.

Implizites Casting
pureQuery Runtime führt implizites Casting zwischen Zeichenfolge- und Datums-/Uhrzeitkonstanten durch.
Zeichenfolgen in DATETIME-Konstanten konvertieren
INSERT INTO DEPARTMENT VALUES(1,5,56,'000010','A00','aa','2008-09-09')

pureQuery Runtime führt keine anderen Arten von implizitem Casting durch.

SQL-Literalersetzung

Hinweise zur Verwendung von DB2 CLI und IBM Data Server Driver

Bei der Verwendung von DB2 Call Level Interface (CLI) oder IBM Data Server Driver mit pureQuery Runtime können Sie die pureQuery Runtime-Eigenschaft als Konfigurationsschlüsselwort verwenden.

IBM CLI-Schlüsselwortsyntax
sqlLiteralSubstitution = ENABLE | DISABLE | NOT_SET
IBM Data Server Driver-Konfigurationssyntax
<parameter name="sqlLiteralSubstitution" value="ENABLE | DISABLE | NOT_SET" />
funktional entsprechendes Verbindungszeichenfolgenschlüsselwort von IBM Data Server Provider für .NET
nicht zutreffend

SQL-Literalersetzung ohne pureQueryXML-Datei aktivieren

Sie können die SQL-Literalersetzung aktivieren, ohne eine pureQueryXML-Datei anzugeben. Es ist nicht erforderlich, SQL-Anweisungen zu erfassen und eine pureQueryXML-Datei zu erstellen. Die Anweisungen werden dynamisch ausgeführt. Es ist nicht erforderlich, sie statisch auszuführen.

Die folgende Beispielkonfigurationsdatei db2dsdriver.cfg aktiviert das Schlüsselwort sqlLiteralSubstitution und enthält nicht das Schlüsselwort pureQueryXml.
<configuration>
  <dsncollection>
    <dsn alias="sample",name="sample",host="server1.test.com", port="50001">
      <parameter name="sqlLiteralSubstitution", value="ENABLE"/>
    </dsn>
  </dsncollection>
  <databases>
    <database name="sample", host=" server1.test.com", port="50001">
    </database>
  </databases>
</configuration>
Bei CLI-Anwendungen, die für die pureQuery-Clientoptimierung aktiviert sind, ersetzt pureQuery Runtime Literalwerte in SQL-Anweisungen durch Parametermarken, bevor es versucht, die Anweisung dynamisch auszuführen.

Feedback