DELETE directive

Deletes the attributes and values of structures.

Options

REDEFINE = string token	Whether or not to delete the attributes of the structures so that the type etc can be redefined (yes, no); default no
LIST = string token	How to interpret the list of structures (inclusive, exclusive, all); default incl
PROCEDURE = string token	Whether the list of identifiers is of procedures instead of data structures (yes, no); default no
NSUBSTITUTE = scalar	Number of times n to substitute a dummy in order to determine which structure to delete; default * i.e. full substitution
REMOVE = string token	Whether or not to remove the structures from Genstat completely i.e. to delete their identifiers as well as their attributes and values (yes, no); default no

Parameter

identifiers	Structures whose values (and attributes, if requested) are to be deleted

Description

The DELETE directive allows values and attributes of data structures to be deleted so that Genstat can recover the space that they occupy. This may also make the program execute more efficiently as Genstat will then need to keep track of less information. By default only the values are deleted but, if the REDEFINE option is set to yes, the attributes of the structures are also deleted. The only information that is still stored is then the identifier and the internal reference number of the structure. Alternatively, you can set option REMOVE=yes to delete the identifier and reference number as well as the attributes and values, so that no trace of the structure remains.

You may want to delete the attributes merely to save further space. However, the main advantage is that the structures can then be redefined to be of different types.

For example, suppose we have defined a variate Dose by

VARIATE [VALUES=0,0,2,2,4,4] IDENTIFIER=DoseThis gives Dose the values 0, 0, 2, 2, 4 and 4. If we then put

DELETE Doseonly the values of Dose are deleted; so we could now assign a new set: for example

READ Dose

2 4 0 4 2 0 :Dose remains a variate but now has the values 2, 4, 0, 4, 2 and 0.

Alternatively, if we set REDEFINE=yes in the above example, we could then redefine Dose as (for example) a text with seven values.

DELETE [REDEFINE=yes] Dose

TEXT [VALUES=none,double,standard,double,\

  none,standard,none] Dose

Once you have defined the type of a structure in a job (as variate, factor or whatever), you cannot redeclare it as a structure of any other type unless you have first used DELETE to delete its values and attributes. The only exception to this rule is that the GROUPS directive also has a REDEFINE option, which allows a variate or text to be redefined as a factor.

The LIST option defines how the parameter list is to be interpreted. With the default setting, LIST=inclusive, attributes or values are deleted only for the structures in the list. LIST=exclusive means that the parameter list is the complement of the set of structures that are deleted: that is, all named structures that are not in the list are deleted. LIST=all causes the attributes or values of all structures to be deleted. Thus, if LIST=all, any parameter list is ignored; and LIST=exclusive with no parameter is equivalent to LIST=all.

The NSUBSTITUTE option is relevant when the list of structures to delete contains dummies. The default setting, missing value, requests all dummies to be replaced by the structures to which they point (so that those are the structures that are deleted). NSUBSTITUTE allows you to delete dummies instead. If you set NSUBSTITUTE=0, no dummies are substituted. So the deleted structures are the actual dummies that you have listed. A positive setting n>0 is useful if you have dummies pointing to other dummies, in a chain. Each dummy in the list is then substituted n times in order to determine which structure in each chain to delete.

Each time that DELETE is used, Genstat will also remove any unnamed structures that are no longer required and recover any space that has been used for temporary storage. This sort of tidying of workspace will happen automatically if Genstat sees in time that the space is becoming short. However, to avoid unnecessary computation, this does not occur after every statement. Thus, if the space appears to be exhausted, it may be worth using DELETE, even if you have no named structures to delete.

Options: REDEFINE, LIST, PROCEDURE, NSUBSTITUTE, REMOVE.

Parameter: unnamed.

See also

Commands for: Data structures, Calculations and manipulation.

Example

" Example STOR-1: simple storage and retrieval

  Store the yield of forage from an experiment to determine the
  effects of cutting and of sulphate of ammonia.
  First set up factors and yield with associated heading.  "

VARIATE PLOTS; VALUES=!(1...32); DECIMALS=0
UNIT PLOTS
FACTOR [LABELS=!T('JUN(11)','JUL(1)','JUL(22)','AUG(12)')] CUTDATE
FACTOR [LEVELS=!(0.0,0.3)] NITROGEN
VARIATE YIELD; DECIMALS=2; EXTRA=' OF FORAGE '

" Read CUTDATE,NITROGEN AND YIELD."
OPEN '%gendir%/examples/STOR-1.DAT'; CHANNEL=2; FILETYPE=input
READ [CHANNEL=2] PLOTS,CUTDATE,NITROGEN,YIELD; FREP=ordinal,label,level,ordinal
CLOSE 2; FILETYPE=input

" Tabulate YIELD in table TYIELD classified by CUTDATE and NITROGEN"
TABULATE [CLASSIFICATION=CUTDATE,NITROGEN; MARGINS=YES]YIELD; TOTAL=TYIELD

" Open a new backing-store file."
OPEN   'STOR-1.GBS'; CHANNEL=1; FILETYPE=backingstore

" Store the table TYIELD and all the structures that its
  definition depends on (such as CUTDATE and YIELD)"
STORE [CHANNEL=1] IDENTIFIER=TYIELD

" List subfiles in file STOR-1.BAC"
CATALOGUE [CHANNEL=1; LIST=ALL]

" Delete TYIELD and other structures and show that they are no longer present"
DELETE [REDEFINE=YES; LIST=ALL] 
LIST ALL

" Retrieve the table TYIELD from the file, and show that it is back."
RETRIEVE [CHANNEL=1] IDENTIFIER=TYIELD
LIST TABLE

" Select some data from what has been retrieved, and
  display just the subset."
RESTRICT YIELD; CUTDATE.IN.'JUN(11)'
PRINT PLOTS,CUTDATE,YIELD; 10

" Close and delete the backing-store file."
CLOSE CHANNEL=1; FILETYPE=backingstore; DELETE=yes