Domain: PROCEDURE
Command description
The FREE-VARIABLE command deletes the contents of one or more S variables.
Read access to the variables is impossible after calling FREE-VARIABLE since the variables do not have valid contents any more. The variable declarations are not deleted, however, by this command. The only exception to this are variables with a dynamic structure.
The FREE-VARIABLE command can be used on simple and composed variables. One or more elements can be deleted from list variables with this command. For variables with a dynamic structure, not only the contents are deleted, but also the element itself.
If the S variable is linked to a variable container of type JV, then the variable container (i.e. the job variable) can also be deleted. However, write access to the variable is not possible anymore.
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 |
Operands
VARIABLE-NAME =
Specifies the variable whose content is to be deleted.
VARIABLE-NAME = <structured-name 1..20 with-wild(40)>
Deletes the content of the variables whose names match the specified search pattern.
VARIABLE-NAME = *LIST(...)
Deletes the contents of elements in a list variable.
LIST-NAME = <composed-name 1..255>
Name of the list variable.
FROM-INDEX = *FIRST / *LAST / <integer 1..2147483647>
Index of the element of the list variable starting at which the specified number of list elements are to be deleted.
*FIRST: The deletion process starts with the first element of the list (default).Specifying *LAST causes the last element in the list to be deleted. In this case the NUMBER-OF-ELEMENTS operand is ignored.
NUMBER-OF-ELEMENTS = 1 / *REST / <integer 1..2147483647>
Number of list elements to be deleted.
Default value: One element will be deleted.
Specifying *REST causes all elements to be deleted from the specified start element (FROM-INDEX operand) to the last element in the list.
VARIABLE-NAME = list-poss(2000): <composed-name 1..255>
Deletes the contents of simple or composed variables which are contained in the specified names list.
DESTROY-CONTAINER-JV = *NO / *YES
You can define whether or not a job variable linked to the S variable as a variable container is to be deleted. After deleting the job variable, the S variable cannot be write-accessed anymore.
If the variable is not linked to a variable container of type JV, then the operand is ignored.
Rules for deleting list variables and other composed variables
If a name designates a composed variable, then the contents of all variable elements are deleted. The attributes of the composed variables (TYPE, SCOPE,...) are still valid, however. Newly created elements of this variable must correspond to those of the original declaration.
Example
/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
If a name designates a dynamic structure, then all element declarations are deleted and removed.
Example
/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
If the elements of a composed variable are dynamic structures, then the information “element is of TYPE = *STRUCTURE(*DYNAMIC)” is retained (the elements of the dynamic structure itself are deleted and removed).
If the elements are statically structured, then the declaration of the structure layout remains valid. The same is also true for lists.Example
/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
If the composed variable that the FREE-VARIABLE command is applied to is an element of a dynamic structure, then all its elements and the composed variable itself are deleted. This means that explicitly declared arrays, list variables and static structures can also be deleted. If such composed variables with the same properties are to be reproduced, then they must be redeclared.
Example
/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
List variables are renumbered after elements are deleted so that the numbering is continuos starting with 1.
Example
/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
Command return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
| 0 | CMD0001 | No error | |
| 1 | 0 | CMD0001 | Warning: no elements deleted; variable has already been deleted |
| 1 | CMD0202 | Syntax error | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | SDP0091 | Semantic error Guaranteed messages: SDP1008 | |
| 130 | SDP0099 | No further address space available |
Examples
/DECLARE-VARIABLE B(100,*INTEGER), SCOPE=*PROCEDURE /FREE-VARIABLE B /B = 33 /FREE-VARIABLE B —————————————————————————————————————————————————————— (1) /SHOW-VARIABLE B —————————————————————————————————————————————————————— (2)
(1) | The FREE-VARIABLE command deletes the value. After that, variable B can only be write-accessed. |
(2) | No output since the variable does not have a valid value anymore. |
Deletion with wildcards specified
/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
Deletion with list elements
/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) | FROM-INDEX=*LAST in the FREE-VARIABLE command deletes the last element in the list T-LIST. |
(2) | The SHOW-VARIABLE command displays the 6 elements still remaining in the list. |
(3) | 2 elements in the list are to be deleted starting at the 4th element. |
(4) | The SHOW-VARIABLE command displays the 4 elements still remaining in the list. Elements 4 and 5 which previously existed are no longer present. |