Benutzer-Werkzeuge

Webseiten-Werkzeuge


engine:procedures:pm_getpersons_ad

pm_GetPersons_Ad

Gibt Personen eines Personen-Typs zurück.

Einziges (optionales) Filterkriterium ist eine Gruppe (→ „GroupID“). Möchte man nach bestimmten Eigenschaften filtern, ist die Prozedur pm_GetPersons_Conditions_Ad zu verwenden.

Anmerkungen zum Parameter „OutputCharacteristicIDs“ :

1. Bei den hier angegebenen Merkmalen muß es sich immer um Pflicht-Merkmale („Required = 1“, siehe pm_GetPersonCharacteristics_Ad) handeln !
2. Für alle angegebenen Merkmale muß der Aufrufer vollständigen lesenden Zugriff besitzen (s. pm_GetPChAccRestrForUsers_Ad), ansonsten gibt es einen Fehler !

Anmerkung zu den Parametern „LastValues“ und „LastPersonID“ :

Die durch „LastValues“ angegebenen Werte müssen natürlich zu den in „OutputCharacteristicIDs“ angegebenen Ausgabemerkmalen korrespondieren ! Sind keine Ausgabemerkmale angegeben, werden die „PersonID“s ermittelt, die größer bzw. kleiner (je nach „Next“) als „LastPersonID“ sind. Letzter Parameter wird auch benötigt, wenn es MEHRERE Personen gibt, die die in „LastValues“ angegebenen Eigenschaften haben.

Anmerkung zur Sortierung (falls Eigenschaften ausgegeben werden) :

Obwohl alle Eigenschaften als „strings“ gespeichert sind, wird bei der Sortierung auf das zum Merkmal hinterlegte Format geachtet, d.h. handelt es sich bei den Eigenschaften z.B. um Datumsangaben, wird die Datums-Sortierung (und nicht die alphanumerische Sortierung) verwendet.

HTTP-MethodGET
HTTP-AuthOptional
Tags
Engine-Kategorieperson management
Engine-TypDaten-Ermittlung
Letzte Aktualisierung7.0.7 (2015-01-29)

Parameter

OutputCharacteristicIDs Enthält (maximal 3) Elemente (durch '¶' getrennt) der Form
„0“ | „1“ + <PersonCharacteristicID>
Falls angegeben, werden zu den Personen Eigenschaften zu diesen Merkmalen ermittelt und das Ergebnis nach den Eigenschaften sortiert („0“ abst., „1“ aufst.)
varchar(255)3.5.0
LastPersonID0 Um „durch die Personendaten blättern“ zu können (mit „Next“ und „RowNumber“), wird der Datensatz der vorherigen „Seite“, sprich des vorherigen Aufrufs, benötigt. Dieser wird durch „LastPersonID“ und „LastValues“ repräsentiert. (siehe Beschreibung)
integer3.5.0
LastValuesNULL Um „durch die Personendaten blättern“ zu können (mit „Next“ und „RowNumber“), wird der Datensatz der vorherigen „Seite“, sprich des vorherigen Aufrufs, benötigt. Dieser wird durch „LastPersonID“ und „LastValues“ repräsentiert. (siehe Beschreibung)
varchar(255)3.5.0
PersonTypeID1 ID eines Personen-Typs, zu dem die vorhandenen Personen ausgegeben werden sollen
tinyint3.5.0
Next1 Mit diesem Parameter und „RowNumber“ kann man „durch das Ergebnis blättern“ („0“ : rückwärts, „1“ : vorwärts)„, wobei „LastPersonID“ und „LastValues“ den Datensatz des vorherigen Aufrufs repräsentieren.
bit3.5.0
GroupIDNULL ID einer Personen-Gruppe. Wenn angegeben, werden nur die Personen berücksichtigt, die dieser Gruppe angehören.
smallint3.5.0
RowNumber50 Maximale Anzahl Datensätze, die zurückgegeben werden soll. Mit diesem Parameter und „Next“ kann man „durch das Ergebnis blättern“, wobei „LastPersonID“ und „LastValues“ den Datensatz des vorherigen Aufrufs repräsentieren.
tinyint3.5.0
SeparatorInLastValues'¶' Gibt an, durch welche Zeichenkette die Werte in „LastValues“ (falls angegeben) getrennt sind
varchar(4)5.5.0

Rückgabe

wenn OutputCharacteristicIDs IN (NULL, %%''%%)

Spaltenname Beschreibung SQL-Datentyp1) ab Version
PersonIDID einer Person des Typs „PersonTypeID“
integer3.5.0
Sortierung der Rückgabe

(parameterunabängige Sortierung)

  • PersonID (aufsteigend)

wenn OutputCharacteristicIDs LIKE '0%%|%%1<PersonCharacteristicID>'

Spaltenname Beschreibung SQL-Datentyp2) ab Version
PersonIDID einer Person des Typs „PersonTypeID“
integer3.5.0
Value1Eigenschaft der Person „PersonID“ zu dem in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Sortierungen der Rückgabe

wenn SortOrder1 = 1

  • Value1 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0

  • Value1 (absteigend)
  • PersonID (aufsteigend)

wenn OutputCharacteristicIDs LIKE '0%%|%%1<PersonCharacteristicID>¶0%%|%%1<PersonCharacteristicID>'

Spaltenname Beschreibung SQL-Datentyp3) ab Version
PersonIDID einer Person des Typs „PersonTypeID“
integer3.5.0
Value1Eigenschaft der Person „PersonID“ zum ERSTEN in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Value2Eigenschaft der Person „PersonID“ zum ZWEITEN in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Sortierungen der Rückgabe

wenn SortOrder1 = 1 und SortOrder2 = 1

  • Value1 (aufsteigend)
  • Value2 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 1

  • Value1 (absteigend)
  • Value2 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 0

  • Value1 (absteigend)
  • Value2 (absteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 1 und SortOrder2 = 0

  • Value1 (aufsteigend)
  • Value2 (absteigend)
  • PersonID (aufsteigend)

wenn OutputCharacteristicIDs LIKE '0%%|%%1<PersonCharacteristicID>¶0%%|%%1<PersonCharacteristicID>¶0%%|%%1<PersonCharacteristicID>'

Spaltenname Beschreibung SQL-Datentyp4) ab Version
PersonIDID einer Person des Typs „PersonTypeID“
integer3.5.0
Value1Eigenschaft der Person „PersonID“ zum ERSTEN in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Value2Eigenschaft der Person „PersonID“ zum ZWEITEN in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Value3Eigenschaft der Person „PersonID“ zum DRITTEN in „OutputCharacteristicIDs“ angegebenen Merkmal
varchar(100)3.5.0
Sortierungen der Rückgabe

wenn SortOrder1 = 1 und SortOrder2 = 1 und SortOrder3 = 1

  • Value1 (aufsteigend)
  • Value2 (aufsteigend)
  • Value3 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 1 und SortOrder3 = 1

  • Value1 (absteigend)
  • Value2 (aufsteigend)
  • Value3 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 0 und SortOrder3 = 1

  • Value1 (absteigend)
  • Value2 (absteigend)
  • Value3 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 1 und SortOrder3 = 0

  • Value1 (absteigend)
  • Value2 (aufsteigend)
  • Value3 (absteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 0 und SortOrder2 = 0 und SortOrder3 = 0

  • Value1 (absteigend)
  • Value2 (absteigend)
  • Value3 (absteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 1 und SortOrder2 = 0 und SortOrder3 = 1

  • Value1 (aufsteigend)
  • Value2 (absteigend)
  • Value3 (aufsteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 1 und SortOrder2 = 1 und SortOrder3 = 0

  • Value1 (aufsteigend)
  • Value2 (aufsteigend)
  • Value3 (absteigend)
  • PersonID (aufsteigend)

wenn SortOrder1 = 1 und SortOrder2 = 0 und SortOrder3 = 0

  • Value1 (aufsteigend)
  • Value2 (absteigend)
  • Value3 (absteigend)
  • PersonID (aufsteigend)

Output-Parameter

CountAusgabeparameter, der die Anzahl ALLER Personen des Typs „PersonTypeID“ (evtl. : die der Gruppe „GroupID“ angehören) enthält

Mögliche Return-Codes

Code Beschreibung Quelle 5)
-697Aktion kann nicht durchgeführt werden, da für ein Merkmal eine Zugriffsbeschränkung bestehtnur indirekt
-569Der Benutzer hat kein Ausführungsrecht für die Prozedurnur indirekt
-567Die Prozedur darf z. Zt. nicht ausgeführt werdennur indirekt
-566Die Prozedur darf mit den übergebenen Parametern nicht ausgeführt werdennur indirekt
-540Falsches Formatnur indirekt
-535Das Datum liegt nicht in der Vergangenheitnur indirekt
-530Der Wert ist nicht konvertierbarnur indirekt
-510Der Benutzer ist nicht registriertnur indirekt
-504Es ist ein Problem aufgetreten, das nicht gelöst werden kann, Prozedur wird daher abgebrochennur indirekt
-502Die Parameter-Werte der Prozedur können nicht verarbeitet werden (kein passendes Trennzeichen)nur indirekt
-500Falsche Parameterdirekt und indirekt

XML-Schema

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

Historie

7.0.7 2015-01-29Interne Änderung : Datentyp-Erweiterung des „ReferenceKey“ [für „_mi_StartProcedure“-Aufruf]
6.5.4 2013-04-29Anpassungen an aktuellen Code-Standard, u.a. wg. UTF8-Unterstützung
6.5.2 2013-02-26Aufruf von „_pm_ParseOutputCharacIDList“ um Parameter „CheckAccessRestrForUserID“ erweitert,
Änderungen zwecks UTF-8-Unterstützung,
Vorbereitung des _StartProcedure-Calls und Aufruf hinsichtlich „SepArator-Parameter“ aktualisiert
6.0.2 2011-06-08Fehler : Falsche (unvollständige) Ergebnismenge auf ASE15. Ursache : Sortierungs-Problem durch ein „deferred-update“
auf temporärer Tabelle [Grund : „NULL“-Spalte, Lösung : „NOT NULL“ und default-Wert]
5.5.0 2008-01-071. Neuer Parameter „SeparatorInLastValues“
2. Ausgabe via „print“ im Fehler-Fall “-500„, die nähere Informationen über die Ursache enthält
3. (interne Änderung :) Code-Verlagerung
4.0.15 2004-07-301. „_mi_StartProcedure“, „_mi_FinishProcedure“ und „_mi_ChooseParamValueSeperator“
2. „set transaction isolation level 1“ und „set rowcount 0“ zu Beginn
3. Konsequente Fehlerbehandlung
4. Performance-Verbesserung bei der Wert-Ermittlung von „Count“
4.0.0 2003-04-031. Es waren doch wahrhaftig noch Testausgaben in einigen Fällen vorhanden !
2. Performance-Optimierung durch „set forceplan“ (für den „optimizer“)
3. Fehler in der Doku behoben
3.5.19 2002-06-17
3.5.16 2002-04-25
3.5.0 2000-11-23Erstmalig in dieser Version erstellt

Code-Snippets

Engine Playground

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

cURL

Unformatierte Ausgabe:

curl -X GET  'http://<partner>-<project>.dstore.de/default/engine/pm_GetPersons_Ad?OutputCharacteristicIDs=<value>'

Mit xmllint 6) formatierte Ausgabe:

curl -X GET  'http://<partner>-<project>.dstore.de/default/engine/pm_GetPersons_Ad?OutputCharacteristicIDs=<value>' | xmllint --format -
dStore_php
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'),
	'pm_GetPersons_Ad',
		array(
			'OutputCharacteristicIDs' => '<value>',
			// 'LastPersonID' => 0,
			// 'LastValues' => NULL,
			// 'PersonTypeID' => 1,
			// 'Next' => 1,
			// 'GroupID' => NULL,
			// 'RowNumber' => 50,
			// 'SeparatorInLastValues' => '¶'
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();
 
$OutputParams = $xml_result->getOutputParametersAsArray();
engine/execute

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="pm_GetPersons_Ad">
			<Parameters>
				<Parameter Name="OutputCharacteristicIDs"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="LastPersonID">0</Parameter> -->
				<!-- <Parameter Name="LastValues">NULL</Parameter> -->
				<!-- <Parameter Name="PersonTypeID">1</Parameter> -->
				<!-- <Parameter Name="Next">1</Parameter> -->
				<!-- <Parameter Name="GroupID">NULL</Parameter> -->
				<!-- <Parameter Name="RowNumber">50</Parameter> -->
				<!-- <Parameter Name="SeparatorInLastValues">'¶'</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>
5)
direkt meint „von der Prozedur selber“ und indirekt meint „von intern aufgerufenen Unterprozeduren“
6)
I.d.R. auf Unix-artigen Systemen bereits installiert, Bestandteil der libxml2, siehe http://www.xmlsoft.org
engine/procedures/pm_getpersons_ad.txt · Zuletzt geändert: 11.01.2016 (Externe Bearbeitung)