To store structures in a subfile of a backing-store file.
|What to print (catalogue); default
||Channel number of the backing-store file where the subfile is to be stored; default 0, i.e. the workfile|
||Identifier of the subfile; default
||How to interpret the list of structures (inclusive, exclusive, all); default
||How to append the subfile to the file (
||Password to be stored with the file; default
||Whether subfile contains procedures only (
||Whether to list unnamed structures (
||Whether or not to merge the structures with the existing contents of the subfile (
||Identifiers of the structures to be stored|
||Identifier to be used for each structure when it is stored|
STORE directive allows you to store data structures or procedures in a backing-store file. The file can be opened using the
OPEN directive, and there is also a backing-store workfile attached to channel 0 which is automatically deleted at the end of a Genstat run.
Each backing-store file contains a number of subfiles. Each subfile starts with a catalogue, recording which structures it stores. Then come the attributes and the values of each data structure. A subfile name can be either an unsuffixed identifier or a suffixed identifier with a numerical suffix. The identifiers of subfiles are kept in a separate catalogue to the identifiers of data structures, so you do not need to worry about keeping the identifiers of data structures and subfiles distinct. However, if you use a suffixed identifier for a subfile,
Sub say, you cannot also use the identifier
Sub. There are two types of subfiles. Ordinary subfiles can hold any type of structures except procedures; procedure subfiles hold only procedures (and their dependent structures).
Whenever you store a structure in a subfile, Genstat automatically stores also all the associated structures to which it points. If these associated structures also point to further structures, then they are stored too, and so on. Some of the structures may be unnamed and some structures may be system structures. For example
TEXT [VALUES=A,B,C] T
FACTOR [LABELS=T; VALUES=1...3] F
creates a subfile containing factor
F. The complete definition of factor
F depends on text
T to supply level names. So
T is stored too. The text
T depends on a system structure (indicating the length of each line), which is therefore also stored. Hence to save factor
F, Genstat has actually saved three structures. However, this is all automatic, so you do not need to worry about any of the details of the system structures.
When you store a structure with a suffixed identifier, Genstat may have to set up a series of pointer structures if they are not already present. An example is:
VARIATE [VALUES=1,2] V[1,2]
STORE [PRINT=catalogue] V
The first line sets up a pointer structure
V, pointing to
V. To store variate
V, a pointer structure
V has to be set up in the subfile, pointing to
V only. Thus two structures are saved on backing store, namely
V. The original pointer
V in the program is left unchanged. (If the example had stored the whole of
V, no such complications would have arisen.)
The structures to be stored are specified by the
IDENTIFIER parameter. The
CHANNEL option indicates the backing-store file to use, and the
SUBFILE option specifies the subfile that is created. Both these options can be omitted; by default the file will be the workfile, and the subfile will be called
SUBFILE. The structures that are stored in the subfile are merely copies of the structures in the job, so the original structures remain available for further use within the job.
STOREDIDENTIFIER parameter allows you to give a structure a different name within the subfile: For example,
VARIATE [VALUES=10.2,15.3,21.4,16.8,22.3] Weight
STORE Weight; STOREDIDENTIFIER=WtWeek2
stores a structure with identifier
Weight within Genstat as a structure with identifier
WtWeek2 in the backing-store file. If you want to rename only some of the structures, you can either respecify the existing identifier, or insert
* at the appropriate point in the list. For example, you could store
Y, renaming only
STORE X,Y; STOREDIDENTIFIER=X,Yy
STORE X,Y; STOREDIDENTIFIER=*,Yy
You can give an unnamed structure in the list of either parameter. For example
STORE !(10.2,15.3,21.4,16.8,22.3); STOREDIDENTIFIER=WtWeek2
But of course you will not be able to retrieve any structure that has been stored as an unnamed structure (except perhaps as a dependent structure of another structure).
All the structures in a subfile must have distinct identifiers, and Genstat will report a fault if you try to give two the same name. You thus need to be careful if you are storing structures inside a procedure, as the same identifier can be used for one structure within the procedure, and for another one outside; you cannot store both in the same subfile.
Procedures that have been retrieved automatically from libraries cannot be stored by
You can set option
PRINT=catalogue to obtain a catalogue of the subfiles in the backing-store file, and of the structures in the subfile just created. If you also set option
UNNAMED=yes Genstat will also list any unnamed structures, with details of how they depend on each other.
LIST option controls how the
IDENTIFIER list is interpreted. The default setting
inclusive simply stores the structures that have been listed.
Alternatively, if you set
LIST=all Genstat will store all the structures in the current job that have identifiers and whose types have been defined. If the statement is inside a procedure, then only the structures defined within the procedure are stored. If you are storing procedures, then this setting will store all procedures that you have created explicitly in this job, by
Finally, you can set
LIST=exclusive to store everything that you have not included in the
IDENTIFIER parameter: that is, all the other named structures that are currently accessible, or all the other procedures that have been created in this job. Note, though, that some of the structures in the
IDENTIFIER list may be stored if they are needed to complete the set of structures to be stored. If you use this setting, the
STOREDIDENTIFIER parameter is ignored. For example
TEXT [VALUES=a,b] T
FACTOR [LABELS=T] F
TEXT [VALUES='variate text'] Vt
VARIATE V; EXTRA=Vt
creates four named structures,
Vt. The statement
STORE [LIST=inclusive] T
stores the text
stores all the four structures that have identifiers;
STORE [LIST=exclusive] F,T
STORE [LIST=exclusive] Vt,T
results in all four structures being saved, because
V points to
F points to
If a subfile of the specified name already exists on the backing-store file, the storing operation will usually fail. You can then set option
METHOD=overwrite to overwrite the old subfile, that is, to replace the old subfile with a new subfile; alternatively, you can put
METHOD=replace to form a new backing-store file containing only the new subfile. Setting
METHOD=update adds new structures to an existing subfile. The
MERGE option then controls what happens if a data structure that is being added to the file is already present; by default it overwrites the previous version but, if you put
MERGE=yes, only new structures are added to the file.
To make your files secure, you can specify a password using the
PASSWORD option. Once you have done this, you must include the same password in any future use of
MERGE with this same userfile; spaces, case and new lines are significant in the password. You cannot change the password in a userfile once you have set it, but you can use the
MERGE directive to create a new userfile with no password or with a new password. If you set the password to be a text whose values have been restricted, the restriction is ignored.
PROCEDURE option indicates whether the subfile is to store procedures (
PROCEDURE=yes), or ordinary data structures.
Commands for: Input and output.
" 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