PDFlib Tutorial 9.0.1

2.4 Cobol-Sprachbindung
In Cobol werden die PDFlib-API-Funktionen nicht über die Standardnamen für C, sondern
über spezielle Kurznamen aufgerufen. Diese Kürzel werden hier nicht näher beschrieben,
sondern in einer eigenen Umsetzungstabelle (xref.txt) aufgeführt. So ist statt
PDF_load_font( ) beispielsweise die abkürzende Schreibweise PDLODFNT zu verwenden.
In Cobol programmierte PDFlib-Clients werden statisch mit dem PDFLBCOB-Objekt
gelinkt. Dieses lädt dynamisch das PDLBDLCB Load Module (DLL), welches beim ersten
Aufruf von PDNEW (entspricht PDF_new( )) wiederum das PDFlib Load Module (DLL) dynamisch
lädt. Das Instanz-Handle der neu allozierten internen PDFlib-Struktur wird im
Parameter P gespeichert, der in allen folgenden Aufrufen übergeben werden muss.
Das PDLBDLCB Load Module liefert die Schnittstellen zwischen den Cobol-Funktionsnamen
mit jeweils 8 Zeichen Länge und den PDFlib-Kernroutinen. Außerdem bildet es
die asynchrone Ausnahmebehandlung von PDFlib auf das von Cobol erwartete, monolithische
Verfahren gemäß »prüfe den Rückgabewert jeder Funktion« ab.
Hinweis PDLBDLCB und PDFLIB müssen dem COBOL-Programm via STEPLIB verfügbar gemacht werden.
Datentypen. Die Datentypen, die in der PDFlib-Referenz benutzt werden, müssen wie
in den folgenden Beispielen in Cobol-Datentypen umgesetzt werden:
05 PDFLIB-A4-WIDTH USAGE COMP-1 VALUE 5.95E+2. // float
05 WS-INT PIC S9(9) BINARY. // int
05 WS-FLOAT COMP-1. // float
05 WS-STRING PIC X(128). // const char *
05 P PIC S9(9) BINARY. // long *
05 RETURN-RC PIC S9(9) BINARY. // int *
Alle an das PDFlib-API übergebene Cobol-Strings sollten mit einem zusätzlichen Byte
zur Speicherung des abschließenden Nullbytes (LOW-VALUES (NULL)) definiert werden.
Rückgabewerte. Der Rückgabewert einer PDFlib-API-Funktion wird in einem zusätzlichen
Parameter namens ret bereitgestellt, der per Referenz übergeben und mit dem Ergebnis
des jeweiligen Funktionsaufrufs gefüllt wird. Der Rückgabewert 0 besagt, dass
die Funktion erfolgreich ausgeführt wurde; alle anderen Werte weisen auf einen Fehler
hin, der zu einem Abbruch der PDF-Generierung führt. Funktionen ohne Rückgabewert
(C-Funktionen mit einem Ergebnis vom Typ void) verwenden diesen Parameter nicht.
Fehlerbehandlung. In der Cobol-Sprachbindung gibt es keine PDFlib-Ausnahmebehandlung,
sondern den zusätzlichen Parameter rc (zur Speicherung des Return Code),
der von allen API-Funktionen als Fehlerindikator unterstützt wird. Der Parameter rc
wird per Referenz übergeben und zur Übermittlung von Problemen verwendet. Jeder
Wert ungleich 0 weist auf ein Fehlschlagen des Funktionsaufrufs hin.
2.4 Cobol-Sprachbindung 39