NAG Graphics Library, Mark 4 GLDAV04DG DEC Alpha AXP OpenVMS Double Precision G_FLOATING 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 5. Interface-specific Information 5.1. DEC ReGIS 5.2. 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) Essential Introduction (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 (NAG$LIBJ06.OLB) - NAG Graphical Interface Library (e.g. TEXTGKS.OLB) - NAG Fortran support routines (NAG$LIBFOR.OLB or the NAG Fortran or Foundation Libraries) - underlying Graphics package (e.g. GKS) For example, to compile, link and execute the example program J06BZF.FOR using data J06BZF.DAT and with the libraries available in the same directory (or accessible via logical names), the steps would be: - to compile the program, type FORTRAN J06BZF - to link the program, using the GKS version of the NAG Graphical Interface and the NAG Fortran support routines, type LINK J06BZF, NAG$LIBJ06/LIB, TEXTGKS/LIB, NAG$LIBFOR/LIB, GKS/LIB - to link the program, using the GKS version of the NAG Graphical Interface and the full NAG Fortran Library, type LINK J06BZF, NAG$LIBJ06/LIB, TEXTGKS/LIB, NAG$LIBRARY/LIB, GKS/LIB - to run the program, type ASSIGN/USER_MODE J06BZF.DAT FOR005 RUN J06BZF 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. 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. Additionally, if the Lineprinter interface is in use then plots are output on the current advisory message unit (see routine J06VBF). Command sequence output may also be produced by the DEC ReGIS, 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. They are suitable for immediate execution, except for initialisation of the underlying plotting package (see Section 3.2). Users of DEC ReGIS, HPGL or PostScript interfaces may also need to include a call to J06VCF to direct the resultant command sequences to a chosen Fortran unit. 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 = 6 (error message unit number) J06VBF GIVES NADV = 6 (advisory message unit number) J06VCF GIVES NCOMM = 7 (command sequence unit number) J06VEF GIVES NSAV = 8 (save file unit number) X02AJF = 1.110223024625157E-016 (the machine precision) X02AKF = 5.562684646268003E-309 (the smallest positive model number) X02ALF = 8.988465674311579E+307 (the largest positive model number) X02AMF = 1.118577894763804E-308 (the safe range parameter) X02BBF = 2147483647 (largest positive integer) X02BEF = 15 (precision in decimal digits) X02DAF = F (indicates how underflow is handled) 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. DEC ReGIS The form and standard use of the ReGIS 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 DEC ReGIS Interface Usage section of the the NAG Graphics Library Reference Manual. 5.2. 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