@(#)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.
