std.hl7 — HL7 v2 Messaging

Fünf Units für HL7 Version 2 — den im Gesundheitswesen meistverbreiteten Nachrichtenstandard. std.hl7 deckt den gesamten Stack ab: MLLP-TCP-Framing, MSH/ACK-Engine, Patientenverwaltung (ADT), Auftragswesen (ORM/OML/RAS), Befundübermittlung (ORU/OUL) und Terminplanung (SIU).

→ Übersicht · Standard Library · Welche Unit?

Alle Beispiele dieser Seite sind mit lyxc 1.0.21A übersetzt und ausgeführt; die gezeigten Ausgaben sind die echten Programmausgaben.

Alle vier Fachunits importieren std.hl7.core — import std.hl7.adt; zieht den Kern also mit.

HL7 (Health Level 7) Version 2 ist der faktische Standard für Datenintegration in Krankenhäusern. Jede Nachricht besteht aus zeilenweise (CR) geschriebenen Segmenten (3 Großbuchstaben + Feldtrenner), die |-getrennte Felder und ^-getrennte Komponenten enthalten:

MSH|^~\&|LIS|HOSPITAL|HIS||20260616083000||ORU^R01|MSG001|P|2.5.1
PID|||PAT123^^^MPI||Muster^Max||19850315|M
OBR|1|ORD042|LAB042|1743-4^Glucose^LN|||20260616082000
OBX|1|NM|1743-4^Glucose^LN||195|mg/dL|70-99||||HH||F

Die Standard-Trennzeichen stehen in MSH-1 und MSH-2 und werden von Hl7MshParse aus der Nachricht gelesen, nicht angenommen:

HL7 v2-Nachrichten werden über TCP immer im MLLP-Frame übertragen (Minimal Lower Layer Protocol):

[VT=0x0B] + HL7-Nachrichtenbytes + [FS=0x1C] + [CR=0x0D]

MllpFrameWrite legt den Rahmen um eine fertige HL7-Nachricht, MllpFrameRead schält die Nachricht aus dem TCP-Empfangspuffer. MllpFrameRead sucht das VT auch mitten im Puffer — Datenmüll davor wird übersprungen.

• Zero-Copy-Parsing: Alle Parse-Funktionen speichern Zeiger und Längen in den Originalnachrichtenpuffer — keine String-Kopien. Der Puffer muss leben, solange die Struct benutzt wird.
• Caller alloziert: Alle Structs (MSH, PID, PV1, ADT, Order, Report, OBX, Appointment) legt der Aufrufer selbst an. Die Größe steht in den HL7_*_SIZE-Konstanten.
• Kein rekursiver Besitz: Eine geparste ORU-Nachricht liefert nur den Befundkopf (Hl7OruParse) — die einzelnen OBX-Segmente werden getrennt mit Hl7ObxParse in einer Schleife geparst. Genauso bei NTE, AIS, AIG und AIL.
• Abgeleitete Flags: HL7_ORD_ISSTAT, HL7_OBX_ISCRIT/HL7_OBX_ISCORR sowie HL7_APPT_ISCANCEL/ISDELETE/ISNOSHOW setzt der Parser selbst — keine manuellen String-Vergleiche nötig.

HIS/ADT-System          HL7-Gateway / Lyx
    |                        |
    |-- ADT^A01 (Aufnahme) ->|  Hl7AdtParse()
    |<-- ACK^AA (Quittung) --|  Hl7AckWrite() + MllpFrameWrite()
    |                        |
    |-- ADT^A08 (Update) --->|  Hl7AdtParse()
    |<-- ACK^AA -------------|
    |                        |
    |-- ADT^A03 (Entlassung)>|  Hl7AdtParse()
    |<-- ACK^AA -------------|

KIS / Station           LIS (Labor)
    |                        |
    |-- ORM^O01 (Auftrag) -->|  Hl7OrmParse()
    |<-- ORR^O02 (OK/ER) ----|  Hl7OrrWrite()
    |                        |  [Analyse laeuft ...]
    |<-- ORU^R01 (Befund) ---|  Hl7OruParse() + Hl7ObxParse() je OBX
    |-- ACK^AA ------------->|

Medikamentensystem      Stationssystem
    |                        |
    |-- RAS^O17 ------------>|  Hl7RasParse()
    |<-- ACK^AA -------------|

Terminplaner            Fachabteilung
    |                        |
    |-- SIU^S12 (neu) ------>|  Hl7SiuParse()
    |-- SIU^S15 (Absage) --->|  HL7_APPT_ISCANCEL = 1
    |-- SIU^S26 (No-Show) -->|  HL7_APPT_ISNOSHOW = 1
    |<-- ACK^AA -------------|

Hl7DupCheck registriert die Nachricht beim Rückgabewert 0 gleich mit — ein zweiter Aufruf mit derselben Control-ID liefert 1.

HL7_ORD_MSGTYPE unterscheidet die Herkunft (1 = ORM, 2 = OML), HL7_ORD_ISSTAT meldet einen STAT-Auftrag (OBR-5 = S).

HL7_RPT_MSGTYPE ist HL7_RPT_TYPE_ORU (1) oder HL7_RPT_TYPE_OUL (2). HL7_OBX_ISCRIT markiert Panikwerte (OBX-8 HH/LL), HL7_OBX_ISCORR korrigierte Ergebnisse (OBX-11 C).

Die Schreib-Funktionen (…Write) melden Überlauf dagegen mit -1 als Rückgabewert, nicht mit HL7_ERR_OVERFLOW — der Rückgabewert ist dort die geschriebene Bytezahl.

HL7_ACK_AA / HL7_ACK_AE / HL7_ACK_AR (1/2/3) sind Kennzahlen für eigene Zustandslogik. Hl7AckWrite erwartet nicht sie, sondern den zweibuchstabigen Code als pchar — seit #1617 ohne Cast: "AA"c.

Die eingebetteten Structs der ADT-Nachricht liegen an festen Offsets: HL7_ADT_PID = 112, HL7_ADT_PV1 = 288, HL7_ADT_MRG = 448, HL7_ADT_NK1 = 496. Ein Feld daraus wird also mit peek64(adt + HL7_ADT_PID + HL7_PID_FAMILY) gelesen.

Empfangen, prüfen, parsen, quittieren — der vollständige Weg einer ADT-Nachricht:

import std.hl7.core;
import std.hl7.adt;
import std.alloc;
import std.string;

// Zero-Copy: die Struct-Felder zeigen in den Nachrichtenpuffer und sind
// NICHT nullterminiert. Fuer die Ausgabe eine Kopie mit \0 anlegen.
fn Feld(ptr: int64, len: int64): pchar {
    var buf: int64 := alloc(len + 1);
    var i: int64 := 0;
    while (i < len) { poke8(buf + i, peek8(ptr + i)); i := i + 1; }
    poke8(buf + len, 0);
    return buf as pchar;
}

fn main(): int64 {
    // Dedup-State: einmalig pro Server-Instanz
    var state: int64 := alloc(HL7_STATE_SIZE);
    Hl7StateInit(state);

    // Eine Nachricht, wie sie aus dem Socket kommt (hier selbst gerahmt)
    var msg: pchar := "MSH|^~\\&|HIS|KH|LIS|LAB|20260813081500||ADT^A01|MSG001|P|2.5.1\rPID|||PAT123^^^MPI||Muster^Max||19850315|M\rPV1||I|ITS^201^A^KH|||||||||||||||V4711\r"c;
    var tcpBuf: int64 := alloc(65536);
    var tcpLen: int64 := MllpFrameWrite(tcpBuf, 65536, msg as int64, StrLen(msg));

    // MLLP-Frame auspacken
    var msgBuf: int64 := alloc(65536);
    var msgLen: int64 := MllpFrameRead(tcpBuf, tcpLen, msgBuf, 65536);
    if (msgLen < 0) { return 1; }

    // MSH parsen und pruefen
    var msh: int64 := alloc(HL7_MSH_SIZE);
    if (Hl7MshParse(msgBuf, msgLen, msh) != HL7_OK) { return 1; }
    if (Hl7VersionCheck(msh) != HL7_OK) { return 1; }
    if (Hl7IsTestMsg(msh) == 1) { PrintLn("Testnachricht - nicht speichern"); }

    // Doppelte Nachricht? (Partnerschluessel: sendende Anwendung)
    var sendApp: int64 := peek64(msh + HL7_MSH_SEND_APP);
    var ctrlId:  int64 := peek64(msh + HL7_MSH_CTRL_ID);
    if (Hl7DupCheck(state, sendApp, ctrlId) == 1) { PrintLn("Duplikat"); return 0; }

    // ADT vollstaendig parsen
    var adt: int64 := alloc(HL7_ADT_SIZE);
    Hl7AdtParse(msgBuf, msgLen, adt);
    var famPtr: int64 := peek64(adt + HL7_ADT_PID + HL7_PID_FAMILY);
    var famLen: int64 := peek64(adt + HL7_ADT_PID + HL7_PID_FAMILY_LEN);
    var bedPtr: int64 := peek64(adt + HL7_ADT_PV1 + HL7_PV1_LBED);
    var bedLen: int64 := peek64(adt + HL7_ADT_PV1 + HL7_PV1_LBED_LEN);
    PrintLn(StrConcat("Nachname: ", Feld(famPtr, famLen)));
    PrintLn(StrConcat("Bett:     ", Feld(bedPtr, bedLen)));

    // ACK bauen und rahmen
    var ackBuf: int64 := alloc(512);
    var ackLen: int64 := Hl7AckWrite(msh, "AA"c, "OK"c, ackBuf, 512);
    var outBuf: int64 := alloc(600);
    var outLen: int64 := MllpFrameWrite(outBuf, 600, ackBuf, ackLen);
    PrintLn(StrConcat("ACK-Bytes: ", IntToStr(outLen)));

    free(outBuf, 600); free(ackBuf, 512); free(adt, HL7_ADT_SIZE);
    free(msh, HL7_MSH_SIZE); free(msgBuf, 65536); free(tcpBuf, 65536);
    free(state, HL7_STATE_SIZE);
    return 0;
}

Nachname: Muster
Bett:     A
ACK-Bytes: 66

Das Bett kommt aus PV1-3.3: die Ortsangabe ITS^201^A^KH zerlegt der Parser in Station (ITS), Zimmer (201), Bett (A) und Einrichtung (KH).

• Segmente trennt \r, nicht \n. Eine mit Zeilenumbrüchen aufgebaute Nachricht wird nicht geparst; der Parser sucht CR (0x0D).
• Zeiger überleben den Puffer nicht. Wird msgBuf freigegeben oder wiederbenutzt, zeigen alle Felder der Structs ins Leere. Werte, die länger gebraucht werden, vorher kopieren.
• Zeichensatz prüfen. Ohne MSH-18 gilt ISO-8859-1. Umlaute aus einem solchen Strom sind kein UTF-8 — Hl7IsUtf8 fragen, bevor der Text weitergereicht wird.
• Testnachrichten erkennen. Hl7IsTestMsg vor jedem Schreibzugriff auf die Produktivdatenbank aufrufen; MSH-11 T kommt in Kopplungstests regelmäßig vor.
• Dedup-Ring ist begrenzt. 16 Partner × 64 Control-IDs. Bei mehr Partnern verdrängt der Ring die ältesten Einträge — die Duplikatserkennung ist eine Nahbereichs-Sicherung, kein Ersatz für eine persistente Nachrichtentabelle.
• Hl7AckWrite erwartet den Code als Text ("AA"c), nicht die Konstante HL7_ACK_AA.

Weiterführend: std.hl7.core · std.hl7.adt · std.hl7.orders · std.hl7.results · std.hl7.scheduling · std.net · Rohspeicher

Letzte Aktualisierung: 2026-08-13 — Tabellen repariert (^ in Zellen maskiert), „Vier Units„ → fünf, Funktionsübersicht je Unit, Rückgabewerte, Größentabelle um die scheduling-Structs und HL7_SLOT_SIZE ergänzt, Quickstart lauffähig gemacht (er benutzte eine nicht deklarierte tcpBufLen). Alles gegen std/hl7/*.lyx und lyxc 1.0.21A geprüft.

Codebeispiele geprüft: gegen lyxc 1.2.5C übersetzt (Prüflauf 2026-09-08 über die gesamte Doku: 574 Vollprogramme, 0 echte Fehler; zusätzlich 5159 Aufrufe gegen die pub fn-Signaturen in aurum/std gehalten, 0 Abweichungen).