bs2cmd - BS2000-Kommandos via CMD-Makro ausführen

Definition	#include <bs2cmd.h> int bs2cmd(const char *cmd, bs2cmd_rc *rc, int maxoutput, int flag                    [, int *outbuflen, char *outbuf [, int *errbuflen, char *errbuf]]); Mit bs2cmd kann ein BS2000-Kommando via CMD-Makro des BS2000 ausgeführt werden. Dabei können nur Kommandos verwendet werden, für die der CMD-Makro zugelassen ist. Insbesondere macht es keinen Sinn, Kommandos auszuführen, die zum Entladen des aufrufenden Programms führen, da die Schnittstelle keine Vorkehrungen enthält, mit denen dies verhindert werden kann. Die Kommando-Ausgaben können optional gepuffert werden. In diesem Fall ist die Schnittstelle auch von einer rlogin-Task ohne SYSFILE-Umgebung nutzbar.
Parameter	const char *cmd Dieser Parameter enthält das auszuführende Kommando oder eine Kommandoliste, in der die einzelnen Kommandos durch Semikolon getrennt angegeben werden. Bis auf Zeichenfolgen, die in Apostrophe eingeschlossen sind, werden alle Zeichen in cmd vor dem Aufruf in Großbuchstaben umgewandelt. bs2cmd_rc *rc rc ist ein Zeiger auf eine Struktur bs2cmd_rc, die Rückkehr-Informationen enthält. Die Struktur bs2cmd_rc ist wie folgt aufgebaut: typedef struct bs2cmd rc { unsigned char subcode2; unsigned char subcode1; unsigned short maincode; unsigned short progrc; char cmdmsg[8]; } bs2cmd rc; Falls beim Aufruf von bs2cmd an rc der NULL-Zeiger übergeben wird, werden keine Rückkehr-Informationen bereitgestellt. int maxoutput Dieser Parameter spezifiziert die Größe des anzulegenden Puffers für die Kommando- Ausgabe in Bytes. Bei der Wahl der Puffergröße ist zu beachten, dass zusätzlich zur eigentlichen Kommando-Ausgabe auch Verwaltungsinformationen ausgegeben werden. Folgende Konstanten können angegeben werden: BS2CMD_DEFAULT Es wird ein Standard-Puffer von 256 KB verwendet. BS2CMD_NOBUFFER Die Ausgaben werden nicht gepuffert. Unter rlogin-Tasks können mit dieser Einstellung Kommandos, die Ausgaben erzeugen, nur dann ausgeführt werden, wenn der Anwender einen Puffer bereitstellt (Angabe BS2CMD_FLAG_USER_BUFFER im Parameter flag). Wenn der Puffer zu klein für die anstehenden Ausgaben gewählt wird, dann bricht die Kommando-Ausführung ab. int flag Dieser Parameter spezifiziert die Konfigurationsflags für die Schnittstelle. Derzeit können Sie die folgenden Flags oder Kombinationen von Flags (mit "|" verknüpft) angeben: BS2CMD_FLAG_STRIP Die Druckersteuerzeichen in der Kommando-Ausgabe werden vor der Ausgabe entfernt. BS2CMD_FLAG_SPLIT Die Kommando-Ausgaben werden auf stdout und stderr aufgeteilt. Meldungen werden nach stderr ausgegeben. BS2CMD_FLAG_USER_BUFFER bs2cmd wird mit einer variablen Parameterliste aufgerufen. Es werden die Parameter der variablen Parameterliste ausgewertet. Diese Parameter müssen vollständig angegeben werden, andernfalls ist das Verhalten der Funktion bs2cmd undefiniert.
Parameter	der variablen Parameterliste: Die folgenden Parameter ermöglichen Kommando-Ausgaben in einen vom Anwender bereitgestellten Speicherbereich, wenn im Parameter flag BS2CMD_FLAG_USER_BUFFER angegeben ist. int *outbuflen Länge des Speicherbereichs für stdout- Ausgaben. Nach Ausführung von bs2cmd steht in outbuflen die aktuelle Anzahl der nach outbuf geschriebenen Bytes oder -1, falls outbuf zu klein für die Ausgaben ist. char *outbuf Adresse des Speicherbereichs für stdout-Ausgaben. int *errbuflen Länge des Speicherbereichs für stderr- Ausgaben. Nach Ausführung von bs2cmd steht in errbuflen die aktuelle Anzahl der nach errbuf geschriebenen Bytes oder -1, falls errbuf zu klein fuer die Ausgaben ist. *errbuflen ist nur dann relevant, wenn im Parameter flag BS2CMD_FLAG_SPLIT angegeben ist. char *errbuf spezifiziert die Adresse des Speicherbereichs fuer stderr- Ausgaben. *errbuf ist nur dann relevant, wenn BS2CMD_FLAG_SPLIT im Parameter flag gesetzt ist.
Returnwert	maincode	bei erfolgreicher Ausführung des Kommandos. errno wird nicht gesetzt.
	-1	bei Fehler. errno wird auf einen der folgenden Werte gesetzt: EINVAL Eines der Argumente hat einen unzulässigen Wert, z.B. ein leeres Kommando oder eine negative Puffergröße. ENOMEM Der Speicherplatz für die anzulegenden Puffer reicht nicht aus. EFAULT Nach der Kommando-Ausführung ist der Inhalt des Ausgabe-Puffers nicht interpretierbar oder Ausrichtungsfehler bei outbuf. EFBIG Die Größe des Ausgabe-Puffers reicht nicht aus für die anfallenden Ausgaben. Im Fehlerfall ist der Inhalt der Benutzerpuffer undefiniert.
Hinweise	Die Meldungen werden, durch \n abgeschlossen, in den vom Anwender übergebenen Speicherbereich geschrieben. Abhängig von den Angaben im Parameter flag werden die Meldungen mit oder ohne Druckersteuerzeichen entweder nur nach outbuf geschrieben oder auf outbuf und errbuf verteilt. Wenn die Größe der übergebenen Speicherbereiche dafür ausreicht, wird die Ausgabe durch \0 abgeschlossen. Das \0 Byte wird bei der zurückgegebenen Länge nicht mitgerechnet. Reicht die Größe der Speicherbereiche für die anfallenden Daten nicht aus, dann wird der Returnwert -1 zurückgeliefert und in errno der Wert EFBIG gesetzt. Um unterscheiden zu können, ob einer der benutzereigenen Speicherbereiche oder der interne Zwischenpuffer zu klein ist, wird in outbuflen bzw. errbuflen der Wert -1 eingetragen, wenn outbuf bzw. errbuf zu klein ist. Wenn für maxoutput der Wert BS2CMD_NOBUFFER und gleichzeitig für flag der Wert BS2CMD_FLAG_USER_BUFFER angegeben ist, dann erfolgt keine interne Zwischenpufferung. Die Kommandoausgaben werden in diesem Fall direkt an den vom Anwender bereitgestellten Puffer outbuf geleitet. Der Aufbau der Ausgaben nach outbuf ist im Handbuch "Makroaufrufe an den Ablaufteil" beschrieben. Achtung! Im beschriebenen Fall muss die Adresse des Speicherbereichs auf Wortgrenze ausgerichtet sein. Bei Ausrichtungsfehler wird errno auf den Wert EFAULT gesetzt. Wenn keine Zwischenpufferung erfolgt, können die flag-Werte BS2C-MD_FLAG_STRIP und BS2CMD_FLAG_SPLIT nicht berücksichtigt werden. Eine Angabe dieser Werte wird ignoriert.