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.