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.

Here is a short example for a DISLIN C programm:

               #include 
               #include "dislin.h"
               main()
               {
                 disini ();
                 messag ("This is a test", 100, 100);
                 disfin ();
               }
An example for a DISLIN C++ programm is:

               #include 
               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 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.
-cpp for compiling a C++ program 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:

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 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 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 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 name of a device.
options is an optional field of keywords (see DISMOV).

D I S G I F

DISGIF displays a GIF file on the screen, or converts it to another format.

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

Additional note:

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 van be used within DISGCL.

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

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

WWW Home Page

DISLIN is available from the Web sites:

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 Sonnensystemforschung, Max-Planck-Str. 2,
   D-37191 Katlenburg-Lindau, 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. Licenses for commercial use are available from the site http://www.dislin.de. Commercial use means selling of programs linked with DISLIN or using DISLIN in an environment related to business.
Next | Previous | Contents