TRANSMIT-BY-STREAM Variablen übertragen

Anwendungsgebiet: PROCEDURE

Kommandobeschreibung

Das Kommando TRANSMIT-BY-STREAM führt von Client-Seite eine Variablen-Übertragung über den angegebenen S-Variablenstrom zu oder vom angesprochenen Server durch.

TRANSMIT-BY-STREAM sendet zuerst die in VARIABLE-NAME angegebene Variable zur Steuereinheit SDF-P und empfängt dann von SDF-P Daten in der in RETURN-VARIABLE-NAME angegebenen Variablen.

Wenn *VARIABLE dem S-Variablenstrom im Kommando ASSIGN-STREAM zugewiesen ist, werden die Variablen, die beim Kommando TRANSMIT-BY-STREAM in RETURN-VARIABLE-NAME und in RET-CONTROL-VAR-NAME enthalten sind, durch die gleichnamigen Variablen vom Kommando ASSIGN-STREAM überschrieben.

Wenn *DUMMY dem S-Variablenstrom zugewiesen ist, gibt das Kommando einen Returncode zurück, der besagt, dass nichts geändert wurde.

Die Reihenfolge der Abarbeitung ist im Kapitel „S-Variablenströme“ beschrieben.

Format

TRANSMIT-BY-STREAM

STREAM-NAME = <structured-name 1..20>

,VARIABLE-NAME = *NONE / <composed-name 1..255>

,RETURN-VARIABLE-NAME = *SAME / *NONE / <composed-name 1..255>

,CONTROL-VAR-NAME = *NONE / <composed-name 1..255>

,RET-CONTROL-VAR-NAME = *SAME / *NONE / <composed-name 1..255>

Operandenbeschreibung

STREAM-NAME = <structured-name 1..20>
Name des S-Variablenstroms, in dem die Variable übertragen wird.

VARIABLE-NAME =
Bei der Übertragung gesendete S-Variable (Output-Variable).

VARIABLE-NAME = *NONE
Es wird keine S-Variable übertragen.
Wenn der Variablenstrom einer Variable zugewiesen wird, bleibt die zugewiesene S-Variable unverändert.

VARIABLE-NAME = <composed-name 1..255>
Name der S-Variable, die zum Server gesendet wird.
Die angegebene S-Variable muss eine Struktur sein, die alle Daten enthält, die vom Client gesendet werden müssen. Wenn eine leere S-Variable angegeben und der Variablenstrom zu *VARIABLE(...) zugewiesen wird, wird ein leeres Listenelement erzeugt.

RETURN-VARIABLE-NAME =
Name der Return-Variable bei der Übertragung.

RETURN-VARIABLE-NAME = *SAME
Die Return-Variable ist die gesendete S-Variable.
Zuerst wird die übertragene S-Variable zum Server geschrieben, danach wird sie mit den Return-Informationen vom Server überschrieben.
Z.B. wenn der S-Variablenstrom zu *VARIABLE(...) zugewiesen wird, wird die übertragene Variable zuerst zur S-Variable (Liste) geschrieben, die im Kommando ASSIGN-STREAM im Operanden VARIABLE-NAME angegeben ist, danach wird sie durch die S-Variable (Liste) überschrieben, die bei RETURN-VARIABLE-NAME angegeben ist.

RETURN-VARIABLE-NAME = *NONE
Es wird vom Client keine Return-Variable zurückerwartet.
Wenn der S-Variablenstrom zu *VARIABLE(...) zugewiesen wird, wird die angegebene Return-Variable (Listenelement) jedoch behandelt, als ob eine Return-Variable in TRANSMIT-BYSTREAM angegeben würde.

RETURN-VARIABLE-NAME = <composed-name 1..255>
Name der S-Variable, die die Daten enthält, die vom Server nach Ausführung von TRANSMIT-BY-STREAM zurückgesendet werden.
Bei RETURN-VARIABLE-NAME =VARIABLE-NAME wird dasselbe durchgeführt wie bei RETURN-VARIABLE-NAME = *SAME.
Wenn der Server keine RETURN-VARIABLE zurücksendet, ist die Variable nicht geändert worden.

CONTROL-VAR-NAME =
Gibt die Kontroll-Informationen für den Server an.
Diese Information wird von einem Standard Header identifiziert, dessen Format und Aufbau nach der Beschreibung der Kommando-Returncodes aufgelistet ist.
Die Art und Weise dieser Kontroll-Information wird von den möglichen Servern bestimmt. Die Kontroll-Information ist nicht Teil der Benutzerdaten. Es sind für diesen Prozess beim Server eigene Feldnamen reserviert: z.B. definiert das Subsystem FHS (TPR-Anzeige) Variablen, die u.a. die Panels bestimmen, die geladen werden müssen und in denen FHS seine Aktionen ausführt.

CONTROL-VAR-NAME = *NONE
Es ist keine Kontroll-Variable angegeben.
Wenn der Server Kontroll-Variablen benötigt, werden entweder (wenn möglich) die Stan-dard-Variablen benutzt oder die Übertragung wird abgewiesen.

CONTROL-VAR-NAME = <composed-name 1..255>
Name der S-Variable, die die Kontroll-Informationen enthält. Die angegebene S-Variable muss eine Struktur sein.

Hinweis

Wenn der Server eine Kontroll-Variable fordert, und es wurde vom Aufrufer keine oder nur eine unvollständige angegeben, gibt es zwei mögliche Ergebnisse der Übertragung:

1. Wenn die fehlende Kontroll-Information für den steuernden Server optional ist, wird die Übertragung mit der Voreinstellung vorgenommen.

2. Wenn die fehlende Kontroll-Information für den steuernden Server obligatorisch ist, wird die Übertragung mit einer Fehlermeldung abgebrochen.

RET-CONTROL-VAR-NAME =
Gibt die S-Variable an, von der Return-Kontroll-Informationen zum Client geschickt werden können.

RET-CONTROL-VAR-NAME = *SAME
Es wird dieselbe S-Variable wie bei CONTROL-VAR-NAME angegeben.
Es gelten dieselben Regeln wie bei gleichzeitiger Angabe von VARIABLE-NAME und RETURN-VARIABLE-NAME.

RET-CONTROL-VAR-NAME = *NONE
Es werden keine Return-Kontroll-Informationen vom Client erwartet.

RET-CONTROL-VAR-NAME = <composed-name 1..255>
Name der S-Variable, durch die Return-Kontroll-Informationen vom Server übertragen werden. Die angegebene S-Variable muss eine Struktur sein.
Wenn der Server keine RET-CONTROL-VARIABLE zurücksendet, ist die Variable nicht geändert worden.

Kommando-Returncode

(SC2)	SC1	Maincode	Bedeutung
	0	CMD0001	Ohne Fehler
1	0	CMD0001	Variablenstrom ist *DUMMY zugewiesen; keine Übertragung, Variable bleibt unverändert
2	0	SDP0512	Server ist nicht länger aktiv. Datenstrom ist *DUMMY zugewiesen
2	0	SDP0531	Warnung vom Server; Prozess wird fortgesetzt
	1	CMD0202	Syntaxfehler
	3	CMD2203	Falsche Syntaxdatei
	32	CMD0221	Systemfehler (interner Fehler)
	64	CMD0216	Erforderliches Privileg fehlt
	64	SDP0091	Semantikfehler garantierte Meldungen: SDP1008
	64	SDP0532	Server-Fehler; Kommando abgewiesen
	64	SDP0534	Interner Server-Fehler; Kommando abgebrochen. Server-Verbindung abgebrochen nach unerwartetem Ereignis oder bei mangelhaften oder fehlenden System-Ressourcen
	64	SDP0517	Variablenstrom existiert nicht
	64	SDP0522	Übertragene Daten inkompatibel zum Format, das der Server bearbeitet
	64	SDP1132	Variablenname zu lang
	130	SDP0099	Kein Adressraum mehr verfügbar

Hinweis

Beim Returncode SDP0512 muss berücksichtigt werden: Wenn S-Variablenströme, die von der Aufruf-Prozedur abhängig sind, zu prozedurlokalen Variablen zugewiesen werden, können sie nach Prozedurende nicht mehr benützt werden. Die darauf folgende Übertragung wird mit einer Warnung ignoriert und der S-Variablenstrom wird auf *DUMMY zurückgesetzt.

Beispiel

/DECLARE-VARIABLE OPS-VAR(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST
/DECLARE-VARIABLE OPS-VAR1(TYPE=*STRUCTURE)
/ASSIGN-STREAM SYSINF,TO=*VARIABLE(OPS-VAR)
/ASSIGN-SYSOUT TO=#ERROR-SYSOUT
/TRANSMIT-BY-STREAM SYSINF, VARIABLE=OPS-VAR1, RETURN-VARIABLE=*NONE

Standard Header

SDF-P liefert einen Standard Header als ein reserviertes Strukturlayout. Dieser Standard Header kann als erstes Element der Kontroll-Variablenstruktur definiert werden.

Sein Layout ist in einer Prozedur deklariert, die mit INCLUDE-PROCEDURE aufgerufen werden muss.

Diese Prozedur steht im Element FHDR in der (ausgelieferten) Bibliothek $TSOS.SYSPRC.SDF-P-BASYS.024, und sieht folgendermaßen aus:

/set-proc-options "caller=include    not supported by sdf-p-basys"
/begin-parameter-declaration 
/   declare-parameter -
/   "------------ std param --------------------------------*"-
/(PREFIX                       (init='SYSSDP') -
                /,INCLUDE-FORM (init='LAYOUT') "/INITIALIZE" -
                /,VARIABLE-NAME(init='') -
/   "------------ include specific param -------------------*"-
/,UNIT                         (init='') -
                /,FUNCTION     (init='') -
                /,VERSION      (init=0) -
                /,SUBCODE2     (init=0) -
                /,SUBCODE1     (init=0) -
                /,MAINCODE     (init='CMD0001') -
                /)
/end-parameter-declaration 
/
/if (not is-sdf-p() )
/   exit-procedure error=*yes(subcode1=41,maincode=cmd2241)
/end-if
/
/if (upper-case(INCLUDE-FORM) == 'LAYOUT')
/
/begin-structure name=&PREFIX.IFID-MDL,scope=proc
/  declare-element -
                  /(UNIT      (type=string) -
                  /,FUNCTION  (type=string) -
                  /,VERSION   (type=integer) -
                  /)
/end-structure
/begin-structure name=&PREFIX.RETC-MDL,scope=proc
/  declare-element -
                  /(SUBCODE2 (type=integer) -
                  /,SUBCODE1 (type=integer) -
                  /,MAINCODE (type=string)  -
                  /)
/end-structure
/begin-structure name=&PREFIX.FHDR,scope=proc
/  declare-element INTERFACE-ID(type=structure(&PREFIX.IFID-MDL))
/  declare-element RETURNCODE  (type=structure(&PREFIX.RETC-MDL))
/end-structure
/
/else-if (upper-case(INCLUDE-FORM) == 'INITIALIZE')
/
/   if (VARIABLE-NAME == '')
/      write-text '%  mandatory parameter variable-name missing.'
/      raise-error
/   end-if
/   declare-variable PARAM(type=string)
/   for PARAM = ('UNIT','FUNCTION')
/      &VARIABLE-NAME..INTERFACE-ID.&PARAM = &PARAM
/   end-for
/   &VARIABLE-NAME..INTERFACE-ID.VERSION = INTEGER(VERSION)
/   for PARAM = ('SUBCODE2','SUBCODE1')
/      &VARIABLE-NAME..RETURNCODE.&PARAM = INTEGER(&PARAM)
/   end-for
/   &VARIABLE-NAME..RETURNCODE.MAINCODE = MAINCODE
/
/else
/  write-text '%  form=&INCLUDE-FORM not supported; include aborts'
/  raise-error
/end-if
/exit-procedure

UNIT (TYPE = *STRING)Beschreibung der Prozedurparameter
Name des Servers, der die Kontroll-Variable definiert. Dieser Name sollte identisch mit dem bei ASSIGN-STREAM definierten Namen sein..

FUNCTION (TYPE = *STRING)
Name der Funktion, für die der Server das Kontroll-Variablen-Layout definiert hat. Dieser Name wird vom Server definiert und weitergereicht.

VERSION (TYPE = *INTEGER)
Version der Kontroll-Variablen. Frühere Versionen der Kontroll-Variablen können so kompatibel vom Server unterstützt werden.

SUBCODE2 (TYPE = *INTEGER)
Subcode2, der vom Server zurückgegeben wird (in RET-CONTROL-VAR-NAME).

SUBCODE1 (TYPE = *INTEGER)
Subcode1, der vom Server zurückgegeben wird (in RET-CONTROL-VAR-NAME).

MAINCODE (TYPE = *STRING)
Message-Id, die vom Server zurückgegeben wird (in RET-CONTROL-VAR-NAME).

Die Operanden SUBCODE2, SUBCODE1 und MAINCODE haben dieselbe Konvention wie der Kommando-Returncode.

Der Router (TRANSMIT-BY-STREAM und TRANSVV) benützt diese Variablen nicht. Warnungen oder Fehlermeldungen von TRANSMIT-BY-STREAM und TRANSVV hängen vom internen Returncode ab, der vom Server und nicht über diese Kontroll-Variablen zurückgegeben wird.

Diese Kontroll-Variablen sollen deswegen vom Server zurückgegeben werden, um genauere Fehlermeldungen als die von TRANSMIT-BY-STREAM und TRANSVV zu erhalten.

Hinweis

Die Fehler und Warnungen, die in diesen Kontroll-Variablen geschrieben werden, sollen mit dem internen Returncode des Servers übereinstimmen. Das bedeutet z.B., wenn TRANSMIT-BY-STREAM die Fehlerklasse SUBCODE2=0,SUBCODE1=64 und MAINCODE=SDP0532 zurückgibt, auch in der Return-Kontroll-Variablen ein Fehlercode enthalten ist; oder wenn SUBCODE2=2,SUBCODE1=0 und MAINCODE= SDP0531 zurückgegeben wird, soll in der Return-Kontroll-Variablen (auch) eine Warnung enthalten sein usw. Diese Konsistenz untersteht allerdings der Verantwortung des Servers.