Introduces a Genstat procedure.
Options
PARAMETER = string token |
Whether to process the structures in each parameter list of the procedure sequentially using a dummy to store each one in turn, or whether to put them all into a pointer so that the procedure is called only once (dummy, pointer); default dumm |
|---|---|
RESTORE = string tokens |
Which aspects of the Genstat environment to store at the start of the procedure and restore at the end (inprint, outprint, outstyle, diagnostic, errors, pause, prompt, newline, case, run, units, blockstructure, treatmentstructure, covariate, asave, dsave, msave, rsave, tsave, vsave, vcomponents, seeds, captions, cmethod, actionafterfault, unsetdummy,all); default * |
SAVE = text |
Text to save the contents of the procedure (omitting comments and some spaces) |
WORDLENGTH = string token |
Length of word (32 or 8 characters) to check in identifiers, directives, options, parameters and procedures within the procedure (long, short); default * i.e. no change |
Parameter
| text | Name of the procedure |
|---|
Description
Once you start to write programs for complicated tasks, you may wish to keep them to use again in future. The most convenient way of doing this is to form them into procedures. You may also wish to use procedures written by other people. The use of a Genstat procedure looks exactly the same as the use one of the standard Genstat directives. Thus, you simply give the name of the procedure, and then specify options and parameters as required. As with directives, the name can be abbreviated to as few as four characters, provided there is no ambiguity with the names of directives or other procedures. Directives and procedures in the official Genstat library are all defined to have names that are distinct within the first four characters so there should be no problem unless you (or your site) have defined procedures with ambiguous names.
When Genstat meets a statement with a name that it does not recognize as one of the standard Genstat directives, it first looks to see whether you have a procedure of that name already stored in your program. Then it looks in any procedure library that you may have attached explicitly to your program, taking these in order of their channel number (see the OPEN directive). The people that manage your computer can define a special site library and arrange for this to be attached to Genstat automatically when it is run. If they have done so, this library will be examined next. Finally Genstat looks in the official Genstat Procedure Library, which is also attached automatically to your program. After locating the required procedure, Genstat reads it in, if necessary, and then executes it. So you do not have to do any more than you would to use a Genstat directive.
The official library thus allows new facilities to be offered to all users. Or your computer manager can make procedures available that cover the special needs of the users at your site, and these will over-ride any procedures of the same name in the official library. Or you can form your own libraries of the procedures that you find particularly useful, and these will always be taken in preference to procedures in the site or the official library. Note however that a procedure cannot have the same name as any of the Genstat directives.
Information is transferred to and from a procedure only by means of its options and parameters. Otherwise the procedure is completely self-contained. Anyone who uses it does not need to know how the program inside operates, what data structures it contains, nor what directives it uses. The data structures inside the procedure are local to the procedure and cannot be accessed from outside.
To write your own procedures, you start by giving a PROCEDURE statement. This has a single parameter which defines the name of the procedure. The name can be up to 32 characters with the same rules as for the identifiers of data structures: the first character must be a letter, the second to the 32nd can be either letters or digits, and characters beyond the 32nd are ignored. However the name cannot be suffixed, and Genstat will warn you if the first four characters are the same as those of a Genstat directive. If so, you will be unable to abbreviate the name fully (down to as few as four characters), but you will need to give enough characters to distinguish it from the directive. If there is ambiguity in the name of a command, Genstat selects the directive or procedure to use according to the following order of priority: directives, user-defined procedures, procedures in libraries attached by the user (in order of channel number), procedures in the site library, and procedures in the official library.
The PARAMETER option indicates whether the settings in any list specified for the parameters of the procedure are to be taken one at a time, or whether they need to be processed together. The difference between these alternatives can be illustrated by considering some of the Genstat directives. For example, with
ANOVA Height,Weight; RESIDUALS=Hres,Wres
Genstat will first do an analysis with the values in the Height variate and store the resulting residuals in the variate Hres; it then analyses Weight and stores the residuals in Wres. This action corresponds to the default setting PARAMETER=dummy; inside the procedure, each parameter will then be a dummy data structure which will point to each item of the list in turn, in the same way as the parameters of a FOR loop. Conversely, in the statement
PRINT Height,Hres
the values of Height and Hres are printed together down the page, and this is possible only if PRINT is able to access both variates simultaneously. In a procedure this would require the setting PARAMETER=pointer; each parameter is then a pointer, storing the whole list.
You may change some aspects of the Genstat environment within a procedure. This may be the intended purpose of the procedure; but if it is an unwanted side effect, you should reset them afterwards. The RESTORE option allows you to list aspects that would like Genstat to reset automatically when it finishes executing the procedure. The settings of RESTORE mainly correspond to the various items that can be saved by the ENVIRONMENT and SPECIAL options of the GET directive. The outstyle setting restores the output style of the current output channel (see OPEN and OUTPUT). The setting all which has the same effect as listing all the other settings. Alternatively, you can save and restore the environment explicitly using the GET, SET, ENQUIRE and OUTPUT directives, although this is usually less efficient.
The SAVE option allows you to store the contents of the procedure, up to and including ENDPROCEDURE, in a text so that you can edit and redefine it or, for example, print it to a file or save it on backing store. The saved version is a modified form of the original input. Each line of the text contains a single statement; thus, where a statement spans several lines of input, these are concatenated into a single line in the text (deleting the continuation characters). Any line that contains several statements is split. Comments are removed, and any occurrence of several contiguous spaces is replaced by a single space. Also, a colon is placed at the end of each line.
Finally, the WORDLENGTH option allows you to set the wordlength to be used for identifiers, directives, options, parameters and procedures within the procedure. If WORDLENGTH=long, up to 32 characters of each of these names are stored and checked; while if WORDLENGTH=short, no more than eight characters are used. The default is to keep the existing setting of the wordlength (as in the program defining the procedure).
After the PROCEDURE statement, you must define what options and parameters the procedure is to have; this is done by the directives OPTION and PARAMETER respectively. Only one of each of these should be given, and they must appear immediately after the PROCEDURE statement, but it does not matter which of the two you give first. They have very similar syntaxes, except that OPTION has an extra parameter which allows you to indicate whether a list of values or of identifiers is allowed. If you do not wish to define options or parameters for a procedure you can simply omit these directives; alternatively you can use OPTION or PARAMETER but with none of their parameters set, which has precisely the same effect. You can alse use the CALLS directive to list any procedures that your procedure calls. (This can be useful when you are defining a suite of procedures that may call each other.)
After the OPTION, PARAMETER and CALLS statements, you then list the statements that are to be executed when the procedure is called: these statements are the sub-program that makes up the procedure. Any data structures defined within the procedure are local to the procedure and cannot be accessed from outside. So you can use any identifiers for the structures, without having to worry about whether they may also be used outside by someone who may later use the procedure. You end these statements making up the procedure by an ENDPROCEDURE statement.
You are allowed to redefine an existing procedure if you wish to change any of the statements that it contains. To do this you specify the PROCEDURE statement, as usual, followed by the statements making up the new version of the procedure, and then an ENDPROCEDURE statement. However, you are not allowed to change the option or parameter definitions, and if there are any changes in the OPTION or PARAMETER statements, Genstat will give an error diagnostic.
Options: PARAMETER, RESTORE, SAVE, WORDLENGTH.
Parameter: unnamed.
See also
Directives: OPTION, PARAMETER, CALLS, ENDPROCEDURE, FAULT, COMMANDINFORMATION, WORKSPACE.
Procedure: CHECKARGUMENT.
Commands for: Program control.
Example
" Example PROC-1: Defining a procedure"
PROCEDURE 'SQUARERT'
" Define the options & parameters of the procedure "
OPTION NAME='PRINT','TRACE'; MODE=t; DEFAULT='no'
PARAMETER NAME='X','ROOTX'; MODE=p
" Check that the option settings are valid and set scalars
Sprint and Strace to indicate whether they are set to yes "
SCALAR Sprint,Strace
FOR Setting=PRINT,TRACE; Sset=Sprint,Strace
IF Setting .EQS. 'yes'
CALCULATE Sset = 1
ELSIF Setting .EQS. 'no'
CALCULATE Sset = 0
ELSE
EXIT [CONTROLSTRUCTURE=procedure]
ENDIF
ENDFOR
" Check for invalid setting of parameter X ( i.e. < 0 ) "
IF X < 0
PRINT 'X < 0 : square root cannot be calculated'
ELSE
" Calculate convergence limit & initialize "
CALCULATE Clim = X/10000 & ROOTX = X
" Loop until convergence "
FOR [NTIMES=20]
CALCULATE Previous = ROOTX
& ROOTX = (X/Previous + Previous)/2
IF Strace
PRINT [IPRINT=*] ROOTX
ENDIF
EXIT ABS(Previous-ROOTX) < Clim
ENDFOR
IF Sprint
PRINT [IPRINT=*] 'square root of ',X,' is ',ROOTX;\
JUSTIFICATION=left
ENDIF
ENDIF
ENDPROCEDURE
" Use the procedure"
SCALAR Rx
SQUARERT X=48; ROOTX=Rx
PRINT Rx
" Use it and set the option"
SQUARERT [PRINT=yes] X=48; ROOTX=Rx
SQUARERT [PRINT=yes; TRACE=yes] 81; ROOTX=Rx