Chapter 3: Introductory Routines

3.1 Initialization and Termination

DISINI initializes DISLIN by setting default parameters and

creating a plot file. The level is set to 1. DISINI must be
called before any other DISLIN routine except for those
noted throughout the manual.

The call is: CALL DISINI level 0

DISFIN terminates DISLIN and prints a message on the screen.

The level is set back to 0.

The call is: CALL DISFIN level 1, 2, 3

3.2 Plotting of Text and Numbers

M E S S A G
MESSAG plots text.

The call is: CALL MESSAG (CSTR, NX, NY) level 1, 2, 3

CSTR is a character string (<= 256 characters).

NX, NY are the plot coordinates of the upper left
corner.

N U M B E R

NUMBER plots a floating point number or integer.

The call is: CALL NUMBER (X, NDIG, NX, NY) level 1, 2, 3

X is a floating point number.

NDIG is the number of digits plotted after the deci-
mal point. If NDIG = -1, X will be plotted as
an integer. The last digit of X will be rounded
up.
NX, NY are the coordinates of the upper left corner.

RLMESS and RLNUMB are corresponding routines for user coor-

dinates. They can be used for plotting text and numbers in
an axis system after a call to GRAF.

The calls are: CALL RLMESS (CSTR, XP, YP) level 2, 3

CALL RLNUMB (X, NDIG, XP, YP) level 2, 3

Notes: - To continue character strings and numbers on

the same line, the coordinates (999, 999)
should be sent to MESSAG and NUMBER. The text
or numbers will be plotted after the last plot-
ted text character or number.
- The angle and height of the characters can be
changed with the routines ANGLE and HEIGHT.
- The format of numbers can be modified with the
routines NUMFMT and NUMODE.
- Text and numbers can be plotted in a box if the
routine FRMESS is used.
- The starting point of text and numbers can be
 interpreted as upper left, upper center and up-
per right point if the routine TXTJUS is used.

3.3 Plotting Symbols

S Y M B O L

The routine SYMBOL plots symbols.

The call is: CALL SYMBOL (NSYM, NX, NY) level 1, 2, 3

NSYM is a symbol number between 0 and 21. Available

symbols are given in the Appendix B.
NX, NY is the centre of the symbol in plot coordina-
tes.

Notes: - The size of symbols can be set with HSYMBL.

- SYMROT (ANGLE) defines a rotation angle for
symbols (in degrees). The symbol is rotated in
a counter-clockwise direction.
- A user-defined symbol can be specified with
the routine MYSYMB.

R L S Y M B

RLSYMB plots a symbol where the centre is specified by user

coordinates.

The call is: CALL RLSYMB (NSYM, XP, YP) level 2, 3

3.4 Plotting a Page Border, Background and Header

P A G E R A

PAGERA plots a border around the page.

The call is: CALL PAGERA level 1, 2, 3

P A G F L L

The routine PAGFLL fills the page with a colour.

The call is: CALL PAGFLL (NCLR) level 1, 2, 3

NCLR is a colour value.

P A G H D R

PAGHDR plots a page header at a corner of the page. The hea-

der line contains date, time and user-defined information.

The call is: CALL PAGHDR (CSTR1, CSTR2, IOPT, IDIR)

level 1, 2, 3
CSTR1 is a character string preceding the header
line.
CSTR2 is a character string following the header
line.
IOPT is the page corner where the header is plot-
ted:
 = 1 is the lower left corner.
= 2 is the lower right corner.
= 3 is the upper right corner.
= 4 is the upper left corner.
IDIR is the direction of the header line:
= 0 is horizontal.
= 1 is vertical.

Note: The character size of the header line is 0.6 *

NH where NH is the parameter used in HEIGHT.

3.5 Sending a Metafile to a Device

A metafile can be converted with a driver program and sent

from the operating system to several devices. From within a
user program, the SYMFIL routine is used for this purpose.

S Y M F I L

SYMFIL sends a metafile to a device. It must be called after

DISFIN.

The call is: CALL SYMFIL (CDEV, CSTAT) level 0

CDEV is the name of the device. 'CONS' refers to

the graphics screen, 'XWIN' to an X Window
terminal, 'PSCi' to a PostScript printer,
'KYOi' to a Kyocera laser printer with Pre-
scribe and 'HPLi' to a HP-plotter. The keyword
'NONE' can be used to delete a metafile with
no device plotting.
CSTAT is a status parameter and can have the values
'DELETE' and 'KEEP'.

Notes: - SYMFIL calls the DISLIN driver utility DISDRV.

The parameter 'REVERS' can be passed to DISDRV
from SYMFIL if the routine SCRMOD is called
before with the parameter 'REVERS'.

- Some DISLIN output files such as GKSLIN and

CGM metafiles does not contain a colour table
so that they only can be displayed correctly
if the same colour table is used in the driver
and in the plot program. If a colour table is
saved to a file with the routine VLTFIL, this
colour table file will be passed from SYMFIL
to DISDRV as colour information.

3.6 Including Meta- and Bitmap files into a Graphics

GKSLIN and CGM metafiles created by DISLIN and general BMP

files can be included into a graphics with the routine INC-
FIL.

I N C F I L

The routine INCFIL includes a GKSLIN or CGM metafile created

by DISLIN, or general PNG, BMP, GIF and TIFF files into a
graphics.
The call is: CALL INCFIL (CFIL) level 1, 2, 3

CFIL is a character string that contains the file-

name.

Notes: - For including PNG, BMP, GIF or TIFF files, the

output format must be a raster, PostScript or
PDF format.
- The routine FILBOX (NX, NY, NW, NH) defines a
rectangular area on the page where the file
will be included. (NX, NY) are the plot coor-
dinates of the upper left corner, (NW, NH) are
the width and length of the box in plot coor-
dinates. By default, the entire page will be
used. If the file is a bitmap and the output
format a raster format, the file will be in-
cluded at the point (NX, NY), while NW and NH
will be ignored by default. This means that
images are copied 1:1 to the screen. With the
option FILOPT ('ON', 'SCALE'), images will be
scaled. If the output format is PostScript or
PDF, the image file is always scaled into
the box defined by the parameters NX, NY, NW
and NH. Therefore, NW and NH should have the
same ratio as the width and height of the
image file.
- The routine FILWIN (NX, NY, NW, NH) defines a
rectangle of the image that will be included
instead of the full image. The parameters in
FILWIN must be specified as pixels.
- INCFIL draws by default a frame around the in-
cluded file that can be modified with the rou-
tine FRAME.
- With the statement CALL FILCLR ('NONE'), col-
our values in GKSLIN and CGM metafiles will be
ignored and the current colour is used. The
default is FILCLR ('ALL').

F I L S I Z

The routine FILSIZ returns the size on an image file.

The call is: CALL FILSIZ (CFIL, NWIDTH, NHEIGT, IRET)

level 0, 1, 2, 3

CFIL is a character string that contains the file-

name.
NWIDTH is the returned width of the image in pixel.
NHEIGHT is the returned height of the image in pixel.
IRET contains a returned status that can have the
values:
1: BMP file, 2: GIF file, 3: TIFF file,
4: PNG file, 0: undefined format, -1: error.

F I L T Y P

The routine FILTYP returns the type on a file.

The call is: CALL FILTYP (CFIL, ITYP)
level 0, 1, 2, 3

CFIL is a character string that contains the file-

name.
ITYP contains a returned status that can have the
values:
1: BMP file, 2: GIF file, 3: TIFF file,
4: PNG file, 5: Dislin Image, 6: GKSL,
7: CGM, 8: WMF, 9: HPGL,
10: PostScript, 11: PDF, 12: Aldus WMF,
0: unknown format, -1: error.