engine:procedures:co_getnewestmembers_pu
Inhaltsverzeichnis
co_GetNewestMembers_Pu
Gibt eine „Top-X“-Liste der neusten Mitglieder einer Community zurück.
Anmerkung zum Parameter „DateTimeFormat“:
Die Möglichkeiten für diesen Parameter sind exakt die, die der ASE in der Funktion „convert“ für Datums-Formatierungen bietet (in Klammern ist das Format angegeben, um in der Jahreszahl das Jahrhundert angezeigt zu bekommen) :
- (0 or 100) : mon dd yyyy hh:mm AM (or PM)
1 (101) : mm/dd/yy
2 : yy.mm.dd
3 (103) : dd/mm/yy
4 (104) : dd.mm.yy
5 (105) : dd-mm-yy
6 (106) : dd mon yy
7 (107) : mon dd, yy
8 (108) : hh:mm:ss
- (9 or 109) : mon dd yyyy hh:mm:sss AM (or PM)
10 (110) : mm-dd-yy
11 (111) : yy/mm/dd
12 (112) : yymmdd
Anmerkung zum Parameter „AvgMinutesUntilNewMembership“:
Dieser besagt, wieviele Minuten (im Durchschnitt) vergehen, bis sich ein neues Mitglied in der Community registriert. Diese Abschätzung benötigt die Prozedur intern zur Ermittlung der Liste. Aufgrund mangelnder Möglichkeiten bei der Indizierung nämlich (keine ABSTEIGNDE Sortierung !) werden immer alle Mitglieder in einem Zeitraum von xxx bis yyy ermittelt, bis die gewünscht Anzahl erreicht ist; wie groß diese Zeiträume sind, sollte sich eben genau daran bemessen, wie lange es im Durchschnitt dauert, bis sich jemand neu in der Community registriert. Wird dieser Parameter nicht übergeben, dann belegt die Prozedur selbst diesen Wert - anhand der Gesamtzahl der Mitglieder in der Community, was natürlich etwas zusätzliche Performance kostet…
Anmerkung zu den „OutputCharacteristicID…“-Parametern :
IDs, die hier übergeben werden und nicht für den Benutzer, der diese Prozedur aufruft, „sichtbar“ sind (aufgrund von Zugriffsbeschränkungen, s. pm_GetPChAccRestrForUsers_Ad), werden grundsätzlich ignoriert ! D.h. es gibt zwar keinen Fehler, aber die entsprechende(n) Eigenschaft(en) werden natürlich nicht zurückgegeben !
Anmerkung zur Rückgabespalte „Nickname“ :
Eine evtl. konfigurierte Zugriffsbeschränkung für das „Nickname“-Merkmal (s. pm_GetPChAccRestrForUsers_Ad) wird bewußt NICHT beachtet (da das ja DIE öffentlich sichtbare Eigenschaft in einer Community schlechthin ist) !
| HTTP-Method | GET |
| HTTP-Auth | Optional |
| Tags | |
| Engine-Kategorie | communities |
| Engine-Typ | Daten-Ermittlung |
| Letzte Aktualisierung | 6.5.4 (2013-04-29) |
Parameter
| Name 1) | Standard-Wert | Beschreibung 2) | SQL-Datentyp3) | ab Version |
|---|---|---|---|---|
| UniqueID | Eindeutige ID eines Besuchers, die dem zu identifizierenden Mitglied aktuell zugeordnet ist. Falls die Identifizierungsdaten zur Person in „SessionManagement“ (zu dieser „UniqueID“) gespeichert sind, darf „PersonIdentificationValues“ auch „NULL“ sein. | varchar(50) | 3.5.2 | |
| PersonIdentificationValues | Liste von Werten, die das Mitglied identifizieren. Diese Werte müssen Eigenschaften zu den Merkmal-IDs sein, die in „PersonTypeSettings“ zur „PersonTypeID“ der „CommunityID“ zum Schlüssel „PersonIdentificationIDs“ hinterlegt sind. | varchar(255) | 3.5.2 | |
| CommunityID | ID einer Community | smallint | 3.5.2 | |
| RowNumber | 10 | Wieviele Datensätze sollen zurückgegeben werden ? (Also quasi : Es werden die „RowNumber“ neusten Mitglieder der Community „CommunityID“ ermittelt) | tinyint | 3.5.2 |
| DateTimeFormat | NULL | Gibt an, wie „MemberSince“ in der Rückgabemenge formatiert sein soll. „NULL“ bedeutet, daß das Format „07.02.2000 17:30:21“ gewählt wird. Ansonsten wird der Parameter für die „style“-Option der ASE-Funktion „convert“ verwendet (siehe Beschreibung). | tinyint | 3.5.2 |
| OutputCharacteristicID1 | NULL | ID eines Merkmals. Falls angegeben, enthält die Rückgabemenge in der Spalte „Value1“ die Eigenschaft des jeweiligen Mitglieds zu diesem Merkmal. Das Merkmal muß aber durch den „Settings“-Eintrag zum Schlüssel „PublicCharacteristicIDs“ freigegeben sein ! | smallint | 3.5.4 |
| OutputCharacteristicID2 | NULL | ID eines Merkmals. Falls angegeben, enthält die Rückgabemenge in der Spalte „Value2“ die Eigenschaft des jeweiligen Mitglieds zu diesem Merkmal. Das Merkmal muß aber durch den „Settings“-Eintrag zum Schlüssel „PublicCharacteristicIDs“ freigegeben sein ! | smallint | 3.5.4 |
| OutputCharacteristicID3 | NULL | ID eines Merkmals. Falls angegeben, enthält die Rückgabemenge in der Spalte „Value3“ die Eigenschaft des jeweiligen Mitglieds zu diesem Merkmal. Das Merkmal muß aber durch den „Settings“-Eintrag zum Schlüssel „PublicCharacteristicIDs“ freigegeben sein ! | smallint | 3.5.4 |
| AvgMinutesUntilNewMembership | NULL | Wieviele Minuten (im Durchschnitt) vergehen, bis sich ein neues Mitglied in der Community registriert. (genaue Erklärung siehe Beschreibung) | integer | 3.5.11 |
| CommunityBinaryCategoryID | NULL | Falls angegeben, enthält die Spalte „BinaryID“ der Rückgabemenge die kleinste „BinaryID“, die dem jeweiligen Mitglied in dieser Kategorie zugeordnet ist | smallint | 3.5.11 |
| OnlineStatusInsteadOfIsOnline | 0 | Soll der genaue „Online-Status“ zurückgegeben werden oder nur, ob der Benutzer online ist oder nicht (siehe Erläuterung zur Rückgabemenge, Spalten „IsOnline“ bzw. „OnlineStatus“) | bit | 3.5.11 |
| SeparatorInIdentVals | '¶' | Gibt an, durch welche Zeichenkette die Werte in „PersonIdentificationValues“ getrennt sind | varchar(4) | 5.5.0 |
Rückgabe
(parameterunabhängig)
| Spaltenname | Beschreibung | SQL-Datentyp4) | ab Version |
|---|---|---|---|
| CreationDateAndTime5) | Wird nur zur Sortierung verwendet. Die Spalte „MemberSince“ gibt es erst seit Version 3.5.7 und stimmt solange mit „CreationDateAndTime“ überein, wie die Person „CommunityMemberID“ nicht nachträglich Mitglied einer anderen Community wird. | datetime | 3.5.2 |
| CommunityMemberID | ID eines (neuen) Mitglieds der Community „CommunityID“ | integer | 3.5.2 |
| Nickname | Eigenschaft des Mitglieds „CommunityMemberID“ zu dem Merkmal, anhand dessen die Communitymitglieder sich untereinander unterscheiden bzw. erkennen können. (Eintrag in „CommunitySettings“ zum Schlüssel „IdentifyingCharacteristicID“) | varchar(100) | 3.5.2 |
| MemberSince | Seit wann ist „CommunityMemberID“ Mitglied ? Falls „DateTimeFormat = NULL“ übergeben wurde, ist das Format „07.02.2000 17:30:21“. Ansonsten wird „DateTimeFormat“ für die „style“-Option der ASE-Funktion „convert“ verwendet (siehe Beschreibung). | datetime | 3.5.2 |
| Value1 | Eigenschaft des Mitglieds „CommunityMemberID“ zum Merkmal „OutputCharacteristicID1“ | varchar(100) | 3.5.4 |
| Value1RestrictedByPattern | Was enthält „Value1“ (womöglich wegen Zugriffsbeschränkungen nur einen Teil) ? - NULL : den vollständigen Wert - „#left(<n>)#“ : nur die ERSTEN n Zeichen - „#right(<n>)#“ : nur die LETZTEN n Zeichen Anmerkung : „n = 0“ möglich, „Value1“ ist dann NULL | varchar(100) | 6.5.4 |
| Value2 | Eigenschaft des Mitglieds „CommunityMemberID“ zum Merkmal „OutputCharacteristicID2“ | varchar(100) | 3.5.4 |
| Value2RestrictedByPattern | Wie „Value1RestrictedByPattern“ - nur eben auf „Value2“ bezogen | varchar(100) | 6.5.4 |
| Value3 | Eigenschaft des Mitglieds „CommunityMemberID“ zum Merkmal „OutputCharacteristicID3“ | varchar(100) | 3.5.4 |
| Value3RestrictedByPattern | Was enthält „Value3“ (womöglich wegen Zugriffsbeschränkungen nur einen Teil) ? - NULL : den vollständigen Wert - „#left(<n>)#“ : nur die ERSTEN n Zeichen - „#right(<n>)#“ : nur die LETZTEN n Zeichen Anmerkung : „n = 0“ möglich, „Value3“ ist dann NULL | varchar(100) | 6.5.4 |
| IsOnline | Falls „OnlineStatusInsteadOfIsOnline = 1“ ist, dann steht hier immer der Wert „0“ („NULL“ ist beim Datentyp „bit“ nicht möglich). Ansonsten bedeutet ein Wert von „1“, daß das Mitglied „CommunityMemberID“ gerade „online“ ist. | bit | 3.5.11 |
| BinaryID | Falls „CommunityBinaryCategoryID“ angegeben wurde, steht hier die kleinste „BinaryID“, die dem Mitglied „CommunityMemberID“ in der Kategorie „CommunityBinaryCategoryID“ zugeordnet ist | integer | 3.5.11 |
| OnlineStatus | Falls „OnlineStatusInsteadOfIsOnline = 0“ ist, ist dieser Wert immer „NULL“. Andernfalls kann hier zwar auch „NULL“ stehen, dies bedeutet aber dann, daß das Mitglied „offline“ ist - ansonsten steht dort der Status aus „CurrentlyUsersOnline“. | tinyint | 3.5.11 |
Sortierung der Rückgabe
(parameterunabängige Sortierung)
- CreationDateAndTime (absteigend)
Output-Parameter
Die Prozedur hat keine Output-Parameter.
Mögliche Return-Codes
| Code | Beschreibung | Quelle 6) |
|---|---|---|
| -781 | Fehlender oder falscher Eintrag in CommunitySettings | nur indirekt |
| -780 | Fehlender oder falscher Eintrag in CommunityMemberSettings | nur indirekt |
| -774 | Login vorübergehend gesperrt | nur indirekt |
| -773 | Login gesperrt | nur indirekt |
| -772 | User ist nicht angemeldet | nur indirekt |
| -771 | Der Sweeper ist nicht gestartet | nur indirekt |
| -770 | Login zur Zeit nicht möglich | nur indirekt |
| -750 | Fehlende Berechtigung für die Anzeige der Daten | nur direkt |
| -660 | Identifikation fehlgeschlagen | nur indirekt |
| -621 | Fehlender oder falscher Eintrag in PersonTypeSettings | nur indirekt |
| -602 | Zur defaultUniqueID („VisitorID = -2“) können keinerlei Daten gespeichert oder verändert werden | nur indirekt |
| -599 | Lizenz ist ungültig oder abgelaufen | nur indirekt |
| -569 | Der Benutzer hat kein Ausführungsrecht für die Prozedur | nur indirekt |
| -567 | Die Prozedur darf z. Zt. nicht ausgeführt werden | nur indirekt |
| -566 | Die Prozedur darf mit den übergebenen Parametern nicht ausgeführt werden | nur indirekt |
| -550 | Fehlender oder falscher Eintrag in Settings | nur indirekt |
| -535 | Das Datum liegt nicht in der Vergangenheit | nur indirekt |
| -530 | Der Wert ist nicht konvertierbar | nur indirekt |
| -510 | Der Benutzer ist nicht registriert | nur indirekt |
| -504 | Es ist ein Problem aufgetreten, das nicht gelöst werden kann, Prozedur wird daher abgebrochen | nur indirekt |
| -502 | Die Parameter-Werte der Prozedur können nicht verarbeitet werden (kein passendes Trennzeichen) | nur indirekt |
| -500 | Falsche Parameter | direkt und indirekt |
XML-Schema
Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema Response/EngineProcedure_v1_0.xsd validiert.
Historie
| 6.5.4 | 2013-04-29 | 1. Implementierung des neuen Merkmal-Zugriffsbeschränkungen-Features [⇒ auch Hinweis in der Doku] 2. Länge des Parameter „SeparatorInIdentVals“ wurde erweitert [von „1“ auf „4“] 3. Neue Rückgabespalten „Value…RestrictedByPattern“ |
| 5.5.0 | 2008-01-07 | 1. Neuer Parameter „SeparatorInIdentVals“ 2. Ausgabe via „print“ im Fehler-Fall „-500“ (mit Informationen über die Ursache) 3. Bearbeitung des Quellcodes hinsichtlich neuer Konventionen 4. diverse interne Änderungen |
| 4.0.3 | 2003-07-10 | Für „MemberSince“ wurde in der Ausgabe bisher „CreationDateAndTime“ aus „Persons“ genommen. Abgesehen davon, daß „CreationDateAndTime“ jetzt in „PersonMetaInformation“ steht, war das falsch ! Jetzt wird der richtige Wert aus „CommunityMembers“ genommen. |
| 3.5.19 | 2002-06-17 | |
| 3.5.11 | 2001-09-06 | |
| 3.5.10 | 2001-07-14 | |
| 3.5.7 | 2001-05-04 | |
| 3.5.4 | 2001-03-11 | |
| 3.5.2 | 2001-01-28 | Erstmalig 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/co_GetNewestMembers_Pu?UniqueID=<value>&PersonIdentificationValues=<value>&CommunityID=<value>'
Mit xmllint 7) formatierte Ausgabe:
curl -X GET 'http://<partner>-<project>.dstore.de/default/engine/co_GetNewestMembers_Pu?UniqueID=<value>&PersonIdentificationValues=<value>&CommunityID=<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'), 'co_GetNewestMembers_Pu', array( 'UniqueID' => '<value>', 'PersonIdentificationValues' => '<value>', 'CommunityID' => <value>, // 'RowNumber' => 10, // 'DateTimeFormat' => NULL, // 'OutputCharacteristicID1' => NULL, // 'OutputCharacteristicID2' => NULL, // 'OutputCharacteristicID3' => NULL, // 'AvgMinutesUntilNewMembership' => NULL, // 'CommunityBinaryCategoryID' => NULL, // 'OnlineStatusInsteadOfIsOnline' => 0, // 'SeparatorInIdentVals' => '¶' ) ); $service->execute($request); $xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument(); $ResultSet = $xml_result->getRowsAsArray();
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="co_GetNewestMembers_Pu"> <Parameters> <Parameter Name="UniqueID"><!-- varchar value --></Parameter> <Parameter Name="PersonIdentificationValues"><!-- varchar value --></Parameter> <Parameter Name="CommunityID"><!-- smallint value --></Parameter> <!-- <Parameter Name="RowNumber">10</Parameter> --> <!-- <Parameter Name="DateTimeFormat">NULL</Parameter> --> <!-- <Parameter Name="OutputCharacteristicID1">NULL</Parameter> --> <!-- <Parameter Name="OutputCharacteristicID2">NULL</Parameter> --> <!-- <Parameter Name="OutputCharacteristicID3">NULL</Parameter> --> <!-- <Parameter Name="AvgMinutesUntilNewMembership">NULL</Parameter> --> <!-- <Parameter Name="CommunityBinaryCategoryID">NULL</Parameter> --> <!-- <Parameter Name="OnlineStatusInsteadOfIsOnline">0</Parameter> --> <!-- <Parameter Name="SeparatorInIdentVals">'¶'</Parameter> --> </Parameters> </Procedure> </Batch> </ListOfBatches>
1)
Pflichtparameter sind unterstrichen
5)
Spalte wird nicht zurückgegeben und ist hier nur aus Dokumentationsgründen aufgeführt.
6)
direkt meint „von der Prozedur selber“ und indirekt meint „von intern aufgerufenen Unterprozeduren“
7)
I.d.R. auf Unix-artigen Systemen bereits installiert, Bestandteil der libxml2, siehe http://www.xmlsoft.org
engine/procedures/co_getnewestmembers_pu.txt · Zuletzt geändert: 11.01.2016 (Externe Bearbeitung)