C: #include <xatmi.h>
int tpinit (TPCLTINFO *tpinfo) (in)
COBOL: 01 TPINIT-REC.
COPY TPCLTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPINIT" USING TPINIT-REC TPSTATUS-REC.
Beschreibung
Die Funktion tpinit() initialisiert einen Client und identifiziert diesen beim Trägersystem. Sie muss als erste XATMI-Funktion in einem Client-Programm aufgerufen werden.
Als Parameter ist in C ein Zeiger auf die vordefinierte Struktur TPCLTINFO zu übergeben.
Der COBOL-Aufruf benötigt zwei Parameter:
Erster Parameter: TPCLTDEF Record.
Der zweite Parameter liefert den Return-Status des Aufrufs zurück.
#define MAXTIDENT 9
#define MAXPASSWORD 17
typedef struct {
long flags; /* for future use */
char usrname[MAXTIDENT];
char cltname[MAXTIDENT];
char passwd [MAXPASSWORD];
} TPCLTINFO;
05 FLAG PIC S9(9) COMP-5. 05 USRNAME PIC X(8). 05 CLTNAME PIC X(8). 05 PASSWD PIC X(16).
In usrname wird eine Benutzerkennung und in passwd ein Kennwort eingetragen. Beide Parameter werden zur Einrichtung einer Conversation verwendet und dienen dazu, auf der UTM-Seite die Zugangsberechtigung nachzuweisen. Mit cltname (= local client name) wird der Client beim Trägersystem identifiziert.
cltname ist (siehe Abschnitt "Enable_UTM_UPIC - Beim Trägersystem UPIC anmelden - Parameter »local name«"):
für Unix-, Linux- und Windows-Systeme: bei UPIC-L der PTERM-Name oder der lokale Anwendungsname aus der
upicfile,- cltname ist beliebig wählbar, wenn ein TPOOL für UPIC-L generiert ist.
- bei UPIC-R der Eintrag in der upicfile.
Wenn usrname und passwd mit dem Nullstring initialisiert sind (COBOL: SPACES), dann werden die Security-Funktionen nicht aktiviert, d.h. es findet bei openUTM keine Zugangsprüfung statt. Enthält mindestens einer dieser beiden Parameter einen gültigen Wert, dann wird dieser von openUTM geprüft.
Ist cltname mit dem Nullstring bzw. SPACES initialisiert, dann wird der „local client name“ mit 8 Leerzeichen vorbelegt.
Wenn tpinit() in C mit einem NULL-Zeiger aufgerufen wird, dann ist keine Zugangsprüfung aktiviert und der „local client name“ ist mit 8 Leerzeichen vorbelegt. Bei COBOL muss dazu die Struktur mit SPACES versorgt werden.
Die Einträge in usrname, passwd und ggf. in cltname müssen den UTM-Namenskonventionen entsprechen, d.h. sie dürfen maximal acht (bzw. 16 für passwd) Zeichen lang sein, wobei Folgendes gilt:
In C müssen sie mit dem Stringende-Zeichen ("\0") abgeschlossen sein.
In COBOL müssen die Einträge mit Leerzeichen auf die jeweilige Länge aufgefüllt werden.
Returnwerte
In C liefert tpinit() im Fehlerfall -1 zurück und setzt die Fehlervariable tperrno auf einen der folgenden Werte:
TPEINVAL
Ein oder mehrere Parameter wurden mit einem ungültigen Wert versorgt.
TPENOENT
Die Initialisierung konnte nicht durchgeführt werden, z.B. steht nicht genügend Speicherplatz für interne Puffer bereit.
TPEPROTO
tpinit wurde an nicht erlaubter Stelle aufgerufen, z.B. der Client ist bereits initialisiert.
TPESYSTEM
Es ist ein interner Fehler aufgetreten.
In COBOL wird beim TPINIT-Aufruf im Fehlerfall der entsprechende tperrno-Wert direkt als Return-Status geliefert.