LIBEXAMPLE procedure

Accesses examples and source code of library procedures (R.W. Payne).


No options


Parameters

PROCEDURE = texts
Single-valued texts indicating the procedures about which the information is required

EXAMPLE = texts
Identifiers of text structures to store the example for each procedure

SOURCE = texts
Identifiers of text structures to store the source code of each procedure


Description

LIBEXAMPLE allows you to obtain an example of the use of any procedure in the GenStat Procedure Library, also to access the source code of any procedure, so that you can see how it works, or modify it. The names of procedures for which examples or source code are required should be listed, in quotes, using the PROCEDURE parameter. The EXAMPLE parameter can be used to specify the identifier of a text to store each example, and the SOURCE parameter to specify texts to store the source code. The examples can then be run (as macros) using the operator ##. Thus,

LIBEXAMPLE 'PERCENT'; EXAMPLE=%Ex

##%Ex

would put an example of how to use PERCENT into the text %Ex, and then run it.

   The examples and source are stored in backing-store files whose names are defined by Library procedure LIBFILENAME; there must be a free backing-store channel to which the files can be attached. A file can also be defined to supply information about procedures in a local library, and LIBEXAMPLE will then look there first so that any local examples are taken in preference to those for the main library. The file can be formed using procedure FLIBHELP.


Options: none. Parameters: PROCEDURE, EXAMPLE, SOURCE.


Method

The examples are held in the same backing-store file that holds the other help information about Library procedures; the name of the file is supplied by procedure LIBFILENAME. This file is opened on the first available backing-store channel; if all the channels are in use, the procedures stops with a diagnostic. Within the help file, the information about each procedure is stored in a subfile whose identifier is the same as the name of the procedure itself. The example is stored in a text with identifier Help['example']. After the required information has been brought back from backing store, the help file is closed. The source code of the procedures is stored in a separate backing-store, and accessed in a similar way.