Anwendungsgebiet: PROCEDURE
Kommandobeschreibung
Das Kommando FREE-VARIABLE löscht den Inhalt einer oder mehrerer S-Variablen.
Lesezugriff auf die Variable ist nach FREE-VARIABLE nicht mehr möglich, da die Variable keinen gültigen Inhalt mehr hat. Die Deklaration der Variablen bleibt jedoch nach dem Löschen erhalten – mit Ausnahme von Variablen mit dynamischer Struktur.
Das Kommando FREE-VARIABLE kann auf einfache und zusammengesetzte Variable angewendet werden. Bei einer Listenvariablen können gezielt ein oder mehrere Elemente gelöscht werden. Bei einer Variablen mit dynamischer Struktur werden nicht nur die Inhalte der Elemente gelöscht, sondern auch die Elemente selbst.
Ist die S-Variable mit einem Variablenbehälter vom Typ JV verknüpft, kann auch der Variablenbehälter (d.h. die Jobvariable) gelöscht werden. Schreibzugriff auf die Variable ist dann nicht mehr möglich.
Format
FREE-VARIABLE |
VARIABLE-NAME = <structured-name 1..20 with-wild(40)> / *LIST(...) / list-poss(2000): <composed-name 1..255> *LIST(...) LIST-NAME = <composed-name 1..255> ,FROM-INDEX = *FIRST / *LAST / <integer 1..214783647> ,NUMBER-OF-ELEMENTS = 1 / *REST / <integer 1..214783647> ,DESTROY-CONTAINER-JV = *NO / *YES |
Operandenbeschreibung
VARIABLE-NAME =
Gibt die Variablen an, deren Inhalt gelöscht werden soll.
VARIABLE-NAME = <structured-name 1..20 with-wild(40)>
Löscht den Inhalt der Variablen, deren Namen dem angegebenen Suchmuster entsprechen.
VARIABLE-NAME = *LIST(...)
Löscht den Inhalt von Elementen einer Listenvariablen.
LIST-NAME = <composed-name 1..255>
Name der Listenvariablen.
FROM-INDEX = *FIRST / *LAST / <integer 1..2147483647>
Index des Elementes der Listenvariablen, mit dem beginnend eine spezifizierte Anzahl von Listenelementen gelöscht werden.
*FIRST: Der Löschvorgang beginnt mit dem ersten Element der Liste; Voreinstellung.Die Angabe *LAST löscht genau das letzte Element der Liste. Der Operand NUMBER-OF-ELEMENTS wird in diesem Fall ignoriert.
NUMBER-OF-ELEMENTS = 1 / *REST / <integer 1..2147483647>
Anzahl der Listenelemente, die gelöscht werden sollen.
Voreinstellung: Ein Element wird gelöscht.
Die Angabe *REST löscht alle Elemente vom angegebenen Startelement (Operand FROM-INDEX) bis zum letzten Element der Liste.
VARIABLE-NAME = list-poss(2000): <composed-name 1..255>
Löscht den Inhalt der einfachen oder zusammengesetzten Variablen, die in der angegebenen Namensliste enthalten sind.
DESTROY-CONTAINER-JV = *NO / *YES
Es kann vereinbart werden, ob eine Jobvariable, die der S-Variable als Variablenbehälter dient, gelöscht werden soll. Auf die S-Variable ist dann kein schreibender Zugriff mehr möglich.
Ist die Variable nicht mit einem Variablenbehälter vom Typ JV verknüpft, so wird der Operand ignoriert.
Regeln für das Löschen von Listen- und anderen zusammengesetzten Variablen
Bezeichnet ein Name eine zusammengesetzte Variable, so werden die Inhalte aller Variablenelemente gelöscht. Die Attribute der zusammengesetzten Variablen (TYPE, SCOPE,...) bleiben jedoch gültig. Neu angelegte Elemente dieser Variablen müssen der ursprünglichen Deklaration entsprechen.
Beispiel
/DECLARE-VARIABLE L(TYPE=*STRING),MULTIPLE-ELEMENT=*LIST /L='ELEM1',WRITE-MODE=*EXTEND /L='ELEM2',WRITE-MODE=*EXTEND /FREE-VARIABLE L &* all elements deleted but declaration remains /SHOW-VARIABLE L &* Nothing displayed /L=3,WRITE-MODE=*EXTEND % SDP1036 VARIABLE TYPE AND VALUE TYPE DO NOT MATCH
Bezeichnet der Name eine dynamische Struktur, so werden alle Elementdeklarationen gelöscht und entfernt.
Beispiel
/DECLARE-VARIABLE S(TYPE=*STRUCTURE(DEFINITION=*DYNAMIC)) /S.ELEM1=1; S.ELEM2='ELEM2'; S.ELEM3 =TRUE; /FREE-VARIABLE S &* all element declarations are deleted /S.ELEM1='ELEM1' &* no type retained, so modification possible
Sind die Elemente einer zusammengesetzten Variablen dynamische Strukturen, bleibt die Information „Element hat TYPE = *STRUCTURE(*DYNAMIC)“ erhalten (die Elemente der dynamischen Struktur selbst werden gelöscht und entfernt).
Falls die Elemente statische Strukturen sind, bleibt aber die Deklaration des Struktur-Layouts gültig. Entsprechendes gilt für Listen.Beispiel
/DCV L1(TYPE=*STRUCTURE(*DYNAMIC)),MULTIPLE-ELEMENT=*LIST /L1#.ELEM1=1; L1#.ELEM2='ELEM2'; L1#.ELEM3=TRUE /FREE-VARIABLE L1# /L1#.ELEM1='ELEM1' &* no type retained, so modification possible / /BEGIN-STRUCTURE S /DECLARE-ELEMENT ELEM1(TYPE=*STRING) /DECLARE-ELEMENT ELEM2(TYPE=*INTEGER) /END-STRUCTURE /DCV L2(TYPE=*STRUCTURE(S)),MULTIPLE-ELEMENT=*LIST /L2#.ELEM1='ELEM1';L2#.ELEM2=2 /FREE-VARIABLE L2# &* Elements deleted but declaration remains /L2#.ELEM1=1 % SDP1036 VARIABLE TYPE AND VALUE TYPE DO NOT MATCH
Ist die zusammengesetzte Variable, auf die das Kommando FREE-VARIABLE angewendet wird, Element einer dynamischen Struktur, werden alle ihre Elemente und die zusammengesetzte Variable selbst gelöscht. So können auch Arrays, Listenvariable oder statische Strukturen gelöscht werden, die explizit deklariert wurden. Sollen solche zusammengesetzten Variablen wieder mit den gleichen Eigenschaften entstehen, müssen sie erneut deklariert werden.
Beispiel
/DCV S(TYPE=*STRUCTURE(*DYNAMIC)) /S.L#.ELEM1=1; S.L#.ELEM2='ELEM2'; S.L#.ELEM3=TRUE; /FREE-VARIABLE S.L /SHOW-VARIABLE S.L
Listenvariablen werden nach dem Löschen von Elementen wieder neu nummeriert, sodass immer eine lückenlose Nummerierung ab 1 besteht.
Beispiel
/DCV L1(TYPE=*INTEGER),MULTIPLE-ELEMENT=*LIST /L1=1,W-M=*EXT; L1=2,W-M=*EXT; L1=3,W-M=*EXT; L1=4,W-M=*EXT; /FREE-VARIABLE L1#2 /SHOW-VARIABLE L1,LIST-INDEX-NUMBER=*YES L1#1 = 1 L1#2 = 3 L1#3 = 4 /DCV L2(TYPE=*INTEGER),MULTIPLE-ELEMENT=*LIST /L2=*STRING-TO-VARIABLE('(1,2,3,4)') /SHOW-VARIABLE L2,LIST-INDEX-NUMBER=*YES L2#1 = 1 L2#2 = 2 L2#3 = 3 L2#4 = 4 /FREE-VARIABLE (L2#1,L2#2) &* Use *LIST syntax to free elem 1 / 2 /SHOW-VARIABLE L2,LIST-INDEX-NUMBER=*YES L2#1 = 2 L2#2 = 4
Kommando-Returncode
| (SC2) | SC1 | Maincode | Bedeutung |
| 0 | CMD0001 | Ohne Fehler | |
| 1 | 0 | CMD0001 | Warnung; keine Elemente gelöscht; Variable ist bereits gelöscht |
| 1 | CMD0202 | Syntaxfehler | |
| 3 | CMD2203 | Falsche Syntaxdatei | |
| 32 | CMD0221 | Systemfehler (interner Fehler) | |
| 64 | SDP0091 | Semantikfehler garantierte Meldung: SDP1008 | |
| 130 | SDP0099 | Kein Adressraum mehr verfügbar |
Beispiele
/DECLARE-VARIABLE B(100,*INTEGER), SCOPE=*PROCEDURE /FREE-VARIABLE B /B = 33 /FREE-VARIABLE B —————————————————————————————————————————————————————— (1) /SHOW-VARIABLE B —————————————————————————————————————————————————————— (2)
(1) | Das Kommando FREE-VARIABLE bewirkt, dass der Wert gelöscht wird; anschließend ist nur noch schreibender Zugriff auf die Variable B möglich. |
(2) | Keine Ausgabe, da die Variable keinen gültigen Wert mehr hat. |
Löschen mit Angabe von Musterzeichen
/TSDP-023-003-0001-1 = ' ALPHA ' /TSDP-023-003-0001-2 = ' BETA ' /TSDP-023-003-0001-3 = ' GAMMA ' /FREE-VAR T<R:T><A:E><N:Q>-02/-*-<1,3> /SHOW-VARIABLE TSDP-023-003-0001-2 = BETA *END-OF-CMD
Löschen mit Listenelementen
/DECLARE-VARIABLE T-LIST (TYPE= *STRING), MULTIPLE-ELEMENTS= *LIST / T-LIST#1 = 'FIRST' / T-LIST#2 = 'SECOND' / T-LIST#3 = 'THIRD' / T-LIST#4 = 'FOURTH' / T-LIST#5 = 'ANTEPENULTIMATE' / T-LIST#6 = 'PENULTIMATE' / T-LIST#7 = 'LAST' /FREE-VARIABLE *LIST (LIST-NAME=T-LIST,FROM-INDEX=*LAST) —————————————— (1) /SHOW-VARIABLE T-LIST ————————————————————————————————————————————————— (2) T-LIST(*LIST) = FIRST T-LIST(*LIST) = SECOND T-LIST(*LIST) = THIRD T-LIST(*LIST) = FOURTH T-LIST(*LIST) = ANTEPENULTIMATE T-LIST(*LIST) = PENULTIMATE /FREE-VARIABLE *LIST(LIST-NAME=T-LIST,FROM-INDEX=4,NUMBER-OF-ELEM= 2 ) (3) /SHOW-VARIABLE T-LIST ————————————————————————————————————————————————— (4) T-LIST(*LIST) = FIRST T-LIST(*LIST) = SECOND T-LIST(*LIST) = THIRD T-LIST(*LIST) = PENULTIMATE
(1) | Mit FROM-INDEX=*LAST im Kommando FREE-VARIABLE soll das letzte Element der Liste T-LIST gelöscht werden. |
(2) | Das Kommando SHOW-VARIABLE zeigt die noch verbleibenden 6 Elemente der Liste an. |
(3) | Ab dem 4. Element sollen 2 Elemente der Liste gelöscht werden. |
(4) | Das Kommando SHOW-VARIABLE zeigt die noch verbleibenden 4 Elemente der Liste an. Die zuvor vorhandenen Elemente 4 und 5 sind nicht mehr vorhanden. |