@(#)aglinsta.doc 10.1 (OAA-ASTRONET) 8/7/95 19:23:13 HEADER : aglinsta.doc - Vers. 3.6.001 - L. Fini, Sep 1993 A G L Vers. 3.61 - Sep 1993 Installation and Customization Luca Fini AGL 3.61 Distribution notice =================== The Astronet Graphic library has been designed and implemented under the coordination of the Astronet Working Group "Graphics and Image Displays". The software is officially supported by Astronet and is distributed by: Astronet Documentation Facility (ADOC) Osservatorio Astronomico di Trieste C.P. Succ. TS 5 Via G.B.Tiepolo, 11 34131 Trieste, Italia Tel: +39 40 319911 Fax: +39 40 309418 e-mail: adoc@astrts.astro.it The distribution release may also be obtained by anonymous ftp at: sisifo.arcetri.astro.it:pub/agl or via e-mail, from the author: Luca Fini Osservatorio Astrofisico di Arcetri L.go E. Fermi 5, 50125 Firenze, Italia Tel: +39 55 27521 Fax: +39 55 220039 e-mail: lfini@astrfi.astro.it Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 1 1 INTRODUCTION This manual is a comprehensive guide to help the system manager to perform AGL installation and customization needed to cope with local environment on a generic Unix system. Details on differences between known Unix implementations are included in the text. Please read the manual before attempting to use the command procedures provided. 1.1 AGL 3.x Kit The AGL library kit is usually distributed on magnetic medium as a set of files. The full kit will contain files for each currently supported AGL version. All files are in text format so that they are easily interchangeable between different operating systems. The complete list of AGL kit is contained in the file readme.doc. 1.2 Library Generation Both first time installation and version update will require a full recompilation of the library. This may seem a cumbersome task, but it has been chosen as the only one which guarantees transportability on each target operating system together with the ability to perform local system dependent optimization. Recompilation will obviously require the availability of the appropriate compilers. In some instances, most notably when window system servers are to be built, window system specific libraries will also be necessary, and the window system servers must be installed and running. More information about AGL in windowing environments can be found in the window system driver specific documentation. See: "AGL Support for Unix Windowing Environments" (file: window.doc). In some instances ASTRONET could also provide on request compiled object libraries. You must contact the ASTRONET Docu- mentation Facility to get information about the availability of specific object libraries for distribution. The main target of installation is the generation of an object library file which can then be moved on the system standard library directory to be accessed by application programs at link time. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 2 1.3 Environment definition A complete installation will usually require a further step for the definition of system dependent environment variables (or global symbols, depending on the terminology) to make the use of the library easier. Such definitions will be used by AGL to locate directories and/or files needed during the functioning. NOTE: STARTING WITH VERSION 3.5 THE ENVIRONMENT VARIABLE (OR LOGICAL NAME IN VMS TERMS) AGL3CONFIG MUST BE DEFINED FOR AGL TO WORK. SEE THE OPERATING SYSTEMS SPECIFIC INSTALLATION PARAGRAPH XX.4 FOR FURTHER INFORMATION. 1.4 Customization In some instances system managers may need to perform some customization steps to better adapt AGL to their particular needs. Usually customization is either needed in order to limit AGL application memory requirements by excluding unneeded drivers from the library, or it is used for the inclusion of new drivers in an existing installation. 1.5 Device Related Information Information which is specific to particular devices (such as Tektronix terminals, PostScript laser printers, etc.) are provided as separate documents one for each supported device. Some pieces of information needed for installation and/or custo- mization will be found there. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 3 2 AGL INSTALLATION AGL installation may differ slightly, depending on the host operating system. Different sections are thus devoted to the three may system families: Unix, VMS and MS-DOS. 2.1 AGL Unix Installation Installation under various blends of Unix machines is pretty similar, so system specific information will only be provided when needed. Unix installation of AGL has been tested on the following machines and/or Operating Systems: o DEC/Ultrix o Sun OS o Stellix o HP/UX o Linux o Alpha/OSF-1 To successfully perform the installation you must have available the C and the f77 compilers and the required libraries for the windowing system. Details about support for the windowing environments will be found in: AGL Support for Unix Windowing Environment (window.doc) 2.1.1 Library generation The AGL kit provided makefiles will perform a full recompi- lation of the AGL library and related utilities on any supported target system. A single makefile will perform the required compilation. When necessary unix blend specific selections are provided (see the makefile for instructions) The full AGL kit must be copied to a work directory (not the same containing previous versions of AGL) in order to proceed Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 4 with installation. 2.1.2 Preinstallation You may go to the next step in that no preinstalltion opera- tions are required. 2.1.3 Compilation To recompile the whole library proceed as follows: - Inspect the makefile to check whether standard symbols definitions are suitable for the local needs. Directions are included within the makefile itself. You may want to modify some selections by editing the makefile. You may also want to modify details such as compiler options and the like. - Build the library for the target system by issuing the appropriate make command: % make <sys> selecting the name of system. See in the makefile header to verify which names are allowed for <sys>. If the name is not there (or if the sele- tion you made failed), read directions in the makefile to obtain information on how to choose the proper configuration. - Issue the "make install" command to move files to target directories. 2.1.4 Configuration file You must provide a configuration file named agldevs.dat on the AGL standard directory (see below) to define names which you will use to identify output devices (see description in sect. 3). 2.1.5 Environment For the correct functioning of AGL some files must be accessible at run time. These file are copied to suitable directories during installation, but the system manager must ensure that each AGL user has the environment variable AGL3CONFIG defined and containing the name of the runtime directory. E.g. the command: setenv AGL3CONFIG /usr/local/agl/ Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 5 is suitable if the runtime directory is /usr/local/agl. This command MUST BE INCLUDED INTO USER'S .login procedure. 2.1.6 Installation testing with program ip After installation a test of the library is suggested, in order to check the proper functioning of AGL. Starting with version 3.3 a single test program is provided with the AGL kit named ip. This program is an improved version of the former intplot program and accepts command input either from a file or from the keyboard. A set of input files for the program ip is provided the AGL kit in order to test various features. These files are named *.m. The testing procedures can be run with the command: ip testfile [device:] where testfile is one of the kit provided command files *.m quoted above and device is an optional device specification (the colon is required). Device must specify a device name included into configuration. If the name tt is properly declared into AGLDEVS.DAT you may use the default to get output on your current terminal. If you are using a windowing workstation you must run the AGL server as directed in the related manual (window.doc). All testing runs will produce a file called "aglerr.log" containing debugging information which may be useful to trace installation errors. Documentation files may also be made available to users according to site specific procedures. 2.2 VAX/VMS Installation Note: In the following lines it is somewhere quoted the installation of windowing support under X11. You must be aware that up to now this part cannot be fully tested under VMS and so it is provided within the manual only because it will be available very soon. Installation under VAX/VMS will require the availability of the following optional software products: - MACRO-32 Assembler [1] - VAX/VMS FORTRAN compiler (Vers. 4) [2] - VAX C Compiler (Vers. 2.x) or GNU CC compiler. - X11 support [3] Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 6 [1] MACRO-32 is needed to compile the Vers. 2.x compatibility library and for the VT125 terminal driver. [2] FORTRAN is needed for the Fortran interface and the Vt125 terminal driver. [3] X11 support (libraries, etc.) is only needed to install the X11 window server. Further information which may be useful for VMS installations may be found into the following documents: File: gpxvms.doc - "AGL support for VAX/VMS windowing work- stations". File: vt125.doc - "AGL Support for DEC VT125 Terminals" 2.2.1 Library generation A command procedures named AGLVMS.COM is provided within the AGL 3.5 kit. This will perform a recompilation of the whole library together with utility and test programs suited for VAX systems without windowing graphic subsystems. The customization step on VAX/VMS systems is usually not necessary, anyway, if customization is desired or necessary follow directions of section 3.3. To recompile the whole library proceed as follows: - Copy all the AGL kit files into a scratch directory (not the same containing previous versions of AGL). - Execute either the command file AGLVMS.COM with the command: @AGLVMS - If your target system is a GPX workstation you may also want to build the GPXSERV.EXE program (needed to create an AGL compatible Tektronix window on the workstation screen). This may be an alternate way to use a windowing workstation if it's not provided with X11 support. In order to build the server you must execute the command file GPXSERV.COM. See further details on the Tektronix compatible window on the specific documentation (file: gpxvms.doc). Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 7 2.2.2 Configuration file The system manager must provide and keep updated the confi- guration file AGLDEVS.DAT (see description in sect. 3) which contains specifications of graphic device types. Each user can also define a specific AGLDEVS.DAT file on the current directory (i.e. the directory or directories from where the graphic appli- cation programs will be run) with definitions which will override system wide ones (this is especially useful either for the pseudo device TT: or for local printer, plotters and so on). 2.2.3 Global symbols and logical names Any AGL installation under VAX/VMS will require the definition of the following symbol: AGL3CONFIG: The directory where AGLDEVS.DAT and the *.CAP files are located. AGL3LIB: The directory and file containing the object library. This may be performed including into SYSTARTUP.COM command procedure two command lines such as: $ASSIGN/SYSTEM DUA0:[AGL] AGL3CONFIG $ASSIGN/SYSTEM DUA0:[AGL]AGL.OLB AGL3LIB where it is supposed that the working AGL library files are contained in the directory DUA0:[AGL]. It may actually be any suitable directory chosen by the system manager. IMPORTANT NOTE. For VAX Cluster systems there may be a single version of the library on a common directory, but each node must have its specific AGLDEVS.DAT file (with node specific device identification). In this case it may be useful to keep the object library and the AGLDEVS.DAT files on different directories, appropriately setting the above mentioned logical names. In order to simplify the use of AGL utility programs it is also suggested to define the following global symbols to be used as DCL foreign commands: $ MF2ASCII :== $AGL3CONFIG:MF2ASCII $ ASCII2MF :== $AGL3CONFIG:ASCII2MF $ IP :== $AGL3CONFIG:IP.EXE NOTE: The installation of the program IP is REQUIRED to allow proper functioning of the testing procedures. If you are installing the Tektronix window process (GPXSERV.EXE) you may also want to define it as a foreign command: Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 8 $ GPXSERV :== $ AGL3CONFIG:GPXSERV A template of the above definitions may be found into the kit provided file VMSCMD.COM. The above definitions can be included in the SYSLOGIN.COM procedure so that each user will have the command synonyms automatically defined at login. 2.2.4 Moving files to their places After the definitions of the above defined logicals, the installation of AGL may be completed with the command: @AGLVMS INSTALL which will copy the run time required files onto target directories. Files will be copied as follows: AGLDEVS.DAT to AGL3CONFIG AGL.OLB to AGL3LIB MF2ASCII.EXE to AGL3CONFIG ASCII2MF.EXE to AGL3CONFIG IP.EXE to AGL3CONFIG [1] *.CAP to AGL3CONFIG *.NFN to AGL3CONFIG GPXSERV.EXE to AGL3CONFIG [2] X11SERV.EXE to AGL3CONFIG [3] KILLSERV.EXE to AGL3CONFIG [3] [1] The availability of the test program may be useful in order to spot possible sources of troubles which are not evident just after installation. [2] The program GPXSERV.EXE is only required to created Tek- tronix compatible windows on the GPX/VMS workstations. It will be generated only if the related command file is exe- cuted (see above). [3] The X11 window support programs are only available if you executed the AGLVMS procedure with the X11 parameter. All other files are neither required nor necessary for the functioning of AGL and may be deleted (you may want to get printed copies of documentation before deleting related files). Documentation files may also be made available to users according to site specific procedures. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 9 NOTE: The only files which MUST necessarily be in the AGL3CONFIG directory are: AGLDEVS.DAT, *.NFN and *.CAP (but see also the note in section 1.1). All other files can be moved to other directories if preferred, provided the logical names and symbols are modified accordingly. 2.2.5 Installation testing Starting with version 3.3 a single test program is provided with the AGL kit named ip.exe. This program is an improved version of the former intplot program and accepts command input either from a file or from the keyboard. A set of input files for the program ip is provided the AGL kit in order to test various features. These files are named *.m. The testing procedures can then be run with the command: $ IP testfile [device:] where testfile is one of the kit provided command files *.M quoted above and device is an optional device specification (the colon is required). Device must specify a device name included into configuration. If your current terminal has been included into AGLDEVS.DAT (and is a graphic terminal!!) you may use the default (which is TT:) to get output onto your current terminal. All testing runs will produce a file called "aglerr.log" containing debugging information which may be useful to trace installation errors. 2.2.6 Compatibility library In order to maintain some level of compatibility with AGL 2.x an interface library has been provided which can be used by program designed for AGL 2.2. No guarantees about completeness of the interface and of the related function is made, but it may be an useful mean to keep old program working. NOTE: This interface library is provided only for compatibi- lity purposes and users are HIGHLY discouraged to use it to develop new programs. The library may be built by means of the command file VMSFIOLD.COM provided with the kit. When linking a program with the interface library you must specify first the interface library, then the AGL library in the link command. You must also ignore warnings due to double definitions of symbols. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 10 2.3 MS-DOS Installation Installation under MS-DOS operating system will require the availability of the following optional software products: - Microsoft C compiler (Vers. 5.00) - Microsoft FORTRAN compiler (Vers. 4.00) [1] - Microsoft Linker to be used with above compilers - Microsoft Librarian to be used with above compilers [1] The Fortran compiler is only needed for the Fortran interface. C only programs can use AGL without compiling and linking with the Fortran interface. Details on the AGL support for the PC screen are provided in: AGL Support for IBM-PC (and Clones) Screen (file: ibmpcscr.doc) 2.3.0 Microsoft C and FORTRAN specific hints There are some difficulties connected with the use of libraries written in C from FORTRAN programs. This is mainly due to the duplication of some modules into the run time libraries needed to support FORTRAN and C programs. Microsoft suggests a way to link together FORTRAN and C programs (See Microsoft provided User Guide, Mixed Language Support). Here we suggest a better way. The following has been tested only with Microsoft C 5.1 and Microsoft FORTRAN 4.1, but there is no reason why it shouldn't work also with previous (or following) versions. Our suggestion is as follows: instead of building what Microsoft calls a C compatible FORTRAN library (or, on the other side, a FORTRAN compatible C library) which cannot be used stand alone, but must be linked together with the C library (FORTRAN library), you might include the required C modules into the FORTRAN library, which then will be used as the standard FORTRAN library and will allow to link FORTRAN program with libraries developed in C (such as AGL) without the need to specify directly the libraries to use. The FORTRAN language processor FL will search the default library and will find the required C modules into it. To do that you may use the Microsoft provided librarian as Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 11 shown below in the case of the math emulator large memory model library: LIB LLIBFORE Operation: +LLIBCE.LIB (Add C modules) List file: Output library: NFLIB.LIB .... a lot of messages .... after that you must still delete from the library two modules which have conflicting entry points: LIB NFLIB.LIB Operation: -lrot-em35 List file: Output library: Now the new library NFLIB.LIB will contain all the modules required to link FORTRAN and C programs. You must rename it LLIBFORE.LIB and put it on the default library directory in order to have it as default FORTRAN library (this will overwrite the original LLIBFORE.LIB). Note that the same operations are suitable for the library LIBBFOR7, but the modules to delete in the second step above are: "lrot" and "8785". 2.3.1 Library generation The command procedure AGLDOS.BAT included in the distribution kit will perform a recompilation of the whole library together with utility and test programs. NOTE: the command files are suitable for the combined version of the FORTRAN library as described in section 2.3.0, they will likely fail to link with standard organizations of the libraries. The customization step on MS-DOS systems is usually required to extract unneeded drivers in order to limit memory occupation. You may refer to section 3 for directions about driver modules extraction. In order to allow different settings of the compiler switches the file MAKEFILE.PC is also provided. You can use it to generate an AGL building procedure as follows: touch readme.doc make -n -f makefile.pc > myagldos.bat Note 1: The Make utility referred to in this section is not the Microsoft provided MAKE program, in that the latter is not fully compatible with standard make utilities as found on most Unix system. It is instead a true Make program as can be found in any "Unix environment Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 12 emulation" package for MS-DOS. Note also that the make command above will also work on any Unix system and will generate the correct building procedure for MS- DOS. Note 2: The makefile includes dummy dependencies to the file README.DOC, so that if a version of the library has been already generated, a full new version can be obtained by "touching" the file README.DOC. The touch utility should be available together with any version of the make utility. By editing the file makefile.pc compiler, and linker settings can be modified as needed and the batch file myagldos.bat can be used to recompile the library. As an alternative you may also use an editor to modify all occurrences of the compiling switch directly into AGLDOS.BAT. To recompile the whole library proceed as follows: - Copy all the AGL kit files into a scratch directory (not the same containing previous versions of AGL). - Execute the command file AGLDOS.BAT (this may require some time) possibly after the generation of the customized version of the batch file as directed above. 2.3.2 Configuration file You must provide a configuration file named AGLDEVS.DAT on the AGL standard directory to define names which you will use to identify output devices (see description in sect. 3). 2.3.3 Environment You must provide the directory \AGL on your hard disk for all the files needed at run-time. 2.3.4 Installation testing Starting with version 3.3 a single test program is provided with the AGL kit named ip.exe. This program is an improved version of the former intplot.exe program and accepts command input either from a file or from the keyboard. A set of input files for the program ip is provided the AGL kit in order to test various features. These files are named *.m. The testing procedures can be run with the command: Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 13 IP testfile [device:] where testfile is one of the kit provided command files *.m quoted above and device is an optional device specification (the colon is required). Device must specify a device name included into configuration. If the name tt is properly declared into AGLDEVS.DAT you may use the default to get output on the screen (see the IBM-PC screen specific manual for details). All testing runs will produce a file called "aglerr.log" containing debugging information which may be useful to trace installation errors. 2.3.5 Moving files to their places After the test you must copy the required files into target directories: AGLDEVS.DAT to \AGL AGL.LIB to \LIB (or any directory of your choice) MF2ASCII.EXE to \BIN (or any directory of your choice) ASCII2MF.EXE to \BIN (or any directory of your choice) IP.EXE to \BIN (or any directory of your choice) *.CAP to \AGL *.NFN to \AGL AGL.H to \INCLUDE (or any directory of your choice) The directory \AGL is the only one which cannot be changed after library compilation (its name is defined into the OS specific definition file: IBMPCDEP.H, and can be changed, if necessary, before library compilation). All the other directory names are only suggestions suited to most standard MS-DOS installations, but can be changed, if required. It is suggested that the library file is contained into a directory automatically searched for by the LINK program, the executable files are contained into a directory in the program execution path and the agl.h file in a directory in the include file path. All other files are neither required nor necessary for the functioning of AGL and may be deleted (you may want to get printed copies of documentation before deleting related files). Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 14 3 CONFIGURATION FILE AGL will perform association between device names and device types on the basis of a configuration file named: AGLDEVS.DAT. The file AGLDEVS.DAT is firstly searched for in the user's current directory, then in the AGL standard directory. Each line of the file contains data related to a physical device according to the following format: <device>:<driver>:<node>:=<command> where: <device> Is the identification of the physical device according to the rules of the operating system. The special device TT stands for the current user's terminal and it is meaningful only in the user's local configuration file. <driver> Is the identification of the corresponding driver as specified in the driver configuration module. Some drivers require further specifications to select specific characteristics of the device (this is device dependent) (e.g.: tkg.vt640). <node> Is the optional specification of the remote node (provided for future support of device in a distributed environment). <command> Is the optional command to be executed when the device is closed. The = sign is required and is not part of the command. The % sign may be used within the command to indicate the place where the driver generated file name must be put into the command line. The colons are field separators. If the node field is void and the command field must be provided, a double colon is required as in: ps:pscript::=print % laser1 # Comment Any (portion of) line after a # sign is considered as a comment and discarded. If a # sign must be included in the line for any reason (E.g. in the print command part of the line, for O.S. specific reasons) it must be doubled (i.e.: ## stands for a Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 15 single # sign). Blank lines or lines containing comments only are also discarded. As an example we assume that the configuration files on the user's current directory contains the following line: tt:tkg.cit101 # This is a comment and the system wide configuration file contains the following lines: nl:null ps:pscript::=lpr -r % # Comment To simplify portability every name checking is performed in lower case. Names in the above file must thus be entered in lower case. The user will thus be able to use his/her current terminal (declared as a CIT101) the null device and a postscript printer. The AGL generated postscript file will be printed and deleted. Any settings in the global file agldevs.dat can be overridden by a user which define a file with the same name into his/her current directory. This may be useful to define the type of the current interactive terminal, which in some instances cannot be defined statically at a system level. A line as follows: tt:tkg.t4010 within the user defined agldevs.dat file will declare the current interactive terminal as a Tektronix 4010. As a further technique to specify device type the user may define the environment variable AGL3DEV as in the following example: setenv AGL3DEV tkg.t4010 the content of such variable will be used if the device name specified in the application program cannot be found either in the global or in the user's agldevs.dat file. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 16 4 CUSTOMIZATION Customization of AGL library, performed at the source code level, is needed in order to either extract specific drivers from the library, or to include newly developed ones. 4.1 Driver selection Driver selection, in order to include only required drivers, may be useful on systems which suffer of memory space. Looking into the system dependent makefile you will notice three lines which control the inclusion of specific drivers, such as: DRIVERS_O = nulldrv.o pscrdrv.o hpgldrv.o tekdrv.o rastdrv.o DRIVERS = -DNULLDRV -DPSCRDRV -DHPGLDRV -DTEKDRV -DRASTDRV You may keep a driver out of your implementation simply deleting from these lines the reference to the driver. E.g.: to exclude the null driver you must delete the names "nulldrv.o" from the first line, and "-DNULLDRV" from the second. 4.2 Driver inclusion To include a specific driver you must retype the three references into the above quoted lines of the system specific makefile. Obviously only drivers supported by the target operating system can be included (see list in appendix). 4.3 Notes to VAX/VMS VAX/VMS is not provided with a standard Make facility, so a building command procedure is provided for VMS instead of a makefile. If you want to customize drivers in a VAX/VMS installation you must use an editor to delete all occurrences of the driver related names into the building procedure (AGLVMS.COM). Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 17 5 TROUBLESHOOTING This section provides useful information for AGL installation troubleshooting, and helps the system manager in error tracking and fixing. Although some error conditions may be system dependent, troubleshooting procedures are essentially the same on any machine, so that a general review is provided. 5.1 Installation errors Installation errors may arise from a variety of sources. Any system manager should know standard points to check depending on the error messages output during installation. More specifically you should check for: - available disk space. - read/write access rights to directory. - proper installation of compilers, standard include and object libraries, linker. 5.2 Test programs errors Errors or not proper functioning will most likely arise when running the test program ip. After the installation the program ip should be exercised with all the procedures provided (files *.m) and on various devices to check for installation errors. It is also good practice to exercise the installation from a standard user account, in order to avoid that problems due to file protections or the like may go unnoticed until a program is run by users. The output of each procedure is self explaining, i.e. after the run graphic output should be correctly generated on the selected device. Note that error output and debug information are not direct- ly displayed but are instead written onto a file named: aglerr.log. This file must be checked for possible error messages after running the test program. Debug output can be ignored in this phase, but may be useful to track possible source of trou- bles. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 18 Error messages are identified by an error number (check into the reference manual appendix for code interpretation). Here, anyway, the most frequent error codes and explanations are briefly listed. Code 306 - Error opening AGLDEVS.DAT file The configuration file AGLDEVS.DAT is not available either on the current directory or on the AGL standard directory, or it is not read accessible. Check existence of the file and access rights (it must be read accessible by everybody). Code 307 - Error opening caps file Code 308 - Error reading caps file This error codes are specific of the driver for Tektronix compatible devices. This driver requires that a cap file for the specific device is available on the AGL standard directory. Debug information into aglerr.log should spot out the name of the required cap file. Note that the *.cap files must be on the AGL standard directory as specified in the system dependent make file (symbol: AGLSTDIR). This problem may also derive from an error in the device specification recorded into one of the two AGLDEVS.DAT files (see the Tektronix device specific information into file TEKLIKE.DOC for details). Code 310 - Device driver name cannot be found By inspecting the debug output you may find out more hints to fix the problem. If the final Driver name comes out to be AGL3DEV, then the name specified at viewport opening cannot be found either into one of the two configuration files or by translating the environment variable AGL3DEV. Specify a correct device name to the test program and run the test again. If the final driver name is one of the supported drivers then is the driver itself which has not been included into confi- guration. The macro ident.m can be used with the program ip to check for drivers included into configuration. I.e. the command: ip ident.m will display a list of the drivers included into your configura- tion. If the required device driver is not included into your configuration you must follow directions to include it as speci- fied in section 4 of this manual. 5.3 User program errors The standard installation procedure directs the system manager to perform installation testing BEFORE moving the Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 19 generated files into target directories, in order to ensure that major installation problems are avoided. Further error conditions may thus arise when user programs are run after the whole installation process is completed. If the same error has not been previously fixed when testing the installation by the test programs, something could be wrong with the last part of the installation, i.e. the moving of generated places onto target directories. In this case the system manager should first check that files have been correctly moved to the required directories (see sections above for system specific information about standard AGL directory) and that users have read access to the files. To get further information about the error conditions either the user program may be recompiled after including the DEBUG facility (with a call: AG_SSET("DEBUG")) and run again to gene- rate more information, or the AGL test program ip can be moved to the user directory and recompiled with the installed version of AGL to get error and debug output in the aglerr.log file. Then troubleshooting directions listed in sect. 5.2 can be applied again. Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 20 APPENDIX A CURRENTLY SUPPORTED DEVICES In the following table the currently supported graphic devices are listed: | | |U| |V|D|n| |M|O|i| Device identification | AGL type | Caps file |S|S|x| -------------------------+--------------+------------+-+-+-+ | | | | | | Apollo Window Syst. (1) | window | No | | |x| | | | | | | Apple Laser Writer | pscript | No |x|x|x| | | | | | | CGA | ibmpc | No | |x| | | | | | | | CIT101 with CIG 201 card | tkg.cit101 | cit101.cap |x|x|x| | | | | | | DEC VT125 Terminal | vt125 | No |x| | | | | | | | | DEC VT240 Terminal | vt125 | No |x| | | | | | | | | DEC VT100 with Retrogr. | tkg.vt640 | vt640.cap |x| |x| | | | | | | EGA | ibmpc | No | |x| | | | | | | | EGC (Olivetti/AT&T) | ibmpc | No | |x| | | | | | | | Epson FX-80 printer (2) | raster | No |x|x|x| | | | | | | HDS 2200 | tkg.hds22 | hds22.cap |x|x|x| | | | | | | HPGL Plotters | hpgl | No |x|x|x| | | | | | | LN03 plus Laser printer | tkg.ln03 | ln03.cap |x|x|x| | | | | | | Null device | null | No |x|x|x| | | | | | | QMS Laser Printer | tkg.qms | qms.cap |x|x|x| | | | | | | Raster devices (General.)| raster | No |x|x|x| | | | | | | Tektronix 4010 (3,4) | tkg.t4010 | t4010.cap |x|x|x| | | | | | | Tektronix 4014 (3,4) | tkg.t4014 | t4014.cap |x|x|x| | | | | | | Sep 20 09:51 1993 AGL Installation - Vers. 3.61 Page 21 Tektronix 4105 | tkg.t4100 | t4100.cap |x|x|x| | | | | | | Sun View (1) | window | No | | |x| | | | | | | Versatec V-80 | raster (5) | No |x|x|x| | | | | | | X-window 11 (1) | window | No | | |x| Notes: (1) Requires the system specific window server (see window.doc). (2) Requires the Epson specific rasterizing program (see: raster.doc). (3) The two terminal types are treated exactly in the same way. They are distinct only for compatibility with previous versions of the library. (4) The same driver may be used to get graphic output on Tek- tronix emulating windows on GPX/VMS workstations (see the related manual in file gpxvms.doc for details). (5) Requires the Versatec specific rasterizing program (see: raster.doc). The rasterizing program has been tested only under VMS.