Does work specified in Fortran subprograms linked into Genstat by the user.
Option
SELECT = scalar |
Sets a switch, designed to allow OWN to be used for many applications; standard set-up assumes a scalar in the range 0-9; default 0 |
|---|
Parameters
IN = identifiers |
Supplies input structures, which must have values, needed by the auxiliary subprograms |
|---|---|
OUT = identifiers |
Supplies output structures whose values or attributes are to be defined by the auxiliary subprograms |
Description
To implement the OWN directive, you must get access to some of the Genstat source code. The relevant section of the code is named Module X, and is distributed with Genstat to all sites, probably in a file called X.FOR. The module consists of several Fortran 77 subprograms but to implement the OWN directive you need to modify only the subprogram called G5XZXO. This contains extensive comments that describe the way it works, and the straightforward changes that you would need to make in order to call your own subprograms. These comments are designed to be the complete documentation, and so the details are not repeated here.
The IN parameter allows you to pass values of data structures into your subprograms. Genstat will check these input structures before calling your subprograms, to ensure that they are of the right type and length for your program, and that they have been assigned values. The OUT parameter copies values calculated by your subprograms into Genstat data structures. You can arrange to define the type and length of these output structures either before or after calling your subprograms.
If the setting of the IN parameter is a list of identifiers, the OWN directive will call your subprograms more than once. Each time it will make available to your subprograms the values of one structure in the IN list, and will take information from the subprograms and put them into the corresponding structure in the OUT list. Therefore, to pass several structures at a time to your subprograms, you must put the structures into pointers. For example,
OWN IN=!p(A1,A2,A3),!p(B1,B2,B3); OUT=X,Y
will call your subprograms twice, passing information about A1, A2, A3 and X the first time, and about B1, B2, B3 and Y the second time. It does this because !p(A1,A2,A3), for example, is a single structure.
If you want to pass just one pointer to your subprograms, you must ensure that OWN does not treat the pointer as a set of structures each of which is to be passed. You can do this by constructing another pointer to hold just the identifier of the pointer that you want to pass; for example:
POINTER [VALUES=A,B,C] S1
OWN IN=!p(S1)
The SELECT option allows you to call any number of subprograms independently. Thus, you can set up OWN so that the statements
OWN [SELECT=1]
and
OWN [SELECT=2]
do totally unrelated tasks. The standard version of G5XZXO deals only with the default value, 0, of SELECT, and would need to be extended if you wanted to cater for alternative values. However, you should be able to use much of the Fortran that deals with the default setting.
The distributed version of Genstat contains a version of the G5XZXO subprogram that carries out a simple calculation, purely for illustration of how the subroutine works. In this version, the result of
OWN IN=!p(V,S,M); OUT=W
is to shift, square and scale the values of V; that is, it does the calculation
W = M * (V + S)**2
The subprogram checks that precisely three structures are given in the pointer specified by the IN parameter, and that they are a variate and two scalars with values already present. It also checks that there is precisely one output structure, a variate; this is implicitly declared by OWN if necessary, based on the length of the input variate. Missing values in the input structures are also checked for and dealt with appropriately. The subprogram calls another one called G5XZSQ actually to carry out the transformation. To modify G5XZXO, you need to alter the details of the checks on the structures and substitute the call for one to your own subprogram.
The standard version of the G5XZXO subprogram will produce Genstat diagnostics if the checks on the input or output structures fail, or if there is not enough workspace. These diagnostics are the standard ones with codes VA, SX and SP, and are dealt with by a section at the end of the G5XZXO subprogram. You can define your own diagnostics, using the code ZZ. You are not allowed to edit the standard file of error messages that stores the one-line definitions of each diagnostic code. However, you can edit the G5XZPF subprogram which is in module X. This prints extra messages after a ZZ diagnostic; instructions for editing the subprogram are contained as comments in it.
Output from your subprograms is most easily arranged by storing the information that you want in data structures, and printing these with a PRINT statement after the OWN statement. Alternatively, you can give Fortran WRITE statements; there are standard routines in Genstat for outputting numbers and strings, but they are not described here. You should use the correct Fortran unit numbers for output, and this varies between implementations of Genstat. Note that a Fortran unit number is not the same as a Genstat channel number.
Option: SELECT.
Parameters: IN, OUT.
See also
Commands for: Program control.