Retrieves structures from a subfile.
Options
CHANNEL = scalar |
Specifies the channel number of the backing-store or procedure-library file containing the subfile (FILETYPE settings 'back' or 'proc'); default 0 (i.e. the workfile) for FILETYPE=back, no default for FILETYPE=proc, not relevant with other FILETYPE settings |
|---|---|
SUBFILE = identifier |
Identifier of the subfile; default SUBFILE |
LIST = string token |
How to interpret the list of structures (inclusive, exclusive, all); default incl |
MERGE = string token |
Whether to merge structures with those already in the job (yes, no); default no, i.e. a structure whose identifier is already in the job overwrites the existing one, unless it has a different type |
FILETYPE = string token |
Indicates the type of file from which the information is to be retrieved (backingstore, procedurelibrary, siteprocedurelibrary, Genstatprocedurelibrary); default back |
Parameters
IDENTIFIER = identifiers |
Identifiers to be used for the structures after they have been retrieved |
|---|---|
STOREDIDENTIFIER = identifiers |
Identifier under which each structure was stored |
Description
You can recover information from a subfile of a backing-store file using the RETRIEVE directive. The CHANNEL option specifies the backing-store file, and the SUBFILE option indicates the subfile. Both these options can be omitted; by default the file will be the workfile, and the subfile will be called SUBFILE.
When you retrieve a structure Genstat may also retrieve a chain of associated structures: that is, all the structures to which it points, and the structures to which they point, and so on. For example, suppose you store the three structures with identifiers T, V and F, along with an unnamed structure storing information about T, in a subfile called SUBFILE in backing-store file FILE1:
OPEN 'FILE1'; CHANNEL=1; FILETYPE=backingstore
TEXT [VALUES=a,b,c] T
VARIATE V; EXTRA=T
FACTOR [LABELS=T] F
STORE [CHANNEL=1] T,V,F
Then the statement
RETRIEVE [CHANNEL=1] V
will retrieve not only V but also T (which was associated with T by the EXTRA parameter of the VARIATE statement), and the unnamed structure that is associated with T. The structures V, T and the unnamed structure, are said to be a complete set from the subfile.
The IDENTIFIER parameter specifies the structures to be retrieved. You can use the STOREDIDENTIFIER parameter to give a structure a different name from the one within the subfile. For example
RETRIEVE IDENTIFIER=Weeks; STOREDIDENTIFIER=Time
You are not allowed to give identical identifiers to two retrieved structures, nor are you allowed to have the same identifier referring to a structure of one type in a subfile, and to a structure of a different type in your job.
As with STORE, 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 STOREDIDENTIFIER list.
Genstat knows whether you are retrieving a procedure by the type of file that you are accessing, as set by the FILETYPE option. You are not allowed to rename a procedure as a suffixed identifier or as the name of a directive.
You can even rename a structure so that it is unnamed in the job. Suppose, for example, that a structure T already exists within Genstat, and that you want to retrieve the variate V stored in the file FILE1 above. Then, as we have seen, the structure T will also be retrieved. However, you can avoid the existing structure T in the job being overwritten by making the retrieved version of T unnamed:
OPEN 'FILE1'; CHANNEL=1; FILETYPE=backingstore
RETRIEVE [CHANNEL=1] V,!T(a); STOREDIDENTIFIER=V,T
The value, a, of the unnamed text !T(a) will be replaced by the values stored for T, and this unnamed text will become the EXTRA text for V. Alternatively you could rename T to be Tnew by
RETRIEVE [CHANNEL=1] V,TNew; STOREDIDENTIFIER=V,T
When you are retrieving a suffixed identifier, Genstat matches the numerical suffix only, and not the whole structure that is denoted by the identifier. For example, suppose pointer P stored in a subfile points to structures with identifiers A, B, C and D, and that P has numerical suffixes 1 to 4 respectively. Also suppose that in your current job, you have never mentioned pointer P either directly or indirectly. Then the statement
RETRIEVE [CHANNEL=1] P[2]
will retrieve the structure B from backing store but, as it has not been referenced only as P[2] in the RETRIEVE statement, the identifier B will not be recovered and it will be known only as P[2] within Genstat.
A structure that you are retrieving from a subfile may sometimes overwrite the values of an existing structure in your program. If this structure is a pointer or a compound structure, the existing suffixes will be overwritten by those of the stored structure, so some existing structures with suffixed identifiers may in effect be lost. For example, suppose that userfile FILE2 contains a pointer P, with suffixes 1 and 2 pointing to structures A and B. If we set up a variate P[3], and then retrieve the pointer P
OPEN 'FILE2'; CHANNEL=1; FILETYPE=backingstore
VARIATE [VALUES=1...6] P[5,6,7]
RETRIEVE [CHANNEL=1] P
P will now have suffixes 1 and 2 pointing to A and B, but the variate P[3] will have been lost.
The LIST option controls how the IDENTIFIER list is interpreted. The default setting inclusive simply retrieves the structures that have been listed. Alternatively, if you set LIST=all Genstat will retrieve all the structures in the subfile that have identifiers and whose types have been defined. Finally, you can see LIST=exclusive to retrieve everything in the subfile that you have not listed in the IDENTIFIER parameter. Note, though, that some of the structures in the IDENTIFIER list may be retrieved if they are needed to complete the set of structures to be retrieved. If you use this setting, the STOREDIDENTIFIER parameter is ignored.
The FILETYPE option specifies whether you wish to retrieve information from backing store files that have been attached as normal backing store files or as procedure libraries by the OPEN directive, or from Genstat Procedure library or from the site procedure library. The CHANNEL setting is ignored if the siteprocedurelibrary or Genstatprocedurelibrary settings are used. The source code of the procedures in the Genstat Procedure library can be accessed using the LIBEXAMPLE procedure.
Normally when you retrieve a complete subset of structures, Genstat overwrites all structures in the job that have the same identifier (after any renaming). As a result, some other structures already in the job may become inconsistent and will be destroyed. You can avoid this happening by setting the MERGE option to yes. Genstat then does not overwrite any structures with the same name and type. However, a consequence is that some of the retrieved structures may now be inconsistent and thus need to be destroyed in the program (although they will of course remain in the subfile).
Options: CHANNEL, SUBFILE, LIST, MERGE, FILETYPE.
Parameters: IDENTIFIER, STOREDIDENTIFIER.
See also
Directives: STORE, 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