RETRIEVE directive

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
How to interpret the list of structures (inclusive, exclusive, all); default incl

MERGE = string
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
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.