# Chapter 3: Introductory Routines

## 3.1 Initialization and Termination

D I S I N I

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
or: | void disini (void);

D I S F I N

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
or: | void disfin (void);

## 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
or: | void messag (const char *cstr, int nx, int ny);

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
or: | void number (float x, int ndig, int nx, int ny);

X | is a floating point number.
NDIG | is the number of digits plotted after the decimal 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 coordinates. 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

or: | void rlmess (const char *cstr, float xp, float yp);
| void rlnumb (float x, int ndig, float xp, float yp);

Additional 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 plotted 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 upper 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
or: | void symbol (int nsym, int nx, int ny);

NSYM | is a symbol number between 0 and 23. Available symbols are given in the Appendix B. The following constants can be used for symbol numbers in C and Fortran 90/95 programs:
       SYMBOL_SQUARE          0   SYMBOL_OCTAGONCROSS         13
       SYMBOL_OCTAGON         1   SYMBOL_SQUARETRIANGLE       14
       SYMBOL_TRIANGLE_UP     2   SYMBOL_CIRCLE               15
       SYMBOL_PLUS            3   SYMBOL_SQUARE_FILLED        16
       SYMBOL_CROSS           4   SYMBOL_OCTAGON_FILLED       17
       SYMBOL_DIAMOND         5   SYMBOL_TRIANGLE_UP_FILLED   18
       SYMBOL_TRIANGLE_DOWN   6   SYMBOL_DIAMOND_FILLED       19
       SYMBOL_SQUARECROSS     7   SYMBOL_TRIANGLE_DOWN_FILLED 20
       SYMBOL_STAR            8   SYMBOL_CIRCLE_FILLED        21
       SYMBOL_DIAMONDPLUS     9   SYMBOL_DOT                  21
       SYMBOL_OCTAGONPLUS    10   SYMBOL_HALFCIRCLE           22
       SYMBOL_DOUBLETRIANGLE 11   SYMBOL_HALFCIRCLE_FILLED    23
       SYMBOL_SQUAREPLUS     12
NX, NY | is the centre of the symbol in plot coordinates.

Additional 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
or: | void rlsymb (int nsym, float xp, float yp);

## 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
or: | void pagera (void);

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
or: | void pagfll (int nclr);

NCLR | is a colour value.

P A G H D R

PAGHDR plots a page header at a corner of the page. The header line contains date, time and user-defined information.

The call is: | CALL PAGHDR (CSTR1, CSTR2, IOPT, IDIR) | level 1, 2, 3
or: | void paghdr (const char *cstr1, const char *cstr2, int iopt, int idir);

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 plotted:
= 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.

Additional 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
or: | void symfil (const char *cdev, const char *cstat);

CDEV | is the name of the device. 'CONS' refers to the graphics screen, 'XWIN' to a X Window terminal, 'PSCi' to a PostScript printer, 'KYOi' to a Kyocera laser printer with Prescribe 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'.

Additional note:

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

## 3.6 Including Meta- and Bitmap files into a Graphics

GKSLIN and CGM metafiles created by DISLIN and general PNG, BMP, GIF or TIFF files can be included into a graphics with the routine INCFIL.

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
or: | void incfil (const char *cfil);

CFIL | is a character string that contains the filename.

Additional 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 coordinates of the upper left corner, (NW, NH) are the width and length of the box in plot coordinates. 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 included 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 will be 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 FRAME.
- With the statement CALL FILCLR ('NONE'), colour values in GKSLIN and CGM metafiles will be ignored and the current colour is used. The default is FILCLR ('ALL').
- A transparent colour can be defined for including image files with the routine IMGTPR.

F I L S I Z

The routine FILSIZ returns the size on an image file.

The call is: | CALL FILSIZ (CFIL, NWIDTH, NHEIGHT, IRET) | level 0, 1, 2, 3
or: | int filsiz (const char *cfil, int *nwidth, int *nheight);

CFIL | is a character string that contains the filename.
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 of a file.

The call is: | CALL FILTYP (CFIL, ITYP) | level 0, 1, 2, 3
or: | int filtyp (const char *cfil);

CFIL | is a character string that contains the filename.
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.

Next | Previous | Contents