To store structures in a subfile of a backing-store file.
Options
PRINT = string token |
What to print (catalogue); default * |
|---|---|
CHANNEL = scalar |
Channel number of the backing-store file where the subfile is to be stored; default 0, i.e. the workfile |
SUBFILE = identifier |
Identifier of the subfile; default SUBFILE |
LIST = string token |
How to interpret the list of structures (inclusive, exclusive, all); default incl |
METHOD = string token |
How to append the subfile to the file (add, overwrite, replace, update); default add, i.e. clashes in subfile identifiers cause a fault (note: replace overwrites the complete file) |
PASSWORD = text |
Password to be stored with the file; default * |
PROCEDURE = string token |
Whether subfile contains procedures only (yes, no); default no |
UNNAMED = string token |
Whether to list unnamed structures (yes, no); default no |
MERGE = string token |
Whether or not to merge the structures with the existing contents of the subfile (yes, no); default no |
Parameters
IDENTIFIER = identifiers |
Identifiers of the structures to be stored |
|---|---|
STOREDIDENTIFIER = identifiers |
Identifier to be used for each structure when it is stored |
Description
The 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[1] 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
STORE 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[1]
The first line sets up a pointer structure V, pointing to V[1] and V[2]. To store variate V[1], a pointer structure V has to be set up in the subfile, pointing to V[1] only. Thus two structures are saved on backing store, namely V and V[1]. 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.
The 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 X and Y, renaming only Y as Yy, by
STORE X,Y; STOREDIDENTIFIER=X,Yy
or by
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 STORE.
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.
The 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 PROCEDURE or RETRIEVE statements.
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, T, F, V and Vt. The statement
STORE [LIST=inclusive] T
stores the text T;
STORE [LIST=all]
stores all the four structures that have identifiers;
STORE [LIST=exclusive] F,T
stores Vt and V; and
STORE [LIST=exclusive] Vt,T
results in all four structures being saved, because V points to Vt, and F points to T.
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 STORE or 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.
The PROCEDURE option indicates whether the subfile is to store procedures (PROCEDURE=yes), or ordinary data structures.
Options: PRINT, CHANNEL, SUBFILE, LIST, METHOD, PASSWORD, PROCEDURE, UNNAMED, MERGE.
Parameters: IDENTIFIER, STOREDIDENTIFIER.
See also
Directives: RETRIEVE, CATALOGUE, MERGE, OPEN, RECORD, RESUME.
Commands for: Input and output.
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