           Chapter 6: Parameter Setting Routines

All parameters in  DISLIN  have default  values  set by  the
initialization routine DISINI.  This chapter summarizes sub-
routines  that allow the user  to alter default values.  The
following routines can be called from level 1, 2 or 3 except
for those noted throughout the chapter. Subroutines that can
only be called  from level 0  must appear before DISINI.  In
general, parameter setting routines should be called between
DISINI and the plotting routines they affect.

6.1 Basic Routines

6.1.1 Resetting Parameters

                         R E S E T

RESET sets parameters back to their default values.

The call is:  CALL RESET (CNAME)               level 1, 2, 3

CNAME         is a character string  containing the name  of
              the routine whose parameters will be set  back
              to default values. If CNAME = 'ALL', all para-
              meters in DISLIN will be reset.

6.1.2 Modifying the Origin

                         O R I G I N

In  DISLIN,  all lines  are plotted  relative  to the origin
which is a  point located  in the upper  left corner  of the
page.  Modifying this point by ORIGIN produces a shifting of
plot vectors on the page.

The call is:  CALL ORIGIN (NX0, NY0)                 level 1

NX0, NY0      are the coordinates of the origin.
                                            Default: (0, 0).

6.1.3 Changing the Foreground Colour

                         C O L O R

COLOR defines the colours used for plotting text and lines.

The call is:  CALL COLOR (CNAME)               level 1, 2, 3

CNAME         is a character string that can have the values
              'BLACK',  'RED',   'GREEN',  'BLUE',   'CYAN',
              'YELLOW', 'ORANGE', 'MAGENTA', 'WHITE', 'FORE'
              and 'BACK'. The keyword 'FORE' resets the col-
              our  to the default value,  while the  keyword
              'BACK' sets the colour  to the background col-
              our.

Note:         Colours can also be defined with SETCLR  which
              selects  a colour index  from an actual colour
              table (see chapter 11).

6.1.4 File Format Control

                         M E T A F L

METAFL defines the metafile format.

The call is:  CALL METAFL (CFMT)                     level 0

CFMT          is a  character string  that defines  the file
              format.
  = 'GKSL'    defines a GKSLIN metafile.
  = 'CGM'     defines a CGM metafile.
  = 'POST'    defines a PostScript file.
  = 'PSCL'    defines  a coloured  PostScript  file  with  a
              black background.
  = 'PDF'     defines a PDF file.
  = 'KYOC'    defines a Kyocera file.
  = 'HPGL'    defines an HPGL file.
  = 'JAVA'    defines a Java applet file.
  = 'WMF'     defines a Windows metafile.
  = 'TIFF'    defines a TIFF file.
  = 'PNG'     defines a PNG file.
  = 'PPM'     defines a portable pixmap format.
  = 'IMAG'    defines an image file.
  = 'VIRT'    defines a virtual file.  The metafile  is hold
              in a raster format in computer memory  and can
              be saved on a file  with the  routines  RIMAGE
              and RTIFF. 
  = 'CONS'    defines a graphics output on the screen.
  = 'XWIN'    defines an X Window display.
  = 'XWIi'    defines  an X Window  display,  where i is the
              window  number  between  1 and 5.  By default,
              window 1  is situated in the  lower right cor-
              ner,  window 2  in  the  upper  right  corner,
              window 3  in the  upper left corner,  window 4
              in the lower left  corner  and window 5 in the
              centre of the screen.
                                     Default: CFMT = 'GKSL'.

Notes:      - The default size  of  JAVA,  TIFF,  PNG,  PPM, 
              IMAGE and  virtual files is set to   853 x 603
              points  but can be modified with  the  routine
              WINSIZ. 
            - JAVA applet files  created  by DISLIN  can  be 
              compiled with  Java  and then  displayed  in a
              browser.  The class names  of the  applets are
              identical  with the  filenames  of  the output 
              files.  They can be changed  with  the routine
              SETFIL. 
            - The default colour table loaded by  DISINI  is
              'RGREY'  for  greyscaled  PostScript files and
              'RAINBOW' for the other file formats. Coloured
              PostScript  files with a white background  can
              be created  with  the keyword  'PSCL'  and the
              statement CALL SCRMOD('REVERS') before DISINI,
              or with the keyword  'POST'  and the statement
              CALL SETVLT('RAINBOW') after DISINI.

                         S E T F I L

By default, the plotfile name consists of the keyword  'DIS-
LIN' and an extension  that depends  on the file format.  An
alternate filename can be set with SETFIL.

The call is:  CALL SETFIL (CFIL)                     level 0

CFIL          is a character string  that contains the file-
              name.


                         F I L M O D

The routine  FILMOD  determines  if a new  plotfile name  is
created for existing files.

The call is:  CALL FILMOD (CMOD)            level 0, 1, 2, 3

CMOD          is a character string containing the mode.
  = 'COUNT'   means that a new file version will be created.
  = 'DELETE'  means that the existing file will be overwrit-
              ten.
  = 'BREAK'   means that  the program  will be terminated by
              DISINI.
                                    Default: CMOD = 'COUNT'.

                         S C R M O D

Normally, the background  of screens and coloured PostScript
files is set to 'BLACK'  and the foreground colour is set to
'WHITE'.  With the routine  SCRMOD,  the back and foreground
colours can be swapped without changing the colour table.  

The call is:  CALL SCRMOD (CMOD)                     level 0

CMOD          is a character string containing the mode.
 = 'AUTO'     uses  a  'BLACK'  background  colour  for  the 
              screen,  PNG,  TIFF  and  coloured  PostScript
              files, and a 'WHITE' background for PDF files.
 = 'REVERS'   means  that  the  background colour  is set to
              'WHITE' and the foreground colour to 'BLACK'.
 = 'NOREV'    means  that  the  background  colour is set to
              'BLACK' and the foreground colour to 'WHITE'.
                                     Default: CMOD = 'AUTO'.

                         C G M B G D

The routine CGMBGD sets the background colour for CGM files.

The call is:  CALL CGMBGD (XR, XG, XB)      level 0, 1, 2, 3 

XR, XG, XB    are the RGB coordinates  of the background co-
              lour in the range 0 to 1.
                                      Default: (1., 1., 1.).

                         C G M P I C

The routine CGMPIC modifies the picture ID in CGM files. The
picture ID may be referenced by some browsers.

The call is:  CALL CGMPIC (CSTR)            level 0, 1, 2, 3 

CSTR          is a character string  containing  the picture
              ID  (<=  256 characters).  By default,  the ID
              'Picture n'  is used  where  n  is the picture
              number beginning with 1. 

                         P D F M O D

The routine  PDFMOD  selects between compressed and non com-
pressed PDF files.

The call is:  CALL PDFMOD (CMOD, CKEY)               level 0 

CMOD          is a character string that can have the values
              'ON' and 'OFF'.
CKEY          is a character string that can have the  value 
              'COMPRESSION'.
                              Default: ('ON', COMPRESSION').

6.1.5 Page Control

                         P A G E

PAGE determines the size of the page.

The call is:  CALL PAGE (NXP, NYP)                   level 0

NXP, NYP      are the length  and height of the page in plot
              coordinates.  The lower  right  corner  of the
              page is the  point (NXP-1, NYP-1).
                                      Default: (2970, 2100).

                         S E T P A G

SETPAG selects a predefined page format.

The call is:  CALL SETPAG (CPAGE)                    level 0

CPAGE         is a character  string  that defines  the page
              format.

  = 'DA4L'    DIN A4,        landscape,  2970 * 2100 points.
  = 'DA4P'    DIN A4,        portrait,   2100 * 2970 points.
  = 'DA3L'    DIN A3,        landscape,  4200 * 2970 points.
  = 'DA3P'    DIN A3,        portrait,   2970 * 4200 points.
  = 'DA2L'    DIN A2,        landscape,  5940 * 4200 points.
  = 'DA2P'    DIN A2,        portrait,   4200 * 5940 points.
  = 'DA1L'    DIN A1,        landscape,  8400 * 5940 points.
  = 'DA1P'    DIN A1,        portrait,   5940 * 8400 points.
  = 'PS4L'    PostScript A4, landscape,  2800 * 1950 points.
  = 'PS4P'    PostScript A4, portrait,   1950 * 2800 points.
  = 'KY4L'    Kyocera A4,    landscape,  2870 * 2000 points.
  = 'KY4P'    Kyocera A4,    portrait,   2000 * 2870 points.
  = 'HP4L'    HP-plotter A4, landscape,  2718 * 1900 points.
  = 'HP4P'    HP-plotter A4, portrait,   1900 * 2718 points.
  = 'HP3L'    HP-plotter A3, landscape,  3992 * 2718 points.
  = 'HP3P'    HP-plotter A3, portrait,   2718 * 3992 points.
  = 'HP2L'    HP-plotter A2, landscape,  5340 * 3360 points.
  = 'HP2P'    HP-plotter A2, portrait,   3360 * 5340 points.
  = 'HP1L'    HP-plotter A1, landscape,  7570 * 5340 points.
  = 'HP1P'    HP-plotter A1, portrait,   5340 * 7570 points.
                                    Default: CPAGE = 'DA4L'.

                         S C L F A C

SCLFAC sets the scaling factor for an entire plot.

The call is:  CALL SCLFAC (XFAC)                     level 0

XFAC          is the scaling factor by which the entire plot
              is scaled up or down.
                                          Default: XFAC = 1.

                         S C L M O D

The method  by which  graphics  are scaled  to the  hardware
pages of devices such as a graphics terminal can be selected
with the routine SCLMOD.

The call is:  CALL SCLMOD (CMOD)                     level 0

CMOD = 'DOWN' means that graphics will be scaled down if the
              hardware page of a device  is smaller than the
              plotting page.
     = 'FULL' means that the  graphics will be scaled  up or
              down depending  upon the size  of the hardware
              page.
                                     Default: CMOD = 'DOWN'.

Notes:     -  The size of  a graphics screen will  be inter-
              preted as DIN A4 landscape. This means that by
              default graphics which are smaller than DIN A4
              will not fill the entire screen.
           -  SCLFAC and SCLMOD can affect each other.

                         P A G M O D

GKSLIN and CGM files can be rotated by 90 degrees to use the
full  hardware page  of a device.  In general,  this is done
automatically by the driver program.

The call is:  CALL PAGMOD (CMOD)                     level 0

CMOD = 'LAND' means that the metafile is not rotated.
     = 'PORT' means that  the metafile is  rotated by 90 de-
              grees.
     = 'NONE' can be used  to disable automatic plotfile ro-
              tation in the driver program   (i.e. for Post-
              Script files).
                                     Default: CMOD = 'LAND'.

Figure 2 shows the effect of PAGMOD:
                                          +--------------+
                                          |              |
                                          |          ^   |
                                          |          |   |
                                          |          |   |
    +-----------------------+             |          |   |
    |  ^                    |             | Portrait |X  |
    |  |                    |             |          |   |
    | Y|    Landscape       |             |          |   |
    |  |                    |             |          |   |
    |  +--------------->    |             |  <-------+   |
    |         X             |             |     Y        |
    +-----------------------+             +---------------

                       Figure 2: PAGMOD

                         N E W P A G

NEWPAG creates a new page.

The call is:  CALL NEWPAG                            level 1

Notes:     -  PostScript  and  CGM files can store  multiple 
              pages. For other output formats, NEWPAG is not
              useful.
           -  On X Window terminals, NEWPAG is waiting for a
              mouse button 2  event  before  displaying  the
              next page. On other terminals,  NEWPAG has the
              same effect as ERASE.                     

                         H W P A G E

The routine  HWPAGE defines the size of the PostScript hard-
ware page.

The call is:  CALL HWPAGE (NW, NH)                   level 0

NW, NH        are the  width  and height  of the  PostScript
              hardware page in plot coordinates.
                                      Default: (1950, 2800).

                         H W O R I G

The routine  HWORIG defines the hardware origin of the Post-
Script hardware page.

The call is:  CALL HWORIG (NX, NY)                   level 0

NX, NY        are the plot coordinates  of the hardware ori-
              gin.                       Default: (75, 100).


6.1.6 Error Handling

                         E R R F I L

By default, the name of the error file is 'dislin.err'.
An alternate filename can be set with ERRFIL.

The call is:  CALL ERRFIL (CFIL)                     level 0

CFIL          is a character string  that contains the file-
              name.

                         E R R D E V

The routine ERRDEV defines the output device for DISLIN war-
nings. By default, warnings are written to the screen.

The call is:  CALL ERRDEV (COPT)                     level 0

COPT          is a character string that can have the values
              'CONS' and 'FILE'.
                                     Default: COPT = 'CONS'.

                         U N I T

UNIT defines the logical unit used for printing  error  mes-
sages and  listing data points  that lie outside of the axis
scaling.

The call is:  CALL UNIT (NU)                   level 1, 2, 3

NU            is the logical unit.  If NU = 0,  all messages
              will be suppressed.
                                             Default: NU = 6

                         W I N A P P

The routine WINAPP defines if a  DISLIN program  should look
like a  Windows console, or more like a Windows program.  If
Windows mode is selected,  all  warnings  are  written to an
error file and the protocol in disfin is displayed in a wid-
get. 

The call is:  CALL WINAPP (COPT)                     level 0

COPT          is a character string that can have the values
              'CONSOLE' and 'WINDOWS'.
                                  Default: COPT = 'CONSOLE'.

6.1.7 Viewport Control

                         W I N D O W

This routine defines,  for  X Window terminals,  a region on
the screen where the graphics will be displayed. By default,
the window size is set to 2/3 of the screen size and located
in the lower right corner of the screen.

The call is:  CALL WINDOW (NX, NY, NW, NH)  level 0, 1, 2, 3

NX, NY        are the  screen  coordinates of the upper left
              corner.
NW, NH        are the  width  and  height  of the  window in
              screen coordinates.

Note:         In general,  the screen  size is   1280 * 1024
              pixels.

                         W I N S I Z

This routine  defines  the size of windows.  By default, the
window size is set to 2/3 of the screen size.

The call is:  CALL WINSIZ (NW, NH)          level 0, 1, 2, 3

NW, NH        are  the  width  and height  of the  window in
              screen coordinates.


                         C L R M O D

The routine  CLRMOD defines the colour mode  used for output
on an X Window terminal.

The call is:  CALL CLRMOD (CMOD)                     level 0

CMOD          is a character string defining the mode.
  = 'NONE'    means  that  a colour table  with 256  colours
              will  be reduced to  129  colours  to conserve
              current screen and window colours.  The colour
              values will be reduced by the formula   (0 <=>
              0, i = (iclr + 1) / 2, iclr = 1, ... 255).
  = 'FULL'    means that all 256 colours will be displayed.
  = 'CONT'    means that  a colour table  with less than 129
              entries will be used.
                                     Default: CMOD = 'NONE'.

                        X 1 1 M O D

The routine  X11MOD  enables or disables backing store  for
graphic windows.

The call is:  CALL X11MOD (CMOD)                     level 0

CMOD          is a character string containing the mode.
 = 'NOSTORE'  means that graphical output  is send  directly
              to the graphics window.
 = 'STORE'    means that graphical output  is send to a pix-
              map that  will be copied  to the graphics win-
              dow.               
 = 'AUTO'     means that  'NOSTORE' will be used on X11  and 
              'STORE' on Windows terminals.
                                     Default: CMOD = 'AUTO'.

                        W I N M O D

The routine  WINMOD  affects the handling  of windows in the
termination routine DISFIN.

The call is:  CALL WINMOD (CMOD)               level 1, 2, 3

CMOD  is a character string containing the mode.
  = 'FULL'    means that  DISFIN is waiting for a mouse but-
              ton 2 event.  After program continuation,  all
              windows are deleted.
  = 'NOHOLD'  means that  DISFIN is not waiting for a  mouse
              button 2 event.  After a call to  DISFIN,  all
              windows are deleted.
  = 'NOERASE' means  that the program  is still  blocked  in
              DISFIN  but windows  will not be deleted after
              program continuation.
  = 'NONE'    means that the program is not blocked in  DIS-
              FIN and windows are not deleted.
  = 'DELAY'   means that the program is blocked  for a short
              time in  DISFIN  before  it is  continued. The
              delay time  can be  defined  with  the routine
              WINOPT.
                                     Default: CMOD = 'FULL'.

                        W I N O P T

The routine WINOPT sets the delay time for the keyword  'DE-
LAY' in WINMOD.

The call is:  CALL WINOPT (IOPT, CKEY)         level 1, 2, 3

IOPT          is the delay time in seconds.
CKEY          is a character string that can have  the value
              'DELAY'.
                                     Default: (10, 'DELAY').

                         W I N K E Y

The routine  WINKEY  enables a an additional key that can be
used for program continuation is DISFIN. Normally, the mouse
button 2 can be used for closing the graphics window. 

The call is:  CALL WINKEY (CKEY)               level 1, 2, 3

CKEY          is a character string that can have the values
              'NONE', 'RETURN' and 'ESCAPE'.
                                     Default: CKEY = 'NONE'.

                         S E T X I D

The routine  SETXID  defines an external graphics window for
X11 and Windows displays.  All graphical output  is sent  to 
the external window.  For X11 displays,  an external  pixmap 
can also be defined.

The call is:  CALL SETXID (ID, CTYPE)                level 0

ID            is the window or pixmap ID.
CTYPE         is a character string that can have the values
              'NONE',  'WINDOW', 'PIXMAP' and 'WIDGET'.  For 
              the keyword 'WIDGET', the ID of a  DISLIN draw
              widget can be used.
                                       Default: (0, 'NONE').

Notes:      - If an external  pixmap is used,  backing store 
              must also be enabled with the routine X11MOD.
            - An external window is not erased by DISINI. 
              This can be done with the routine ERASE.
            - External windows are not blocked in DISFIN 
              (see WINMOD).   
