Performs tasks specified in subprograms supplied by the user, but not linked into Genstat; this directive may not be available on some computers.
Option
NAME = text |
Filename of external executable program; default 'GNPASS' |
|---|
Parameters
DATA = pointers |
Structures whose values are to be passed to the external program, and returned |
|---|---|
ERROR = scalars |
Reports any errors in the external program |
Description
On some computers, you can arrange that one program, such as Genstat, calls for another to be executed, passing information directly between the two. You can then cause Genstat to execute your own subprograms without having to modify Genstat in any way. This is done by the PASS directive.
To find out if the PASS directive has been implemented in your version, you can either look at local documentation, or type
PASS
in any Genstat program. You will either get a message saying that the PASS directive has not been implemented, or you will get a Genstat diagnostic telling you that Genstat has failed to initiate a sub-process: this means that PASS has been implemented. If PASS has not been implemented, you could use the OWN directive. Alternatively, you may be able to use the SUSPEND directive.
To use the PASS directive when it is available, you must first get access to the GNPASS program which is distributed with Genstat. You then form an executable program consisting of GNPASS, slightly modified as detailed below, and your own subprograms. GNPASS is written in Fortran 77; however, on most computers, it is possible to use equivalent programs in other computing languages. The GNPASS program deals with communication with Genstat, and passes information to and from your subprograms.
You can use the DATA pointer to pass the values of any data structures except texts. All the structures needed by your subprograms must be combined in a pointer structure, unless only one structure is needed and it is not a pointer. The structures must have values before you include them in a PASS statement; if you want to use some of the structures to store results from your subprograms, you must initialize them to some arbitrary values, such as zero or missing. If you specify several pointers in a PASS statement, your subprograms will be invoked several times, to deal in turn with each set of structures stored by the pointers. However, the values of the structures in all the pointers are copied before any work is done by your subprograms. Thus, if you want to operate with PASS on the results of a previous operation by PASS, you must give two PASS statements with one pointer each rather than one statement with two pointers. The ERROR parameter allows you to pass a scalar value back into Genstat to indicate whether any errors have occurred.
As an example, consider using PASS to carry out a simple transformation of a variate, as would be done by the statement
CALCULATE W = M*(V+S)**2
where V and W are variates, and M and S are scalars. You would need a Fortran subprogram to calculate the values of W from supplied values of M, V and S. The distributed version of the GNPASS program is accompanied with just such a subprogram, called SQUARE, for the purpose of illustrating how to use PASS. So all you need to do is to compile and link the program and subprogram into an executable program, called GNPASS for convenience. Then you can run Genstat and give the following statements:
SCALAR S,M; VALUE=2,10
VARIATE [VALUES=1...10] V
& [VALUES=10(*)] W
PASS !p(V,S,M,W)
The PASS statement will cause the GNPASS program to run, and assign the calculated values to the variate W.
Numbers can be used in place of scalars, as usual in Genstat statements:
PASS !p(V,2,10,W)
To transform the values in both V, as above, and another variate X, with values 10…50 say, you could give the statements:
VARIATE [VALUES=41(*)] Y
PASS !p(V,2,10,W),!p(X,2,10,Y)
The NAME option is used to specify the filename of the executable program formed from the GNPASS program and your subprograms. By default, the name GNPASS is assumed.
The distributed form of the GNPASS program, if available on your computer, consists of Fortran statements that receive information from Genstat as supplied by a PASS statement, call the SQUARE subprogram, and then send back the information as modified by SQUARE. To make it do the task that you require, you need to edit the program to call your subprograms instead of SQUARE. The documentation for GNPASS is provided as comments within the GNPASS program, so the details are not included here as well. After preparing the Fortran, you need to form it into an executable program. This will require a Fortran compiler, and to be certain of communicating successfully with Genstat, the compiler should be the same as that used in preparing Genstat – details will be given in the information that accompanies your copy of Genstat. It may also be possible to use other source languages, provided the input and output formats of their compilers are compatible with that used by Genstat.
Option: NAME.
Parameters: DATA, ERROR.
See also
Directive: SUSPEND.
Commands for: Program control.