Displays the contents of a backing-store file.
Options
PRINT = string tokens |
What to print (subfiles, structures); default subf, stru |
|---|---|
CHANNEL = scalar |
Channel number of the backing-store file; default 0, i.e. the workfile |
LIST = string token |
How to interpret the list of subfiles (inclusive, exclusive, all); default incl |
SAVESUBFILE = text |
To save the subfile identifiers; default * |
UNNAMED = string token |
Whether to list unnamed structures (yes, no); default no |
Parameters
SUBFILE = identifiers |
Identifiers of subfiles in the file to be catalogued |
|---|---|
SAVESTRUCTURE = texts |
To save the identifiers of the structures in each subfile |
Description
You can use CATALOGUE to obtain details of the subfiles contained in a backing-store file, or the structures within an ordinary subfile, or the procedures within a procedure subfile. The file is indicated by the CHANNEL option, and the SUBFILE parameter specifies the subfiles (of ordinary structures or of procedures) that are to be catalogued.
The PRINT option specifies which catalogues are to be printed. The subfiles setting prints the catalogue of subfiles in the backing-store file attached to the channel specified by the CHANNEL option, while the structures setting prints the catalogue of structures or procedures that are in the subfiles specified by the SUBFILE parameter. If you set option UNNAMED=yes the unnamed structures in each subfile will also be listed, together with details of how the structures depend on each other.
The LIST option controls how the SUBFILE list is interpreted. The default setting inclusive simply catalogues the subfiles that have been listed. Alternatively, if you set LIST=all Genstat will catalogue all the subfiles in the backing-store file. Finally, you can see LIST=exclusive to catalogue everything that you have not included in the SUBFILE list.
The SAVESTRUCTURE parameter allows you to set up texts, one for each subfile in the SUBFILE parameter. Each text contains the identifiers of all structures with an unsuffixed identifier in the subfile. Each identifier is put on a separate line, and the characters ,\ are appended to all but the last line. You would normally use these texts as a macro; the ,\ makes them useable as lists of identifiers. If the text is used as a macro, it is subject to the restriction on the length of statements. The SAVESUBFILE option allows you to save a similar text containing the identifiers of all the subfiles in a backing-store file.
Options: PRINT, CHANNEL, LIST, SAVESUBFILE, UNNAMED.
Parameters: SUBFILE, SAVESTRUCTURE.
See also
Directives: STORE, RETRIEVE, MERGE.
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