Chapter 2: Basic Concepts and Conventions 2.1 Page Format In DISLIN, the graphics are limited to a rectangular area called the page. All lines outside of or crossing page bor- ders will be suppressed. The size of the page is determined by the routines SETPAG and PAGE. SETPAG corresponds to a predefined page while PAGE defines a global page setting. In default mode, there are 100 points per centimeter and the point (0,0) is located in the upper left corner (Figure 1): (0,0) +----------------------------------+ | | | | | | | DIN A 4 Landscape | | | | | | | +----------------------------------+ (2969,2099) Figure 1 : Default Page (DA4L) 2.2 File Format DISLIN can create several types of plotfiles. Device-inde- pendent plotfiles or metafiles can be coded in ASCII or bi- nary format. Device-dependent plotfiles are available for several printers and plotters. The file formats are: a) a CGM metafile according to the ANSI standard Plot vectors are coded in binary format as non negative integers with 200 points per cm. Because of binary coding, CGM metafiles are smaller than other plotfiles. b) a GKSLIN metafile Plot vectors are stored as floating-point numbers be- tween 0 and 1 in ASCII format. These files are easily transferable from one computer to another. c) a PostScript file PostScript is an international standard language that has been developed for laserprinters in the last few years. Some of the PostScript features such as hardware fonts and shading can be used within DISLIN. d) a Prescribe file The plotfile is created in the graphics language of Kyocera laserprinters and may also contain hardware fea- tures such as shading for rectangles and pies. e) a HPGL file Plot vectors and colours are coded in a language re- cognized by Hewlett-Packard plotters. f) a WMF file The Windows metafile format is also supported by DISLIN. Plot vectors a converted to 1/1440 inch. WMF files can contain hardware fonts defined with the DISLIN routine WINFNT. g) a Java applet file Plot vectors and colours are stored in form of a Java applet. h) a TIFF file The raster format TIFF can be used for storing graphical output. i) a PNG file The Portable Network Graphics format is a compressed and therefore very small raster format for storing graphical output. PNG files can be displayed directly by several Internet browsers. The compression of PNG files is done in DISLIN with the zlib compression routines written by Jean-loup Gailly and Mark Adler. j) an IMAGE file This easy raster format is used by DISLIN to store images. The files contain an ASCII header of 80 bytes and the following image data. k) a Tektronix, VGA and X Window emulation Data can be displayed on X Window terminals, VGA screens and graphic terminals with a Tektronix emulation 4010/ 4014. File formats can be set with the routine METAFL. The file- name consists of the keyword 'DISLIN' and an extension that depends on the file format. An alternate filename can be chosen by calling the routine SETFIL. Both subroutines must be called before the initialization routine DISINI. 2.3 Level Structure of DISLIN Most routines in DISLIN can be called anywhere during pro- gram execution. Certain routines, however, use parameters from other routines and must be called in a fixed order. DISLIN uses a level structure to control the order in which routines are called. The levels are: 0 before initialization or after termination 1 after initialization or a call to ENDGRF 2 after a call to GRAF 3 after a call to GRAF3 or GRAF3D. Generally, programs should have the following structure: (1) setting of page format, file format and filename (2) initialization (3) setting of plot parameters (4) plotting of the axis system (5) plotting the title (6) plotting data points (7) termination. 2.4 Conventions The following conventions appear throughout this manual for the description of routine calls: - INTEGER variables begin with the character N or I - CHARACTER variables begin with the character C - other variables are REAL - arrays end with the keyword 'RAY'. Notes: - CHARACTER variables may be specified in upper or lower case and may be shortened to four characters. - DISLIN stores parameters in common blocks whose names begin with the character 'C'. Common block names in user programs should not begin with the character 'C' to avoid possible name equalities. - The Fortran logical units 15, 16 and 17 are reserved by DISLIN for plot and parameter files. - Two types of coordinates are continually referred to throughout the manual: plot coordinates which corres- pond to the page and always have 100 points per cm, and user coordinates which correspond to the scaling of the axis system. 2.5 Error Messages When a DISLIN subroutine or function is called with an ille- gal parameter or not according to the level structure, DIS- LIN writes a warning to the screen. The call of the routine will be ignored and program execution resumed. Points lying outside of the axis system will also be listed on the screen. Error messages can be suppressed or written to a file with the routines UNIT and NOCHEK. 2.6 Programming in C There are two different libraries in DISLIN: one is develo- ped for Fortran programmers and written in the language For- tran, the other is written in the programming language C and useful for C programmers. Though it is possible to call C routines in Fortran programs and Fortran subroutines in C programs, it is easier to use the corresponding library. Especially, the passing of strings can be complicate in mixed language programming. The number and meaning of parameters passed to DISLIN rou- tines are identical for both libraries. The Fortran version uses INTEGER, REAL and CHARACTER variables while the C li- brary uses int, float and char variables. A detailed de- scription of the syntax of C routines is given by the utili- ty program DISHLP or can be found in the header file 'dislin.h' which must be included in all C programs. For example: #include #include "dislin.h" main() { disini (); messag ("This is a test", 100, 100); disfin (); } 2.7 Programming in Fortran 90 Several DISLIN distributions contain native libraries for the programming language Fortran 90 where the source code of DISLIN is written in Fortran 90. Since the passing of para- meters to subroutines and functions can be different in For- tran 90 and Fortran 77, you should not link Fortran 77 pro- grams with Fortran 90 libraries and vice versa. Note: All program units in Fortran 90 programs that contain calls to DISLIN routines must include the statement 'USE DISLIN'. The module 'DISLIN' contains interfaces for all DISLIN routines and enables the compiler the correct passing and checking of parameters passed to DISLIN routines. For example: PROGRAM TEST USE DISLIN CALL DISINI () CALL MESSAG ('This is a test', 100, 100) CALL DISFIN () END PROGRAM TEST 2.8 Linking Programs The linking of programs with the graphics library depends upon the operating system of the computer. Therefore, DISLIN offers a system-independent link procedure that can be used on all computers in the same way. Command: DLINK [option] main option is an optional parameter containing a minus sign and a character. The following options can be used on all computers: -c for compiling programs before linking. -r for running programs after linking. -a for compiling, linking and running programs. main is the name of the main program. Notes: - If DLINK is called without parameters, the de- scription of the program will be printed on the screen. There may be other local features avai- lable depending upon the operating system used. - Linking of C programs should be done with the procedure CLINK. 2.9 Utility Programs The following programs are useful for working with DISLIN. They send plotfiles to devices, check the use of DISLIN rou- tines in Fortran programs and print the description of rou- tines on the screen. D I S H L P DISHLP prints the description of a DISLIN routine on the screen. Command: DISHLP routine [options] routine is the name of a DISLIN routine or a question mark. For a question mark, all routine names will be listed. An empty input terminates the program. options is an optional field of keywords (see DISHLP). D I S M A N DISMAN prints an ASCII version of the DISLIN manual on the screen. Command: DISMAN [options] options is an optional field of keywords (see DISMAN). D I S P R V DISPRV checks the use of DISLIN routines in a Fortran pro- gram. The type and dimension of parameters and the overlap- ping of common block and routine names with internal DISLIN declarations will be checked. Command: DISPRV filename[.FOR] [options] filename describes the file containing the Fortran code. options is an optional field of keywords (see DISPRV). D I S D R V DISDRV sends a plotfile to a device. CGM and GKSLIN files can be used for all devices while device-dependent plotfiles can only be sent to corresponding devices. Command: DISDRV filename[.MET] [device] [options] filename is the name of a plotfile. device is the name of a device. CONS refers to the graphics screen, XWIN to an X Window terminal, PSCi to a PostScript printer, KYOi to a Kyocera laserprinter with Prescribe and HPLi to a HP- plotter, where i = 1, 2, 3, ..., n is the printer number. options is an optional field of keywords (see DISDRV). D I S H P J DISHPJ sends a GKSLIN or CGM metafile to a printer using a raster graphics emulation (i.e. HP PCL). Command: DISHPJ filename[.MET] [device] [options] filename is the name of the metafile. device is the name of the device. options is an optional field of keywords (see DISHPJ). D I S I M G DISIMG displays an image file on the screen, or converts it to PostScript and TIFF. Command: DISIMG filename[.IMG] [device] [options] filename is the name of the image file. The file must be created with the routine RIMAGE. device is the device name. options is an optional field of keywords (see DISIMG). D I S M O V DISMOV displays a sequence of image files. Command: DISMOV filename[.MOV] [device] [options] filename is the name of a data file where the filenames of the images are stored (1 line for each file- name). The images must be created with the rou- tine RIMAGE. device is the device name. options is an optional field of keywords (see DISMOV). D I S T I F DISTIF displays a TIFF file created by DISLIN on the screen, or converts it to PostScript and an image format. Command: DISTIF filename[.TIF] [device] [options] filename is the name of the TIFF file. The file must be created with the routine RTIFF. device is the device name. options is an optional field of keywords (see DISTIF). D I S G I F DISGIF displays a GIF file on the screen, or converts it to PostScript and TIFF. Command: DISGIF filename[.GIF] [device] [options] filename is the name of the GIF file. device is the device name. options is an optional field of keywords (see DISGIF). D I S A P S DISAPS converts an ASCII file to a PostScript file. Several page layouts can be defined. Command: DISAPS filename [output] [options] filename is the name of the ASCII file. output is the name of the output file. By default, the name of the input file and the extension ps will be used. options is an optional field of keywords (see DISAPS). Note: If a utility program is called without parame- ters, a description of possible parameters will be printed on the screen. DISDRV, for example, lists the local output devices available. 2.10 FTP Sites, WWW Homepage DISLIN is available via ftp anonymous from the following sites: ftp://ftp.gwdg.de/pub/grafik/dislin (fast connection) ftp://linhmi.mpae.gwdg.de/pub/dislin (slower connection) The DISLIN Homepage is: http://www.linmpi.mpg.de/dislin 2.11 Reporting Bugs DISLIN is well tested by many users and should be very bug free. However, no software is perfect and every change can cause new bugs. If you have any problems with DISLIN, con- tact the author: Helmut Michels Max-Planck-Institut fuer Aeronomie D-37191 Katlenburg-Lindau, Max-Planck-Str. 2, Germany E-Mail: michels@linmpi.mpg.de Tel.: +49 5556 979 334 Fax: +49 5556 979 240 2.12 License Information DISLIN is free for the operating systems Linux and FreeBSD and for the GNU compilers GCC+G77/MS-DOS and GCC+G77/Win- dows95. Other DISLIN versions are available at low charge and can be tested free of charge. Programs linked with DIS- LIN can be distributed without any royalties together with neccessary shareable DISLIN libraries. Normally, DISLIN programs check for a valid DISLIN license in the file 'license.dat' in the DISLIN directory. If DISLIN is not installed on a system, a DISLIN program can be execu- ted if the file 'license.dat' is created with the entry 'License: Runtime'. The environment variable 'DISLIN' should be set to the di- rectory where the file 'license.dat' is placed. A valid DISLIN license can be received by running the program 'license' in the DISLIN directory and sending the output file 'license.lis' to the author.