           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 centimetre 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 plot files. Device-inde-
pendent plot files or metafiles can be coded in ASCII or bi-
nary format.  Device-dependent plot files 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 plot files.

 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 laser printers  in the last  few
    years.  Some of the PostScript features such as hardware
    fonts and shading can be used within DISLIN.  PostScript
    is a trademark of Adobe Systems, Inc.

 d) an EPS file
    the  Encapsulated PostScript  file  format is similar to 
    the PostScript format.  It is useful for importing Post-
    Script files into other applications.
 
 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 true colour
    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 true colour 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, GRAFP or GRAFMP
      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/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 program:

               #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/95

Several  DISLIN  distributions contain  native libraries for 
the programming language Fortran 90/95 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.

Notes:
 
     - All program units in Fortran 90 programs that contain
       calls to DISLIN routines should include the statement
       'USE DISLIN'. The module 'DISLIN' contains interfaces 
       for all DISLIN routines  and enables  the compiler to
       check  the  number  and type  of parameters passed to
       DISLIN routines.

     - Since  version 9.1 of  DISLIN, the array declarations 
       in the  DISLIN  module file are changed from assumed-
       shape arrays to explicit-shape arrays for native For-
       tran 90 libraries.  All  DISLIN  Fortran 90 libraries 
       (native of wrapper) use  now  the same interfaces.
       A missing 'USE DISLIN' statement for a native Fortran
       90 library of DISLIN should no longer cause a general
       protection fault.

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) floating point 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 plot files to devices 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 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 plot file  to a device. CGM and  GKSLIN files
can  be used  for all  devices  while  device-dependent plot
files can only  be sent to corresponding devices.

Command:     DISDRV   filename[.MET]   [device]   [options]

filename     is the name of a plot file.
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.

                         D I S G C L

DISGCL is an interpreter for DISLIN.  All DISLIN  statements
can be written to a script file  and then  be executed  with
DISGCL, or can be entered in an interactive mode. High-level
language  elements  such variables,  operators, expressions,
array operations,  loops and  user-defined functions  can be
used within DISGCL.

Command:     DISGCL  [filename[.gcl]]  [args]  [options]

filename     is the name of a DISGCL script file. The exten-
             sion '.gcl' is optional.
args         are optional  arguments  that can be  passed to
             DISGCL scripts (see DISGCL).
options      is an optional  field  of keywords separated by
             blanks (see DISGCL).

2.10  WWW Homepage

DISLIN is available from the web site

  https://www.dislin.de    

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 
   Email: michels@dislin.de

2.12 License Information

The DISLIN distributions can be used freely without any re-
strictions. 
