NAG TOOLPACK/1 DISTRIBUTION BASE TAPE Release: 2.5 README NOTES FOR INSTALLERS 1. Tape Format Information The format of the tape is given on the printed tape label. The following information applies to all formats; The information is recorded: 9 track, phase encoded, 1600bpi. The files on the tape contain upper and lower case characters. FORMAT A: The data is in ASCII. The data is formatted as: 80 bytes per record, 4000 bytes per block. The tape has no header. FORMAT B: The data is in EBCDIC (includes these characters: "[]!|\^"). The data is formatted as: 80 bytes per record, 4000 bytes per block. The tape has no header. FORMAT C: The data is in ASCII. The data is written in ANSI X3.27 - 1978, level 4 format. The tape volume ID is: TPACK1 The tape owner name is blank. The data is formatted as: 80 bytes per record, 4000 bytes per block. FORMAT D: The data is stored in 'tar' format for Unix(tm) sites. The files are restored into a sub-tree rooted at 'toolpack' in the current working directory. NOTE: Format C is compatible with VAX/VMS Copy format with versions of VMS of 4.2 or later. 2. Disclaimer Toolpack/1 Release 2.5 is the latest version of the second Release of the Toolpack Fortran software tools distribution tape. It replaces Release 1.1 which was first Released in February 1985. The software is the result of an international collaborative project started in 1979. The project was supported by the Department of Energy and the National Science Foundation in the USA and by the Science and Engineering Research Council in the UK. Additional material for Release 2 has been provided by a number of organisations as a result of work carried out since Release 1.1. In making Toolpack/1 available, NAG is acting as a distribution agent on behalf of the Toolpack Council. Neither NAG nor the other Toolpack participants nor contributors of host specific TIECODE installations accept responsibility for the content or performance of Toolpack/1, and none of them will be liable in any way for the use of Toolpack/1 or the consequences of such use. 3. Tape Content Information This tape contains all the basic, portable Toolpack/1 software; TIECODE, tools, documentation and 2 host specific implementations of TIE. The files on the tape are detailed in Appendix A. Forms of TIECODE suitably modified for a variety of host environments are available optionally on seperate distribution tapes. 4. Documentation The Toolpack/1 Introductory Guide (second edition) applies to this software. Guides for TIECODE, machine-specific versions of TIE and for tool installers are provided in formatted forms that can be printed out on a line printer (page length assumed 72 lines, page width assumed 72 characters). Unformatted versions are also included for local formatting. The remaining documentation is provided in unformatted versions that must be processed before they can be printed out as they contain embedded formatting commands. These documents are in '---.RF' type files and should be processed using the Release 2.5 Toolpack/1 tool ISTRF using the macro file TDM provided on the tape in ISTRF.FILE, this contains the Toolpack Documentation Macros. If you use the Toolpack/1 command executor (ISTCE), formatting of a text file in the host file system can be performed as follows: rf #XXX.RF, #XXX, #TDM The formatted result is in file 'XXX' in the host system (the character '#' is the host file identification character used to specify the name of a host file to a Toolpack/1 tool). The file TDM forms part of the formatter tool and can be found in tape file 'ISTRF.FILE'. 5. What To Do Next Before proceeding to install Toolpack/1, you are STRONGLY advised to read the Toolpack/1 Introductory Guide. The next task is to read the TIECODE Installers' Guide provided, which will direct you in the selection and installation of an appropriate implementation of TIE (the portability base). Upgrading from Release:1 Sites that have already installed Release 1 of Toolpack/1 should note the following; a) There have not been any changes to the TIE definitions so it is not necessary to update your TIE implementation. However, both TIECODE and TIEVMS have undergone changes to improve their performance and quality and all bug fixes have been incorporated. Future bug fixes will be in terms of these new versions. b) The supplementary libraries have all undergone changes and improvements. They should be replaced with the new versions. c) Intermediate object (token stream, parse tree etc) formats have all changed, old style files are not acceptable to the new tools. Either delete intermediate objects or convert them back to source before replacing the old tools. d) All tools should be replaced with the new versions. NOTE For sites installing contributed TIECODE installations, the file ZDFLIB which is used by Release 1 TIEMAC, can be found in SUPORT.FILE. ZDFLIB is unnecessary, if the version of TIEMAC on this tape is used. 6. Recovering Files From Tape Documentation files may be recovered and expanded as described above. Files containing source code need to be split up using the SPLIT utility program before use. If the host system can not accept file names of the form 'XIIOOP.MAC' it will be necessary to edit the unsplit files. The split utility recognises the lines 'C $$$SPLIT$$$ ' and uses the supplied as the destination for the split text. Each file may split up into a number of individual units (COMMON.FILE splits into over 110 files). Further description of this utility can be found in the TIE Installers' Guide. 7. Service and Support While continuing to provide a distribution service for Toolpack/1, NAG can no longer undertake to provide a free bug fixing service. NAG will continue to receive bug reports, but no guarantee of response can be given except for those sites subscribing to the enhanced level of support (Service D). 8. Feedback This public distribution of Toolpack/1 is meant to provide a useful tool suite for processing Fortran 77 and to promote further interest in the development of programming support environments. You and your Toolpack/1 users may be able to assist that development in several ways: TIE: If you install the TIECODE version of the portability base on your host system, you may be willing to make your installed version available to other sites. If you produce an enhanced, or host specific TIE implementation, that may also be of great interest to other sites. Tools: As well as providing tools for immediate use, Toolpack/1 provides the capabilities required for users to produce portable tools for the Fortran community. If you build any tools that could be converted to the TIE portability base (and, if appropriate, the Toolpack/1 token stream and/or parse trees) please inform the tape distributor. General: Reports of suspected errors, comments, suggestions and criticisms would all be appreciated. All communications on the above catagories may be addressed in writing to the following address. An example form that will ensure that all the relevant information is provided is shown in Appendix B. Toolpack/1 Distribution Service Numerical Algorithms Group Ltd Mayfield House 256 Banbury Road Oxford United Kingdom OX2 7DE North American sites should contact NAG Incorporated at the Address below: Toolpack/1 Distribution Service Numerical Algorithms Group Inc 1101 31st Street, Suite 100 Downers Grove, IL 60515-1263 USA Target Language There have been some extensions made to the target language processed by Toolpack/1 tools. The extensions are described in the Toolpack/1 Fortran Definition documentation. Software The software has had all available bug fixes reported during the life of Release 1 applied. Documentation The documentation has been brought up to date. The TIE Installers' Guide has been modified to provide greater assistance in the installation of a TIE implementation and to reflect changes in the underlying software. TIE Implementations The following implementations of TIE are provided on the tape: TIEVMS This implementation for VAX/VMS sites has been improved. The .DIR empty file is no longer required and arguments are picked up automatically from the command line, if provided. A Pascal compiler and a 4.2 version of VMS (or later) are required. TIEC The TIEC implementation for Unix sites is included, this version is written in C and is intended for use on Unix based systems. TIECODE The 'portable' Fortran implementation of TIE is provided. It has been revised so that there is no BLOCK DATA required. Supplementary Libraries ACCESS The access functions for ISTPR format trees have been removed. There are additional functions to allow access to the attribute information generated by ISTSA. There have been extensive changes made to both the formats of intermediate files and the operation of token stream access functions. These changes have 2 benefits. Firstly they make operation much faster as fewer read/write operations are required. Secondly it is now possible to use the scanner and polish tools as subroutines within user written tools, avoiding the need to write out intermediate files when these are not actually required for further processing. Additional token and parse tree node types have been added. There is no longer any BLOCK DATA in this library, ZCTYPE/ZBTYPE have been replaced with an include file of parameters (ZPTYPE). STRING A new routine has been added to check the legality of Fortran variable, routine and common block names. There is now no BLOCK DATA associated with this library. TABLES A new set of linked list functions have been provided that allow the setting up and manipulation of lists of linked lists. WINDOW Pop up menus and information windows are now provided. Tools Below is a list of the tools giving a brief description of their function and changes that have been introduced since Release 1.1, these changes are in addition to the fixing of bugs and tidying of code to improve maintainability and readability. ISTAL The documentation generation aid. This tool can now report unexecuted segments in instrumented code. Some other minor improvements have also been made. ISTAN The Fortran 77 instrumentor has been improved. ISTCB The change bar processor is a new tool at this Release. Used as a pre-processor it will find differences between documents and insert ISTRF instructions to display change and delete bars. ISTCD/ISTSB/ISTUD These three new tools will unroll and condense DO loops. The restructured code is in a form that can be more easily optimised by compilers for vector machines. ISTCE The command executor tool. This tool now recognizes the new tools, this has meant a change in name of some of the internal commands, most notably the LS command is now named LD. ISTCN A simple, stream based token stream editor that can be used for changing strings within Fortran program units. A new tool at this Release. ISTCR A name changer for Fortran program units that works selectively on the symbol table. A new tool at this Release. ISTDC The data file comparison tool has been tidied up but remains operationally unchanged. ISTDS The declaration standardiser, this can now deal with the new types and also will not interfer with items declared in INCLUDE files if these have been included using ISTIN. ISTDX The documentation extractor. ISTED The editor has remained unchanged, but now incorporates the new version of the scanner. ISTET A tab expander tool has been added to Toolpack/1. ISTFD The fortran differencer has remain unchanged. ISTFI The utility for finding include file dependencies. ISTFL The file length utility and example tool for the tool writers guide. ISTFP The fast polish utility. ISTFR A new tool to convert REAL, DOUBLE PRECISION, COMPLEX and DOUBLE COMPLEX constants to a consistent form. ISTGI The tool to turn intrinsics into generic references has remained essentially unchanged but now accepts the defined DOUBLE COMPLEX intrinsics. ISTGP The generalised pattern matching utility. ISTHP The simple help program. ISTIN A new tool to assist in the use of INCLUDE files. ISTJS A new tool to manipulate FORMAT statements, can join adjacent strings and turn H and X edit descriptors into strings. ISTLS A long name changer, allows Fortran programs to be written using long variable names, this tool then be using to map them to legal names. This is a new tool at this Release. ISTLX The Fortran 77 scanner tool files. This tool has been extensively modified. The tool can now split up files into individual token streams, one per program unit, to assist in the processing of large input files. The error file has now been dropped and the list file made optional. There are changes to the format of the token stream and comment file to speed operation. The grammar has been modified to handle all types of comments, to allow DOUBLE COMPLEX and to improve general processing. ISTME A new tool to modify complicated expressions so that during calculation the sub-expression stack is kept to a minimum. ISTMF A new Fortran sensitive differencing program that will insert the differences as comments in the output code. ISTMP The macro processor has been tidied up but remains operationally unchanged. ISTPF A new tool, this provides a Fortran 77 equivalent of the PFORT portablility verifier capability. ISTPL The polish tool has been modified to cope with the new token types, several new processing options have also been added. ISTPO The polish option editor has been modified to accept the new polish options. ISTPP Ensures the consistency of PARAMETER statements across program units. ISTPT The arithmetic precision transformer can now handle the defined COMPLEX/DOUBLE COMPLEX mappings. ISTRF The text formatter has been modified to provide additional functionality. The most important result of this is that Toolpack/1 documentation can now be processed by ISTRF in a single stage without the need for pre-processing through ISTMP. ISTSA A new tool providing a static analysis capability to check software conformance to the Fortran 77 standard. ISTSP The file split utility. ISTST A new tool that will rebuild the structure of programs to a standard form. ISTSV The save/restore tool has remained unchanged. ISTTD The text differencer has remained unchanged. ISTUN This tool reverses the effect of ISTIN, replacing included files by an INCLUDE statement. ISTVA The attribute viewing utility is a new tool at this Release that allows the user to examine the attribute tables created by ISTSA. ISTVC The version controller file. The minus sign for specifying options is now optional. ISTVS The symbol viewing utility allows users to view the symbol table. ISTVT The parse tree viewing utility allows users at sites that have installed the WINDOW Supplementary Library to graphically display and print out parse trees. ISTVW A new tool, based on ISTVS that gives a simple listing of warnings about a program unit. The warnings are the same as those reported by ISTAL. ISTYF The parse tree flattener. ISTYP The parser has been modified to accept the target language extensions. The output form of the parser has been modified to speed up operation. Combined Tool Fragments ISTDT The combined ISTYP/ISTDS/ISTPL tool. Token stream to source with declaration standardisation. ISTLA The combined ISTLX/ISTYP/ISTSA tool. Source to full static analysis. ISTLP The combined ISTLX/ISTPL tool. Source to source polishing operation. ISTLY The combined ISTLX/ISTYP tool. Source to parse tree. ISTP2 The combined ISTLX/ISTPP/ISTPL tool. Source to source parameter setting. ISTQD The combined ISTLX/ISTYP/ISTDS/ISTPL tool. Source to source declaration standardiser. ISTQP The combined ISTLX/ISTYP/ISTPT/ISTPL tool. Source to source precision convertor. ISTQT The combined ISTLX/ISTYP/ISTPT tool. Source to token stream with a precision conversion. Experimental Tools ISTCI The experimental command interpreter. ISTJF The symbolic differentiator tool. ISTXX The experimental simple expert systems. NEWTON The old Newton system (ISTPR, ISTNA, ISTNI, ISTNL and ISTNR) has been deleted. Replacement of this facility is now underway. The file supplied on this tape is an early version of the instrumentor and loader. No run time library can be supplied yet. Subscribers to the Toolpack information service will receive news of the release date of the complete NEWTON system. Documentation TOOLS All the tool documents have been updated as required to reflect current tool operation. Documents for deleted tools are no longer provided, documents have been provided for new tools. The new monolithic tools are all covered in a single manual. TIG The TIE Installers' Guide (formally the TIECODE Installers' Guide) has been modified to try and ease the installation process. This guide should be used by all installers as it directs the selection of a TIE implementation and its installion. TAPE CONTENTS Below is a list of the contents of the tape. Files marked '+' are unformatted documentation that must be run through ISTRF as described above. Files marked '*' should be split up using the SPLIT utility prior to use. -- Toolpack/1 Utilities -- 1) README A brief summary of tape contents 2) SPLIT.FTN The split tool 3) TIEMAC.FTN The Toolpack/1 simple pre-processor -- Formatted Documentation -- 4) TIC TIEC User and Installation documentation 5) TIG The TIE Installers' Guide 6) TOL The Tool Installers' Guide 7) VMS TIEVMS User and Installation documentation 8) WIT What is TIE? -- TIECODE 'Portable' Implementation of TIE -- * 9) TIE.FILE The files for the TIE directory. * 10) COMMON.FILE The files for the COMMON directory. * 11) PFS.FILE The files for the PFS directory. 12) HOST.MAC The files for the HOST directory. 13) DIRECT.MAC The files for the DIRECT directory. 14) EMBED.MAC The files for the EMBEDDED directory. * 15) SUPORT.FILE The files for the SUPPORT directory. -- VAX/VMS Implementation of TIE -- * 16) VMSPAS.FILE The Pascal source files for TIEVMS. * 17) VMSMAC.FILE The macro definition and TIEMAC compatible files for TIEVMS. * 18) VMSCOM.FILE The example script files for tool operations. 19) VMSCMN.MAC The routines from the TIECODE COMMON file used in TIEVMS. * 20) CWIN.RF Documentation of a C version of the WINDOW Supplementary Library. * 21) CWIN.FILE A C version of the WINDOW Supplementary Library. -- Unix Implementation of TIE -- * 22) TIEC.FILE The C code and include files for TIEC. * 23) UNIX.FILE Script file documentation and utilities. * 24) ROS3.2 Ross 3.2 script files. * 25) BERK4.1 Berkley 4.1 script files. -- TIE Supplementary Libraries -- * 26) ACCESS.FILE The access functions supplementary library. * 27) STRING.FILE The string manipulation supplementary library. * 28) TABLES.FILE The table handling supplementary library. * 29) WINDOW.FILE The screen and window handling supplmementary library -- Toolpack/1 Tool Fragments -- * 30) MISC.FILE Miscellaneous smaller tools * 31) LOOPS.FILE The DO loop unrolling tools * 32) ISTAL.FILE The documentation generation aid * 33) ISTAN.FILE The Fortran 77 instrumentor * 34) ISTCE.FILE The command executor * 35) ISTCN.FILE The name changers ISTCN and ISTCR * 36) ISTDC.FILE The data file comparison tool * 37) ISTDS.FILE The declaration standardiser * 38) ISTED.FILE The editor * 39) ISTFD.FILE The fortran differencer * 40) ISTGI.FILE The tool to turn intrinsics * 41) ISTLS.FILE The long name changer * 42) ISTLX.FILE The Fortran 77 scanner * 43) ISTMF.FILE The merge Fortran differencer * 44) ISTMP.FILE The macro processor * 45) ISTPF.FILE The PFORT 77 tool * 46) ISTPL.FILE The polish tool * 47) ISTPO.FILE The polish option generator * 48) ISTPT.FILE The precision transformer * 49) ISTRF.FILE The text formatter file * 50) ISTSA.FILE The semantic analyser * 51) ISTSV.FILE The save/restore tool * 52) ISTST.FILE The Fortran structurer. * 53) ISTTD.FILE The text differencer * 54) ISTVA.FILE The attribute viewing utlity * 55) ISTVC.FILE The version controller * 56) ISTVS.FILE The ISTVS and ISTVW viewing tools * 57) ISTVT.FILE The parse tree viewing utility * 58) ISTYF.FILE The parse tree flattener * 59) ISTYP.FILE The parse tree builder -- Toolpack/1 Combined Tool Fragments -- * 60) MONOL.FILE The monolithic tools. -- Toolpack/1 Experimental Tool Fragments -- * 61) ISTCI.FILE The experimental command interpreter. * 62) ISTJF.FILE The symbolic differentiator tool. * 63) ISTXX.FILE The experimental simple expert systems. * 64) NEWTN.FILE A pre-release version of the NEWTON system. -- General Toolpack/1 Documentation -- + 65) EXT.RF Toolpack/1 Target Fortran 77 Definition + 66) FOC.RF Flow of control documentation. + 67) TWG.RF Tool Writers guide. + 68) WIT.RF What is TIE?. -- Toolpack/1 Tool Documentation -- + 69) EXP.RF Experimental expert system guide. + 70) MISC.RF Miscellaneous smaller tools documentation. + 71) MTG.RF Monolithic Tool Guide. + 72) TAL.RF ISTAL documentation. + 73) TAN.RF ISTAN documentation. + 74) TCE.RF ISTCE documentation + 75) TCI.RF ISTCI documentation. + 76) TCN.RF ISTCN/CR documentation. + 77) TDC.RF ISTDC documentation. + 78) TDO.RF DO Loop Unrolling tools documentation. + 79) TDS.RF ISTDS documentation. + 80) TED.RF ISTED documentation + 81) TFD.RF ISTFD documentation. + 82) TGI.RF ISTGI documentation. + 83) TJF.RF ISTJF documentation. + 84) TLS.RF ISTLS documentation. + 85) TLX.RF ISTLX documentation. + 86) TMF.RF ISTMF documentation. + 87) TMP.RF ISTMP documentation. + 88) TPF.RF ISTPF documentation. + 89) TPL.RF ISTPL/ISTPO documentation. + 90) TPT.RF ISTPT documentation. + 91) TRF.RF ISTRF documentation. + 92) TSA.RF ISTSA documentation. + 93) TST.RF ISTST documentation. + 94) TSV.RF ISTSV documentation. + 95) TTD.RF ISTTD documentation. + 96) TVA.RF ISTVA documentation. + 97) TVC.RF ISTVC documentation. + 98) TVS.RF ISTVS documentation. + 99) TVT.RF ISTVT documentation. +100) TYF.RF ISTYF documentation. +101) TYP.RF ISTYP documentation. -- Toolpack/1 Library Documentation -- +102) ASG.RF ACCESS supplementary library guide. +103) QRG.RF Quick reference guide. +104) SSG.RF STRING supplementary library guide. +105) TRD.RF TIE Routine Definitions. +106) TSG.RF TABLES supplementary library guide. +107) WIN.RF WINDOW Supplementary Library Guide. -- Toolpack/1 Installation Documentation (unformatted) -- +108) TIC.RF TIEC User and Installation documentation. +109) TIG.RF TIECODE installers guide. +110) TOL.RF Tool Installers' Guide. +111) VMS.RF TIEVMS User and Installation documentation. -- Toolpack/1 Incomplete Tool (explanation) -- +112) NEWTN.RF Notes on the incomplete Newton Dynamic Debugger. ****** Toolpack/1 Release 2 Problem Reporting Form ****** _______________________________________________________________________________ 1) Details of person raising report. Name: Address: Phone: Extension: e-mail: Date: _______________________________________________________________________________ 2) Details of Toolpack installation. Host computer/operating system: TIE Implementation in use: TIECODE System.............. TIEVMS TIEC Other: Toolpack Update Notices applied: Does your site subscribe to the Toolpack/1 support service? YES/NO _______________________________________________________________________________ 3) Report: _______________________________________________________________________________ 4) Enclosures: _______________________________________________________________________________ ------------------------------FOR NAG USE ONLY--------------------------------- Reference: Support service: Date received: Routed to: Date completed: Action taken: