# 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 centimetre 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 plot files. Device-independent plot files or metafiles can be coded in ASCII or binary format. Device-dependent plot files are available for several printers and plotters.

The file formats are:

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

- a GKSLIN metafile
  Plot vectors are stored as floating point numbers between 0 and 1 in ASCII format. These files are easily transferable from one computer to another.

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

- an EPS file
  the Encapsulated PostScript file format is similar to the PostScript format. It is useful for importing PostScript files into other appications.

- 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. PostScript fonts can be used for PDF files in the same way as for PostScript files.

- a HPGL file
  Plot vectors and colours are coded in a language recognized by Hewlett-Packard plotters.

- a WMF file
  The Windows Metafile format is also supported by DISLIN. Plot vectors are converted to 1/1440 inch. WMF files can contain hardware fonts defined with the DISLIN routine WINFNT.

- an EMF file
  The Windows Enhanced Metafile format is a 32-bit extension of the WMF format. DISLIN stores plot vectors as pixels with the origin in the upper left corner.

- a SVG file
  Scalable Vector Graphics (SVG) is a language for describing 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.

- a GIF file
  The Graphics Interchange Format (c) is the Copyright property of Compuserve Incorporated.

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

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

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

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

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

- a Tektronix, X Window and VGA emulation
  Data can be displayed on graphic terminals such as X Window, VGA and Tektronix 4010/4014.

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

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:

- 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 correspond 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 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 <stdio.h>
                   #include "dislin.h"
                   main()
                   {
                     disini ();
                     messag ("This is a test", 100, 100);
                     disfin ();
                   }

## 2.7 Programming in C++

Some DISLIN distributions contain additional C++ libraries for using DISLIN from C++. All DISLIN routines are implemented as methods of the class Dislin, so that the description of the routines in this DISLIN manual is also valid for C++. An example for a DISLIN C++ programm is:

                   #include <iostream>
                   #include "discpp.h"

                   main()
                   { Dislin g;
                     g.disini ();
                     g.messag ("This is a test", 100, 100);
                     g.disfin ();
                   }

It's also possible to use a DISLIN C library from C++ and call the DISLIN routines as extern C functions:

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

## 2.8 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.

Additional notes:

- All program units in Fortran 90/95 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 Fortran 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.9 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:

- If DLINK is called without parameters, the description of the program will be printed on the screen. There may be other local features available depending upon the operating system used.
- Linking of C programs should be done with the procedure CLINK.
- Linking of Fortran 90 programs should be done with the procedure F90LINK.

## 2.10 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 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 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:

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

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

## 2.11 WWW Home Page

DISLIN is available from the Web site:

- https://www.dislin.de

## 2.12 Printed Manual

A printed manual of Dislin is available from Amazon, or directly from the author. The book describes the current version 11 of Dislin.

| ### The Data Plotting Software DISLIN - Version 11 by Helmut Michels (Author) Paperback : 353 pages Publisher: Shaker Media GmbH: (March. 2017) Language: English ISBN: 978-3-95631-557-2 Weight: 662 g Product Dimension: 17 x 24 cm Price: 22,90 Euro + shipping

## 2.13 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
       Dislin Software
       Am Hachweg 10
       37083 Göttingen, Germany
       Email: michels@dislin.de

## 2.14 License Information

DISLIN can be used freely without any restrictions. Access to the source code is available from the site www.dislin.de via a support contract.

Next | Previous | Contents