                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. 
