POINTER directive

Declares one or more pointer data structures.

Options

NVALUES = scalar or text

Number of values, or labels for values; default *

VALUES = identifiers

Values for all the pointers; default *

SUFFIXES = variate

Defines an integer number for each of the suffixes; default * indicates that the numbers 1,2,... are to be used

CASE = string

Whether to distinguish upper- and lower-case in the labels of the pointers (significant, ignored); default sign

ABBREVIATE = string

Whether or not to allow the labels to be abbreviated (yes, no); default no

FIXNVALUES = string

Whether or not to prohibit automatic extension of the pointers (yes, no); default no

RENAME = string

Whether to reset the default names of elements of the pointer if they do not have their own identifiers (yes, no); default no

MODIFY = string

Whether to modify (instead of redefining) existing structures (yes, no); default no

IPRINT = strings

Information to be used by default to identify the pointers in output (identifier, extra); if this is not set, they will be identified in the standard way for each type of output

Parameters

IDENTIFIER = identifiers

Identifiers of the pointers

VALUES = pointers

Values for each pointer

EXTRA = texts

Extra text associated with each identifier

Description

Lists of data structures can be stored in a GenStat pointer structure to save having to type the list in full every time it is used. For example

POINTER [VALUES=Rain,Temp,Windspeed] Vars

VARIATE #Vars

READ [CHANNEL=2] #Vars

PRINT #Vars; DECIMALS=2,1,2

defines Rain, Temp and Windspeed to be variates, and then reads and prints their values. When none of the structures in the list is itself a pointer, the substitution symbol (#) simply replaces the pointer by its values. If, however, there are pointers in the list, they too are substituted, as are any pointers to which they point. An example is given below.

The individual elements of a pointer can also be referred to by the use of suffixes. We can refer to Rain above either using its own identifier, or as the first element of Vars by using the suffix [1]: so

Vars[1]

is Rain

Vars[2]

is Temp

Vars[3]

is Windspeed

Furthermore, we can put a list within the brackets:

Vars[3,1]

is Windspeed,Rain.

Also, you can put a null list to mean all the available suffixes of the pointer:

Vars[]

is Rain,Temp,Windspeed.

Identifiers like Vars[1], Vars[2] and Vars[3] are called suffixed identifiers and, in fact, you can use these even without defining the identifier of the pointer explicitly. Whenever a suffixed identifier is used, GenStat automatically sets up a pointer for the unsuffixed part of the identifier if it does not already exist. Furthermore the pointer will automatically be extended (whether it has been set up by you or by GenStat) if you later use a new suffix, like Vars[93] for example. Notice that the suffixes do not need to be a contiguous list, nor need they run from one upwards, although they must be integers; if you give a decimal number it will be rounded to the nearest integer (for example, -27.2 becomes -27).

The SUFFIXES option of the POINTER directive allows you to specify the required suffixes for pointers that are defined explicitly. For example

VARIATE [VALUES=1990,1991,1992,1993] Suffs

POINTER [NVALUES=4; SUFFIXES=Suffs] Profit

defines Profit to be a pointer of length four, with suffixes 1990 to 1993. If you are setting the suffixes explicitly, you might want to forbid GenStat to extend the pointer if another suffix is encountered later in the program; this can be done by setting option FIXNVALUES=yes.

We could actually omit the NVALUES option in the definition of the pointer Profit above, as GenStat can determine the length of the pointer by counting the number of values. However, by supplying a text instead of a scalar for NVALUES you can define labels for the suffixes of the pointer. The length of the text defines the number of values of the pointer, and its values give the labels. For example

TEXT [VALUES=name,salary,grade] Labs

POINTER [NVALUES=Labs] Employee

would allow you to refer to Employee['name'], Employee['salary'], and so on.

Usually, when the pointer is later used, GenStat requires the labels to be given exactly as in the definition. However, you can set option CASE=ignored to indicate that case is unimportant, so they can be specified in capitals, or lower-case, or in any mixture. You can also set option ABBREVIATE=yes to allow each one to be abbreviated to the minimum number of characters required to distinguish it from the labels of earlier elements of the pointer.

The identifiers in a suffix list can be of scalars, variates or texts; this of course includes numbers and strings as unnamed scalars and texts respectively. If one of these structures contains several values, it defines a sub-pointer: for example Vars[!(3,2)] is a pointer with two elements, Windspeed and Temp. You must thus be careful not to confuse a sub-pointer with a list of some of the elements of a pointer: for example Vars[!(3,2)] is a single pointer with two elements, whereas Vars[3,2] is a list of the two structures Windspeed and Temp.

Elements of pointers can themselves be pointers, allowing you to construct trees of structures. For example

VARIATE A,B,C,D,E

POINTER R; VALUES=!P(D,E)

& S; VALUES=!P(B,C)

& Q; VALUES=!P(A,S)

& P; VALUES=!P(Q,R)

You can refer to elements within the tree by giving several levels of suffixes: for example P[2][1] is R[1] which is D; P[2,1][1,2] is (R,Q)[1,2] or D,E,A,S. The special symbol # allows you to list all the structures at the ends of the branches of the tree: #P replaces P by the identifiers of the structures to which it points (Q and R); then, if any of these is a pointer, it replaces it by its own values, and so on. Thus #P is the list A,B,C,D,E.

As you have seen, structures need not have an identifiers of their own, but may simply be identifiable as a member of a pointer using the suffix notation. Where a structure like this is a member of more than one pointer, GenStat will refer to it in output using the pointer with which it was first associated. So, for example, in

POINTER [NVALUES=2] P

& [VALUES=P[1,2],C] Q

VARIATE [VALUES=1,2,3,4] Q[]

PRINT Q[]

the output will be labelled as P[1], P[2] and C. However, we can set option RENAME=yes when Q is defined

POINTER [VALUES=P[1,2],C; RENAME=yes]

to request that the pointer Q takes precedence over earlier definitions, so the labels become Q[1], Q[2] and C.

Options: NVALUES, VALUES, SUFFIXES, CASE, ABBREVIATE, FIXNVALUES, RENAME, MODIFY, IPRINT.

Parameters: IDENTIFIER, VALUES, EXTRA.