This section covers the steps needed to install the PVT code on a typical computer system. The advice is necessarily general, since many aspects of installation are system-dependent. Installation consists of the following steps:
Copy the PVT files from the medium on which they are delivered to the hosting system. If the medium is magnetic tape, there is an accompanying information sheet to describe the physical format of the files. Also, see Appendix: Building the PVT in UNIX for detailed guidance on creating the C version under UNIX.
Store the files in a hierarchical directory as described in section 2.1 and the PVT Tree Structure. In particular, use the same two-digit level numbers as in the files' own self-identification. The name of the PVT root level is arbitrary; a name like USER~PVT~... is a reasonable choice. See section 2.1 for a list of the files that belong in the PVT root directory. The global and module-level documentation need not be stored on-line, although this may be convenient for automatic searching for entities within the PVT suite.
Assign the source code filenames in the format "pxx.f" or "pxx.c" where "xx" indicates the ordinal number within the module, and ".f" or ".c" indicates the source language. For example, the program with the header
C ********************************************************* C * * C * TEST NUMBER: 04.02.05.04/05 * C * TEST TITLE : WSL pattern table initialized * C * properly * C * * C * PHIGS Validation Tests, produced by NIST * C * * C *********************************************************should be stored as "user~pvt~04~02~05~04~p05.f". Different operating systems have various conventions for the suffix to denote Fortran source code, such as ".FOR" or ".FTN". Any such convention is acceptable as long as it is consistently applied. It is strongly recommended, however, that the initial part of the name be in the format "Pxx". Throughout the PVT documentation, programs are always identified according to this format, and it avoids confusion if the program's physical name matches its logical identification.
Likewise, copy subroutine libraries into the appropriate tree nodes. The banner of each subroutine identifies the correct node for the library. The recommended file name is sublib.f (Fortran) or sublib.c (C).
When done, check your file hierarchy against the PVT tree structure as described in the PVT Tree Structure to ensure that all the files have been copied.
The local subroutine libraries are assigned to nodes of the tree only for the purpose of clarifying the logical relationship among the test programs and subroutines. If linking in several libraries is difficult in your system, you can simply concatenate all the subroutine source code together as one large file, and compile it as one library, presumably in the root. No two PVT subroutines have the same name, so no name clashes will occur.
This alternative method is also on the distribution tape for the C binding under the PVT root, pvt~V2LIB (see Figure 3). This may allow easier generation of object libraries for some operating systems. The sub-directory pvt/V2LIB contains all routines, one routine per file, each file name being the routine name. Files ending in .c are the C versions translated from the equivalent FORTRAN versions (e.g. XPOPPH.c was translated from XPOPPH.f). Each of the files must be compiled and assembled into a library for linking. All object files resulting from the compilation of source files ending in .c should comprise a single library. It is not recommended that the files be separated into multiple libraries because many operating systems require that the calling order of the routines be followed.
Some of the source code may need to be changed in order to run on your system. These places are noted in the code by a comment line beginning with "CMOD". Use any text editor to perform these changes. The first change, naming the PVT configuration file, is mandatory for all systems. All the other changes are optional.
First, choose a name for the PVT configuration file. The name you pick must be absolute, i.e. it must be valid when used from any part of the hierarchy. We recommend locating the PVT configuration file in the PVT root.
This name must be inserted in three locations all of which are in the PVT root:
In all three cases, search for the string "INITPH.DAT" (the name we used) in these routines to locate the insertion point.
The PVT configuration report file is a human-readable version of the PVT configuration file. Pick a name for it as well, such as "INITPH.PRT", and insert it into the INITPH program.
All the test cases call XPOPPH to open PHIGS, rather than the standard POPPH. The XPOPPH subroutine, as delivered, simply calls POPPH. If your system has special processing requirements for accessing PHIGS, these may be addressed by additions to XPOPPH. Note, however, that for validation purposes, such changes are subject to approval by NIST.
The last routine in the global subroutine library, RND01 is written in non-standard Fortran, since that standard provides no way to randomly initialize a seed for a random number generator. You may alter RND01 (possibly using a local non-standard time function) so that the seed is different for each execution. This is the preferred mode of execution. All the other random-number routines are built on RND01, so if it works, the others need not and should not be changed.
For the C version, the standard C function, gmtime is used to obtain a random starting value, and so no modification should be necessary.
If you request that the test programs generate individual message files (see section 4.2.3) INITGL will, by default, form the name of the file by using "p" as a prefix, the two-digit ordinal number of the program, and ".msg" as a suffix; e.g. p04.f will write to p04.msg. if you prefer another naming convention, search for ".msg" in the INITGL routine and change the code accordingly.
The INITGL and MULTWS subroutines read the PVT configuration file in order to determine the parameter values needed to open the primary and secondary workstations (workstation identifier, connection identifier, and workstation type), and report these back to the calling program. INITGL sets the value of three variables in COMMON to do this, while MULTWS returns the values in its output parameters. In both cases, the assumption is that the correct values are static and can be set once by the INITPH procedure (see section 4.2, below). If your system is such that this information can be determined only at run-time, you must re-code the relevant sections of INITGL and MULTWS, so that they still deliver the required values.
The subroutine AVARNM, in node 03 of the PVT tree, must return to the caller an integer representing the valid name of an available empty archive file. The code assumes that this name should be interpreted as a Fortran logical unit number. If your system has a different interpretation, or has special requirements for opening an archive file, you must modify this subroutine accordingly.
The Fortran standard provides no function for determining time or date. If, however, your implementation does provide such a feature and you wish to include this information in the PVT output, we suggest you alter the INITGL subroutine at the point where it formulates the header system message. This is done at the very end of the subroutine, in the last call to BRDMSG.
If you are modifying the C version, you may wish to use one of the standard C functions that return the current time.
The OPMSG and OPYN routines in the global subroutine library write messages to and read messages from the operator. Because a workstation may not be open at the time these are executed, the PVT Fortran code resorts to the use of the print and read statements. If there is a better way to send a character string to and from the operator in your system, you may re-code these routines accordingly. If print and read work well within your system no change is necessary.
If you specify a global message file (see section 4.2.3), the INITGL routine must position the file pointer at end of file so as to append new messages. In standard Fortran, the only way to do this is to read through the whole file. If your Fortran system provides a more efficient (though non-portable) way to do this, you may wish to substitute that method in INITGL. Otherwise, no change is needed.
Since the translator uses the FORTRAN code, this inefficiency is carried into the generated C code. If you wish to provide a more efficient way in C, such as opening the file in append mode, you may substitute the method for the one provided in INITGL.
Since ANSI compliant C allows the use of prototyping [C1989], the layer code for the C binding provides for both non-prototyped and prototyped source code. The use of a #define directive in each source file regulates which function declaration will be used. If your complier supports prototyping, no #define directive need be used. If your complier does not support prototyping, all code must be compiled with the directive NO_PROTO. This may be done by changing the "Makefiles" in the PVT root, in V2LIB, and in the LAYER directories.
The test suite makes use of the entire printable ASCII character set (one of the requirements of the PHIGS standard for the <text> function). The characters appear in the source code and may also have another meaning on some systems (e.g. the backslash "\" character in UNIX). Most compilers have a switch/parameter that notifies the compiler to ignore the special "system" meaning of these characters during compilation. If the code does not compile, check if your system uses any special characters, and the switch/parameter for your compiler that disables them. If that doesn't work, the source code itself may have to be modified (e.g. "ab\cd" re-written as ab\\cd").
In most systems, you will need to compile all the subroutine files so as to create subroutine libraries, which may then be linked in with each test program. Test suite programs for both language bindings require:
Of course not all the test programs use all the subroutines, so do whatever your system requires such that only needed subroutines are linked in. E.g. in VMS, the /LIBRARY qualifier performs this function.
We strongly recommend setting up a command procedure to compile, link, and execute a test program solely by referring to the name of the program. In particular, all local subroutine libraries (those above the program in the directory tree) and the global libraries must be made available, as well as linking to the code of the PHIGS implementation. Note that errlib.f contains the PERHND subroutine - the standard PHIGS-Fortran name for an error-handler. Correspondingly, errlib.c in the C version contains perr_hand - the standard PHIGS-C name for an error-handler. Some PHIGS implementations may require special treatment to link in PERHND or perr_hand. Since most linkers prefer to be given access to libraries in order from caller to called procedure, the normal sequence would be:
It may prove useful to construct a batch procedure (such as a shell script in Unix) for the passive tests of each category of workstation, so that you can automatically invoke the correct subset of programs. Be careful, however, that you provide for the possibility of non-completion (e.g. failure to compile, aborted execution) of programs run in batch mode.
Previous section is Section 2: Structure and Format of PVT Suite. Next section is Section 4: Operation.