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 or scalar Defines an integer number for each of the suffixes; default * indicates that the numbers 1,2,… are to be used
CASE = string token Whether to distinguish upper and lower case in the labels of the pointers (significant, ignored); default sign
ABBREVIATE = string token Whether or not to allow the labels to be abbreviated (yes, no); default no
FIXNVALUES = string token Whether or not to prohibit automatic extension of the pointers (yes, no); default no
RENAME = string token 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 token Whether to modify (instead of redefining) existing structures (yes, no); default no
IPRINT = string tokens 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
EXTEND = string token Whether to extend (instead of redefining) an existing pointer (yes, no); default no

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.

As mentioned above, a pointer can be extended automatically to include a new suffix, if that suffix is used with the pointer in your program. However, it is not possible to extend the pointer automatically to include a new label, as Genstat would not know which suffix to give it and an automatic choice could lead to errors or confusion. So, the POINTER directive has an option EXTEND which can be set to yes to do this explicitly. The pointer elements that are defined are then added to the existing elements of the pointer. So, we could add additional labels to the pointer Employee, above, by the statements

TEXT [VALUES=department,room] Newlabs

VARIATE [VALUES=4,5] Newsuffs

POINTER [NVALUES=Newlabs; SUFFIXES=Newsuffs; EXTEND=yes] Employee

adds Employee['department'] as suffix 4, and Employee['room'] as suffix 5. If you do not specify a label, the new suffix is still added (but unlabelled). If you do not specify a suffix, the new label is given a suffix of one plus the largest suffix already in the pointer. When EXTEND=yes, the EXTRA parameter and the CASE, ABBREVIATE, FIXNVALUES, MODIFY and IPRINT options are ignored.

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, EXTEND.

Parameters: IDENTIFIER, VALUES, EXTRA.

See also

Directives: ASSIGN, STRUCTURE, DECLARE, DUMMY, LRV, SSPM, TSM, TREE.

Procedure: PDUPLICATE.

Functions: VSUMS, VTOTALS, VMEANS, VMEDIANS, VMINIMA, VMAXIMA, VRANGE, VCOVARIANCE, VCORRELATION, VSD, VSEMEANS, VSKEWNESS, VKURTOSIS, VVARIANCES, VNOBSERVATIONS, VNVALUES, VNMV, VPOSITIONS.

Commands for: Data structures.

Example

" Example POIN-1: Declaring a pointer"

VARIATE [NVALUES=2] Yield,Costs,Profit
READ Yield,Costs,Profit
5.6 1200 455
6.1 1530 620 :
POINTER [VALUES=Yield,Costs,Profit] Info
PRINT Info[1]
Updated on January 16, 2018

Was this article helpful?