Python API – DTP und Datensatzoperationen

1. Einleitung

2. Globale DTP-Funktionen

2.1 `search_record()` – Datensätze suchen

Element	Beschreibung
Funktion	`search_record()`
Zweck	Sucht Datensätze in einer Data Table und liefert einen `DtpRecord` zurück.
Rückgabewert	`DtpRecord` bei erfolgreichem Treffer, sonst `None`.
Mögliche Fehler	`DataTableError`, wenn die Tabelle oder Parameter ungültig sind.
Hinweise	Nutzt `dt_num`, `key_list`, `di_list`, `dblookup` zur Steuerung der Suche.

Parameter	Beschreibung
`dt_num`	Nummer der Data Table, in der gesucht wird.
`key_list`	Liste von Schlüsselfeldern/Werten zur Identifikation des Datensatzes.
`di_list`	Liste weiterer Data Items, die geladen werden sollen (optional).
`dblookup`	Steuert, ob direkt in der DB gesucht wird oder im Cache (je nach Implement.).

2.2 `create_record()` – Datensätze anlegen

Element	Beschreibung
Funktion	`create_record()`
Zweck	Legt einen neuen Datensatz in einer Data Table an und liefert einen `DtpRecord` zurück.
Rückgabewert	`DtpRecord` bei erfolgreichem Anlegen, sonst `None`.
Mögliche Fehler	`DataItemError`, `DataTableError`
Wichtige Hinweise	Primärschlüssel-DIs müssen korrekt gesetzt sein (ggf. Auto‑ID). Duplikate lassen sich über `DtpRecord.state()` erkennen.

Parameter	Beschreibung
`dt_num`	Nummer der Data Table, in der der Datensatz angelegt wird.
`value_dict` o. Ä.	Zu setzende Werte je Data Item (abhängig von exakter Signatur).

2.3 Beispiel: Global DTP

Element	Beschreibung
Beispiel	„Global DTP example“: Zeigt die Verwendung von `create_record()` und `search_record()` in DT700 „Book“.
Inhalt	Struktur der Data Table (z. B. DT700 Book) und Codebeispiel (Record anlegen und wiederfinden).

3. `DtpPool` – Iteration über Tabellen

3.1 `DtpPool`-Klasse

Element	Beschreibung
Klasse	`DtpPool`
Zweck	Erlaubt die Iteration über alle Datensätze einer Data Table.
Konstruktor	`DtpPool(dt_number)`
Mögliche Fehler	`DataTableError`, wenn die angegebene Data Table nicht existiert oder nicht geladen werden kann.
Typische Verwendung	`for record in DtpPool(461): ...` – Durchlaufen aller Datensätze einer DT.

Parameter	Beschreibung
`dt_number`	Nummer der Data Table, über deren Datensätze iteriert wird.

3.2 Beispiel: Iteration

Element	Beschreibung
Beispiel	Kurzes Codebeispiel mit `for record in DtpPool(dt): ...` und Zugriff auf DIs per Python-ID.

4. `DtpRecord` – Arbeiten mit einzelnen Datensätzen

4.1 Grundlagen

Element	Beschreibung
Klasse	`DtpRecord`
Zweck	Repräsentiert einen logischen Datensatz in einer Data Table.
Zugriff	Sub‑Data Items sind als Attribute über Python-IDs verfügbar, z. B. `rec.L123_name`.

4.2 Zugriff auf Data Items

Methode	Beschreibung
`get_di_by_id(number)`	Liefert das `DataItem` mit der angegebenen technischen ID.
`get_di(name)`	Liefert das `DataItem` mit dem angegebenen Namen.
`get_dis()`	Liefert alle zugehörigen `DataItem`-Objekte.
`get_changed_dis()`	Liefert nur `DataItem`-Objekte, deren Wert geändert wurde.
`append_dis(di_list)`	Ergänzt den Record um zusätzliche Data Items aus der angegebenen Liste.

Hinweis	Beschreibung
Zweck	Selektiver Zugriff auf und Analyse von Spaltenwerten.
Einsatz	Vor allem vor/nach `save()` oder zum diffen von Änderungen.

4.3 Navigieren in Strukturen

Methode	Beschreibung
`get_children(dt, di_list=None, structure=False)`	Liefert Child-Records für eine angegebene Data Table. Optional können zusätzliche DIs geladen werden.

Parameter	Beschreibung
`dt`	Nummer der Child-Data-Table.
`di_list`	Optionale Liste von Data Items, die zusätzlich geladen werden sollen.
`structure`	Wenn `True`, werden Strukturinformationen (z. B. Hierarchien) mitgeladen.

4.4 Speichern und Löschen

Methode	Beschreibung
`save(dis=None)`	Speichert den Record. Führt je nach Zustand einen INSERT oder UPDATE aus. Optional kann die Speicherung auf bestimmte DIs (`dis`) beschränkt werden.
`delete()`	Löscht den Record (inkl. verbundener Kinder, je nach Implementierung). Danach darf die Instanz nicht weiterverwendet werden.

Element	Beschreibung
Mögliche Fehler	`DataItemError` beim Speichern/Löschen.

4.5 Zustände von Datensätzen

Methode	Beschreibung
`state()`	Liefert den Status des Records (z. B. nach `create_record()` oder nach Ladeoperationen).

Mögliche Zustände	Bedeutung
`NONEXISTENT`	Record existiert nicht in der DB.
`INVALID`	Record ist unvollständig/inkonsistent.
`NEW`	Neuer, noch nicht gespeicherter Datensatz.
`STORED`	Datensatz ist dauerhaft gespeichert.

4.6 Praxisbeispiele

Element	Beschreibung
Beispiel	Kurzer Code: Record suchen oder anlegen, Werte über `DataItem.set_value` ändern, `save()` ausführen und `state()` prüfen.

5. `DataItem` – Arbeiten mit Einzelwerten

5.1 Grundlagen

Element	Beschreibung
Klasse	`DataItem`
Zweck	Repräsentiert einen einzelnen Spaltenwert eines `DtpRecord`.
Abgrenzung	MTS-`DataField` zeigt Werte in der UI, `DataItem` hält die Daten auf DTP-Ebene.

5.2 Lesen von Werten

Methode	Beschreibung
`get_value()`	Liefert den Wert in „benutzerfreundlicher“ Form (z. B. Text anstelle von IDs).
`get_tech_value()`	Liefert den technischen Wert (z. B. I‑TEXT‑ID, interne Codes).

Hinweis	Beschreibung
Unterschied	Anzeige-/Textwerte vs. interne IDs/Codes.

5.3 Änderungsstatus und Originalwerte

Methode	Beschreibung
`has_been_updated()`	Gibt an, ob sich der Wert seit dem Laden geändert hat.
`get_original_value()`	Liefert den ursprünglichen (benutzerfreundlichen) Wert.
`get_original_tech_value()`	Liefert den ursprünglichen technischen Wert.

Typischer Einsatz	Beschreibung
Change-Tracking	Ermitteln, welche Spalten sich geändert haben, Vergleich alt/neu.

5.4 Kontextinformation

Methode	Beschreibung
`get_dtp_record()`	Liefert den zugehörigen `DtpRecord`.
`get_dfs()`	Liefert zugeordnete MTS-Felder (`DataField`s), falls vorhanden.

5.5 Setzen von Werten

Methode	Beschreibung
`set_value(value)`	Setzt den Wert unter Berücksichtigung des Datentyps.
`set_string_value(value)`	Setzt den Wert aus einem String, inkl. möglicher Konvertierung.

Rückgabecodes	Bedeutung
`SUCCESS`	Wert wurde erfolgreich gesetzt.
`FAILURE`	Setzen des Werts ist fehlgeschlagen.
`WRONG_FMT`	Falsches Format für den Datentyp.
`KEY`	Verletzung von Schlüsselbedingungen.
`UNCHANGED`	Neuer Wert entspricht dem alten Wert.

Besonderheit	Beschreibung
Primärschlüssel-DIs	Besondere Behandlung über `DI_VALUE_SETTER_KEY`.
Validierung	Komplette Validierung erfolgt i. d. R. beim Speichern/MTS-Ebene.

5.6 Metadaten

Methode	Beschreibung
`get_id()`	Liefert die technische ID des Data Items.
`get_customizing_name()`	Liefert den Namen aus dem Data-Item-Customizing.

6. Hyperlinks an DTP-Datensätzen

6.1 Hyperlink-Unterstützung auf `DataItem`

Methode	Beschreibung
`is_hyperlink()`	Prüft, ob das Data Item einen Hyperlink enthält.
`get_hyperlink_type()`	Liefert den Hyperlink-Typ (z. B. UNSTRUCTURED, CLIENT_BASED, SERVER_BASED, NO_HYPERLINK).
`get_hyperlink()`	Liefert das zugehörige `Hyperlink`-Objekt.
`insert_hyperlink()`	Erzeugt einen neuen Hyperlink an diesem Data Item.

Hinweis	Beschreibung
Konstanten	Verwendet die Typ-Konstanten der `Hyperlink`-Klasse (UNSTRUCTURED, CLIENT_BASED, SERVER_BASED, NO_HYPERLINK).

6.2 `Hyperlink`-Klasse

6.2.1 Identifikation und Basisattribute

Methode	Beschreibung
`get_id()`	Liefert die eindeutige ID des Hyperlinks.
`get_schema()`	Liefert das Schema des Hyperlinks (z. B. Typ).
`get_uid()`	Liefert eine eindeutige UID des Hyperlinks.
`get_hyperlink_di()`	Liefert das zugehörige `DataItem` (Hyperlink-DI).
`get_record()`	Liefert den zugehörigen `DtpRecord`.

6.2.2 Inhalte und Metadaten

Methode	Beschreibung
`get_title()`	Liefert den Anzeigetitel des Hyperlinks.
`get_url()`	Liefert die hinterlegte URL/Pfadangabe.
`get_initial_crc()`	Liefert die ursprüngliche CRC des Inhalts.
`get_current_crc()`	Liefert die aktuelle CRC des Inhalts.
`get_database_crc()`	Liefert die in der Datenbank gespeicherte CRC.

6.2.3 BLOB-Daten

Methode	Beschreibung
`get_blob()`	Liefert den gespeicherten Inhalt als `bytearray`.

6.2.4 Schreiben / Ändern

Methode	Beschreibung
`set_value(binary=None, url=None, is_folder=False, is_weblink=False)`	Setzt den Hyperlink-Inhalt: BLOB oder URL/Pfad. Steuert außerdem Ordner-/Weblink-Eigenschaften.
`set_title(title)`	Setzt den Anzeigetitel des Hyperlinks.

Hinweis	Beschreibung
`None`/leerer String	Spezielles Verhalten je nach Implementierung (Löschen/Leeren).
Client/Server-basiert	Unterschiedliche Behandlung von Pfaden/URLs.

6.2.5 Löschen

Methode	Beschreibung
`delete_blob()`	Löscht nur den BLOB-Inhalt, lässt den Hyperlink-Eintrag bestehen.
`delete()`	Löscht den Hyperlink vollständig. Danach Objekt nicht weiterverwenden.

6.3 Beispiel: Datei-Hyperlink anlegen

Element	Beschreibung
Beispiel	Codebeispiel: `insert_hyperlink()`, `set_value()` mit Pfad/BLOB, anschließend `save()` des zugehörigen `DtpRecord`.