FSPREADSHEET procedure

Creates a GenStat Spreadsheet file (GSH) from specified data structures, PC Windows only (D.B. Baird).


Options

OUTFILE = text
Name of GSH file to store data in

SHEET = number
Sequence number of existing sheet, if this is set to 0 the data will be added to the first compatible spreadsheet open in the Windows interface

METHOD = string
What to do with any existing columns with the same names as the new columns (replace, rename); default rena

READONLY = string
Whether to make the complete sheet read-only (yes, no); default no

TITLE = text
The title associated with the spreadsheet

POINTER = pointer or text
A pointer or a name of a pointer to the columns in the spreadsheet

ANALYSIS = text
GenStat directives to analyse columns in the spreadsheet

ASETUP = text
GenStat directives to be run once before the analysis of any columns in the spreadsheet

ADUMMY = text
The name of the dummy (if any) used in the ANALYSIS directives

CURSOR = variate
A variate of length 2 giving the active cell position (x,y) when the spreadsheet is first displayed

NOUNITS = string
Whether to stop the inclusion of a units column in the spreadsheet (yes, no); default no

BOOK = number
Window number of existing book, if this is set to 0 the sheet will be created in a new book, if to -1 it will be created in the last book formed with BOOK=0, and if set to -2 it will be created in the last book created in the Windows interface.

PAGENAME = string
The 16 character text to be displayed on the sheet tab


Parameters

DATA = identifiers
Data to write to the spreadsheet

PROTECT = strings
Whether to protect each data column by making it read-only (yes, no); default no


Description

FSPREADSHEET can be used to create a new spreadsheet or GSH spreadsheet file or to update an spreadsheet open in the windows interface.

   The DATA parameter should be set to any one of the following combinations of data structures: a list of vectors (variates, factors and texts), a matrix, a symmetric matrix, a diagonal matrix, a two-way table, a list of one-way tables or a list of scalars. If you specify a list of vectors they must all be the same length and, if any are restricted, the restrictions must be compatible (the same subset of units for all restricted vectors). By default, if the columns have unit labels, they will be included as the initial column of the spreadsheet, but you can set option NOUNITS=yes to exclude them.

   You can set option READONLY=yes to make the entire spreadsheet read-only (so that its contents cannot be changed). Alternatively, you can use the PROTECT parameter to protect any individual column (by making it read-only). Settings of the PROTECT parameter override the setting of the READONLY option.

   If OUTFILE is set, the output is sent to the specified file; otherwise a new spreadsheet is opened containing the data. The SHEET and METHOD options are for updating open spreadsheets. The number provided by SHEET is the position of the spreadsheet in the list of currently open spreadsheets. Thus SHEET=1 will add or update data in the first spreadsheet in the window list, SHEET=2 the second etc. Setting SHEET=0 will cause GenStat to update the first sheet with matching stuctures (i.e. for a variate this will be a VECTOR sheet with the same number of rows). The GenStat interface uses internal pointers to the spreadsheet structures which appear as large integers, and these should not be re-used in your saved code. The BOOK option allows you to specify the particular book that the sheet is to be created in (if SHEET is not set). Setting BOOK=0 will cause the sheet to be placed in a new book, even if the default option in the Windows interface is to add sheets from the server to the last book with focus, and setting BOOK=-1 will cause the sheet to be added to the last book created by FSPREADSHEET with BOOK=0. Setting BOOK=-2 will cause the sheet to be added to the last created spreadsheet. The PAGENAME option allows the tab name displayed when multiple sheets are in a book to be specified. If METHOD=replace, then any existing columns of the same name will be replaced in the spreadsheet, and if METHOD=rename, the old columns will be retained, and the new columns will be renamed.

   The TITLE option can supply textual information (e.g. a title or a description) to be stored with the spreadsheet. The CURSOR option specifies the current cell to have focus when the spreadsheet is opened in a window. The POINTER, ANALYSIS, ASETUP and ADUMMY options allow GenStat directives to be attatched to the spreadsheet for use in the Spread > Sheet > Analysis menu.

   (Note: FSPREADSHEET replaces the procedure %WSPREAD from earlier editions of GenStat.)

 

Options: OUTFILE, SHEET, METHOD, READONLY, TITLE, POINTER, ANALYSIS, ASETUP, ADUMMY, CURSOR, NOUNITS, BOOK, PAGENAME.

Parameters: DATA, PROTECT.


Method

Internal directives are used to write the data to a GSH file which holds the data in a binary format. A message is sent to the windows interface to read this file if OUTFILE is not set.


Action with RESTRICT

Restrictions on the structures are included in the spreadsheet created. If the restrictions on the structures are not consistent, a fault will occur.