Prozedur zur Suche von Beiträgen in einem Forum.

Wie immer werden natürlich eine Identifizierung durchgeführt und die Berechtigungen (es müssen Lese-Rechte vorhanden sein) der entsprechenden Person für das Forum, zu dem der Beitrag gehört, überprüft.
Falls die Identifizierung fehlschlägt oder in „UniqueID“ der Wert „defaultUniqueID“ angegeben wird, werden die Rechte für die anonyme Person (mit der speziellen „PersonID = 0“) gecheckt.

Es wird grundsätzlich nach zwei Arten von Suchen unterschieden :

A) Suche anhand der „Wörter“ der Beiträge und/oder dem Erstellungs-Zeitpunkt.
Anmerkung : Grundlage ist die Tabelle „SearchPostings“, die NUR gepflegt wird, wenn beim Erstellen/Ändern eines Beitrags (fo_InsertPosting_Pu bzw. fo_ModifyPosting_Pu) die Suchbegriffe (in der Regel die Wörter, aus denen „Subject“ und „Body“ bestehen) angegeben werden und der Parameter „MaintainSearchPostings“ auf „1“ gesetzt ist !

B) Suche anhand von „Properties“. Dabei handelt es sich um Eigenschaften zu Beiträgen.
Anmerkung : Diese werden ebenfalls von der jeweiligen „Client-Anwendung“ gepflegt, sieht z.B. fo_ModifyPostingProperties_Pu

Hinweise zur „Suchvariante“ A)

Diese Suchvariante wird genau dann angewendet, wenn „NULL“ für den Parameter „PostingCharacteristicIDList“ angegeben ist.

Die Wörter bzw. Wortteile, nach denen gesucht werden soll, sind über „tempdb.dbo.AnyValues“ anzugeben, wobei folgendes gilt :
„Value“s mit gleicher „ID“ stellen einen „Bedingungsblock“ dar und werden mit „und“ verknüpft; die Bedingungsblöcke werden mit „oder“ verknüpft. Seit Version 4.0.0 ist es aber auch möglich, keine Suchbegriffe zu übergeben und nur nach dem Datum zu suchen (→ „FromDate“, „ToDate“) !

Beispiel :

ID Value
—————
1 hallo
1 welt
2 42

Bedeutet : Suche alle Postings, in denen die Wörter „hallo“ UND „welt“ vorkommen ODER in denen das Wort „42“ vorkommt.

WICHTIGE Anmerkungen:
1. Die Wörter bzw. Wortteile, nach denen gesucht werden soll, sind KOMPLETT in KLEINBUCHSTABEN („lowercase“) anzugeben, weil intern alle Wörter (gespeichert in der Tabelle „SearchPostings_Words“) in Kleinbuchstaben hinterlegt sind !
2.Die Wörter in „SearchPostings_Words“ sind maximal 100 Zeichen lang (d.h. man kann die mehr als 200 möglichen Zeichen in „tempdb.dbo.AnyValues“ NICHT voll nutzen).
3. Möchte man die Postings suchen, die ein Wort enthalten, das mit einer bestimmten Zeichenfolge BEGINNT, muß in „Value“ der Wert mit einem '%' am Ende stehen UND der Parameter „SearchWithLikeOperator“ muß auf „1“ gesetzt sein. Bei diesem Vorgehen muß jedoch darauf geachtet werden, dass der Suchbegriff nicht mit einem der Wildcards '%', '_', '[', ']' oder '^' beginnt, da sonst der Index auf SearchPostingsWords nicht benutzt werden kann. Es ist tatsächlich ein Performance-Unterschied, ob man z.B. mit „… LIKE 'hallo' …“ oder „… = 'hallo' …“ sucht, deswegen sollte dieser Parameter nur wenn unbedingt gewünscht auf „1“ gesetzt sein !

Hinweise zur „Suchvariante“ B)

Ermittelt werden alle Beiträge, deren Eigenschaften zu den durch „PostingCharacteristicIDList“ angegebenen Merkmalen die in „ConditionList“ aufgeführten Bedingungen erfüllen (die Elemente in den Listen sind jeweils durch „¶“ zu trennen).
Für Vergleichsoperationen müssen die einzelnen Bedingungen in „ConditionList“ ein entsprechendes Format haben :

• Wert : „Like“ Wert
• ~Wert : „Like“ Wert, aber case-INsensitiv
• ^Wert : „soundex(Wert)“
• {Wert : „<>“ Wert
• (Wert : „>=“ Wert
• Wert) : „⇐“ Wert
• [Wert : „>“ Wert
• Wert] : „<“ Wert
• (Wert1|Wert2) : „>=“ Wert1 und „⇐“ Wert2
• (Wert1|Wert2] : „>=“ Wert1 und „<“ Wert2
• [Wert1|Wert2) : „>“ Wert1 und „⇐“ Wert2
• [Wert1|Wert2] : „>“ Wert1 und „<“ Wert2

—

• {} oder {) oder {] oder (} oder () oder (] oder [} oder [) oder [] : Postings, die KEINE Eigenschaft zum Mermal haben

Sofern eine Bedingung (in „ConditionList“) eines der Formate <Wert> oder <~Wert> („LIKE“-Suche nach <Wert>) hat, können sogenannte „Platzhalter“ (o.a. „wildcards“) verwendet werden :

• '_' oder '?' : Platzhalter für EIN Zeichen
• '%' oder '*' : Platzhalter für eine ZeichenKETTE

Weitere Hinweise :
1. Um nach einem Wert zu suchen, der mit „[“ oder „(“ oder „{“ oder „~“ oder „^“ beginnt oder der mit „]“ oder „)“ oder „}“ endet, muß man den „~“-Operator verwenden (z.B. „~[*“ angeben, um nach Werten zu suchen, die mit „[“ beginnen)
2. Soll nach einem Platzhalter-Zeichen gesucht werden, ist dieses Zeichen 2mal hintereinander einzugeben (z.B. würde durch Angabe von „%%%“ nach Werten gesucht werden, die mit „%“ beginnen)
3. Im Falle einer „LIKE“-Suche (Format „Wert“ oder „~Wert“) werden (in dieser Reihenfolge !) folgende Ersetzungen vorgenommen :

• „?“ durch „_“, ausgenommen „??“ (diese Zeichenkette wird durch „?“ ersetzt)
• „*“ durch „%“, ausgenommen „**“ (diese Zeichenkette wird durch „*“ ersetzt
• „__“ durch „[_] (um nach dem Zeichen „_“ selbst suchen zu können)
• “%%„ durch “[%] (um nach dem Zeichen „%“ selbst suchen zu können)

⇒ Daher wird z.B. „?_“ sowie „_?“ durch „[_]“ ersetzt, oder „*%“ sowie „%*“ durch „[%]“. Allerdings wird z.B. „__?“ durch „[_]_“ ersetzt !

Posting-Eigenschaften sind grundsätzlich immer an eine „PersonID“ gebunden (die besondere ID „0“ bedeutet, daß die Eigenschaft „allgemein“ zum Beitrag hinterlegt ist), daher bietet der Parameter „FilterByPersonIDList“ die Möglichkeit, hiernach zu filtern.
In diesem Parameter muß eine Liste von Elementen (durch „¶“ getrennt) angegeben werden, die jeweils zur an entsrechender Stelle in „PostingCharacteristicIDList“ befindlichen Merkmal-ID korrespondiert.
Diese Elemente müssen jeweils die Form <PersonID>_<FilterCriteria> haben, wobei <FilterCriteria> ein „tinyint“-Wert ist, der angibt, WIE nach der <PersonID> zu filtern ist :

• „0“ : Nur Eigenschaften, die zur „PersonID“ hinterlegt sind
• „1“ : Nur Eigenschaften, die NICHT zur „PersonID“ hinterlegt sind
• „2“ : Nur Eigenschaften, die zur „PersonID“ ODER zur „PersonID = 0“ hinterlegt sind

Weitere Hinweise :
1. Ist für eine Suchbedingung KEINE Filterung nach einer „PersonID“ angegeben, wird implizit IMMER eine Einschränkung nach der identifizierten Person vorgenommen (im folgenden abgekürzt durch „IdentifiedPersonID“), und zwar mit dem Filter-Kriterium „2“. D.h. es werden dann nur Eigenschaften berücksichtigt, die zur „IdentifiedPersonID“ ODER zur „PersonID = 0“ hinterlegt sind !
2. Derzeit ist es nur erlaubt in EIGENEN oder ALLGEMEINEN Eigenschaften zu suchen, d.h. bei „PersonID“ MUSS es sich entweder um „IdentifiedPersonID“ oder um die ID „0“ handeln !

Anmerkungen zum Parameter „Visibility“ :
1. Sofern auch gelöschte Beiträge berücksichtigt werden sollen, muß die identifizierte Person für das Forum mindestens eines der folgenden Rechte besitzen :
„16“ : „löschen eigener Postings, sofern keine Replies vorhanden“
„32“ : „löschen eigener Postings (inkl. Replies)„
„128“ : „löschen aller Postings des Forums, sofern keine Replies vorhanden“
„256“ : „löschen aller Postings des Forums (inkl. Replies)„
Besitzt die Person nur das Recht „16“ oder „32“ wird zudem nur in EIGENEN (Author entspricht der identifizierten Person) gelöschten Beiträge gesucht !
2. Sollen nicht bestätigte Beiträge berücksichtigt werden, benötigt die identifizierte Person das Recht
„64“ : „bestätigen von Postings des Forums“
für das Forum.
3. Falls die Identifizierung fehlschlägt, werden die Rechte für die anonyme Person (mit der speziellen „PersonID = 0“) gecheckt.

Anmerkungen zum Parameter „OutputIntoOneID“ :
Alternativ zu einer Rückgabemenge kann man sich die „PostingID“s auch in „tempdb.dbo.OneID“ einfügen lassen (für einen anschließenden Aufruf von fo_GetPostingProperties_Pu z.B.). Dazu ist „OutputIntoOneID“ auf „1“ zu setzen. Möchte man sowohl eine Ergebnismenge erhalten, als auch die „PostingID“s in „OneID“ einfügen lassen, übergibt man für besagten Parameter den Wert „2“.
Möchte man quasi „ODER“-Suchen durchführen, macht es Sinn, daß man das Suchergebnis zu evtl. bereits vorhandenen „PostingID“s in „tempdb.dbo.OneID“ HINZUfügen läßt. Dazu ist für „OutputIntoOneID“ der Wert „3“ anzugeben. Um gleichzeitig wiederum auch eine Ergebnismenge zu erhalten, setzt man den Parameter auf „4“.

(parameterunabängige Sortierung)

• PostDateSortNo (aufsteigend)

(parameterunabängige Sortierung)

• PostDateSortNo (aufsteigend)

Die Prozedur hat keine Output-Parameter.

Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema Response/EngineProcedure_v1_0.xsd validiert.

Der folgende Link öffnet in einem separaten Fenster den Engine Playground der fest mit dem dbap-demo System verbunden ist:

• fo_SearchPostings_Pu im Engine Playground öffnen

Unformatierte Ausgabe:

curl -X GET  'http://<partner>-<project>.dstore.de/default/engine/fo_SearchPostings_Pu?PersonIdentificationValues=<value>&PersonTypeID=<value>&UniqueID=<value>&ForumID=<value>'

Mit xmllint ⁹⁾ formatierte Ausgabe:

curl -X GET  'http://<partner>-<project>.dstore.de/default/engine/fo_SearchPostings_Pu?PersonIdentificationValues=<value>&PersonTypeID=<value>&UniqueID=<value>&ForumID=<value>' | xmllint --format -

use dStore_php\WebService;
 
$service = new WebService\Service( WebService\Scheme::HTTP,'<partner>-<project>.dstore.de', 80);
 
$request = new WebService\Requests\Engine\Procedure\Request(
			new WebService\Requests\AccessData('default'),
	'fo_SearchPostings_Pu',
		array(
			'PersonIdentificationValues' => '<value>',
			'PersonTypeID' => <value>,
			'UniqueID' => '<value>',
			'ForumID' => <value>,
			// 'SearchWithLikeOperator' => 0,
			// 'IncludePostingBodies' => 0,
			// 'RowCount' => 50,
			// 'IncludeAdditionalInfos' => 0,
			// 'FromDate' => NULL,
			// 'ToDate' => NULL,
			// 'Visibility' => 12,
			// 'GetOwnNotApprovedPostings' => 0,
			// 'OutputIntoOneID' => 0,
			// 'PostingCharacteristicIDList' => NULL,
			// 'ConditionList' => NULL,
			// 'FilterByPersonIDList' => NULL,
			// 'Country' => 'Germany',
			// 'SearchOnlyPostingsInOneID' => 0,
			// 'SeparatorInIdentVals' => '¶'
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();

XML zur Ausführung mit der Methode engine/execute, z.B. per

curl --header 'Content-Type: application/xml' -X POST 'http://<partner>-<kunde>.dstore.de/default/engine/execute' -d '<xml-daten>'

<?xml version="1.0" encoding="UTF-8"?>
<ListOfBatches>
	<Batch No="0">
		<Procedure Name="fo_SearchPostings_Pu">
			<Parameters>
				<Parameter Name="PersonIdentificationValues"><!-- varchar value --></Parameter>
				<Parameter Name="PersonTypeID"><!-- tinyint value --></Parameter>
				<Parameter Name="UniqueID"><!-- varchar value --></Parameter>
				<Parameter Name="ForumID"><!-- smallint value --></Parameter>
				<!-- <Parameter Name="SearchWithLikeOperator">0</Parameter> -->
				<!-- <Parameter Name="IncludePostingBodies">0</Parameter> -->
				<!-- <Parameter Name="RowCount">50</Parameter> -->
				<!-- <Parameter Name="IncludeAdditionalInfos">0</Parameter> -->
				<!-- <Parameter Name="FromDate">NULL</Parameter> -->
				<!-- <Parameter Name="ToDate">NULL</Parameter> -->
				<!-- <Parameter Name="Visibility">12</Parameter> -->
				<!-- <Parameter Name="GetOwnNotApprovedPostings">0</Parameter> -->
				<!-- <Parameter Name="OutputIntoOneID">0</Parameter> -->
				<!-- <Parameter Name="PostingCharacteristicIDList">NULL</Parameter> -->
				<!-- <Parameter Name="ConditionList">NULL</Parameter> -->
				<!-- <Parameter Name="FilterByPersonIDList">NULL</Parameter> -->
				<!-- <Parameter Name="Country">'Germany'</Parameter> -->
				<!-- <Parameter Name="SearchOnlyPostingsInOneID">0</Parameter> -->
				<!-- <Parameter Name="SeparatorInIdentVals">'¶'</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>