           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) an EPS file
    the  Encapsulated PostScript  file  format is simular to 
    the PostScript format.  It is useful for importing Post-
    Script files into other appications.
 
 e) a PDF file
    The Portable Document Format  is the  de facto  standard 
    for the electronic exchange of documents. Compressed and
    non compressed PDF files can be created by DISLIN. Post-
    Script fonts can be used for  PDF  files in the same way 
    as for PostScript files. 

 f) a HPGL file
    Plot vectors and  colours  are  coded in a  language re-
    cognized by Hewlett-Packard plotters.

 g) 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.
 
 h) a SVG file
    Scalable  Vector  Graphics (SVG)  is a  language for de-
    scribing graphics  in XML.  SVG files  can be  displayed 
    directly by some browsers if a  corresponding plug-in is
    installed. The most of the standard PostScript fonts are
    supported by the DISLIN SVG files.

 i) a GIF file

    The  Graphics  Interchange Format (c)  is the  Copyright 
    property of Compuserve Incorporated.
       
 j) a TIFF file
    The raster format TIFF can be used for storing graphical
    output.  DISLIN can create 8 bit palette  and truecolour
    TIFF files.

 k) 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.  DISLIN supports 8 bit
    palette and truecolour PNG files.
 
 l) a PPM file
    The portable pixmap format  is a well-known colour image 
    file format in the UNIX world.  There are many tools for
    converting PPM files into other image formats. The pixel
    values are stored in DISLIN PPM files in plain bytes  as
    RGB values.

 m) a BMP file
    The Windows Bitmap  format  can be used for storing gra-
    phical output.  DISLIN can create  uncompressed 8 and 24
    bit BMP files.

 n) 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.

 o) 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 ERRMOD and ERRDEV.

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.

Here is a short example for a DISLIN C programm:

               #include <stdio.h>
               #include "dislin.h"
               main()
               {
                 disini ();
                 messag ("This is a test", 100, 100);
                 disfin ();
               }

An example for a DISLIN C++ programm is:
      
               #include <iosteam>
               namespace dislin {
               #include "dislin.h"
               }
               main()
               {
                 dislin::disini ();
                 dislin::messag ("This is a test", 100, 100);
                 dislin::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.
       -cpp  for compiling a C++ programs before linking.
       -r    for running programs after linking.
       -a    for compiling, linking and running programs.
       -r8   for using the double precision libraries of
             DISLIN. 
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.
          -  The most DISLIN distributions contain libraries
             for single precision (32 bit) and double preci-
             sion (64 bit) floatingpoint parameters. 
             The double precision  libraries  can be identi-
             fied by the term '_d' in the library filename.
 
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 and XWIN to a smaller  graphics
             window.
options      is an optional field of keywords (see DISDRV).

                         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,  or converts it to another  file
format.

Command:     DISTIF   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  WWW Homepage

DISLIN is available from the Web sites

  http://www.dislin.de    
  http://www.mps.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 Sonnensystemforschung
   D-37191 Katlenburg-Lindau, Max-Planck-Str. 2, Germany
   E-Mail: michels@mps.mpg.de
   Tel.: +49 5556 979 334
   Fax: +49 5556 979 240

2.12 License Information

DISLIN  is free  for non-commercial  use  for the  operating 
systems Linux and FreeBSD and for the GNU compilers GCC+G77/
MS-DOS  and GCC+G77/Windows 9x/NT. 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 librar-
ies.

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, the license  check is ignored,
so that  DISLIN programs can be copied and executed on other
machines.

A valid  DISLIN  license can be received by running the pro-
gram  'license' in the DISLIN directory and sending the out-
put file  'license.lis'  to  the  author,  or  by  using the 
'License Request' at the DISLIN site http://www.dislin.de.



