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

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.

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.

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

The call is:	CALL SYMBOL (NSYM, NX, NY)	level 1, 2, 3
or:	void symbol (int nsym, int nx, int ny);

The call is:	CALL RLSYMB (NSYM, XP, YP)	level 2, 3
or:	void rlsymb (int nsym, float xp, float yp);

The call is:	CALL PAGFLL (NCLR)	level 1, 2, 3
or:	void pagfll (int nclr);

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.

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

The call is:	CALL INCFIL (CFIL)	level 1, 2, 3
or:	void incfil (const char *cfil);

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.

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.