Sets the identifier of a data structure to be one specified in a text (R.W. Payne).
No options
Parameters
DATA = identifiers |
Specifies the data structures to be given new names (i.e. identifiers) |
|---|---|
NAME =texts |
Text for each data structure containing its new identifier |
Description
SETNAME allows you to set a new identifier (or name) for a data structure. It differs from the similar RENAME directive in that the new identifier is supplied in a text structure. In RENAME the new identifier itself is specified.
The data structure to be given a new name is specified by the DATA parameter. If DATA is set to a dummy, SETNAME will operate on the data structure to which it points, not on the dummy itself. The text containing the new identifier is specified by the NAME parameter. This must be a simple identifier; identifiers with suffixes are not allowed. Also, note that the scope of the identifier will always be global (i.e. in your main program), even if SETNAME is called from inside another procedure.
For example, if you put
SETNAME A; NAME='B'
the data structure previously known as A would be renamed to have the identifier B, and the data structure previously known as B would lose its identifier and become unnamed. The identifier A would then no longer belong to anyone (and could if required be reused).
In the simplest situations, the first appearance of the new identifier will be in the SETNAME command. So there will be no consequences from the fact that the “orphan” data structure that it previously identified becomes unnamed. If the identifier has already been used, the orphan data structure will be deleted, unless it is found to belong to another (named) data structure. So, for example, if the full program was
SCALAR B; VALUE=1
POINTER [VALUES=B] Q
SETNAME A; NAME='B'
the scalar 1 would survive as the first element of the pointer Q. So it could still be referred to as Q[1], although of course no longer as B.
Options: none.
Parameters: DATA, NAME.
See also
Directive: RENAME.
Commands for: Calculations and manipulation, Data structures.
Example
CAPTION 'SETNAME example'; STYLE=meta SPLOAD '%GENDIR%/Data/Canola.gsh' " form N x S table of mean yields (to show what happens when N and S are renamed) " TABULATE [CLASSIFICATION=N,S] yield; MEAN=MeanYield PRINT MeanYield " print to show the original values of N and S " PRINT N,S " rename N to Nitrogen, and S to Sulphur " SETNAME N,S; NAME='Nitrogen','Sulphur' " print to show that N has become Nitrogen, and S has become Sulphur " PRINT Nitrogen,Sulphur " notice the renaming carries over to the classification of MeanYield " PRINT MeanYield