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 borders 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 2.1):

     (0,0) +----------------------------------+
           |                                  |
           |                                  |
           |                                  |
           |        DIN A 4  Landscape        |
           |                                  |
           |                                  |
           |                                  |
           +----------------------------------+ (2969,2099)

             Figure 2.1 : Default Page (DA4L)

2.2 File Format

DISLIN can create several types of plotfiles. Device-independent plotfiles or metafiles can be coded in ASCII or binary format. Device-dependent plotfiles are available for several printers and plotters.

The file formats are:

File formats can be set with the routine METAFL. The filename 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 program 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:

  1. INTEGER variables begin with the character N or I
  2. CHARACTER variables begin with the character C
  3. other variables are REAL
  4. arrays end with the keyword 'RAY'.
Notes:

2.5 Error Messages

When a DISLIN subroutine or function is called with an illegal parameter or not according to the level structure, DISLIN 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 different DISLIN libraries for the programming languages Fortran 77, Fortran 90 and C. The DISLIN C library 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 routines are identical for all libraries. The Fortran version uses INTEGER, REAL and CHARACTER variables while the C library uses int, float and char variables. A detailed description of the syntax of C routines is given by the utility 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 parameters to subroutines and functions can be different in Fortran 90 and Fortran 77, you should not link Fortran 77 programs with Fortran 90 libraries and vice versa.

Important:

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:

2.9 Utility Programs

The following programs are useful for working with DISLIN. They send plotfiles to devices, check the use of DISLIN routines in Fortran programs and print the description of routines 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 program. The type and dimension of parameters and the overlapping 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 filename). The images must be created with the routine 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.

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 parameters, 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:

The DISLIN Homepage is:

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, contact the author:

   Helmut Michels 
   Max-Planck-Institut fuer Aeronomie, Max-Planck-Str. 2,
   D-37191 Katlenburg-Lindau, 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/Windows95. Other DISLIN versions are available at low charge and can be tested free of charge. Programs linked with DISLIN 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 executed if the file 'license.dat' is created with the entry 'License: Runtime'. The environment variable 'DISLIN' should be set to the directory 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.

This manual of the data plotting software DISLIN can be copied and distributed freely.


Next | Previous | Contents