NAG Graphics Library, Mark 4 GLW3204DD Windows 95/NT Digital Visual Fortran Double Precision Users' Note Contents 1. Introduction 2. NAG Graphical Software 3. General Information 3.1. Accessing the High-level Library and Interfaces 3.2. Initialisation of Underlying Plotting Package 3.3. Output from Graphics Library Routines 3.4. Interpretation of Bold Italicised Terms 3.5. Example Programs 3.6. User Documentation 3.6.1. On-line help 3.7. Interface Block 4. Routine-specific Information 4.1. J06AQF 4.2. Constants 4.3. J06DAF 4.4. J06GGF 5. Interface-specific Information 5.1. Hewlett Packard HPGL 6. Additional Services from NAG 7. Support from NAG 8. NAG Users Association 1. Introduction This document is essential reading for every user of the NAG Graphics Library Implementation specified in the title. It provides implementation-specific detail that augments the information provided in the NAG Graphics Library Handbook. NAG recommends that users read the following minimum reference material before calling any library routine: (a) Essential Introduction (b) Chapter Introduction (c) Routine Documentation (d) Implementation-specific Users' Note Items (a), (b) and (c) are included in the NAG Graphics Library Handbook; item (c) is also provided in on-line form; item (d) is this document which is provided in plain text form. 2. NAG Graphical Software The NAG Graphics Library can be considered to consist of three distinct parts: high-level graphics routines, low-level routines and support routines. When calling the NAG Graphics Library to draw a contour map or graph you are invoking what are termed 'high-level' or package-independent graphics routines. These are written in terms of a small set of primitive, or 'low-level', routines known collectively as the NAG Graphical Interface. NAG Graphical Interface routines in turn call routines in a locally available plotting package, and perform such functions as drawing a line or changing the current text font. The support routines are a subset of the routines available in the NAG Fortran Library, and hence are optional if that Library is available at an installation, but are needed otherwise to ensure that the NAG Graphics Library is complete. There is a version of the NAG Graphical Interface for each plotting package (or protocol) supported. The Interface translates drawing requests into a form which can be accepted by the underlying plotting software. As an appropriate interface is selected at link time, only one version of an application program need be written and maintained. Irrespective of the plotting software used, all routines in the NAG Graphical Interface have the same parameter sequence. The main new feature at Mark 4 is the improved text handling. The following capabilities have been included: (a) Hershey fonts have been included, guaranteeing the presence of fully scalable fonts irrespective of the underlying plotting software used. As the plotting of Hershey font characters is fully under control of the NAG Graphics Library, it was also possible to introduce the use of proportional spacing for these fonts. Several Greek alphabet fonts and a mathematical symbols font are perhaps the most significant among a total of 25 Hershey fonts supplied as part of Mark 4. (b) Strings to be plotted may include keywords; this facilitates the plotting of subscripts and superscripts and in-line changing of fonts, as well as typesetting of fairly complex mathematical formulae. (c) Character strings may be plotted along an arbitrary (i.e. non-horizontal) direction, with the base line of individual characters pointing in the same direction. This is useful for example in the plotting of y axis labels which no longer need to be plotted as `hotel signs'. (d) Definition of character size may be independent of the user co-ordinates currently in force; character size and spacing may now be defined as a fraction of the maximum plotting area, in addition to the method of defining them in terms of user co-ordinates. This enables the use of fixed size character strings which are the same for plots which may have different user co-ordinates and/or viewport sizes. (e) Text may be aligned in relationship to the current point; text can begin (left-justified), end (right-justified) or be centred at the current pen position. (f) Text may be underlined. Further improvements to the presentational aspects of the Library have been made by allowing user-specified margins and the plotting of axis labels on all sides of the plots (rather than to the left-hand side and bottom only). The high-level code was extensively revised to make full use of the new features introduced. 3. General Information 3.1. Accessing the High-level Library and Interfaces A user's compiled program will need to be linked with the following libraries (in the given order): - NAG Graphics Library high-level routines (NAGMK4.LIB) - NAG Graphical interface library, e.g. INTERACTER interface library (NAGISS.LIB) - NAG Fortran support routines (NAGSUP.LIB or the NAG Fortran Library) - underlying Graphics package, e.g. INTERACTER short names library (SHORTDVF.LIB) and INTERACTER subset library (NAGMWDVF.LIB) For example, to compile, link and execute the example program J06GEFE.FOR using the data file J06GEFE.DAT (assuming that the NAG Graphics Library is installed in the default directory \GLW3204DD, and that the Digital Visual Fortran compiler has been installed and made accessible) the steps would be: 1) Copy LINKNAG.BAT from the \GLW3204DD\BATCH sub-directory to your current working directory. 2) Copy J06GEFE.FOR from the \GLW3204DD\EXAMPLES\SOURCE sub-directory to your current directory. 3) Copy J06GEFE.DAT from the \GLW3204DD\EXAMPLES\DATA sub-directory to your current directory. 4) Compile and link J06GEFE.FOR using the LINKNAG.BAT batch file by typing LINKNAG J06GEFE where may be ISS, APS, HPG, GKS, DGKS or LPR according to which interface and graphical package is to be used. Note: LINKNAG.BAT assumes that the NAGGL04 environment variable is set. If you have not set this variable, it can be set as follows: SET NAGGL04=C:\GLW3204DD where C:\GLW3204DD is the location of the NAG Graphics Library. When using the INTERACTER interface, LINKNAG.BAT assumes that the libraries: C:\Program Files\DevStudio\VC\LIB\GDI32.LIB C:\Program Files\DevStudio\VC\LIB\KERNEL32.LIB C:\Program Files\DevStudio\VC\LIB\USER32.LIB need to be linked. Depending on your system configuration, it may not be necessary to specifically link with these three libraries. If it is necessary to link with these libraries and they have been installed in a different location, it will be necessary to modify the corresponding pathnames in LINKNAG.BAT. 5) Run J06GEFE.EXE by typing J06GEFE If ISS is used as the argument to LINKNAG, J06GEFE will be run using the interactive mode (see Section 6.2 of the INTERACTER Interface Usage section of the NAG Graphics Library Handbook for detailed information about running in an alternative non-interactive mode using a setup file INTERACT.SET). You will then be asked to enter: a) type of hardcopy output (screen dump, HPGL or Postscript) Use the "TAB" Key to switch between the different options and enter "YES" to select the hardcopy driver required. If high quality HPGL or Postscript output is required, we recommend that you use the NAG HPGL or Postscript Interfaces. b) file name to which hardcopy output protocol will be directed. c) type of frame advance prompt. If APS or HPG are used as the argument to LINKNAG, J06GEFE will be run and command sequence output will be written to a file in your current directory named J06GEFE.CMD. Users may plot the file by directing it to their target output device via the use of the MS-DOS COPY/B command, e.g. COPY/B J06GEFE.CMD COM1: Users should ensure that their hardware is correctly configured prior to attempting to direct the file to the output device. Note: If the ISS interface is used, you should specify the exact type of display and other hardware connected to your machine (e.g. plotter, printer etc.) by using an initialisation file INTERACT.INI (see Section 6.2 of the INTERACTER Interface Usage section of the NAG Graphics Library Handbook for more details). The ISS interface will try to determine the type of display in use; if it fails to do so it may prompt you with a menu in which you can choose the exact type of display installed. The size of the INTERACTER graphics windows may be controlled by adjusting the parameters WINSIZ-H and WINSIZ-V in the file INTERACT.SET. If the file is not located in your current working directory, default values for WINSIZ-H and WINSIZ-V of 640 and 480 respectively are used. The INTERACTER graphics window may be moved by clicking and holding down the left mouse button on the title bar of the window and then dragging the window as required. Clicking on the right mouse button or pressing any key on the keyboard will advance the frame or, if viewing the last frame, will terminate the graphics window. If using the INTERACTER interface to produce hard copy output (but note that NAG recommends that you use the NAG HPGL or Postscript interfaces for this), then it is recommended that the parameters WINSIZ-H and WINSIZ-V be set such that WINSIZ-H/WINSIZ-V=AR, where AR is the aspect ratio of the usable area on the hard copy device. For example, by default, for A4 Postscript output in landscape mode under the INTERACTER interface, AR=1.40. In the file INTERACT.SET, WINSIZ-H has been set to 700 and WINSIZ-V has been set 500. If you wish to run programs using the INTERACTER interface in a DOS environment, then they should be run in a DOS Window. The programs should not be run in Full-screen DOS mode as the frame advance and graphics window termination mechanisms may prove unreliable. 3.2. Initialisation of Underlying Plotting Package Usually the first step when using a graphics package is to initialise the system and/or select a particular graphical output device. Users must make an explicit call to the local graphics software to perform this step, before calling any NAG graphical routine. The Interface Usage section of the NAG Graphics Library Handbook gives recommended initialisation statements. However, for generality, the example programs contain the dummy initialisation statement: CALL XXXXXX Users who adapt the example programs for their own use must replace this statement by an appropriate initialisation call if local versions of XXXXXX have not been established at installation time. Users of the INTERACTER NAG Graphical Interface are referred to the INTERACTER Interface Usage section of the NAG Graphics Library Handbook for details of the initialisation of the INTERACTER graphics package. 3.3. Output from Graphics Library Routines It is important to note that a file must always be attached to the current error and warning message units (see routines J06VAF and J06VBF), even when graphs are the only expected output. This is because warning messages may be output by some interface routines if they are called with invalid parameters and error messages may be output by some high-level routines when an error condition is detected. The supplied examples open an appropriate file internally. Command sequence output may also be produced by the HPGL and Adobe PostScript interfaces (see routine J06VCF). Some routines for contouring or the plotting of the solution of ordinary differential equations use option-setting facilities. Routine J06VEF specifies the unit number of any corresponding option-setting SAVE file. 3.4. Interpretation of Bold Italicised Terms For this implementation, the bold italicised terms used in the NAG Graphics Library Handbook and Reference Manual (and shown here as //.....//) should be interpreted as: //basic precision// - double precision //real// as a type declarator - DOUBLE PRECISION //real// as an intrinsic function name - DBLE //e// in constants, e.g. 1.0//e//-4 - D, e.g. 1.0D-4 //e// in formats, e.g. //e//12.4 - D, e.g. D12.4 Thus a parameter described as //real// should be declared as DOUBLE PRECISION in the user's program. 3.5. Example Programs The example programs published in the NAG Graphics Library Reference Manual are presented in a generalised form, using bold italicised terms as described in Section 3.4. The programs supplied to a site in machine-readable form have been modified as necessary to run on this system. In particular, files are opened internally for reading any data, for writing error or advisory messages and for writing command sequence output. The files are identified in the following way: Example Program: J06xxFE.FOR Example Data: J06xxFE.DAT Example Error or Advisory output: J06xxFE.ERR Example Command Sequence output: J06xxFE.CMD where xx represents the chapter and routine mnemonic, for example J06AAFE.FOR (AA representing the first routine in the J06A chapter). They are suitable for immediate execution, except for initialisation of the underlying plotting package (see Section 3.2). 3.6. User Documentation The following machine-readable information files are provided by NAG on the library release medium. Please consult your local advisory service or NAG Site Contact for further details: UN.TXT - Users' Note (this document) SUMMARY.TXT - a brief summary of the routines CALLS.TXT - a list of routines called directly or indirectly by each high-level routine, and by each example program CALLED.TXT - for each high-level routine (including auxiliaries), a list of routines and example programs which call it directly or indirectly 3.6.1. On-line help On-line help is provided in DOS browser form by running the batch file NAGHELP in the HELP sub-directory. This can be achieved by clicking on the NAG Graphics Library Help icon in the NAG Graphics Library Mark 4 program folder. When the documentation browser starts up, a list of routines will be presented, one of which can be chosen by using the cursor keys and pressing return. The on-line version of the documentation for the routine selected will then be displayed on the screen. A simple paging program is used to display the routine information. The controls are summarised below: The PageDown key or the space bar will show the next screen of information. The PageUp key or the minus key will show the previous screen of information. The Return key will show the next line of information. The Escape key will return to the list of chapter sections. The X key will extract the information to a file named after the routine. While in the naghelp program the F1 key will give some simple help information. 3.7. Interface Block The NAG Graphics Library Interface Block defines the type and arguments of each user callable NAG Graphics Library routine. This is not essential to calling the NAG Graphics Library from Fortran 90 programs. Its purpose is to allow the Fortran 90 compiler to check that NAG Graphics Library routines are called correctly. The interface block enables the compiler to check that: (a) Subroutines are called as such (b) Functions are declared with the right type (c) The correct number of arguments are passed (d) All arguments match in type and structure This interface block has been generated automatically by analysing the source code for the NAG Graphics Library. As a consequence, and because this file has been thoroughly tested, it is more reliable than writing your own declarations. The NAG Graphics Library Interface Block file has been named NAGIFB_J.MOD. Users of the NAG Fortran Library compiled with Fortran 90 will be familiar with this chapter naming convention. The interface block, NAGIFB_J.MOD is supplied in pre-compiled form. If it is required, it must be copied to the current directory. In order to make use of this module from existing Fortran 77 code the following changes need to be made: (a) Add a USE statement for the module file. (b) Delete all EXTERNAL statements for NAG Graphics Library routines. These are now declared in the module. (c) Delete the type declarations for any NAG Graphics Library functions. These are now declared in the module. These changes are illustrated by showing the conversion of the Fortran 77 version of the example program for NAG Graphics Library routine J06AJF. Please note that this is not exactly the same as the example program that is distributed with this implementation. Each change is surrounded by comments boxed with asterisks. The previous Fortran 77 statement is shown commented out followed, where appropriate, with the new Fortran 90 line. C J06AJF EXAMPLE PROGRAM TEXT (Fortran 90 version) C MARK 4 RE-ISSUE. NAG COPYRIGHT 1992. ************************************************************************ * Add USE statement for chapter J06 * USE NAGIFB_J * * ************************************************************************ C .. Parameters .. INTEGER NIN, NOUT PARAMETER (NIN=5,NOUT=8) INTEGER NYAXIS, NXAXIS, MARGIN PARAMETER (NYAXIS=2,NXAXIS=1,MARGIN=1) C .. Local Scalars .. DOUBLE PRECISION UMAX, UMIN, VMAX, VMIN, XMAX, XMIN, YMAX, YMIN INTEGER IQUAL LOGICAL PROPOR ************************************************************************ * Remove EXTERNAL declarations for NAG Graphics Library routines * * (and type declarations for functions) * C .. External Subroutines .. C EXTERNAL J06AAF, J06AHF, J06AJF, J06TBF, J06VAF, J06WAF, C * J06WBF, J06WCF, J06WZF, J06XFF, XXXXXX * * ************************************************************************ C .. Executable Statements .. C C Select output channel for error messages C CALL J06VAF(1,NOUT) C C Initialise plotting device C C OPEN(NIN,FILE='j06ajfe.dat') OPEN(NOUT,FILE='j06ajfe.err') C CALL J06VCF(0,NCOM) OPEN(NCOM,FILE='j06ajfe.cmd') C CALL XXXXXX C C Read data region limits C followed by viewport co-ordinates C READ (NIN,FMT=*) READ (NIN,FMT=*) XMIN, XMAX, YMIN, YMAX READ (NIN,FMT=*) UMIN, UMAX, VMIN, VMAX C C Call NAG Graphical Interface to initialise C the NAG Graphics and indicate the data region. C CALL J06WAF CALL J06WBF(XMIN,XMAX,YMIN,YMAX,MARGIN) CALL J06WCF(UMIN,UMAX,VMIN,VMAX) C C Select Hershey quality characters and proportional spacing C READ (NIN,FMT=*) IQUAL CALL J06XFF(IQUAL) PROPOR = .TRUE. CALL J06TBF(1,PROPOR) C C Draw title, axes, and axis labels C CALL J06AHF('J06AJF EXAMPLE PLOT') CALL J06AAF CALL J06AJF(NYAXIS,'Y axis label') CALL J06AJF(NXAXIS,'X axis label') C C Terminate plotting C CALL J06WZF STOP END 4. Routine-specific Information 4.1. J06AQF Users are warned that axis annotation produced by J06AQF may show variations in tick mark positioning and numbering on different systems. This is due to differences in machine precision. 4.2. Constants Graphics Library routines make use of the following implementation-dependent constants: J06VAF GIVES NERR = 6 (error message unit number) J06VBF GIVES NADV = 6 (advisory message unit number) J06VCF GIVES NCOMM = 7 (command sequence unit number) J06VDF GIVES NFONT = 10 (font file unit number) J06VEF GIVES NSAV = 8 (save file unit number) J06VKF GIVES NINT = 10 (initialisation file unit number) X02AJF = 1.110223024625157E-016 (the machine precision) X02AKF = 2.225073858507201E-308 (the smallest positive model number) X02ALF = 1.797693134862316E+308 (the largest positive model number) X02AMF = 2.225073858507201E-308 (the safe range parameter) X02BBF = 2147483647 (largest positive integer) X02BEF = 15 (precision in decimal digits) X02DAF = F (indicates how underflow is handled) 4.3. J06DAF In this implementation IFAIL = 3 if NCOMPS > 5000 4.4. J06GGF In this implementation IFAIL = 1 if M < 3 or M > 1500 The maximum number of data points supported by NAG Graphics Library routines J06GGY and J06GGZ is 1500. 5. Interface-specific Information The in-string keyword delimiter referred to in the Details of Plot Control section of the NAG Graphics Library Handbook is the exclamation mark ('!'). 5.1. Hewlett Packard HPGL The form and standard use of the HPGL instruction set does not lend itself to easy incorporation into Fortran code. It has, therefore, been necessary to develop a set of emulator routines for this Interface. This should not affect the user, except that the names used for these routines should not be duplicated. Details of the 'reserved names' can be found in the Hewlett Packard HPGL Interface Usage section of the NAG Graphics Library Handbook. 6. Additional Services from NAG (a) Documentation Each NAG Graphics Library site is provided with a printed copy of the NAG Graphics Library Handbook. The NAG Graphics Library Reference Manual, which contains full routine documentation, is available at prices published in the NAG documentation order form. (b) On-line Information Supplement The NAG On-line Information Supplement provides a system to assist with routine selection and gives abbreviated on-line documentation of the routines. Information from the On-line Information Supplement relevant to the Graphics Library is provided in DOS browser form with this implementation (see Section 3.6.1). 7. Support from NAG (a) Contact with NAG Queries concerning this document or the implementation generally should be directed initially to your local Advisory Service. If you have difficulty in making contact locally, you can write to NAG directly, at one of the supplied addresses. Users subscribing to the support service are encouraged to contact one of the NAG Response Centres (see below). (b) NAG Response Centres The NAG Response Centres are available for general enquiries from all users and also for technical queries from sites with an annually licensed product or support service. The Response Centres are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times. When contacting a Response Centre please quote your NAG user reference and NAG product code. (c) Network Network, NAG's newsletter, is produced periodically and sent free of charge to sites with a supported product or service. (d) NAG Website The NAG Website is an information service providing items of interest to users and prospective users of NAG products and services. The information is regularly updated and reviewed and includes implementation availability, descriptions of products, downloadable software and technical reports. The NAG Website can be accessed at http://www.nag.co.uk/ or http://www.nag.com/ (in the USA) 8. NAG Users Association NAGUA, the NAG Users Association, is a self-financing, non-profitmaking body. It exists to promote communications between NAG and users of its products and services. It provides information to NAG on the requirements of users, who are in turn kept informed of developments in services. Membership is available to any institution or individual holding a licence for any NAG product or service. Members receive discounts on the registration fees at conferences and workshops. For an information pack and membership application form, please contact NAGUA at the supplied address. Appendix - supplied addresses NAG Ltd Wilkinson House Jordan Hill Road OXFORD OX2 8DR NAG Ltd Response Centre United Kingdom email: support@nag.co.uk Tel: +44 (0)1865 511245 Tel: +44 (0)1865 311744 Fax: +44 (0)1865 310139 Fax: +44 (0)1865 310139 NAG Inc 1400 Opus Place, Suite 200 Downers Grove IL 60515-5702 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 630 971 2337 Tel: +1 630 971 2345 Fax: +1 630 971 2706 Fax: +1 630 971 2346 NAG Users Association PO Box 426 OXFORD OX2 8SD United Kingdom email: nagua@nag.co.uk Tel: +44 (0)1865 311102 [NP3255/UN]