DBreturnExpandedText

Inhalt des Textes incl. Attributen liefern.

Zum Handle eines Textelements wird dessen Textinhalt ermittelt. Der Inhalt wird kopiert, eine Änderung in dem zurückgegebenen Textstring wirkt sich nicht auf den Inhalt der Datenbank aus. Da die Länge des Textes nicht begrenzt ist, wird über den Parameter len beim Aufruf von DBreturnTextString die Maximallänge des Textes (inklusive 0-Character als Abschluss) an die Prozedur übergeben. Bei Rückkehr aus der Prozedur enthält das Feld entweder die reale Länge der Textes, falls dieser kürzer als der Maximalwert ist oder den Maximalwert, wenn er länger ist. In diesem Fall wird der zurückgegebene Text gekürzt. Wird len mit 0 initialisiert, wird statt dessen in len die Länge des Textes geschrieben und der Text wird nicht zurückgegeben. Wenn in diesem Textelement das Flag für Attributtext gesetzt ist, wird von dieser Prozedur der expandierte Text geliefert, während DBreturnTextString den nicht expandierten Text liefert. Da das Expandieren des Textes Zeit benötigt, ist es zu empfehlen, nicht zuerst den Platzbedarf berechnen zu lassen und dann mit diesem Bedarf den Inhalt abzufragen, sondern statt dessen sofort einen Versuch mit einem wahrscheinlich ausreichenden Feld zu unternehmen. Falls dieses zu klein ist, kann dann der Aufruf über Berechnen des Bedarfs und Aufruf mit genügend Speicher erfolgen. In Attributnamen, die über DBreturnExpandedText ausgewertet werden sollen, darf kein % vorkommen, da dieses Zeichen als Markierung benutzt wird.

Parameter

element (PELEMENT)                                [IN]

Das Handle des Textes, von dem der Textinhalt ermittelt werden soll. Hier darf auch nur ein Text-Handle übergeben werden, alles andere mag das System nicht. Eine Überprüfung findet statt, wenn die Debugversion verwendet wird.

len (int *)                                              [IN/OUT]

Wenn bei Aufruf hier der Wert 0 steht, so wird nur in len die reale Länge des Strings eingetragen. Ein Wert ungleich 0 beschreibt die maximale Länge des Textes bei der Rückgabe. Ist der Text länger als dieser Wert, so wird er abgeschnitten. Gemeint ist jeweils die Länge inklusive des abschließenden 0-Zeichens.

textString (char *)                               [IN/OUT]

Dies ist ein Zeiger auf einen Bereich von mindestens len Zeichen. In diesem Bereich wird der Textinhalt kopiert, wobei auftretende Attribute expandiert werden. Wenn bei Aufruf in len 0 steht, wird dieser Zeiger nicht benutzt, kann also jeden Wert besitzen.

Ergebnis

(T_ERROR)                                            [OUT]

Wenn die Prozedur fehlerfrei ausgeführt werden konnte, dann liefert sie ERROR_OK, sonst eine der Fehlermeldungen aus error.h.

Deklaration

#include "database.h"

T_ERROR DLLENTRY DBreturnExpandedText (

     PTEXT_ELEMENT     element,

     int *          len,

     char *            textString

);

Verwandte Prozeduren

DBreturnTextString