NAG Graphics Library, Mark 4 GLDO304DS DOS/386 Salford FTN77/386 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 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 Reference Manual. NAG recommends that users read the following minimum reference material before calling any library routine: (a) Using the NAG Graphics Library (b) Chapter Introduction (c) Routine Document (d) Implementation-specific Users' Note Items (a), (b) and (c) are included in the NAG Graphics Library Reference Manual; item (d) is this document. Each NAG Graphics Library Service site is supplied with at least one copy of each of the above. Please ask your NAG Site Contact for further information. 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 or Foundation Libraries, and hence are optional if one of those Libraries 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.OBJ) - NAG Graphical interface library: (e.g. INTERACTER interface library NAGISS.OBJ) - NAG Fortran support routines (NAGSUP.OBJ or the NAG Fortran or Foundation Libraries) - underlying Graphics package, e.g. INTERACTER subset library (NAG386.OBJ) For example, to compile, link and execute the example program J06GEFE.FOR using the data file J06GEFE.D (assuming that the NAG Graphics Library is installed in the default directory \GL04, and that the Microsoft compiler has been installed and made accessible) the steps would be: 1) Copy LINKNAG.BAT from the \GL04\BATCH sub-directory to your current working directory 2) Copy J06GEFE.FOR from the \GL04\EXAMPLES\SOURCE sub-directory to your current directory. 3) Copy J06GEFE.D from the \GL04\EXAMPLES\DATA sub-directory to your current directory. 4) Compile and link J06GEFE.FOR using the LINKNAG.BAT batch file by typing: LINKNAG J06GEFE [DLL] where may be ISS, APS, GKS, DGKS, HPG or LPR according to which interface and graphical package is to be used. The optional DLL switch will force linking with a dynamic link library (DLL) if you have created one using the MAKE_DLL batch file (see Section 4.1.2 of the Installer's Note for more details). 5) Run J06GEFE.EXE by typing RUN77 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 Reference Manual for detailed information about running in an alternative non-interactive mode using an initialisation 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 toggle 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: the ISS interface will try to determine the type of graphics card in use. If it fails to do so it will prompt you with a menu in which you can choose the exact type of graphics card installed. You can also specify the exact type of graphics card 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 Reference Manual for more details). 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 Reference Manual 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 interface appendix for details on 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 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.D 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.DOC - Users' Note (this document) SUMMARY.DOC - a brief summary of the routines CALLS.DOC - a list of routines called directly or indirectly by each routine in the library, and by each example program CALLED.DOC - for each routine in the library (including auxiliaries) this gives a list of those routines and example programs which call it directly or indirectly 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 = 8 (error message unit number) J06VBF GIVES NADV = 8 (advisory message unit number) J06VCF GIVES NCOMM = 50 (command sequence unit number) J06VEF GIVES NSAV = 60 (save file unit number) J06VKF GIVES NINT = 10 (initialisation file unit number) X02AJF = 1.111307226797650E-016 (the machine precision) X02AKF = 2.225073858507201E-308 (the smallest positive model number) X02ALF = 1.797693134862310E+308 (the largest positive model number) X02AMF = 2.225073285072010E-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 Reference Manual 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 Reference Manual. 6. Additional Services from NAG (a) Printed Manuals Where a manual has been provided as part of the contract issue, this manual is updated automatically at each new release of the software, by the supply of a manual update set or a complete new manual. If additional manuals have been ordered in the past then updates to these manuals may be ordered separately. They are NOT sent automatically. Additional complete manuals and the manual updates (where relevant) are available at prices published in the NAG documentation order form. (b) On-line Information Supplement To complement the manuals NAG produces an On-line Information Supplement which fulfils two roles: - it gives key-word-driven guidance on the selection of the appropriate NAG routine - it gives abbreviated on-line documentation of the NAG routines, to enable the user to call the routines and investigate any IFAIL messages without recourse to the manual. 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 quarterly and sent free of charge to sites with a supported product or service. (d) NAG Bulletin Board The NAG Bulletin Board 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; new features are added and special interest groups are continually developing. 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 which holds a licence for any NAG product or service. Members receive discounts on the registration fees at conferences and workshops. Members also receive 'NAGUA News', NAGUA's own newsletter. 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 865 511245 Tel: +44 865 311744 Fax: +44 865 310139 Fax: +44 865 310139 NAG Inc 1400 Opus Place, Suite 200 Downers Grove IL 60515-5702 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 708 971 2337 Tel: +1 708 971 2345 Fax: +1 708 971 2706 Fax: +1 708 971 2346 NAG Users Association PO Box 426 OXFORD OX2 8SD United Kingdom email: nagua@nag.co.uk Tel: +44 865 311102