Because I wasn't able to find a PDF version of this manual I'm providing the ASCII source code for the online manual instead. To read this inside the system log into IAF and type EXPLAIN,M=FTN5UG. This will present the manual in the way it was intended to be viewed which is very similar to GNU Info. \s,about \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,about_a \m=b,about_b \m=c,about_c \m=d,about_d \m=e,about_e \m=f,about_f \c,---------------------------------------------------------------------------- \i,about this manual \i,about \c,---------------------------------------------------------------------------- FTN5UG ABOUT THIS MANUAL Screen 1 of 1 (FORTRAN VERSION 5 USER'S GUIDE) (Publication Number L60484000) This is the online version of the FORTRAN Version 5 User's Guide, publication number L60484000. These menu topics give background information about this manual. a. Copyright Information b. Manual History c. Submitting Comments d. Preface e. Notational Conventions f. Additional Related Manuals Press RETURN to read the Copyright Information. Enter UP to return to the Main menu. \c,---------------------------------------------------------------------------- \s,about_a \u,about \c,---------------------------------------------------------------------------- \i,copyright information \i,front matter \i,control data corporation \i,cdc \i,copyright \i,control data \c,---------------------------------------------------------------------------- FTN5UG COPYRIGHT INFORMATION Screen 1 of 1 This product is intended for use only as described in this document. Control Data cannot be responsible for the proper functioning of undescribed features or parameters. COPYRIGHT CONTROL DATA CORPORATION 1984 All Rights Reserved. Limited local reproduction of this document is permitted within a customer site providing Control Data is given acknowledgement for the original document. Control Data grants permission to modify this document according to local site requirements. The revised document must bear an acknowledgement that it is based on a Control Data Corporation document, must be protected by copyright, and cannot be made available for sale. Press RETURN to read the Manual History. \c,---------------------------------------------------------------------------- \s,about_b \u,about \c,---------------------------------------------------------------------------- \i,manual history \i,revision \i,revision c \i,revision record \i,revision level \c,---------------------------------------------------------------------------- FTN5UG MANUAL HISTORY Screen 1 of 1 Revision C documents the FORTRAN Version 5 product for NOS 2 Version at PSR level 617. This manual was published September, 1984. Press RETURN to read about Submitting Comments. \c,---------------------------------------------------------------------------- \s,about_c \u,about \c,---------------------------------------------------------------------------- \i,submitting comments \i,address \i,address of cdc \i,address of control data \i,cdc address \i,control data address \i,comments \i,comment sheet \i,questions \c,---------------------------------------------------------------------------- FTN5UG SUBMITTING COMMENTS Screen 1 of 1 (FORTRAN Version 5 User's Guide) (Publication Number L60484000) Please submit a comment sheet to give us your opinion of the manual's usability, to suggest specific improvements, to report missing screens or topics, or to report technical or typographical errors. Please supply the following information: Your name Your business telephone number Your company's name The date Your company's address Whether you would like a written response Address comments concerning this manual to: CONTROL DATA CORPORATION Publications and Graphics Division P.O. Box 3492 Sunnyvale, California 94088-3492 Press RETURN to read the Preface. Enter UP to return to the About This Manual menu. \c,---------------------------------------------------------------------------- \s,about_d \u,about \c,---------------------------------------------------------------------------- \i,preface \i,fortran user's guide \i,60484000 \i,background \i,publication number \c,---------------------------------------------------------------------------- FTN5UG PREFACE Screen 1 of 1 This user's guide provides helpful information for the interactive use of CDC FORTRAN 5 under the NOS 2 operating system. This guide is intended primarily for the nonprofessional FORTRAN programmer who is familiar with a version of FORTRAN 77 but is unfamiliar with the NOS 2 operating system and with running FORTRAN programs in a CDC environment. It is a supplement to the FORTRAN Version 5 Reference Manual (publication number 60481300), with minimal duplication of information. This guide concentrates on the interfaces between FORTRAN 5 and other software products as well as on programming, debugging, and optimization techniques of interest to the FORTRAN 5 programmer. Press RETURN to read about Notational Conventions. \c,---------------------------------------------------------------------------- \s,about_e \u,about \c,---------------------------------------------------------------------------- \i,notational conventions \i,notations \i,uppercase \i,uppercase words \i,lowercase \i,lowercase words \i,conventions in examples \i,conventions \c,---------------------------------------------------------------------------- FTN5UG NOTATIONAL CONVENTIONS Screen 1 of 2 This manual uses various conventions in formats and examples. The conventions in formats are: UPPERCASE Uppercase text in examples of terminal dialog indicates output. Uppercase words in statement and command formats must appear exactly as shown. lowercase Lowercase text in examples of terminal dialog indicates user input. Lowercase words in statement and command formats indicate values or options supplied by you. . . . Horizontal ellipsis in statement formats indicate that the immediately preceding parameter can be repeated at your option. . Vertical ellipsis indicates that other FORTRAN statements or . parts of a program are not shown; they are not relevant to the . example. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,about \c,---------------------------------------------------------------------------- FTN5UG NOTATIONAL CONVENTIONS Screen 2 of 2 System control statement formats described in this manual are shown with a period terminator. This period is a required part of the statement syntax when the statement is is specified in a batch job, and is optional when the statement entered interactively. All numbers appearing in this manual are decimal unless otherwise specified Press RETURN for Additional Related Manuals. \c,---------------------------------------------------------------------------- \s,about_f \u,about \c,---------------------------------------------------------------------------- \i,additional related manuals \i,related manuals \i,other manuals \i,additional manuals \i,related information \i,cid reference manual \i,cyber interactive debug manual \i,cid rm \i,cid,9 \i,debug,9 \i,cyber loader reference manual \i,loader reference manual \i,loader rm \i,loader,9 \i,fortran reference manual \i,fortran rm \i,fortran,9 \i,nam ccp terminal interfaces reference manual \i,terminal interfaces reference manual \i,terminal interfaces rm \i,network access method \i,communications control program \i,nos reference manual \i,nos,9 \i,nos rm \i,nos volume 1 reference manual \i,nos volume 1 rm \i,introduction to interactive usage \i,nos volume 2 reference manual \i,nos volume 2 rm \i,guide to system usage \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL RELATED MANUALS Screen 1 of 3 The following screens show publications that might be of interest to the FORTRAN programmer. CYBER Interactive Debug Version 1 Guide for 60484100 Users of FORTRAN Version 5 CYBER Loader Version 1 Reference Manual 60429800 FORTRAN Version 5 Reference Manual 60481300 Network Access Method Version 1/ Communications 60480600 Control Program Version 3 Terminal Interfaces Reference Manual NOS Version 2 Reference Set, Volume 1, Introduction 60459660 to Interactive Usage NOS Version 2 Reference Set, Volume 2, Guide 60459670 to System Usage Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,about \c,---------------------------------------------------------------------------- \i,nos volume 3 reference manual \i,nos volume 3 rm \i,system commands,9 \i,xedit reference manual \i,xedit rm \i,xedit,9 \i,common memory manager reference manual \i,common memory manager rm \i,cmm reference manual \i,cmm rm \i,crm aam user's guide \i,crm advance access method user's guide \i,crm bam user's guide \i,crm basic access method user' guide \i,fortran data base facility reference manual \i,fortran data base facility rm \i,fortran dbf reference manual \i,fortran dbf rm \i,fdbf reference manual \i,fdbf rm \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL RELATED MANUALS Screen 2 of 3 NOS Version 2 Reference Set Volume 3, System 60459680 Commands Update Version 1 Reference Manual 60449900 XEDIT Version 3 Reference Manual 60455700 Common Memory Manager Version 1 Reference Manual 60499200 CYBER Interactive Debug Version 1 Reference Manual 60481400 CYBER Record Manager Advanced Access Methods 60499400 Version 2 User's Guide CYBER Record Manager Basic Access Methods 60495800 Version 1.5 User's Guide FORTRAN Data Base Facility Version 1 Reference Manual 60482200 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,about \n,about \c,---------------------------------------------------------------------------- \i,common library math routines reference manual \i,common library math routines rm \i,library math routines reference manual \i,library math routines rm \i,math routines reference manual \i,math routines rm \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL RELATED MANUALS Screen 3 of 3 FORTRAN Version 5 Common Library Mathematical 60483100 Routines Reference Manual NOS Version 2 Abstracts 60485500 Sort/Merge Version 4 Reference Manual 60497500 Sort/Merge Version 5 Reference Manual 60484800 Control Data manuals are available through Control Data sales offices, or from Control Data Literature Distribution Services at the following address: 308 North Dale Street St. Paul, Minnesota 55103 Press RETURN to return to the About This Manual menu. \c,---------------------------------------------------------------------------- \s,help \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,help_a \m=b,help_b \m=c,help_c \c,---------------------------------------------------------------------------- \i,how to use this manual \i,help \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE THIS MANUAL Screen 1 of 1 There are two ways to use this manual. The first is to select a topic from a menu by typing the corresponding letter followed by a carriage return. The second is to type a particular topic followed by a question mark and then a carriage return. The second way uses the index. The following menu topics discuss how to use this manual: a. Summary of Explain Commands b. How to Use a Menu c. How to Use the Index Enter the letter in front of the corresponding menu topic and press the carriage return key to select a menu topic. From now on, the phrase "enter one of the following letters" will be used to mean "enter the letter in front of the corresponding menu topic." Also, from now on, the phrase "press RETURN" will be used to mean "press the key that transmits data to the computer." Press RETURN for a Summary of Explain Commands. Enter UP return to the Main menu. \c,---------------------------------------------------------------------------- \s,help_a \u,help \c,---------------------------------------------------------------------------- \i,explain commands \i,commands \i,terminal commands \i,manual commands \i,return \i,return key \i,+ \i,+ key \i,+ command \i,plus sign,9 \i,- \i,- key \i,- command \i,minus sign,9 \i,topic? \i,topic? command \i,? \i,? command \i,< \i,< command \i,back arrow \i,less than \i,less than key \i,top \i,help \i,excerpt \i,revert \i,quit \i,next key \i,next \i,fwd \i,bkw \i,refresh \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF EXPLAIN COMMANDS Screen 1 of 1 CDC 721 Command Key Function ======= ======= ======== RETURN NEXT or FWD Goes to the next screen. - BKW Goes to the previous screen. UP UP Goes to the menu screen one level up. xxxx? DATA xxxx NEXT Goes to the first screen indexed for xxxx. ? DATA NEXT Goes to the next indexed screen for xxxx. < BACK Goes to where you last started an index search or made a menu selection. TOP SHIFT BACK Goes to the main menu. HELP HELP Goes to the How to Use This Manual topic. DISI (none) Displays beginning of index. DISI xxxx (none) Displays index, beginning at xxxx. QUIT SHIFT STOP Leaves the manual. Note: Commands can be typed in uppercase or lowercase. Press RETURN to read about How to Use a Menu. \c,---------------------------------------------------------------------------- \s,help_b \u,help \c,---------------------------------------------------------------------------- \i,how to use a menu \i,using a menu \i,menu usage \i,menus \i,+ \i,- \i,up \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE A MENU Screen 1 of 1 Each section of the FORTRAN user's guide online manual begins with a menu (a list of topics preceded by a letter). To read information about a particular topic, simply type the letter that corresponds to the desired topic and press RETURN. In many cases, another menu will be displayed and you will make another more detailed selection. Some topics are described on a single screen, while other topics are described on several screens. The phrase Screen 1 of n indicates that the topic is continued on one or more screens. The +, -, and UP commands allow you to page through the manual. A plus sign (+) or RETURN will take you to the next screen. A minus sign (-) will take you to the previous screen. UP will take you to the menu from which you made your current selection. Each time you type UP, you are taken up another level until you get to the main menu. Press RETURN to read about How to Use the Index. \c,---------------------------------------------------------------------------- \s,help_c \u,help \c,---------------------------------------------------------------------------- \i,how to use the index \i,using the index \i,index usage \i,index \i,topic? \i,xxxxx? \i,? \i,? command \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE THE INDEX Screen 1 of 4 The online index works much like the index of a book. To use the index, just type the name of a topic (cannot contain a comma or more than 50 characters) followed by a question mark (?). You will be taken directly to the discussion of that topic. You can do this from any point in the manual. For example, if you type LOADER? you will go directly to the discussion of the Loader. If you type a topic that is not in the index of the manual, an informative message will appear. In some cases there may be several parts of the manual that contain information on a topic. In this case, typing the index topic will take you to the most commonly used information first. If this is not the discussion you want, just type ? and you will be taken to another discussion of the topic. You can repeat this until no more information is found. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,help \c,---------------------------------------------------------------------------- \i,< \i,< key \i,< command \i,less than key \i,less than \i,back arrow \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE THE INDEX Screen 2 of 4 When you read a printed book, and you wish to momentarily refer to another part of the book, you might place a finger between the pages to hold your current place in the book. The online manual offers a similar "placeholding" capability. If you are at a given screen in the manual, and you proceed to another screen via the index feature, the manual "remembers" the screen you started from. You can go back to that screen simply by typing a back arrow (<). If you type < and you have not initiated a topic search, the result is the same as if you had typed UP. That is, you are taken to the menu from which you made your last selection. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,help \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE THE INDEX Screen 3 of 4 Here are some hints for using the index: 1. You can type either uppercase or lowercase letters. EXPLAIN treats uppercase and lowercase the same. For example, the following are equivalent: LOADER DIRECTIVES LOADER directives loader directives 2. If you make a spelling error, EXPLAIN will attempt to correct the error and take you to the desired part of the manual. For example, if you type COMPILTION?, EXPLAIN recognizes this as COMPILATION?. If, however, the error is too severe, EXPLAIN will be unable to correct it and will issue a message indicating that your entry cannot be recognized. For example, CMPLTAION? will not be recognized as COMPILATION?. Sometimes correction attempts will locate several equally valid corrections. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,help \n,help \c,---------------------------------------------------------------------------- FTN5UG HOW TO USE THE INDEX Screen 4 of 4 Index Hints: (continued) 3. The more specific you are, the more likely you will be taken where you expect. 4. If you want to see some example of a particular topic, type the topic followed by EXAMPLES? . For example, type SEGMENTED PROGRAM EXAMPLES? to see some segmented program examples. Press RETURN to return to the How to Use This Manual menu. \c,---------------------------------------------------------------------------- \s,$no_screen \u,main \p,main \n,main \c,---------------------------------------------------------------------------- FTN5UG NO SCREEN Screen 1 of 1 \ / 0 -XXX- -XXXXX- -XXX- X You found a bug in the manual. Your seeing this screen indicates that this manual is missing one or more screens. If you can remember how you got here, please report the circumstances to: CONTROL DATA CORPORATION Publications and Graphics Division P.O. Box 3492 Sunnyvale, CA. 94088-3492 Press RETURN to go to the Main menu. \c,---------------------------------------------------------------------------- \s,$no_topic \u,main \p,main \n,main \c,---------------------------------------------------------------------------- FTN5UG NO INDEX TOPIC Screen 1 of 1 \ / 0 -XXX- -XXXXX- -XXX- X You found a bug in the manual. Your seeing this screen indicates that this manual is missing the topic you tried to index. Please report the topic to: Control Data Corporation Publications and Graphics Division P.O. Box 3492 Sunnyvale, CA. 94088-3492 Press RETURN to go to the Main menu. \c,---------------------------------------------------------------------------- \s,main \p,main \i,about \c,---------------------------------------------------------------------------- \m=a,about \m=b,help \m=c,pe_c \m=d,ft_d \m=e,db_e \m=f,op_f \m=g,mn_g \m=h,ld_h \m=i,bt_i \m=j,gl_j \c,---------------------------------------------------------------------------- \i,main \i,main screen \i,main menu \i,beginning \i,manual beginning \i,beginning of manual \c,---------------------------------------------------------------------------- FTN5UG FORTRAN VERSION 5 USER'S GUIDE Screen 1 of 1 Welcome to the FORTRAN Version 5 User's Guide. Enter one of the following letters to learn about FORTRAN: a. About This Manual b. How to Use This Manual c. The Programming Environment d. FORTRAN 5 Features e. Debugging f. Optimization g. Program Maintenance h. Loading FORTRAN Programs i. Batch Programming j. Glossary Press RETURN to read About This Manual. Enter TOP to return to this screen at any time while reading this manual. \c,---------------------------------------------------------------------------- \s,pe_c \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,pe_ca \m=b,pe_cb \m=c,pe_cc \m=d,pe_cd \m=e,pe_ce \c,---------------------------------------------------------------------------- \i,the programming environment \i,programming environment \i,environment \c,---------------------------------------------------------------------------- FTN5UG THE PROGRAMMING ENVIRONMENT Screen 1 of 1 The software facilities that enable you to communicate with the NOS operating system from an interactive terminal is called the network. To access the operating system you must establish a connection to the network. (Enter BATCH? for parallel information for batch jobs.) Once the connection is made, you can enter commands and control statements for manipulating files and performing other useful operations. Enter one of the following letters for more information: a. The Terminal Session b. The Network - interacting with the computer from a terminal c. Executing in an Interactive Environment d. File Usage e. Magnetic Tape Processing Press RETURN to read about The Terminal Session. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,pe_ca \u,pe_c \c,---------------------------------------------------------------------------- \i,the terminal session \i,terminal session \i,session \i,beginning a session \i,beginning a terminal session \i,batch session,1 \i,batch,1 \i,batch job,1 \c,---------------------------------------------------------------------------- FTN5UG THE TERMINAL SESSION Screen 1 of 2 A terminal session is the interactive counterpart of the batch job. With batch execution, you generally punch a card deck containing the program to be executed, the required accounting information, and the control statements necessary to compile and execute the program and to perform other desired functions (such as retrieving and retaining files). You then submit the card deck to a card reader which reads the cards into the computer's memory. Finally, the operating system executes each control statement in sequence. The job terminates after the last control statement is executed. Enter BATCH? for more information on batch jobs. A terminal session begins when you establish a logical connection between the terminal and the computer and ends when you terminate the connection. The session consists of the commands and control statements you enter while the connection is active and the computer's responses to those commands and statements. The terminal session is interactive; that is, the computer immediately responds to each command and waits for the next command. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_c \c,---------------------------------------------------------------------------- FTN5UG THE TERMINAL SESSION Screen 2 of 2 In batch execution, the job communicates directly with the operating system. Interactive execution, however, requires additional software to provide a communication link between the terminal and the operating system. This software is known as the network. Press RETURN to read about The Network. Enter UP to return to The Programming Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cb \u,pe_c \c,---------------------------------------------------------------------------- \m=a,pe_cba \m=b,pe_cbb \m=c,pe_cbc \c,---------------------------------------------------------------------------- \i,the network \i,network \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK Screen 1 of 1 Enter one of the following letters to learn more about the network: a. Overview b. Interactive Facility c. Establishing a Connection to the System Press RETURN to read the Overview. Enter UP to return to The Programming Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cba \u,pe_cb \c,---------------------------------------------------------------------------- \i,the network overview \i,network overview \i,network concepts \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK OVERVIEW Screen 1 of 5 The network is a collection of software modules which enables you to interact with the computer from a terminal. As a FORTRAN programmer, you need not have an extensive knowledge of the network in order to use it; in fact, for most of the operations associated with maintaining and executing FORTRAN programs, you need only a few basic concepts. All you really need to know is the procedure for establishing a connection to the network (enter CON? if you wish to read the information now); most other network functions will be transparent to you. However, a basic understanding of the functions of the network and of the services that it offers can be helpful, if for no other reason than to take some of the mystery out of interactive programming. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cb \c,---------------------------------------------------------------------------- \i,information processing \i,processing information \i,system security,1 \i,unauthorized access,1 \i,security,1 \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK OVERVIEW Screen 2 of 5 When you enter a command at the terminal and receive an immediate response, you might think that you are communicating directly with the operating system. However, all information that passes between you and the computer is subject to some rather complex processing before reaching its final destination. The software modules composing the network are responsible for this processing. Although the detailed operations of these modules and the interactions between them might appear difficult to understand, the concepts involved are relatively simple. All information that passes between you and the computer must be processed as follows: It must be protected from unauthorized access. It must be converted to specific formats. It must be diagnosed for errors. It must be routed to the appropriate destination. It must be coordinated with information passing to or from other terminals. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cb \c,---------------------------------------------------------------------------- \i,basic operation of the network \i,network operation \i,operation of the network \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK OVERVIEW Screen 3 of 5 Most of the processes listed on the previous screen require no knowledge or intervention on your part. Therefore, for the sake of simplicity, the network and the operating system are collectively referred to as the system throughout the remainder of this guide. The basic operation of the network is diagrammed in the following figure on the following screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cb \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK OVERVIEW Screen 4 of 5 Network Function Host Computer +---------------------------------------------------------------------------+ | +-----+ | | | | | | /-----| | | | +---------+ +--------------------------+ / +-----+ | | | | |+------------+ | / +-----+ FORTRAN | | | | || Network | Operating |/ | | Program | | | Network |<---->|| Application| System |---------| | and | | | | || Program | |\ +-----+ Data | | | | |+------------+ | \ +-----+ Files | | +---------+ +--------------------------+ \ | | | | ^ \-----| | | | | +-----+ | +------V--------------------------------------------------------------------+ +----------+ | Terminal | +----------+ Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cb \c,---------------------------------------------------------------------------- \i,network application program \i,interactive facility,1 \i,iaf,1 \i,transaction facility \i,taf \i,remote batch facility \i,rbf \c,---------------------------------------------------------------------------- FTN5UG THE NETWORK OVERVIEW Screen 5 of 5 A network component of particular interest to the FORTRAN programmer is the network application program. The network application program performs specific terminal servicing functions in addition to those outlined above. Several of these programs are available; during the login procedure, you must indicate which of the network application programs you wish to use. In the vast majority of cases, you will be using a network application program called the Interactive Facility (IAF). IAF is the network component that enables you to interactively communicate with the NOS operating system. Throughout the remainder of this guide, it is assumed that you are using IAF. Other network application programs which might be of interest to you are the Transaction Facility (TAF) and the Remote Batch Facility (RBF). TAF and RBF are more specialized than IAF, and have limited usefulness to the FORTRAN programmer; they are not described in this guide. Refer to the appropriate publications for more information. Press RETURN to read about the Interactive Facility. Enter UP to return to The Network menu. \c,---------------------------------------------------------------------------- \s,pe_cbb \u,pe_cb \c,---------------------------------------------------------------------------- \m=a,pe_cbba \m=b,pe_cbbb \c,---------------------------------------------------------------------------- \i,interactive facility \i,iaf \i,communicating with NOS \i,operating system communication \i,iaf operation \i,iaf subsystem \i,program processing \i,subsystems \c,---------------------------------------------------------------------------- FTN5UG INTERACTIVE FACILITY Screen 1 of 1 The Interactive Facility enables you to communicate interactively with the NOS 2 operating system. IAF provides special features and commands for creating, compiling, and executing FORTRAN programs and for manipulating files. A summary of IAF is presented here. Refer volume 2 of the NOS 2 reference set for detailed information on IAF operation. IAF is composed of several subsystems, each designed to simplify some aspect of program processing. When you initially enter IAF, a default subsystem is automatically selected. You can switch to another subsystem at any time during the terminal session by entering the appropriate command. The subsystems of most interest to the FORTRAN programmer are the BATCH, FORTRAN, and EXECUTE subsystems. Enter one of the following letters to learn more about these subsystems: a. BATCH Subsystem - provides the most power and flexibility. In most cases, BATCH is the default subsystem. b. FORTRAN and EXECUTE Subsystems - provide abbreviated methods of creating, compiling, and executing FORTRAN programs. Press RETURN to read about the BATCH Subsystem. Enter UP to return to The Network menu. \c,---------------------------------------------------------------------------- \s,pe_cbba \u,pe_cbb \c,---------------------------------------------------------------------------- \i,batch sybsystem \i,batch,1 \i,batch control statement \i,batch statement \i,batch command \i,iaf prompt \i,slash prompt \i,/ \i,slash \i,prompt \c,---------------------------------------------------------------------------- FTN5UG BATCH SUBSYSTEM Screen 1 of 3 The BATCH subsystem is so named because it allows you to enter batch control statements as well as IAF commands. You should not confuse the BATCH subsystem with batch mode execution. In the BATCH subsystem, all commands and statements you enter are processed interactively; that is, the system executes the command and returns control to you. The command to enter the BATCH subsystem is: BATCH IAF responds with the message: RFL,0 / and waits for you to input an IAF command or a control statement. The / character is the IAF prompt for a command or control statement. When IAF is through processing the command or control statement, IAF displays a / and returns control to you. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbb \c,---------------------------------------------------------------------------- \i,system control statement format \i,control statement format \i,format of control statement \i,subsystem control statement format \i,termination character \i,entering control statements from a terminal \c,---------------------------------------------------------------------------- FTN5UG BATCH SUBSYSTEM Screen 2 of 3 If BATCH is the default subsystem at your site, you do not need to enter the BATCH command after connecting to IAF; you can begin entering commands and control statements immediately. The format for system control statements entered under IAF is the same as for batch jobs (as described in the NOS reference manual), except that you can omit the termination character (either a period or a right parenthesis). For example: FTN5,I=PROG. LGO. is identical to: FTN5,I=PROG LGO when entered from a terminal. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbb \c,---------------------------------------------------------------------------- \i,invalid control statements \i,invalid statements \i,illegal control statements \i,illegal statements \c,---------------------------------------------------------------------------- FTN5UG BATCH SUBSYSTEM Screen 3 of 3 When a batch job is executing, an illegal control statement usually terminates the job. Under IAF, however, an invalid statement does not terminate the terminal session. If you enter a statement incorrectly and you detect the error before pressing carriage return, you can backspace to the position of the error and reenter the statement from that point. If you enter an incorrect statement and press carriage return, IAF displays the message: ILLEGAL CONTROL CARD / and you can reenter the statement. In either case, the terminal session continues. Press RETURN to read about the FORTRAN and BATCH Subsystems \c,---------------------------------------------------------------------------- \s,pe_cbbb \u,pe_cbb \n,pe_cbb \c,---------------------------------------------------------------------------- \i,fortran and execute subsystems \i,fortran subsystem \i,execute subsystem \c,---------------------------------------------------------------------------- FNT5UG FORTRAN AND EXECUTE SUBSYSTEMS Screen 1 of 1 The FORTRAN and EXECUTE subsystems provide a convenient method for creating, modifying, and executing a FORTRAN program. These subsystems are useful mainly for working with very short FORTRAN programs. Refer to volume 1 of NOS 2 reference set for more information on these subsystems. Press RETURN to return to the Interactive Facility menu. \c,---------------------------------------------------------------------------- \s,pe_cbc \u,pe_cb \p,pe_cb \c,---------------------------------------------------------------------------- \m=a,pe_cbca \m=b,pe_cbcb \m=c,pe_cbcc \c,---------------------------------------------------------------------------- \i,con,0 \i,establishing a connection to the system \i,terminal connection \i,connecting to the system \i,system connection \i,connecting to the terminal \c,---------------------------------------------------------------------------- FTN5UG ESTABLISHING A CONNECTION TO THE SYSTEM Screen 1 of 1 For any terminal session, the very first step is to establish the connection between the terminal and the system. A brief description of this procedure is presented here. A more detailed description appears in the IAF reference manual. The actual procedure you will follow depends on the type of terminal you are using and on various installation parameters; however, it will be similar to the one presented here. Enter one of the following letters to learn more about connecting the terminal and the system: a. Overview b. Login Procedure c. Logout Procedure Press RETURN to read the Overview. Enter UP to return to The Network menu. \c,---------------------------------------------------------------------------- \s,pe_cbca \u,pe_cbc \c,---------------------------------------------------------------------------- \i,establishing a connection to the system overview \i,steps to establish terminal connection \i,terminal switch checking \i,terminal connection \i,terminal switches \i,switches \i,power switch \i,dial-in \i,calling the computer \i,phone connection \i,connecting the terminal \i,talking to the computer \i,selecting a host \i,host selection \i,host path \c,---------------------------------------------------------------------------- FTN5UG ESTABLISHING A CONNECTION TO THE SYSTEM OVERVIEW Screen 1 of 2 Establishing a connection to the system involves the following steps: Terminal switch checking. You must first turn the power switch on. Normally, this is the only switch you will need to set; the remaining switches should already have the correct setting. The switches that are present on your terminal, and their correct settings, depend on the terminal type. If you have any doubt about the settings of these switches, or if the terminal does not perform as expected, check with terminal administrative personnel. Dial-in. Again, this procedure depends on the terminal type. Basically, the procedure consists of dialing the computer number on the phone next to the terminal. (If the data set is in the terminal, the dial is on the front of the terminal. If the terminal is hardwired, the connection is automatic and dial-in is not performed.) If you do this correctly, the terminal will display an informative message and then request that you begin the login procedure or a list of host names is displayed if you need to choose a host. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,login,1 \i,login procedure,1 \c,---------------------------------------------------------------------------- FTN5UG ESTABLISHING A CONNECTION TO THE SYSTEM OVERVIEW Screen 2 of 2 Selecting a host. You might need to select the host which will run the software you want to use. This is not necessary if your installation personnel select a host path for your terminal when the network is configured. Check with your site analyst if you do not know which host to use. Login. The login procedure identifies you as a valid computer user and opens the communication path to the network. For some terminals, this procedure is initiated automatically following dial-in; for others, you must enter a certain character or press carriage return. Check with your site analyst if you have any doubt. Once you successfully complete the login procedure, you can begin the terminal session. Press RETURN to read about the Login Procedure. \c,---------------------------------------------------------------------------- \s,pe_cbcb \u,pe_cbc \c,---------------------------------------------------------------------------- \i,login,0 \i,login procedure,0 \i,purpose of login \i,security \i,system security \i,unauthorized access \i,protecting files \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 1 of 6 The login procedure involves a dialog with the network in which the network issues various requests and you respond with the appropriate information. The primary purpose of the login procedure is to provide security for the system. Requiring each user to enter certain preassigned values before completing the connection prevents unauthorized users from using the system and protects your files against access by other computer users. If you enter any of the required information incorrectly, or if any of the information is invalid, the network issues an appropriate message and repeats the request. After a certain number of unsuccessful tries (usually three), the network automatically breaks the connection, and you must repeat the dial-in procedure. If this occurs, it is a good idea to seek help. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,information needed to login \i,login information \i,user name \i,password \i,family name \i,charge number \i,project number \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 2 of 6 In order to complete the login procedure, you must have the following information: Your user name Your password Your family name Your charge number Your project number The preceding values are assigned to you by personnel at your installation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,login prompt \i,family: \i,entering family name \i,family name \i,user name prompt \i,user number: \i,entering user name \i,entering password \i,password: \i,password \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 3 of 6 Immediately after dial-in, the terminal displays the following prompt: FAMILY: In response, enter your family name, or, if yours is the system default name, enter carriage return. The terminal then displays the prompt: USER NUMBER: Enter your user name followed by carriage return. The system then requests your password: PASSWORD: Enter your password, followed by carriage return. If a password is not required by your system, enter only carriage return. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,application prompt \i,application: \i,network application program \i,charge number prompt \i,recover/charge: \i,entering charge number \i,entering application \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 4 of 6 The next request is for the name of the network application program you wish to use: APPLICATION: Enter the desired application name (usually IAF). The next prompt is either: RECOVER/SYSTEM: or RECOVER/CHARGE: The first prompt appears if your system does not use charge numbers. In this case, the login procedure is complete; enter a valid command. If the second prompt appears, enter CHARGE followed by your charge number and project number. For example: CHARGE,5432,PROG1 This completes the login procedure; you can now begin the terminal session. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,shortening login procedure \i,login on one line \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 5 of 6 You can shorten the login procedure by entering all of the required information on the same line in response to the FAMILY request, as follows: FAMILY: familyname,username,password,application If you omit any of the parameters from the preceding line, the commas must remain. For example: FAMILY:,username,password,application The figure on the following screen illustrates a typical login sequence. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cbc \c,---------------------------------------------------------------------------- \i,login example \i,example of login \c,---------------------------------------------------------------------------- FTN5UG LOGIN PROCEDURE Screen 6 of 6 The following figure illustrates a typical login sequence: FAMILY: abc USER NAME: def444 PASSWORD: qrst TM1234 - APPLICATION: iaf TERMINAL: 15,NAMIAF RECOVER/CHARGE: charge,8698,3456123 / Press RETURN to read about the Logout Procedure. \c,---------------------------------------------------------------------------- \s,pe_cbcc \u,pe_cbc \n,pe_cbc \c,---------------------------------------------------------------------------- \i,logout procedure \i,logout \i,terminating a session \i,breaking the terminal connection \i,end a terminal session \i,end a session \i,goodby command \i,goodby \i,bye command \i,bye \i,logout command \c,---------------------------------------------------------------------------- FTN5UG LOGOUT PROCEDURE Screen 1 of 1 The logout procedure ends the terminal session by breaking the connection between the terminal, the network, and the operating system. To end the terminal session, enter one of the commands: GOODBYE or BYE or LOGOUT The network displays the total connect time and amount of system resource units used and then disconnects the terminal. Press RETURN to return to the Establishing a Connection to the System menu. \c,---------------------------------------------------------------------------- \s,pe_cc \u,pe_c \p,pe_c \c,---------------------------------------------------------------------------- \m=a,pe_cca \m=b,pe_ccb \m=c,pe_ccc \m=d,pe_ccd \c,---------------------------------------------------------------------------- \i,executing in a interactive environment \i,executing interactively \i,interactively executing \i,xedit,1 \i,interactive environment \c,---------------------------------------------------------------------------- FTN5UG EXECUTING IN AN INTERACTIVE ENVIRONMENT Screen 1 of 1 Once you have logged in to the system, you can begin to perform the procedures associated with executing a FORTRAN program. A program to be compiled and executed at the terminal consists of a text file of FORTRAN statements, usually created through a text editor such as XEDIT. (Enter XEDIT? for a description of XEDIT.) You can compile and execute a program, or you can execute a binary program created by a previous compilation. The program can read or write data files stored on mass storage or magnetic tape, or it can perform input and output interactively, reading data directly from and writing data directly to the terminal. After the program has terminated, you can enter commands to dispose of any files associated with the program, to make corrections to the program and reexecute it, or to perform other desired operations. Enter one of the following letters to learn more about the interactive environment: a. Sample Terminal Sessions c. Changing the Execution Time Limit b. Interactive Input/Output d. Informative Commands Press RETURN to see the Sample Terminal Sessions. Enter UP to return to the Programming Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cca \u,pe_cc \c,---------------------------------------------------------------------------- \m=a,pe_ccaa \m=b,pe_ccab \m=c,pe_ccac \c,---------------------------------------------------------------------------- \i,sample terminal sessions \i,terminal sessions \i,terminal session examples \i,examples of terminal sessions \i,session examples \c,---------------------------------------------------------------------------- FTN5UG SAMPLE TERMINAL SESSIONS Screen 1 of 1 The figures on the following screens illustrate typical terminal sessions in which FORTRAN programs are executed. In each session, it is assumed that login has already been performed. The statements appearing in these sessions are explained in later topics. Enter on of the following letters to choose a session: a. Program Creation, Compilation, and Execution b. Execution With Data on Magnetic Tape c. Input/Output From a Terminal Press RETURN to see the Program Creation, Compilation, and Execution session. Enter UP to return to the Executing in an Interactive Environment menu. \c,---------------------------------------------------------------------------- \s,pe_ccaa \u,pe_cca \c,---------------------------------------------------------------------------- \i,program creation compilation and execution \c,---------------------------------------------------------------------------- FTN5UG PROGRAM CREATION, COMPILATION, AND EXECUTION Screen 1 of 2 This figure shows a terminal session in which a FORTRAN program is created (by using XEDIT), compiled, and executed. After execution has completed, the compiler output file is routed to a local system printer, and the source program, binary program, and program output file are saved as permanent files. /xedit,srce,c __ XEDIT | ?? input | INPUT | ? program fred | ? open (unit=2,file='infile') | ? open (unit=3,file='outfile') | : > Call XEDIT and create ? end | source program ? | EDIT | ?? end | SRCE IS A LOCAL FILE -- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cca \c,---------------------------------------------------------------------------- FTN5UG PROGRAM CREATION, COMPILATION, AND EXECUTION Screen 2 of 2 /get,infile=files <----------- Get input file. /ftn5,i=srce,l=listf <---------------- Compile program and write output listing to file LISTF. 0.006 CP SECONDS COMPILATION TIME. /route,listf,dc=pr <----------- Print output listing. ROUTE COMPLETE /lgo <------------------------- Execute program. .005 CP SECONDS EXECUTION TIME. /save,scre=prg001 __ /save,lgo=bprog > Save source program, binary program, and program /save,outfile=data1 -- output as permanent files. Press RETURN to see the Execution With Data on Magnetic Tape session. \c,---------------------------------------------------------------------------- \s,pe_ccab \u,pe_cca \c,---------------------------------------------------------------------------- \i,execution with data on magnetic tape \c,---------------------------------------------------------------------------- FTN5UG EXECUTION WITH DATA ON MAGNETIC TAPE Screen 1 of 1 The following figure shows a terminal session in which the program compiled in the figure on the previous two screens is executed with data read from a magnetic tape. The program creates a new tape file. /get,bin=bprog <-------------------------- Get local copy of binary program. /resourc,nt=2 __ | /label,infile,nt,f=i,vsn=123456 | LABEL,INFILE,NT,F=I,VSN=123456 > Assign files INFILE and OUTFILE to | magnetic tapeunits. /label,outfile,nt,po=w,f=i,vsn=987654 | LABEL,OUTFILE,NT,PO=W,F=I,VSN=987654 -- /bin <------------------------------------- Execute program. .006 CP SECONDS EXECUTION TIME. /purge,data1 <----------------------------- Purge data file saved in previous session. Press RETURN to see the Input/Ouput From a Terminal session. \c,---------------------------------------------------------------------------- \s,pe_ccac \u,pe_cca \n,pe_cca \c,---------------------------------------------------------------------------- \i,input/output from terminal \c,---------------------------------------------------------------------------- FTN5UG INPUT/OUTPUT FROM A TERMINAL Screen 1 of 1 The following figure illustrates interactive input and output. An existing source program is compiled and the binary program is executed. The program reads input from the terminal and displays output at the terminal. /get,aaa <--------------------------- Get local file copy of source program. /list,fn=aaa <----------------------- List source program. PROGRAM MAIN PRINT *, 'TYPE 3 INTEGERS' READ *, I,J,K <------------------ Program reads input from terminal. . . END EOI ENCOUNTERED /ftn5,i=aaa,l=0,rew <---------------- Compile program. Note the REW parameter 0.007 CP SECONDS COMPILATON TIME. rewinds source file before compilation. /lgo <------------------------------- Initiate program execution. TYPE 3 INTEGERS ? 1 3 5 <---------------------------- Enter input data. .006 CP SECONDS EXECUTION TIME. Press RETURN to return to the Sample Terminal Sessions menu. \c,---------------------------------------------------------------------------- \s,pe_ccb \u,pe_cc \p,pe_cc \c,---------------------------------------------------------------------------- \i,interactive input/output \i,interactive input \i,interactive output \i,input from a terminal \i,output from a terminal \i,input \i,output \i,input file \i,output file \i,reading data from a terminal \i,displaying data on a terminal \i,print statement \i,write statement \c,---------------------------------------------------------------------------- FTN5UG INTERACTIVE INPUT/OUTPUT Screen 1 of 3 You can write programs to receive input directly from the terminal and to send output directly to the terminal. The file names INPUT and OUTPUT are reserved for this purpose; reading from file INPUT causes data to be read from the terminal, and writing to file OUTPUT causes data to be displayed at the terminal. You can use files INPUT and OUTPUT by omitting the unit specifier from the READ and WRITE statements. For example, the sequence: READ 100,A,B,C . . . PRINT 200,X,Y,Z reads A, B, and C from the terminal and writes X, Y, and Z to the terminal. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cc \c,---------------------------------------------------------------------------- \i,data input prompt \i,input prompt \i,? prompt \i,print statement \i,write statement \c,---------------------------------------------------------------------------- FTN5UG INTERACTIVE INPUT/OUTPUT Screen 2 of 3 When a READ statement for file INPUT is executed, the system prompts for input by displaying a question mark. In response, you enter values corresponding to the input variable list, followed by a carriage return. If the input list is satisfied, program execution continues; otherwise, the system displays another ? prompt. Thus, in the example on the previous screen you could enter three values on a single line, or a single value on three lines. A recommended procedure for avoiding confusion when reading from the terminal is to precede the READ statements by PRINT statements that display a descriptive request for input. For example: PRINT*, 'ENTER RATE AND HOURS WORKED' READ*, RATE,HRS displays a prompt describing the input needed, and awaits the user response. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cc \c,---------------------------------------------------------------------------- \i,end of data test \i,test for end of data \i,end= prompt \i,end= \c,---------------------------------------------------------------------------- FTN5UG INTERACTIVE INPUT/OUTPUT Screen 3 of 3 You can include a test in your program for end of data by specifying the END= parameter in the READ statement. In this case, you indicate the end of data during execution of the READ statement by entering a carriage return in response to the ? prompt. Alternatively, you can include statements in the program to test for your own end of data condition. For example, the sequence: READ*, I,J IF (I .EQ. 999) STOP causes execution to terminate if the value read for I is equal to 999. (This technique should not be used with type REAL numbers, because many such numbers do not have a precise internal representation.) Press RETURN to read about Changing the Execution Time Limit. \c,---------------------------------------------------------------------------- \s,pe_ccc \u,pe_cc \c,---------------------------------------------------------------------------- \i,changing the execution time limit \i,execution time limit \i,time limit \i,execution time \i,central processor time \i,cpu time \i,settl control statement \i,settl statement \i,settc \c,---------------------------------------------------------------------------- FTN5UG CHANGING THE EXECUTION TIME LIMIT Screen 1 of 2 The operating system assigns a maximum time limit to each executing program. (The actual value assigned is an installation parameter.) This time limit is the amount of central processor time the program is allowed to use. If a program exceeds this time limit, the system interrupts the program and displays the message: *TIME LIMIT* ENTER T TO CONTINUE OR CR KEY TO STOP: If you enter the letter T, execution resumes; if you enter a carriage return, the program terminates. The default time limit at most installations should be sufficient for most programs. Exceeding this limit is often caused by an error in the program, such as an infinite loop. However, if you determine that the program is correct and requires execution time, you can increase the time limit for subsequent executions with the SETTL control statement. (Certain CYBER Interactive Debug features increase the execution time required by a program; use of these features often results in a time limit interrupt.) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cc \c,---------------------------------------------------------------------------- \i,settl statement format \i,settl format \c,---------------------------------------------------------------------------- FTN5UG CHANGING THE EXECUTION TIME LIMIT Screen 2 of 2 The SETTL statement has the form: SETTL,n where n is the number of central processor seconds to be assigned to a program. The default base for n is decimal; however, you can specify the base for n as octal by typing a B after the number. The time limit established by SETTL is effective for the remainder of the terminal session, unless you enter a subsequent SETTL statement. Before increasing the execution time limit, however, you should be sure your program does not require excessive time because of a programming error. Needless use of SETTL can result in wasted computer time. Press RETURN to read about Informative Commands. \c,---------------------------------------------------------------------------- \s,pe_ccd \u,pe_cc \c,---------------------------------------------------------------------------- \i,informative commands \i,system commands \i,iaf commands \i,commands \c,---------------------------------------------------------------------------- FTN5UG INFORMATIVE COMMANDS Screen 1 of 3 IAF provides commands intended for use during terminal sessions that provide helpful information about the status of the session. These commands are summarized in the table on the following screen. The listed commands have optional parameters that provide additional control over the information displayed. Refer to volume 2 of the NOS 2 reference set for descriptions of these parameters. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cc \c,---------------------------------------------------------------------------- \i,terminal status \i,determining terminal status \i,status of the terminal \i,system resources \i,system record \i,enquire \i,enquire command \i,summary \i,summary command \i,dayfile \i,dayfile command \c,---------------------------------------------------------------------------- FTN5UG INFORMATIVE COMMANDS Screen 2 of 3 --------------+--------------------------------------------------------------- Command | Description --------------+--------------------------------------------------------------- ENQUIRE | Displays terminal status information, including terminal | number and type, subsystem currently active, current primary | file, and status of an executing program (IDLE, EXECUTE, or | WAIT). | SUMMARY | Lists the amount of system resources you have used during the | current terminal session. | DAYFILE | Lists the system record of all activity for the current | terminal session. This record includes each command you have | entered, the system responses to the commands, and the time | of each entry or response. -------------+--------------------------------------------------------------- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cc \n,pe_cc \c,---------------------------------------------------------------------------- \i,command descriptions \i,file length \i,length of a file \i,pru \i,system resources \i,help command \i,length \i,length command \i,help \i,limits \i,limits command \c,---------------------------------------------------------------------------- FTN5UG INFORMATIVE COMMANDS Screen 3 of 3 -------------+--------------------------------------------------------------- Command | Description -------------+--------------------------------------------------------------- HELP | Displays a list of IAF commands. The form HELP,command | displays a description of the specified command. | LENGTH,file | Displays the name, length (in PRUs), type, and status of the | specified file. (One PRU contains 640 6-bit characters.) | LIMITS | Lists the amounts and kinds of system resources currently | available to you. -------------+--------------------------------------------------------------- Press RETURN to return to the Executing in an Interactive Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cd \u,pe_c \p,pe_c \c,---------------------------------------------------------------------------- \m=a,pe_cda \m=b,pe_cdb \m=c,pe_cdc \m=d,pe_cdd \c,---------------------------------------------------------------------------- \i,file usage \i,files \i,file operations \i,file manipulation \i,manipulation of files \c,---------------------------------------------------------------------------- FTN5UG FILE USAGE Screen 1 of 1 Many of the operations performed at an interactive terminal involve file manipulations. During a typical terminal session you will be dealing with many different files, including the file containing the FORTRAN source program, the file containing the FORTRAN binary program, data files read and written by the program, files produced by the FORTRAN compiler, library files, and so forth. Although these files contain different types of information, they have certain characteristics in common and can be manipulated by the same commands and control statements. This topic describes some of the more commonly used control statements for manipulating files. These statements are valid both in terminal sessions and in batch jobs. Refer to the NOS and IAF reference manuals for additional information. Enter one of the following letters to learn more about using files: a. Local Files c. Permanent File Subroutine Call b. Permanent Files d. Copy and Skip Operations Press RETURN to read about Local Files. Enter UP to return to the Programming Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cda \u,pe_cd \c,---------------------------------------------------------------------------- \i,local files \i,working file \i,temporary file \c,---------------------------------------------------------------------------- FTN5UG LOCAL FILES Screen 1 of 2 A local file (also called a working file or temporary file) is a file that exists only for the duration of a terminal session (interactive environment) or job (batch environment). All files created during a terminal session or job are local files. Files are created by executing programs that write files, by copy operations, and by retrieving copies of permanent files. If you wish to retain a copy of a local file after the end of a terminal session or job, you must explicitly provide for doing so by making the file permanent or by creating a permanent copy of the file. Any existing file to be used during a terminal session or job must be a local file. Control statements are provided to make local copies of permanent files. The table on the following screen summarizes the control statements for use with local files. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,rew \i,ret \i,local file control statements \i,local file statements \i,file control statements \i,file statements \i,renaming a file \i,rewinding a file \i,changing a file name \i,deleting a file \i,return a file \i,status information \i,file status \i,rename \i,rename statement \i,return statement \i,return \i,rewind \i,rewind statement \i,enquire \i,enquire statement \c,---------------------------------------------------------------------------- FTN5UG LOCAL FILES Screen 2 of 2 ----------------------+------------------------------------------------------ Statement | Description ----------------------+------------------------------------------------------ RENAME,nfn=ofn. | Changes the name of a local file from ofn to nfn. | RETURN,lfn1,...,1fnn. | Deletes the specified local file from the system. | RETURN,*,lfn1,..,lfnn.| Deletes all local files associated with the current | job or terminal session except those that are named. | REWIND,lfn1,...,lfnn. | Repositions the specified local file to the | beginning-of-information. | REWIND,*,lfn1,..,lfnn.| Repositions all local files associated with the | current job or terminal session to the | beginning-of-information except those that are named. | ENQUIRE,F. | Displays status information about all local file job | or terminal session. ----------------------+------------------------------------------------------ Press RETURN to read about Permanent Files. \c,---------------------------------------------------------------------------- \s,pe_cdb \u,pe_cd \c,---------------------------------------------------------------------------- \i,permanent files \i,direct access files \i,indirect access files \i,permanent file types \i,types of permanent files \i,kinds of permanent files \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILES Screen 1 of 4 A permanent file is a file that is retained on mass storage after a terminal session or batch job ends and that can be retrieved in a subsequent terminal session or job. You can retain any local file as a permanent file. There are two types of permanent files: direct access and indirect access. (The direct access designation should not be confused with the record manager direct access file organization or the FORTRAN direct access file type.) When you retrieve an indirect access file, the system creates a local copy of the file. Any alterations you make to this copy do not affect the permanent copy. To alter the permanent copy, you must explicitly instruct the system to replace that copy with the local copy. For most applications, indirect access is the recommended method of retaining a file, because this method is more convenient and more secure (you are less likely to inadvertently alter an indirect access file than a direct access file.) Also, storing smaller files as indirect access files requires fewer system resources; however, for larger files (greater than 500 PRUs), the time required to create a permanent copy can be excessive. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,permanent file ownership \i,alternate user access \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILES Screen 2 of 4 With direct access files, all operations are performed directly on the permanent copy. Thus, any changes you make to a direct access file are permanent. For this reason, you should exercise care when altering a direct access file. In most cases, you should retain your files as indirect access files. The advantage of the direct access method is that less computer time is required to create a direct access file. The savings in computer time can be significant for very large files. (Large data files and user libraries should be stored as direct access files; in fact, many installations require that files exceeding a certain size be retained as direct access files.) Ownership of permanent files is determined by your user name. For interactive sessions, you specify this name when you login; for batch jobs you specify this name on the USER statement. Normally, you have access only to those files that were made permanent under your user name. However, you can access files belonging to a different user by following the procedure for alternate user access described in the IAF reference manual (interactive sessions) or the NOS reference manual (batch jobs). Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,file control statements \i,permanent file control statements \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILES Screen 3 of 4 Control statements are available to create, destroy, and perform other operations on permanent files. The table on the following screen summarizes these statements. In the listed statement formats, lfn is a local file name and pfn is a permanent file name. If you specify only one file name in any of the statements, the local and permanent file names are assumed to be identical. Optional parameters for the listed statements allow you to specify additional file attributes. Refer to the NOS reference manual for more information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,create an indirect access file \i,create a direct access file \i,destroy a file \i,change a file name \i,catalog \i,file catalog \i,list of permanent files \i,save \i,save statement \i,define \i,define statement \i,get \i,get statement \i,attach \i,attach statement \i,purge \i,purge statement \i,replace \i,replace statement \i,change \i,change statement \i,catlist \i,catlist statement \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILES Screen 4 of 4 Statement | Description ----------------+------------------------------------------------------------ SAVE,lfn=pfn. | Creates an indirect access file from the local file | DEFINE,lfn=pfn. | Makes the local file a direct access permanent file | GET,lfn=pfn. | Creates a local copy of the indirect access permanent file | ATTACH,lfn=pfn. | Retrieves the direct access permanent file for use as a | local file | PURGE,pfn. | Destroys the permanent file | REPLACE,lfn=pfn.| Replaces the permanent file with the local file | CHANGE,nfn=ofn. | Changes the name of permanent file ofn to nfn | CATLIST. | Lists information about all permanent files retained under | the current user name ------------------+------------------------------------------------------------ Press RETURN to read about Permanent File Subroutine Calls. \c,---------------------------------------------------------------------------- \s,pe_cdc \u,pe_cd \c,---------------------------------------------------------------------------- \i,permanent file subroutine call \i,call pf statement \i,call pf \i,save statement \i,define statement \i,get statement \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILE SUBROUTINE CALL Screen 1 of 4 A special subroutine call is available that enables you to perform permanent file operations directly from a FORTRAN program. The form of this call is: CALL PF (op,lfn,pfn) where op is a character string specifying the operation to be performed, and lfn and pfn are character strings specifying the local and permanent file names respectively. The following strings can be specified for the op parameter: 'SAVE' Creates an indirect access permanent file name pfn from local file lfn. 'DEFINE' Establishes a direct access permanent file named pfn and assigns to it the local file name lfn. 'GET' Retrieves the indirect access file pfn and assigns the name lfn the local copy. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,attach statement \i,purge statement \i,change statement \i,replace statement \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILE SUBROUTINE CALL Screen 2 of 4 Op parameter values (continued): 'ATTACH' Retrieves the direct access file pfn and assigns the local name lfn. 'PURGE' Purges permanent file pfn. When you specify the 'PURGE' option, omit the parameter lfn from the call. 'CHANGE' Changes the name of permanent file pfn to lfn. 'REPLACE' Replaces permanent file pfn with local file lfn. The operations performed by the PF call are identical to those performed by the corresponding control statements. Note that when you select the 'PURGE' option, the parameter lfn is omitted. For all other options, you can substitute a value of zero for either 'lfn' or 'pfn' in which case the local and permanent file names are assumed to be the same. For example, CALL PF ('GET',0,'AAA') creates a local copy of permanent file AAA having the same name. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,pf call advantages \i,pf call disadvantages \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILE SUBROUTINE CALL Screen 3 of 4 One advantage of the PF call is that it saves programmer time by eliminating the need for specifying the corresponding control statements in each job or terminal session in which the program is run. Also, for production jobs to be run by many different users, less knowledge about files used by the program is required, and the possibility of error is reduced. For instance, after running a program that creates one or more files, you might forget to specify control statements to make the files permanent; when the job or terminal session ends, the files are lost. However, if you use the PF routine to save the files, this oversight cannot occur. The primary disadvantage in using the PF call instead of control statements is that any changes to the CALL PF statements require recompilation of the program. The figure on the following screen illustrates a simple FORTRAN program that uses the PF routine to retrieve an indirect access file for input, and to retain an output file as a direct access permanent file. Note that the permanent file is created by the DEFINE option before the file is actually written. The requirement that an empty direct access file be created before the file is written is the same as for the DEFINE control statement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cd \c,---------------------------------------------------------------------------- \i,pf call example \i,call pf statement example \i,example of pf call \i,example of call pf statement \c,---------------------------------------------------------------------------- FTN5UG PERMANENT FILE SUBROUTINE CALL Screen 4 of 4 CALL PF example: PROGRAM PFCALL DIMENSION A(100), B(100) CALL PF ('GET','INFILE','F001') CALL PF ('DEFINE','NEWFILE',0) OPEN (UNIT=1,FILE='INFILE') OPEN (UNIT=2,FILE='NEWFILE') 10 READ (1,100,END=99) A . . . WRITE (2,100) B GO TO 10 99 STOP END Press RETURN to read about Copy and Skip Operations. \c,---------------------------------------------------------------------------- \s,pe_cdd \u,pe_cd \c,---------------------------------------------------------------------------- \m=a,pe_cdda \m=b,pe_cddb \m=c,pe_cddc \c,---------------------------------------------------------------------------- \i,copy and skip operations \i,position forward in a file \i,position backward in file \i,positioning a file \c,---------------------------------------------------------------------------- FTN5UG COPY AND SKIP OPERATIONS Screen 1 of 1 The copy and skip operations allow you to copy part or all of one file to another, and to position forward or backward in a file. Several control statements are provided to perform these operations. However, in order to determine the correct statement to use in a given situation, you should have an understanding of basic file structure. Enter one of the following letters to learn more about copying and skipping: a. File Structure b. Copy Operations c. Skip Operations Press RETURN to read about File Structure. Enter UP to return to the File Usage menu. \c,---------------------------------------------------------------------------- \s,pe_cdda \u,pe_cdd \c,---------------------------------------------------------------------------- \i,file structure \i,structure of a file \i,record manager \i,crm \i,beginning of information \i,boi \i,end of information \i,eoi \i,record \i,section \i,end of section \i,end of section boundary \i,eos \i,partitions \i,end of partition \i,end of partition boundary \i,section boundary \i,partition boundary \c,---------------------------------------------------------------------------- FTN5UG FILE STRUCTURE Screen 1 of 3 All FORTRAN input/output operations are performed by Record Manager, which organizes files into various groupings of data. A special delimiter terminates each grouping. All user-written information in a file exists between the beginning-of-information (BOI) and the end-of-information (EOI). (Certain system-related information can exist before BOI and after EOI.) The smallest grouping of information within a file is a record; a record consists of the information transferred by a single READ or WRITE statement. Records are grouped into sections delimited by an end-of-section boundary (EOS), and sections are grouped into partitions delimited by an end-of-partition boundary (EOP). This file structure is illustrated in the following figure: User Records +---------+ +--------+ +--------+ +--------+ +--+ +--+ | | | |EOS | |EOS | | EOS | | EOS | | | |EOS | | | | | |EOP | | | | EOP | |...| |EOP BOI| | | | | | | | | | | | | |EOI +---------+ +--------+ +--------+ +--------+ +--+ +--+ Press RETURN to continue. \c,---------------------------------------------------------------------------- \s, \u,pe_cdd \c,---------------------------------------------------------------------------- \i,end= \i,end= parameter \c,---------------------------------------------------------------------------- FTN5UG FILE STRUCTURE Screen 2 of 3 You can copy or skip sections, partitions, or an entire file with the appropriate copy or skip statement. As a FORTRAN programmer, however, your primary concern is with partition boundaries, because these boundaries are used in the following contexts: A carriage return entered in response to a ? prompt while inputting data from the terminal is interpreted as an EOP. The FORTRAN ENDFILE statement writes an EOP. When you close an output file (with a CLOSE statement or by program termination), or when you execute a REWIND or BACKSPACE for an output file, an EOP is written following the last record. The END= parameter in a READ statement detects an EOP. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s, \u,pe_cdd \c,---------------------------------------------------------------------------- \i,unformatted files \i,w records \i,w type records \i,record manager eos \i,crm eos \i,record manager end of section \i,system end of record \i,system eor \i,end of record \i,eor \i,record manager eop \i,record manager end of partition \i,system end of file \i,end of file \i,eof \i,multifile files \c,---------------------------------------------------------------------------- FTN5UG FILE STRUCTURE Screen 3 of 3 The only time you need to be concerned with sections is when you use unformatted files. The unformatted WRITE statement writes Record Manager type W records. For this record type, an EOP is detected as an EOS by the operating system and, therefore, by the copy and skip operations. Processing required for EOS boundaries differs from that required for EOP boundaries. Confusion often arises because of the difference between Record Manager and operating system terminology. A Record Manager EOS is equivalent to a system end-of-record (EOR), and a Record Manager EOP is equivalent to a system end-of-file (EOF). (Thus, in the operating system environment, multi-file files are possible.) Press RETURN to read about Copy Operations. \c,---------------------------------------------------------------------------- \s,pe_cddb \u,pe_cdd \c,---------------------------------------------------------------------------- \i,copybr,0 \i,copy operations \i,copying a file \i,copy statements \c,---------------------------------------------------------------------------- FTN5UG COPY OPERATIONS Screen 1 of 5 Control statements are provided enabling you to copy an entire file, or portion of a file, to another file. The particular statement to use for a copy operation depends on the structure of the file and on whether you wish to copy an entire file, or partitions or sections within a file. The table on the following two screens summarize the control statements used for copying files. In the statement formats, lfn1 is the local file to copy onto lfn2 and lfn2 is the local file onto which lfn1 is copied. Each statement begins a copy operation at the current file position; however, the boundary at which the operation terminates depends on the statement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,copy statement \i,copy \i,copyei statement \i,copyei \i,copybf statement \i,copybf \c,---------------------------------------------------------------------------- FTN5UG COPY OPERATIONS Screen 2 of 5 --------------------+-----------------------------+-------------------------- Statement | Function | Recommended File Types --------------------+-----------------------------+-------------------------- COPY,lfn1,lfn2. | Copies to EOI or double EOP,| All file types. | if present. | | | COPYEI,lfn1,lfn2. | Copies to EOI. | All file types except | | S, L, or F format tapes. | | COPYBF,lfn1,lfn2,n. | Copies n partitions. | All file types except | | S, L, or F format tapes. | | COPYSBF,lfn1,lfn2,n.| Copies n partitions with | Print files in which the | one-character right shift | first character is not a | for carriage control. | carriage control charac- | | ter. Should not be used | | with S, L, or F format | | tapes. --------------------+-----------------------------+-------------------------- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,copycf statement \i,copycf \i,copybr statement \i,copybr \c,---------------------------------------------------------------------------- FTN5UG COPY OPERATIONS Screen 3 of 5 -------------------+-----------------------------+--------------------------- Statement | Function | Recommended File Types -------------------+-----------------------------+--------------------------- COPYCF,lfn1,lfn2,n.| Copies n partitions. | Use when creating a | | 9-track tape to be used | | at another site, or a | | 7-track tape. Should not | | be used with S, L, or F | | format tapes. | | COPYBR,lfn1,lfn2,n.| Copies n sections. | Files written by FORTRAN ments. (The system re | | unformatted WRITE state- | | ments. (The system recog- | | nizes the EOP boundaries | | on these files as EOS | | boundaries.) Should not | | be used with S, L, or F | | format tapes. --------------------+-----------------------------+--------------------------- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,copybf example \i,example of copybf statement \i,copybf statement \i,copybf \i,copysbf statement \i,copysbf \i,copycf statement \i,copycf \c,---------------------------------------------------------------------------- FTN5UG COPY OPERATIONS Screen 4 of 5 Because COPYBF, COPYSBF, and COPYCF count EOP boundaries without regard for intervening data, the amount of information copied might not be what you expect. For example, the figure on the following screen shows three files containing multiple partitions. The letter A indicates the initial position of the files. In each case, the statement: COPYBF,FILEA,FILEB,3. copies information from A to B. Because of differing file structures, the results of the copy are different for each example. If the EOI is reached on lfn1 before the specified number of partitions has been copied, a single EOP is written on lfn2 at the end of the copy. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- FTN5UG COPY OPERATIONS Screen 5 of 5 COPYBF EXAMPLE +---------+ +--------+ +--------+ +--+ FILEA | |EOP | |EOP | |EOP | | | | | | | | | |. . . +---------+ +--------+ +--------+ +--+ A B +---------+ +--------+ +--------+ +--+ FILEA | |EOP | |EOP | |EOP | | | | | | | | | |. . . +---------+ +--------+ +--------+ +--+ A B +---------+ +--------+ +--+ FILEA | |EOP | |EOP EOP | | | | | | | |. . . +---------+ +--------+ +--+ A B Press RETURN to read about Skip Operations. \c,---------------------------------------------------------------------------- \s,pe_cddc \u,pe_cdd \c,---------------------------------------------------------------------------- \i,skip operations \i,reposition a file \i,file repositioning \i,skip statements \i,skipr statement \i,skipr \c,---------------------------------------------------------------------------- FTN5UG SKIP OPERATIONS Screen 1 of 5 Control statements are provided enabling you to reposition a file in a forward or backward direction. The particular statement to use for a given skip operation depends on the direction of the skip and on the file boundary at which you wish to reposition the file. The table on the following screen summarizes the control statements used to reposition a file. Each operation begins at the current file position; however, the boundary at which the operation terminates depends on the statement. In the statement formats, lfn is the local file name of the file to be repositioned and m has one of the following values: C Coded format (print files and FORTRAN formatted files). B Binary format (default; applies to all other files). The lvl option of the SKIPR statement indicates the level number of boundaries to be skipped. 17 indicates partitions (same as SKIPF), and any other value indicates sections (0 is the default value). Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,skipf statement \i,skipf \i,skipfb statement \i,skipfb \i,skipr statement \i,skipr \i,bksp statement \i,bksp \c,---------------------------------------------------------------------------- FTN5UG SKIP OPERATIONS Screen 2 of 5 ------------------+-------------------------+-------------------------------- Statement | Function | Recommended File Types ------------------+-------------------------+-------------------------------- SKIPF,lfn,n,m. | Skips n partitions in a | All files except those | forward direction | created by unformatted WRITE | | statements | | SKIPFB,lfn,n,m. | Skips n partitions in a | All files except those | backward direction | created by unformatted | | WRITE statements | | SKIPR,lfn,n,lvl,m.| Skips n sections in a | Files created by unformatted | forward direction | WRITE statements | | BKSP,lfn,n,m. | Skips n sections in a | Files created by unformatted | | WRITE statements ------------------+-------------------------+-------------------------------- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,skip examples \i,examples of skip statements \i,skipf statement \i,skipf \i,skipr statement \i,skipr \i,skipfb statement \i,skipfb \i,bksp statement \i,bksp \i,skipf example \i,example of skipf statement \c,---------------------------------------------------------------------------- FTN5UG SKIP OPERATIONS Screen 3 of 5 When a skip operation is performed, n EOP or EOS boundaries are skipped. SKIPF or SKIPR positions the file immediately after the nth boundary; SKIPFB or BKSP positions the file immediately after the n+1th boundary. The following figures show how files are positioned using SKIPF, SKIPFB, and SKIPR. In each case, the position of the file is moved from A to B by the control statement shown. SKIPF,ABC,3 +---------+ +--------+ +--------+ +-------+ +--------+ | |EOS | |EOP | |EOS | |EOP EOP | | | | | | | | | | | | +---------+ +--------+ +--------+ +-------+ +--------+ A B Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \c,---------------------------------------------------------------------------- \i,skipfb statement \i,skipfb \i,skipfb example \i,example of skipfb statement \i,skipr statement \i,skipr \i,skipr example \i,example of skipr statement \c,---------------------------------------------------------------------------- FTN5UG SKIP OPERATIONS Screen 4 of 5 Skip examples (continued): SKIPFB,ABC,3 +---------+ +--------+ +--------+ +-------+ +--------+ | |EOS | |EOP | |EOS | |EOP EOP | | | | | | | | | | | | +---------+ +--------+ +--------+ +-------+ +--------+ B A SKIPR,ABC,3 +---------+ +--------+ +--------+ +-------+ +--------+ | |EOS | |EOS EOP | |EOS | |EOS EOP | | | | | | | | | | | | +---------+ +--------+ +--------+ +-------+ +--------+ A B Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_cdd \n,pe_cdd \c,---------------------------------------------------------------------------- \i,bksp statement \i,bksp \i,bksp example \i,example of bksp statement \c,---------------------------------------------------------------------------- FTN5UG SKIP OPERATIONS Screen 5 of 5 Skip examples (continued): BKSP,ABC,5 +---------+ +--------+ +--------+ +-------+ +--------+ | |EOS | |EOS EOP | |EOS | |EOS EOP | | | | | | | | | | | | +---------+ +--------+ +--------+ +-------+ +--------+ B A Press RETURN to return to the Copy and Skip Operations menu. \c,---------------------------------------------------------------------------- \s,pe_ce \u,pe_c \p,pe_c \c,---------------------------------------------------------------------------- \m=a,pe_cea \m=b,pe_ceb \m=c,pe_cec \m=d,pe_ced \m=e,pe_cee \c,---------------------------------------------------------------------------- \i,magnetic tape processing \i,processing magnetic tapes \i,magnetic tapes \i,tapes \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING Screen 1 of 1 Some sites do not permit interactive processing of tapes. Check with your site administrative personnel to determine local procedures. Enter one of the following letters to learn more about magnetic tape processing: a. Overview b. Describing Tape Attributes c. Using Multiple Tape or Disk Units d. Releasing a Tape File e. Rewinding a Tape File Press RETURN to read the Overview. Enter UP to return to the Programming Environment menu. \c,---------------------------------------------------------------------------- \s,pe_cea \u,pe_ce \c,---------------------------------------------------------------------------- \i,magnetic tape processing overview \i,overview of magnetic tape processing \i,processing magnetic tape overview \i,magnetic tape overview \i,tape overview \i,tape volume \i,volume \i,advantages of tape use \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING OVERVIEW Screen 1 of 5 Magnetic tapes provide an alternative means of storing information. As with disk storage, information is stored on a tape reel in the form of a file. A reel of tape is known as a volume. A tape volume generally contains a single file. Tape use offers advantages when compared to disk: Tapes are more portable. Once you write a tape, you can carry the tape to another computer or to another site and read the tape. Tapes are usually less expensive than the equivalent amount of disk storage. (Actual costs are determined by the installation; in some cases, tapes might be more expensive than disk.) Tapes provide an excellent archival medium for long-term storage of information. The primary disadvantages of tapes are that additional time is required to mount the tape, and that tapes are not suitable for random operations. Thus, the advisability of using tapes depends on the particular application. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ce \c,---------------------------------------------------------------------------- \i,reading a tape \i,tape attributes \i,attributes of tape \i,tape processing \i,processing a tape \i,volume serial number,1 \i,vsn,1 \i,label statement \i,request statement \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING OVERVIEW Screen 2 of 5 If you wish to read an existing tape, you must know certain attributes of that tape. If the tape was written on a computer system not manufactured by CDC, or if it was written by a different CDC system (such as one of the 3000 series), special processing is required. Processing of such tapes is not described in this guide; refer to the NOS reference manual for information on tapes for which special processing is required. Tapes are processed according to the following steps: 1. You must assign a volume serial number (VSN). This is done before the tape is read or written. 2. In the terminal session or job which creates the tape, you must enter a LABEL or REQUEST control statement before entering the statement (such as COPY or LGO) that creates the tape. The LABEL or REQUEST control statement specifies the name to be assigned to the tape and the tape attributes. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ce \c,---------------------------------------------------------------------------- \i,resourc statement \i,unload statement \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING OVERVIEW Screen 3 of 5 Steps for processing magnetic tapes (continued): 3. If a program uses more than one tape or disk, you must enter a RESOURC control statement specifying the number and type of devices to be used. 4. At the end of the terminal session, or when you enter an UNLOAD or RETURN the tape is logically unloaded (released from the terminal) and physically dismounted from the tape drive. 5. Any future job or terminal session using the tape must specify the correct VSN on a LABEL or REQUEST control statement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ce \c,---------------------------------------------------------------------------- \i,tape attributes \i,attributes of tapes \i,tape drive \i,tape density \i,tape format \i,label type \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING OVERVIEW Screen 4 of 5 When writing a program to create a tape (that is, to write a new file on a tape), you must select certain attributes to be permanently associated with the tape. These attributes include: Tape drive used to read and write the tape (7-track or 9-track). Tape density in bits per inch or in characters per inch. Tape format. When writing a tape, you will normally use the system default format. You can, however, read or write tapes in different formats. Label type. The tape label is a block located at the beginning of the tape which contains certain identifying information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ce \c,---------------------------------------------------------------------------- \i,tape security \c,---------------------------------------------------------------------------- FTN5UG MAGNETIC TAPE PROCESSING OVERVIEW Screen 5 of 5 Magnetic tape attributes (continued): Tape security. The procedure you use to specify how long a tape is to be retained depends on the site; however, if the expiration date field of the tape label is set, the tape cannot be overwritten without explicit operator command. Before the tape can be written, a write-enabling ring must be mounted; the user who wishes to write the tape must explicitly request this through the LABEL or REQUEST control statement. In addition to the LABEL control statement, other statements are available to perform various tape processing functions. Press RETURN to read about Describing Tape Attributes. \c,---------------------------------------------------------------------------- \s,pe_ceb \u,pe_ce \c,---------------------------------------------------------------------------- \m=a,pe_ceba \m=b,pe_cebb \m=c,pe_cebc \m=d,pe_cebd \m=e,pe_cebe \m=f,pe_cebf \m=g,pe_cebg \c,---------------------------------------------------------------------------- \i,describing tape attributes \i,tape attributes \i,attributes of tapes \i,label statement \i,request statement \i,label statement format \c,---------------------------------------------------------------------------- FTN5UG DESCRIBING TAPE ATTRIBUTES Screen 1 of 1 Before executing a program that reads or writes a tape, you must enter a LABEL or REQUEST control statement. This statement makes the tape available to the terminal or job, specifies the file to be read or written, and describes various attributes of the tape. Only the LABEL statement is described here. The REQUEST statement is described in the NOS reference manual. The LABEL statement has the form: LABEL,file,type,D=den,CV=conv,PO=p,F=fmt,VSN=vsn,LB=lab,labwr where file is the name of the file to be read or written. Enter one of the following letters for a description of the remaining parameters: a. type - Tape Drive e. fmt - Tape Format b. den - Density f. vsn - Volume Serial Number c. conv - Conversion Mode g. lab,labwr - Tape Labels d. p - Tape Security Press RETURN to read about type - Tape Drive. Enter UP to return to the Magnetic Tape Processing menu. \c,---------------------------------------------------------------------------- \s,pe_ceba \u,pe_ceb \c,---------------------------------------------------------------------------- \i,type - tape drive \i,tape drive \i,7 track tape \i,9 track tape \i,type option \i,type \i,nt \i,mt \c,---------------------------------------------------------------------------- FTN5UG TYPE - TAPE DRIVE Screen 1 of 1 You can write tapes on either a 7-track or a 9-track tape drive. The type option on the LABEL statement controls the tape drive to be used, as follows: NT 9-track MT 7-track The default tape drive is an installation option. The availability of these tape drives depends on the site. Data is stored in 6-bit units on 7-track tapes and in 8-bit units on 9-track tapes (the extra bit indicates parity). On a 9-track binary tape, four 6-bit characters in memory are stored as three 8-bit characters on tape without conversion mode. In conversion mode, each 6-bit character is converted to an 8-bit character. Conversion is performed according to either ASCII or EBCDIC codes. Press RETURN to read about den - Tape Density. \c,---------------------------------------------------------------------------- \s,pe_cebb \u,pe_ceb \c,---------------------------------------------------------------------------- \i,den - tape density \i,tape density \i,den \i,9 track tape \i,7 track tape \i,d parameter \c,---------------------------------------------------------------------------- FTN5UG DEN - TAPE DENSITY Screen 1 of 1 You can write a 9-track tape at a density of 800, 1600, or 6250 characters per inch (cpi), or a 7-track tape at a density of 200, 556, or 800 bits per inch (bpi). The D parameter on the LABEL statement controls tape density. This parameter has the form: D=den where den has one of the following values: HD 800 cpi (9-track) PE 1600 cpi (9-track) GE 6250 cpi (9-track) LO 200 bpi (7-track) HI 556 bpi (7-track) HY 800 bpi (7-track) Press RETURN to read about conv - Conversion Mode. \c,---------------------------------------------------------------------------- \s,pe_cebc \u,pe_ceb \c,---------------------------------------------------------------------------- \i,conv - conversion mode \i,conversion mode \i,conv \i,cv parameter \i,conversion of codes \i,code conversion \i,9 track tape \i,copycf statement \i,copycf \i,copybf statment \i,copybf \c,---------------------------------------------------------------------------- FTN5UG CONV - CONVERSION MODE Screen 1 of 1 The CV parameter controls the conversion of codes when data is transmitted between memory and 9-track tapes in coded mode. The CV parameter is meaningful only if COPYCF is used to create the tape file; CV has no meaning if COPYBF is used. This parameter has the form: CV=conv where CV is one of the following: AS Conversion to or from ASCII from or to 6-bit display code. EB Conversion to or from EBCDIC from or to 6-bit display code. Press RETURN to read about p - Tape Security. \c,---------------------------------------------------------------------------- \s,pe_cebd \u,pe_ceb \c,---------------------------------------------------------------------------- \i,p - tape security \i,tape security \i,p \i,po parameter \i,write ring \c,---------------------------------------------------------------------------- FTN5UG P - TAPE SECURITY Screen 1 of 2 Any tape to be written must be mounted with a write ring. The PO parameter protects against accidental overwriting of a tape file by allowing you to specify whether or not a write ring can be used the next time the tape is accessed. This parameter has the form: PO=p1...pn where pi is one of the following: R Write ring is prohibited for the tape. If the tape is mounted with write ring in, processing suspends until the operator removes the ring. This option is recommended for tapes to be read. W Write ring is required for the tape. If the tape is mounted with the write ring out, processing suspends until the operator inserts the ring. This option is required for tapes to be written. R and W are mutually exclusive. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ceb \c,---------------------------------------------------------------------------- FTN5UG P - TAPE SECURITY Screen 2 of 2 PO options (continued): U Tape is not to be unloaded at end of use. This parameter allows a subsequent job to access the tape without requiring a physical remount of the tape. Additional PO options are described in the NOS reference manual. Press RETURN to read about fmt - Tape Format. \c,---------------------------------------------------------------------------- \s,pe_cebe \u,pe_ceb \c,---------------------------------------------------------------------------- \i,fmt - tape format \i,tape format \i,fmt \i,f parameter \c,---------------------------------------------------------------------------- FTN5UG FMT - TAPE FORMAT Screen 1 of 1 Several different tape formats can be processed. For writing a tape, the NOS operating system default format is recommended. When reading a tape, you must specify the format of that tape. The F parameter controls the tape format. This parameter has the form: F=fmt where fmt is one of the following: I NOS internal (default) SI NOS/BE internal S Stranger L Long stranger Press RETURN to read about vsn - Volume Serial Number. \c,---------------------------------------------------------------------------- \s,pe_cebf \u,pe_ceb \c,---------------------------------------------------------------------------- \i,vsn - volume serial number \i,volume serial number \i,vsn \i,vsn parameter \c,---------------------------------------------------------------------------- FTN5UG VSN - VOLUME SERIAL NUMBER Screen 1 of 1 The volume serial number (VSN) identifies the tape reel; all tapes must be assigned a VSN before they are written. At many sites, tapes are blank-labeled before being made available to programmers. In this case, a serial number identical to the serial number on the visual sticker on the tape reel is recorded on the tape. If the tape has not been blank-labeled, you must assign an arbitrary volume serial number. For reading an existing tape, you must specify the correct volume serial number. The VSN parameter specifies the volume serial number assigned to the tape. This parameter has the form: VSN=vsn where vsn is the volume serial number. Press RETURN to read about lab,labwr - Tape Labels. \c,---------------------------------------------------------------------------- \s,pe_cebg \u,pe_ceb \c,---------------------------------------------------------------------------- \i,lab labwr - tape labels \i,tape labels \i,lab \i,labwr \i,labeled tapes \i,lb parameter \c,---------------------------------------------------------------------------- FTN5UG LAB,LABWR - TAPE LABELS Screen 1 of 2 A tape can be either labeled or unlabeled. Labeled tapes are strongly recommended. They provide greater security against accidental overwriting, and they are simpler to process because you can assign them without operator intervention. Labels are either ANSI standard or user-defined. ANSI labels are the system default and are recommended for new tapes. The LB parameter specifies the label type to be written (or, when reading a tape, the label type initially assigned). This parameter has the form: LB=lab where lab is one of the following: KL NOS labeled (ANSI standard labels; default) NS Nonstandard labels KU Unlabeled Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,pe_ceb \n,pe_ceb \c,---------------------------------------------------------------------------- \i,labwr \i,labwr parameter \c,---------------------------------------------------------------------------- FTN5UG LAB,LABWR - TAPE LABELS Screen 2 of 2 You can specify whether a label is to be read or written with the labwr parameter. If a label is read, it is checked against the label type indicated by the LB parameter; otherwise, the indicated label type is written. This parameter has one of the following values: R Label is read and checked W Label is written Press RETURN to return to the Describing Tape Attributes menu. \c,---------------------------------------------------------------------------- \s,pe_cec \u,pe_ce \p,pe_ce \c,---------------------------------------------------------------------------- \i,using multiple tape or disk units \i,multiple tape units \i,multiple disk units \i,using more than one tape \i,using more than one disk \i,resourc statement \i,resourc \i,resourc statement format \i,resourc format \i,option code \c,---------------------------------------------------------------------------- FTN5UG USING MULTIPLE TAPE OR DISK UNITS Screen 1 of 1 If a program uses more than one tape or disk unit concurrently, you must enter a RESOURC control statement indicating the maximum number of units that will be used. This statement has the form: RESOURC,t1=n1,...,tn=nn. where ti is an option code indicating the device type and ni is the maximum number of allowable units. For tape drives, valid option codes are: HD 800 cpi (9-track) PE 1600 cpi (9-track) GE 6250 cpi (9-track) LO 200 bpi (7-track) HI 556 bpi (7-track) HY 800 bpi (7-track) Additional option codes are used to indicate the different types of disk drives and are described in the NOS reference manual. If you omit a RESOURC statement, one device is permitted. Press RETURN to read about Releasing a Tape File. \c,---------------------------------------------------------------------------- \s,pe_ced \u,pe_ce \c,---------------------------------------------------------------------------- \i,releasing a tape file \i,release a tape \i,unload statement \i,unload \i,unload statement format \i,unload format \c,---------------------------------------------------------------------------- FTN5UG RELEASING A TAPE FILE Screen 1 of 1 You can release a tape file from the terminal with the RETURN or UNLOAD statement. When you release a tape file, it is no longer accessible from the terminal. The RETURN and UNLOAD statements also perform other functions associated with tape termination processing: trailer labels are written and the tape is rewound. The RETURN and UNLOAD statements are identical in function except when the maximum allowable number of units (as established by a preceding RESOURC statement) is currently assigned to the job or terminal session. In this case, RETURN decreases the maximum allowable number of units by one. The UNLOAD statement does not alter the values specified by a RESOURC statement. Enter RET? for a description of the RETURN statement. The UNLOAD statement has the form: UNLOAD,file1,...,file2. where filei is the file to be released. Press RETURN to read about Rewinding a Tape File. \c,---------------------------------------------------------------------------- \s,pe_cee \u,pe_ce \n,pe_ce \c,---------------------------------------------------------------------------- \i,rewinding a tape file \i,boi \i,rewind statement \i,rewind \i,beginning of information \c,---------------------------------------------------------------------------- FTN5UG REWINDING A TAPE FILE Screen 1 of 1 You can rewind a tape file with the REWIND statement. (Enter RET? to see the format of the REWIND statement.) The REWIND statement positions the tape file at the beginning-of-information. The beginning-of-information for a labeled tape file is defined as the point immediately after all header labels. Press RETURN to return to the Programming Environment menu. Enter UP to return to the Magnetic Tape Processing menu. \c,---------------------------------------------------------------------------- \s,ft_d \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,ft_da \m=b,ft_db \m=c,ft_dc \m=d,ft_dd \m=e,ft_de \m=f,ft_df \m=g,ft_dg \m=h,ft_dh \m=i,ft_di \c,---------------------------------------------------------------------------- \i,fortran 5 features \i,fortran features \i,features of fortran \i,features \c,---------------------------------------------------------------------------- FTN5UG FORTRAN 5 FEATURES Screen 1 of 1 FORTRAN 5 offers a number of features that, if used properly, can improve both the clarity and efficiency of a program. Other FORTRAN features increase the capabilities of the language by providing interfaces to other CDC products. Enter one of the following letters to learn about some of these features. a. Block IF Structure b. Character String Processing c. Parameter Statement d. GETPARM Subroutine Call e. Intrinsic and External Declarations f. Upper and Lower Array Bounds g. Internal I/O h. Open and Close Statements i. Introduction to Product Interfaces Press RETURN to read about the Block IF Structure. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,ft_da \u,ft_d \c,---------------------------------------------------------------------------- \i,block if structures \i,block if \i,block if statement \i,if statement \i,if structures \i,logical if statement \i,logical if \i,advantage of block if statements \i,block if statement advantage \i,structured style \i,structured programming \i,program structure \i,eliminate go to statements \i,eliminate statement labels. \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 1 of 4 Block IF structures provide an alternative to using logical IF statements for executing different statements depending on the outcome of IF tests. The main advantage of block IF statements is that they allow a structured style of programming, which results in a clearer program. For example, the example 1 sequence can be rewritten using a block IF statement as shown in example 2: Example 1 | Example 2 | IF (.NOT.(I.LT.10)) GO TO 100 | IF (I.T.10) THEN PRINT*,I | PRINT*,I I=I+10 | I=I+10 100 I=I-10 | ENDIF | I=I-10 The block IF structure eliminates the need for the GO TO and statement label. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,else statement \i,else \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 2 of 4 In some cases, you might wish to execute one set of statements if a condition is true and another set if the condition is false. You can do this by using the ELSE statement together with the block IF statement. For example, the sequence: IF (X.GE.0.0) THEN Y=SQRT(X) ELSE PRINT*,'SQRT OF NEGATIVE VALUE' ENDIF calculates the SQRT(X) if X is positive or zero, and prints an error message if X is negative. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,else if statement \i,else if \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 3 of 4 You can test for multiple mutually exclusive conditions by using the ELSE IF statement. This statement allows you to execute a different set of statements for each outcome, as illustrated by the following example: IF (AGE.GT.65) THEN SALARY=WAGES*.70 ELSE IF (AGE.GT.60) THEN SALARY=WAGES*.6 ELSE IF (AGE.LT.18) THEN SALARY=WAGES*.52 ELSE SALARY=WAGES ENDIF When using IF and ELSE IF statements as in the preceding example, you can improve efficiency by ordering the tests so that the most likely condition is tested first, the second most likely is tested second, and so forth. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,indenting block if \i,nested block if statements \i,nested block if \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 4 of 4 Indenting block IF structures makes a program more readable, especially when structures are nested, as in the following example: IF (I.LT.0) THEN I=I+1 IF (J.LT.10) THEN J=J+1 ELSE J=J-1 ENDIF ELSE I=I+1 ENDIF Enter BLDIF? for additional examples of block IF structures. Press RETURN to read about Character String Processing. \c,---------------------------------------------------------------------------- \s,ft_db \u,ft_d \c,---------------------------------------------------------------------------- \i,character string processing \i,processing character strings \i,character strings \i,strings \i,manipulating charcater strings \i,character string manipulation \i,string processing \i,processing strings \i,manipulating strings \i,string manipulation \i,character handling \i,manipulate character strings \i,character variable \i,character constant \i,substring notation \i,substrings \i,concatenation operator \i,concatenation \i,index function \i,index \i,len function \i,len \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 1 of 6 The character handling features of FORTRAN allow you to easily and efficiently manipulate character strings. These features include: Type CHARACTER constants and variables. A character constant or variable can be of any desired length and is independent of word length. Substring notation. This notation allows you to easily reference substrings within a character string. Concatenation operator. This feature allows you to join strings or substrings to form new strings. INDEX function. This function locates a particular pattern within a string. LEN function. This function returns the length of a string. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,character statement \i,character \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 2 of 6 Although you can process character strings without these features, their use makes character handling much easier. The character handling features are completely independent of the computer's word length and the length of the string; thus, you need not be concerned with the number of bits in a character, the position of characters within a word, or the number of words occupied by a string. The CHARACTER statement declares character variables and defines the length of the variables. For example, the statement: CHARACTER CARD*80, LINE*136, C(5,5)*8 declares the variable CARD to be 80 characters long, the variable LINE to be 136 characters long, and the array C to have dimensions (5,5) with each element being 8 characters long. The statement: CHARACTER*20 A,B declares character variables A and B, each 20 characters long. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,character dummy arguments \i,dummy arguments \i,(*) \i,symbol (*) \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 3 of 6 When you write a subroutine or function that uses character data, you should always declare the character dummy arguments (or function name for a character function) to have a length of (*). The symbol (*) causes the actual length of the variable to be the length used in the current reference to the routine. For example, the sequence: SUBROUTINE SUB(A,J) CHARACTER*80 A DO 10 I=1,80 IF (A(I:I) .NE. ' ') THEN : works only for strings 80 characters long. However, the sequence: SUBROUTINE SUB (A,J) CHARACTER A*(*) DO 10 I=1,LEN(A) IF (A(I:I) .NE. ' ') THEN : works for strings of any length. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,len function \i,len \i,substring notation \i,substrings \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 4 of 6 The LEN function returns the number of characters in a string. This function is useful in situations such as the one on the previous screen, where the length of a string is known only at execution time. The example on the previous screen also illustrates the use of substring notation. This notation allows you to reference a substring within a string. For example, the following sequence counts the blanks in a 100-character string: CHARACTER C*100 J=0 DO 10 I=1,100 IF (C(I:I) .EQ. ' ') J=J+1 10 CONTINUE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,index function \i,index \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 5 of 6 The INDEX function locates the first occurrence of one string within another string. INDEX returns the starting character position if the string is found, or zero if the string is not found. This function is useful for scanning a string. Another use for the INDEX function is to determine if a given character belongs to a set of characters. The following sequence determines if the ith character of a line is a vowel: CHARACTER LINE*80 IF (INDEX('AEIOU',LINE(I:I)) .NE. 0) THEN . . . In this example, INDEX searches for an occurrence of the substring LINE(I:I) in the string 'AEIOU'. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \m=a,ft_dba \m=b,ft_dbb \m=c,ft_dbc \m=d,ft_dbd \c,---------------------------------------------------------------------------- \i,character string processing example \i,example of character string processing \c,---------------------------------------------------------------------------- FTN5UG CHARACTER STRING PROCESSING Screen 6 of 6 Two programs are presented to illustrate the use of the preceding features. Enter one of the following letters to see the examples: a. Source Listing of Program RTEXT - reads lines of text, counts the numbers of characters, words, and sentences in the text, and calculates the average number of characters per word and the average number of words per sentence. This program illustrates the use of substring notation to test for the occurrence of characters within a string. b. Sample Terminal Dialog for RTEXT c. Source Listing of Program EDIT - performs a pattern search and replacement on a single line of text. This program illustrates the use of substring notation, the concatenation operator, and the INDEX function. d. Sample Terminal Dialog for EDIT Press RETURN to see the source listing for RTEXT. Enter UP to return to the FORTRAN 5 Features menu. \c,---------------------------------------------------------------------------- \s,ft_dba \u,ft_db \c,---------------------------------------------------------------------------- \i,program rtext \i,source listing of rtext \i,rtext \i,rtext listing \i,listing of rtext \c,---------------------------------------------------------------------------- FTN5UG PROGRAM RTEXT Screen 1 of 4 PROGRAM RTEXT CHARACTER LINE*80, CHAR*1 DATA NC, NW, NS, NB/4*0/ PRINT*, 'ENTER TEXT' 10 READ '(A)', LINE PRINT*, LINE C SKIP LEADING BLANKS. DO 12 I = 1,80 IF (LINE(I:I) .NE. ' ') GO TO 14 12 CONTINUE PRINT*, 'BLANK LINE' GO TO 10 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM RTEXT Screen 2 of 4 Program RTEXT (continued): C TEST REMAINDER OF INPUT LINE. THE FOLLOWING COUNTERS ARE USED: C NC TOTAL CHARACTERS C NW TOTAL WORDS C NS TOTAL SENTENCES 14 DO 16 J = I,80 CHAR = LINE(J:J) C BLANK INDICATES END OF WORD. LOGIC IS INCLUDED TO ACCOUNT FOR C SUCCESSIVE BLANKS AND BLANKS AFTER END OF SENTENCE. IF (CHAR .EQ. ' ') THEN IF (NB .EQ. 0) NW = NW + 1 NB = 1 C PERIOD OR QUESTION MARK INDICATES END OF SENTENCE. ELSE IF (CHAR .EQ. '.' .OR. CHAR .EQ. '?') THEN NC = NC + 1 NS = NS + 1 NW = NW + 1 NB = 1 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM RTEXT Screen 3 of 4 Program RTEXT (continued): C COMMA INDICATES END OF WORD. ELSE IF (CHAR .EQ. ',') THEN NC = NC + 1 NW = NW + 1 NB = 1 C SLASH INDICATES END OF TEST. CALCULATE AVERAGES, PRINT RESULTS, C STOP. ELSE IF (CHAR .EQ. '/') THEN AVCPW = REAL(NC) / REAL(NW) AVCPS = REAL(NW) / REAL(NS) PRINT 120, NC, NW, NS, AVCPW, AVWPS 120 FORMAT (/'TOTAL CHARACTERS = ',I4, + /'TOTAL WORDS = ',I4, + /'TOTAL SENTENCES = ',I4, + /'AVERAGE CHARACTERS/WORD = ',F5.1, + /'AVERAGE CHARACTERS/SENTENCE = ',F5.1) STOP Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM RTEXT Screen 4 of 4 Program RTEXT (continued): C IF CHARACTER IS NOT A TERMINATOR, IT IS PART OF A WORD. ELSE NC = NC + 1 NB = 0 ENDIF 16 CONTINUE GO TO 10 END Program RTEXT reads input from the terminal. Any number of lines can be input; a slash (/) at the end of a line indicates the end of the input text. The program skips any leading blanks and tests the remainder of the input lines for characters that indicate the end of a word or sentence. (This is a simplified program and does not test for all contingencies. For example, blanks between the last word of a sentence and the period produce incorrect results.) Press RETURN to see the Sample Terminal Dialog for RTEXT. \c,---------------------------------------------------------------------------- \s,ft_dbb \u,ft_db \c,---------------------------------------------------------------------------- \i,sample terminal dialog for rtext \i,rtext output \c,---------------------------------------------------------------------------- FTN5UG SAMPLE TERMINAL DIALOG FOR RTEXT Screen 1 of 1 /lgo ENTER TEXT ? comments should be interspersed throughout a program. COMMENTS SHOULD BE INTERSPERSED THROUGHOUT A PROGRAM. ? comments are especially desirable before each major COMMENTS ARE ESPECIALLY DESIRABLE BEFORE EACH MAJOR ? step of a program. comments should also appear wherever STEP OF A PROGRAM. COMMENTS SHOULD ALSO APPEAR WHEREVER ? the program does something devious, or non-obvious./ THE PROGRAM DOES SOMETHING DEVIOUS, OR NON-OBVIOUS./ TOTAL CHARACTERS = 184 TOTAL WORDS = 30 TOTAL SENTENCES = 3 AVERAGE CHARACTERS/WORD = 6.1 AVERAGE WORDS/SENTENCE = 10.0 Press RETURN to see the source listing for Program EDIT. \c,---------------------------------------------------------------------------- \s,ft_dbc \u,ft_db \c,---------------------------------------------------------------------------- \i,program edit \i,source listing of program edit \c,---------------------------------------------------------------------------- FTN5UG PROGRAM EDIT Screen 1 of 4 PROGRAM EDIT CHARACTER*80 LINE, STR1, STR2, TEMP C GET INPUT FROM TERMINAL. 10 PRINT*, 'ENTER TEXT LINE' READ '(A)', LINE IF (LINE(1:2) .EQ. '//') STOP 15 PRINT*, 'ENTER STRING TO BE REPLACED' READ '(A)', STR1 I = INDEX(STR1,'/') IF (I .EQ. 0) THEN PRINT*, 'NO TERMINATOR' GO TO 15 ENDIF LEN1 = I - 1 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM EDIT Screen 2 of 4 20 PRINT*, 'ENTER REPLACEMENT STRING' READ '(A)', STR2 I = INDEX(STR2,'/') IF (I .EQ. 0) THEN PRINT*, 'NO TERMINATOR' GO TO 20 ENDIF LEN2 = I - 1 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM EDIT Screen 3 of 4 C SEARCH TEXT LINE FOR KEY STRING. WHEN AN OCCURRENCE IS FOUND, C REPLACE IT WITH THE REPLACEMENT STRING. K = 1 DO 45 I = 1,80 J = INDEX(LINE(K:80), STR1(1:LEN1)) IF (J .EQ. 0) GO TO 50 J = J + K - 1 K = J + LEN1 TEMP = LINE LINE = TEMP(1:J-1)//STR2(1:LEN2)//TEMP(K:80) K = J + LEN2 IF (K .GT. 80) GO TO 50 45 CONTINUE 50 PRINT*, LINE GO TO 10 END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_db \c,---------------------------------------------------------------------------- FTN5UG PROGRAM EDIT Screen 4 of 4 Program EDIT reads three input lines from the terminal: a line of text to be edited, a key string to be replaced, and a replacement string. The key string and the replacement string must be terminated with a slash. An input line of two successive slashes causes the program to terminate. The program contains a DO loop in which the input line is searched for all occurrences of the key pattern. The INDEX function returns the first character position of the first occurrence of the key string within the input line. (A return value of zero indicates no occurrences.) The key string is then replaced by the replacement string. Each pass through the loop searches for a single occurrence of the key pattern. When no more occurrences are detected, the program exits from the loop, prints the edited line, and requests another line of input. The figure on the following screen shows a sample terminal dialog for program EDIT. Press RETURN to see the Sample Terminal Dialog for EDIT. \c,---------------------------------------------------------------------------- \s,ft_dbd \u,ft_db \c,---------------------------------------------------------------------------- \i,sample terminal dialog for edit \i,edit output \c,---------------------------------------------------------------------------- FTN5UG SAMPLE TERMINAL DIALOG FOR EDIT Screen 1 of 1 /lgo ENTER TEXT LINE ? this line contains a spelling error. ENTER STRING TO BE REPLACED ? l NO TERMINATOR ENTER STRING TO BE REPLACED ? l/ ENTER REPLACEMENT STRING ? ll/ THIS LLINE CONTAINS A SPELLING ERROR. ENTER TEXT LINE ? // 0.007 CP SECONDS EXECUTION TIME. Press RETURN to read about the PARAMETER Statement. \c,---------------------------------------------------------------------------- \s,ft_dc \u,ft_d \c,---------------------------------------------------------------------------- \i,parameter statement \i,parameter \i,symbolic name to constant \i,assign symbolic name \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 1 of 7 The PARAMETER statement assigns a symbolic name to a constant. There are several programming situations in which this feature is especially useful. One important use of PARAMETER statements is to assign meaningful names to constants, thus making a program more readable. For example, in a program that calculates the area of a circle, you could assign the name PI to the constant 3.14159 with the statement PARAMETER (PI=3.14159). The calculation: AREA = 3.14159*R**2 could then be replaced by the more meaningful statement: AREA = PI*R**2 No efficiency is lost, because the PARAMETER statement is not executable (the operation is performed at compile time) and no extra instructions are generated. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,c$ directive,1 \i,c$,1 \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 2 of 7 Another useful application of PARAMETER statements is with C$ directives. These directives provide instructions to the compiler. You can control the effects of C$ directives within a program by changing the value of the constant tested by the directives. This process is made easier by using symbolic constants, since it is then necessary to change only a PARAMETER statement rather than the directives themselves. Enter PARM? to see this use of PARAMETER statements illustrated. A third use of PARAMETER statements occurs when a constant appears several times within a program, and it might be necessary to change the value of the constant at times throughout the existence of the program. By assigning a symbolic name to the constant, you need only change a single PARAMETER statement rather than each statement where the constant is used. Program CORR, shown following this discussion illustrates this type of situation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,program corr \i,corr \i,correlation coefficient \i,correlation \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 3 of 7 When assigning a character string to a parameter, you must declare the parameter in a CHARACTER statement. For this use of the CHARACTER state- ment, you can use the symbol (*) for the length of the variable. This means that the parameter has the length of the string assigned to it. For example, in the statements: CHARACTER FMT*(*) PARAMETER (FMT='(3X,2F10.2)') the symbolic constant FMT has a length of 11 characters. Program CORR, shown on the following two screens, calculates a correlation coefficient for two sets of numbers. The correlation coefficient provides a means of measuring the correlation between two sets of numbers. A coefficient with a value close to 1 indicates close correlation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 4 of 7 PROGRAM CORR PARAMETER (N=10) INTEGER SUMJ, SUMK, SUMJK, SUMJSQ, SUMKSQ REAL NUM DIMENSION J(N),K(N) C READ NUMBERS TO BE CORRELATED. 10 PRINT*, 'ENTER FIRST SET' READ*, J IF (J(1) .EQ. 9999) STOP PRINT*, 'ENTER SECOND SET' READ*, K C INITIALIZATION. SUMJ = 0 SUMK = 0 SUMJSQ = 0 SUMKSQ = 0 SUMJK = 0 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 5 of 7 Program CORR (continued): C CALCULATE CORRELATION COEFFICIENT. DO 20 I = 1,N SUMJ = SUMJ + J(I) SUMK = SUMK + K(I) SUMJSQ = SUMJSQ + J(I)**2 SUMKSQ = SUMKSQ + K(I)**2 SUMJK = SUMJK + J(I)*K(I) 20 CONTINUE NUM = REAL(N * SUMJK - SUMJ * SUMK) A = REAL(N * SUMJSQ - SUMJ**2) B = REAL(N * SUMKSQ - SUMK**2) DENOM = SQRT(A) * SQRT(B) R = NUM / DENOM PRINT 100, R 100 FORMAT (' CORRELATION COEFFICIENT = ',F6.2,//) GO TO 10 END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 6 of 7 Program CORR reads two sets of numbers from the terminal. If the first number of the first set is 9999, the program immediately terminates; otherwise, the program performs the calculation, branches to the beginning, and requests another set of input values. The program is written to process sets containing 10 numbers. The statement PARAMETER (N=10) assigns the name N to the constant 10. This symbolic constant is used in the DIMENSION statement, the DO statement, and in the statements that calculate the intermediate values NUM, A, and B. The program can be modified to calculate a result for a different number of values by changing only the PARAMETER statement. A sample terminal dialog for program CORR is shown on the following screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,sample terminal dialog for corr \i,corr output \c,---------------------------------------------------------------------------- FTN5UG PARAMETER STATEMENT Screen 7 of 7 Sample terminal dialog for program CORR: /lgo ENTER FIRST SET ? 1 2 3 4 5 6 7 8 9 0 ENTER SECOND SET ? 0 9 8 7 6 5 4 3 2 1 CORRELATION COEFFICIENT = -.03 ENTER FIRST SET ? 1 2 3 4 5 6 7 8 9 0 ENTER SECOND SET ? 1 2 3 4 5 6 7 8 9 0 CORRELATION COEFFICIENT = 1.00 ENTER FIRST SET ? 9999 0 0 0 0 0 0 0 0 0 0.008 CP SECONDS EXECUTION TIME. Press RETURN to read about the GETPARM Subroutine Call. \c,---------------------------------------------------------------------------- \s,ft_dd \u,ft_d \c,---------------------------------------------------------------------------- \i,getparm subroutine call \i,getparm subroutine \i,getparm \i,getparm feature \i,passing values at execution time \i,execution time values \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 1 of 9 The GETPARM feature allows you to pass values to a program at execution time. You can use this feature to control various aspects of program execution at the time execution is initiated. Parameter names and values to be passed to a program must be specified on the execution control statement as follows: LGO,name1,...,namen. or LGO,name1=value1,...,namen=valuen. where name1 is a parameter name and valuei is a value assigned to the parameter. Parameter names and values must be placed after file names that are specified on the execution control statement. For example, LGO,file1,file2,name1=value1. The parameter name and value are passed to the executing program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,call getparm \i,getpram \i,call getparm subroutine call \i,call getparm subroutine \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 2 of 9 The parameter names and values are accessed from the program by a call to the GETPARM subroutine. This subroutine call has the form: CALL GETPARM (c1,c2,i) The following values are returned in the calling arguments: c1 Contains the parameter name in character format. c2 Contains the parameter value in character format. i Is a status indicator having one of the following values: -1 No parameters were specified on the execution control statement. 0 Normal return. Values are returned in c1 and c2. 1 A parameter name only was specified on the execution control statement (c2 is undefined). Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,execution-time file name substitution \i,file name substitution \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 3 of 9 You can include a call to GETPARM at any point in your program where you want to access the parameters specified on the execution control statement. This feature is especially useful for production programs, to allow users to select various options at execution time. GETPARM provides a preferred alternative to the use of the PROGRAM statement for execution-time file name substitution. The program following this discussion illustrates a typical use of the GETPARM feature: to allow execution-time specification of the name of a file to be read by the program. Program AREA reads a file containing the lengths of the sides of a triangle and calculates the area of the triangle. The GETPARM subroutine is used to allow the name of the input file to be specified on the LGO statement in the following form: LGO,I=lfn. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 4 of 9 If no file name is specified, the program assumes the default name INPUT (input read from the terminal). The first part of the program contains a nested block IF structure to test the values specified on the LGO statement. If no values are specified (IFG=1), the value assigned to LFN in the DATA statement ('INPUT') is retained. In this case, a message is printed to prompt the user for input. If a keyword and value of the form I=lfn are specified (IFG=0), the keyword is tested for validity. If the keyword is correct, the file name is assigned to the variable LFN, and the OPEN statement associates the file name with unit 1. The program then reads the input values, performs the calculation, and branches back to read another set of input values. Press RETURN to see the listing for program AREA. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,program area \i,source listing of area \i,area \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 5 of 9 PROGRAM AREA CHARACTER*7 KEY, VAL, LFN DATA LFN/'INPUT'/, ITERM/O/ CALL GETPARM (KEY,VAL,IFG) IF (IFG .GE. O) THEN IF (IFG .EG. 0) THEN IF (KEY .EQ. 'I') THEN LFN = VAL ELSE PRINT*, ' INVALID KEYWORD' STOP ENDIF ENDIF ELSE ITERM = 1 ENDIF Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 6 of 9 Program AREA (continued): OPEN (1,FILE=LFN) 10 IF (ITERM .EQ. 1) PRINT*, 'ENTER SIDES' READ (1,*,END=20) S1,S2,S3 S = (S1 + S2 + S3)/2.0 ASQ = S*(S-S1)*(S-S2)*(S-S3) IF (ASQ .LT. 0.0) THEN PRINT*,' INVALID TRIANGLE' ELSE A = SQRT(ASQ) PRINT 100, S1,S2,S3,A 100 FORMAT (' SIDES = ',3F8.2,/'AREA = ',F8.2) ENDIF GOTO 10 20 STOP END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 7 of 9 The figure on the following two screens shows a sample input file and terminal dialog for program AREA. The program is executed two times. The first time, execution is initiated by the statement LGO, and input values are read from the terminal. The second time, execution is initiated by the statement LGO,I=AFILE, and input is read from a file named AFILE. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,sample output for area \i,area output \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 8 of 9 Sample terminal dialog for program AREA: /lgo ENTER SIDES ? 3.0 4.0 5.0 SIDES = 3.00 4.00 5.00 AREA = 6.00 ENTER SIDES ? .006 CP SECONDS EXECUTION TIME Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG GETPARM SUBROUTINE CALL Screen 9 of 9 Sample terminal dialog for program AREA (continued): Sample input file: 1.0 1.0 1.0 4.0 5.0 6.0 1.0 0.0 0.0 Sample terminal dialog for program AREA: /lgo,i=afile SIDES = 1.00 1.00 1.00 AREA = .43 SIDES = 4.00 5.00 6.00 AREA = 9.92 INVALID TRIANGLE .010 CP SECONDS EXECUTION TIME. Press RETURN to read about INTRINSIC and EXTERNAL Declarations. \c,---------------------------------------------------------------------------- \s,ft_de \u,ft_d \c,---------------------------------------------------------------------------- \i,intrinsic and external declarations \i,intrinsic declarations \i,intrinsic \i,external declarations \i,external \i,subprogram names as argument \c,---------------------------------------------------------------------------- FTN5UG INTRINSIC AND EXTERNAL DECLARATIONS Screen 1 of 5 The INTRINSIC and EXTERNAL declarative statements allow you to pass subprogram names as arguments to other subprograms. Whenever an intrinsic function name is passed as an argument, the function name must be declared in an INTRINSIC statement; whenever an external function or subroutine (whether user-defined or library) is passed as an argument, the subroutine or function name must be declared in an EXTERNAL statement. The program shown on the following two screens uses the INTRINSIC and EXTERNAL declarations. The program consists of a main program, TSTPLT, and a subroutine, PLOT. Subroutine PLOT plots the functional values of a given function. Input to PLOT consists of the function to be plotted (F), the upper and lower limits of the values to be plotted (XLIM1 and XLIM2), and the interval at which values are to be plotted (DELT). Values are plotted starting with XLIM1 and continuing through XLIM2 at intervals of DELT. The main program declares intrinsic functions ALOG10, EXP, and SIN to be INTRINSIC, and user-defined function FNC to be EXTERNAL. These functions can then be passed through the argument list to subroutine PLOT. Output from PLOT is shown following the program listing. Press RETURN to see program TSTPLT. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,program tstplt \i,tstplt \c,---------------------------------------------------------------------------- FTN5UG INTRINSIC AND EXTERNAL DECLARATIONS Screen 2 of 5 PROGRAM TSTPLT INTRINSIC ALOG10,EXP,SIN EXTERNAL FNC PRINT*, 'PLOT OF Y=2.0*X +1.0' CALL PLOT (FNC,0.0,0.5,0.5) PRINT*, 'PLOT OF Y=ALOG10(X)' CALL PLOT (EXP,-1.0,0.0,0.1) END Press RETURN to see the listing of subroutine PLOT and function FNC. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG INTRINSIC AND EXTERNAL DECLARATIONS Screen 3 of 5 SUBROUTINE PLOT (F,XLIM1,XLIM2,DELT) CHARACTER*1 BLANK,STAR DATA BLANK/' '/,STAR/'*'/ STEP = XLIM1 10 Y = F(STEP) IPT = MAX(1,MIN(80,INT(10.0*Y)+11)) PRINT 100, (BLANK,I = 1,IPT),STAR 100 FORMAT (120A1) STEP = STEP + DELT IF STEP .LE. XLIM2) GO TO 10 RETURN END FUNCTION FNC(X) FNC = 2.0*X + 1.0 RETURN END Press RETURN to see the output from subroutine PLOT. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,plot output \i,subroutine plot output \c,---------------------------------------------------------------------------- FTN5UG INTRINSIC AND EXTERNAL DECLARATIONS Screen 4 of 5 Subroutine PLOT output: PLOT OF Y=2.0*X + 1.0 * * * * * * * * * * Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG INTRINSIC AND EXTERNAL DECLARATIONS Screen 5 of 5 Subrouting PLOT output (continued): PLOT OF Y=ALOG10(X) * * * * * * * * * * Press RETURN to read about Upper and Lower Array Bounds. \c,---------------------------------------------------------------------------- \s,ft_df \u,ft_d \c,---------------------------------------------------------------------------- \i,upper and lower array bounds \i,upper array bounds \i,lower array bounds \i,array bounds \i,bounds of arrays \c,---------------------------------------------------------------------------- FTN5UG UPPER AND LOWER ARRAY BOUNDS Screen 1 of 3 Upper and lower bounds declarations can also be used to simplify subscript calculations. Two versions of a subroutine that moves elements N1 through N2 of an array A to successive locations starting with the first word of a second array B are shown on the next screen. The first example specifies an asterisk for the array dimensions: the lower dimension bound defaults to 1 and the upper bound is determined by the number of elements stored into the array. The subsequent DO loop to move the desired values requires the subscript calculation I-N1+1 for the array B. In the second example, however, the DIMENSION declaration B(N1:N2) establishes upper and lower dimension bounds for B corresponding to the range of elements from A to be moved. This declaration specifies that a subscript equal to N1 references the first element of B, a subscript equal to N1+1 references the second element of B, and so forth. The subscript calculation for B is then simplified to B(I). For large arrays, the savings in execution time could be significant. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,* symbol \i,* \i,dummy arguments \i,dummry arguments in arrays \i,array dummy arguments \c,---------------------------------------------------------------------------- FTN5UG UPPER AND LOWER ARRAY BOUNDS Screen 2 of 3 Example 1 Example 2 SUBROUTINE MOVEN (A,B,N1,N2) SUBROUTINE MOVEN (A,B,N1,N2) DIMENSION A(*), B(*) DIMENSION A(*), B(N1:N2) DO 10 I=N1,N2 DO 10 I=N1,N2 B(I-N1+1) = A(I) B(I) = A(I) 10 CONTINUE 10 CONTINUE RETURN RETURN END END The preceding example also illustrates the use of the * symbol to declare the dimension of an array passed as a dummy argument in a subroutine. The size of the array is determined by the number of elements stored in the array. This method of dummy argument array declaration is preferred to the common practice of declaring the array to have a dimension of one. Both methods improve object code efficiency, but using the asterisk suppresses the bounds checking errors that occur when a dimension of one is used. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- FTN5UG UPPER AND LOWER ARRAY BOUNDS Screen 3 of 3 When you dimension an array in a FORTRAN program, you can declare both the upper and lower dimension bounds of the array. One use of this feature is to make a program more understandable. For example, a program dealing with an array of years from 1964 to 1980 can be declared as: INTEGER YEARS(17) The program can be made clearer, however, by using upper and lower bounds to declare the array as: INTEGER YEARS (1964:1980) Press RETURN to read about Internal I/O. \c,---------------------------------------------------------------------------- \s,ft_dg \u,ft_d \c,---------------------------------------------------------------------------- \i,internal i/o \i,internal input \i,internal output \i,read statement \i,write statement \i,encode statement \i,decode statement \i,read \i,write \i,encode \i,decode \i,character conversion \c,---------------------------------------------------------------------------- FTN5UG INTERNAL I/O Screen 1 of 2 The internal I/O feature of FORTRAN 5 allows you to use READ and WRITE statements to move data from one memory location to another, and to convert the data according to a format specification. The function of these statements is similar to that of the ENCODE and DECODE statements. However, READ and WRITE are preferred because they are easier to understand and they do not depend on the number of characters in a word. The concept of internal I/O is similar to that of external I/O, except that data is moved between memory locations rather than between memory and an external I/O device. A useful application of internal I/O is the conversion of data between character and Hollerith formats. (Although programs should be written to use character data only, many existing programs still expect data in Hollerith format.) The sequence on the following screen performs this conversion. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_d \c,---------------------------------------------------------------------------- \i,data conversion routine \c,---------------------------------------------------------------------------- FTN5UG INTERNAL I/O Screen 2 of 2 Data conversion routine: BOOLEAN H CHARACTER*10 X READ(X,'(A10)')H Convert character to Hollerith WRITE(X,'(A10)')H Convert Hollerith to character The READ statement reads data from the character variable X according to A10 format and stores it in the Boolean variable H. The WRITE statement writes data from H to X, converting the data according to A10 format. Press RETURN to read about OPEN and CLOSE Statements. \c,---------------------------------------------------------------------------- \s,ft_dh \u,ft_d \c,---------------------------------------------------------------------------- \i,open and close statements \i,open statement \i,open \i,close statement \i,open a file \i,close a file \i,file buffer \i,buffer \i,establish file attributes \i,file attributes \i,bufl parameter \i,bufl \c,---------------------------------------------------------------------------- FTN5UG OPEN AND CLOSE STATEMENTS Screen 1 of 1 The OPEN and CLOSE statements allow you to assign file names, create buffers, and establish and subsequently release various other file attributes. Declaring a file in an OPEN statement has the same effect as declaring the file on the PROGRAM statement; however, OPEN provides more options and is the preferred method. OPEN statements or PROGRAM statement declarations are not required for files used in a program. If you omit these statements, file buffers are automatically created when the file is first referenced. A useful application of OPEN and CLOSE statements is to restrict the amount of memory used for I/O operations. If you know exactly how much buffer space is required for an operation, you can assign that amount with the BUFL parameter in an OPEN statement. When the operation is complete, you can use the CLOSE statement to release the buffers. Press RETURN to read the Introduction to Product Interfaces. \c,---------------------------------------------------------------------------- \s,ft_di \u,ft_d \c,---------------------------------------------------------------------------- \m=a,ft_dia \m=b,ft_dib \m=c,ft_dic \m=d,ft_did \c,---------------------------------------------------------------------------- \i,introduction to product interfaces \i,product interfaces \i,interfaces \c,---------------------------------------------------------------------------- FTN5UG INTRODUCTION TO PRODUCT INTERFACES Screen 1 of 1 CDC supplies several software facilities that perform various useful functions. These facilities are available to FORTRAN 5 programs through special statements or subroutine calls. Following are brief descriptions of these facilities. These descriptions are intended only to introduce the products; in order to use them, you are directed to the appropriate publications. Complete titles and publication numbers are listed in the preface (enter PREFACE?). Enter one of the following letters to learn more about product interfaces: a. Cyber Record Manager b. Common Memory Manager c. Sort/Merge d. FORTRAN Database Facility Press RETURN to read about Cyber Record Manager. Enter UP to return to the FORTRAN 5 Features menu. \c,---------------------------------------------------------------------------- \s,ft_dia \u,ft_di \c,---------------------------------------------------------------------------- \i,cyber record manager \i,crm \i,record manager \i,call crm directly \i,call crm \i,advanced access methods \i,amm \i,file organizations \i,indexed sequential \i,actual key \i,direct access \i,non-standard files \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 1 of 14 CYBER Record Manager (CRM) performs input and output operations. All FORTRAN input and output statements invoke CRM to perform the actual operations. In addition, you can call CRM directly from a FORTRAN program through special subroutine calls. CRM provides a set of FORTRAN-callable subroutines that allows you to read or write files having a structure different from that used by standard FORTRAN input and output statements. You can use these routines to define file attributes, to read or write complete or partial records, to replace selected records, to position a file, to access the file information table, and to terminate a section or partition within a file. The Advanced Access Method file organizations that are available to users of CRM are: Indexed sequential Actual key Direct Access Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,basic access method \i,bam \i,sequential \i,word addressable \i,file call \i,fileak \i,fileis \i,fileda \i,file information table \i,fit \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 2 of 14 The Basic Access Method file organizations are: Sequential Word addressable Descriptions of the CRM interface routines are contained in the FORTRAN 5 reference manual. Refer to the Advanced Access Method and Basic Access Method user's guides for information on how to use these routines and for information on the CRM file organizations. When you create a new CRM file, you must define certain attributes of the file with a call to either FILE (under BAM) or FILExx (under AAM); xx denotes the file type and can be indexed sequential (IS), actual key (AK), or direct access (DA). FILE or FILExx stores values in the File Information Table (FIT); this table completely describes the file to CRM. The FIT contains such information as file organization, record type and length, block type and length, and record key information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,openm \i,closem \i,call openm \i,call closem \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 3 of 14 Certain FIT values must be assigned by a call to FILE or FILExx at creation time; others are optional. Optional values are assigned a default value by CRM. To read an existing file, you must first call FILE or FILExx to set certain FIT fields to the same value as on the creation run. The information in the FIT is required by all succeeding CRM subroutines. After establishing the FIT, you must open the file with a call to OPENM. After the file is opened, you can read and update the file using other CRM calls. The last CRM routine called is CLOSEM, which initiates file termination processing. The figures on the following screens illustrate the use of the CRM calls to update an existing indexed sequential file. The file format and a listing of the file are shown on the next screen. Records within the indexed sequential file are identified by a key that was established when the file was created. Individual records can be subsequently retrieved by referencing the key in the appropriate CRM call. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,crm example \i,example of crm \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 4 of 14 File ISFILE listing: Order Key and Company Name Amount Year to Date 1 31 41 ------------------------------------------------------------ B695 ABC DISTRIBUTORS 412658 7880621 E482 CORP SALES INC 89207 1145853 H314 DAY AND NIGHT SALES 52753 2066122 K620 FRIENDLY SALES 1027866 6247410 M875 OAKVILLE CORP 149287 3014192 R500 RETAILERS INC 76854 1255868 T258 SELECTIVE SALES CO 248916 4337092 V440 WORLD SALES CO 914819 6844272 X179 YOUNG BROTHERS 527638 2428535 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,program isupdat \i,isupdat \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 5 of 14 The listing on the following screens shows a program to update the indexed sequential file. Program ISUPDAT reads update information from the terminal. The first character of an input line is a one-digit code determining the update operation to be performed (add, delete, or replace a record). Subsequent information on the input line is placed in the new record. The program reads an input line, performs the indicated operation, and branches to the beginning to read another input line. When end of input is indicated (carriage return entered), the program prints the updated file and terminates. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 6 of 14 PROGRAM ISUPDAT IMPLICIT INTEGER (A-Z) DIMENSION FIT(35), WSA(5) CALL FILEIS (FIT,'LFN','ISFILE','ORG','NEW','RT','F', + 'WSA',WSA,'KA',KEY) CALL OPENM (FIT,'I-O') IERR = IFETCH (FIT,'ES') IF (IERR .NE. 0) GO TO 900 C READ UPDATE INFORMATION FROM TERMINAL. CALL REWND (FIT) PRINT*, 'ENTER CODE, RECORD KEY, AND UPDATE INFORMATION' 20 READ (*,120,END=30) CODE, KEY, ORDER, WSA 120 FORMAT (I1,1X,A4,1X,I10,1X,3A10,2I10) IF (ICODE .EQ. 1) THEN Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 7 of 14 Program ISUPDAT (continued): C UPDATE EXISTING RECORD. CALL GET(FIT) IERR = IFETCH (FIT,'ES') IF (IERR .NE. 0) GO TO 900 WSA(4) = ORDER WSA(5) = WSA(5) + ORDER CALL REPLC(FIT) IERR = IFETCH(FIT,'ES') IF (IERR .NE. 0) GO TO 900 GO TO 20 ELSE IF (CODE .EQ. 2) THEN C ADD NEW RECORD. CALL PUT(FIT) IERR = IFETCH(FIT,'ES') IF (IERR .NE. 0) GO TO 900 GO TO 20 ELSE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 8 of 14 Program ISUPDAT (continued): C DELETE EXISTING RECORD. CALL DLTE (FIT) IERR = IFETCH (FIT,'ES') IF (IERR .NE. 0) GO TO 900 GO TO 20 ENDIF Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 9 of 14 Program ISUPDAT (continued): C REWIND AND PRINT UPDATED FILE. 30 CALL REWND(FIT) PRINT 100 40 CALL GETN(FIT) IERR = IFETCH(FIT,'ES') IF (IERR .NE. 0) GO TO 900 IF (IFETCH(FIT,'FP') .EQ. 16) THEN PRINT 110, WSA GO TO 40 ELSE CALL CLOSEM(FIT) ENDIF 100 FORMAT(/'KEY COMPANY ORDER YTD AMT') 110 FORMAT(3A10,2I10) STOP 900 PRINT*, 'CRM ERR ', IERR END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,call fileis \i,fileis \i,call openm \i,openm \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 10 of 14 Program ISUPDAT defines an array FIT to contain the file information table, and an array WSA to be used as a working storage area by the input output routines. The following CRM subroutine calls are used in the program: CALL FILEIS (FIT,'LFN','ISFILE',...) Specifies the name of the file to be read (ISFILE) and sets fields in the FIT to describe the structure of the file. As described by the subroutine parameters, the file is an indexed sequential file, is named ISFILE, has NEW organization, and has F-type records. Array WSA is the working storage area, and the variable KEY is associated with the key field of the file records. CALL OPENM (FIT,'I-O') Opens the file for input/output. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,call get \i,get \i,call replc \i,replc \i,call put \i,put \icall dlte \idlte \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 11 of 14 CRM subroutines used in program ISUPDAT (continued): CALL GET (FIT) Reads the record identified by the current value of KEY. (The key field within the record is defined when the file is created.) The record is read into array WSA. CALL REPLC (FIT) Replaces the current record with the values in WSA. CALL PUT (FIT) Writes a new record from array WSA to the file. CALL DLTE (FIT) Deletes the record identified by the current value of KEY. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,call rewnd \i,rewnd \i,call getn \i,getn \i,ifetch \i,call closem \i,closem \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 12 of 14 CRM subroutines used in program ISUPDAT (continued): CALL REWND (FIT) Rewinds the file. CALL GETN (FIT) Reads the next record in sequence and stores it in WSA. IFETCH (FIT,'FP') Retrieves the value of the file position (FP) field of the FIT. The FP field is set to 16 after a successful read. This field is used in the example to test for the end of the file. CALL CLOSEM (FIT) Performs file termination processing. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 13 of 14 After each update operation, IFETCH is called to retrieve the value of the ES (error) field of the FIT. If ES contains a zero, the operation was successful; if an error occurred, ES contains the error number. (Error numbers and their meanings are listed in the CYBER Record Manager Advanced Access Methods reference manual.) The terminal dialog for this example, including program input and output, is shown on the following screen. The following operations are performed: The records having keys R500 and B695 are updated. A new record, having key S703, is added. The record having key H314 is deleted. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_di \c,---------------------------------------------------------------------------- \i,sample terminal dialog for isupdat \i,isupdat output \c,---------------------------------------------------------------------------- FTN5UG CYBER RECORD MANAGER Screen 14 of 14 Sample terminal dialog for program ISUPDAT: /lgo ENTER CODE, RECORD KEY, AND UPDATE INFORMATION ? 1 R500 104476 ? 1 B695 384292 ? 2 S703 S703 ROYAL SUPPLY 185722 185722 ? 3 H314 ? KEY COMPANY ORDER YTD AMT B695 ABC DISTRIBUTORS 385292 8265913 E482 CORP SALES INC 89207 1145853 K620 FRIENDLY SALES 1027866 6247410 M875 OAKVILLE CORP 149287 3014192 R500 RETAILERS INC 104476 1360344 T258 SELECTIVE SALES CO 248916 4337092 V440 WORLD SALES CO 914819 6844272 X179 YOUNG BROTHERS 527638 2428535 Press RETURN to read about Common Memory Manager. \c,---------------------------------------------------------------------------- \s,ft_dib \u,ft_di \c,---------------------------------------------------------------------------- \m=a,ft_diba \m=b,ft_dibb \m=c,ft_dibc \m=d,ft_dibd \c,---------------------------------------------------------------------------- \i,common memory manager \i,cmm \i,allocation of memory \i,memory allocation \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER Screen 1 of 1 Common Memory Manager (CMM) is a system facility that provides a program with execution-time control over the allocation of memory. Enter one of the following letters to learn more about CMM: a. Overview b. Requesting a Block of Memory c. Freeing a Block of Memory d. Common Memory Manager Example Press RETURN to read the Overview. Enter UP to return to the Introduction to Product Interfaces menu. \c,---------------------------------------------------------------------------- \s,ft_diba \u,ft_dib \c,---------------------------------------------------------------------------- \i,common memory manager overview \i,field length \i,execution field length \i,fixed field length \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER OVERVIEW Screen 1 of 2 Before a program begins execution, the CYBER Loader assigns to it a fixed area of memory called the execution field length. The program's execution field length contains all the executable code (except for any overlays or OVCAPs used by the program) and data storage areas to be used by the program during execution. Generally, the execution field length remains fixed throughout execution. However, a fixed field length can result in wasted space in cases where portions of the field length are unused throughout much of a program's execution time. For example, a large array within a program might be in actual use for a short period of time relative to the total execution time of the program. If the array is defined by DIMENSION or COMMON declaration, that array remains a fixed part of the program throughout execution. Using CMM, however, you can request a block of memory when it is needed, use the block just as you would use any other locations in your program, and release the block when it is no longer needed. When the block is allocated, the execution field length is increased; when the block is released, the field length is reduced to its original value and the released space is returned to the operating system. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- \i,ovcap,1 \i,call cmm directly \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER OVERVIEW Screen 2 of 2 CMM is called directly by many system programs (and implicitly by FORTRAN programs that interface with these system programs), to achieve optimal memory usage. For example, the OVCAP feature (enter OVCAP?), uses CMM to allocate memory for the execution-time loading and unloading of programs. Other programs use CMM to allocate input/output buffers or storage for large blocks of data. Special CMM subroutine calls enable you to call CMM directly from a FORTRAN program. You can use these calls to request blocks of memory, alter the size of the blocks, release the blocks, request CMM status information, and perform various other operations associated with dynamic memory management. Press RETURN to read about Requesting a Block of Memory. \c,---------------------------------------------------------------------------- \s,ft_dibb \u,ft_dib \c,---------------------------------------------------------------------------- \i,requesting a block of memory \i,requesting memory \i,cmmalf \i,cmmalf routine \i,call cmmalf \c,---------------------------------------------------------------------------- FTN5UG REQUESTING A BLOCK OF MEMORY Screen 1 of 1 You can request CMM to assign a block of memory to your program by calling the CMMALF routine. This call has the form: CALL CMMALF (size,0,0,fwa) The input argument size is a decimal integer indicating the number of words to be allocated. CMMALF returns the first word address of the block in the argument fwa. The memory block allocated by CMMALF becomes a part of the program's field length, which is increased by the length of the block. You can use the block first word address, returned by CMMALF, to calculate an index that enables you to access any location in the block in the same manner as locations in an array. Press RETURN to read about Freeing a Block of Memory. \c,---------------------------------------------------------------------------- \s,ft_dibc \u,ft_dib \c,---------------------------------------------------------------------------- \i,freeing a block of memory \i,cmmfrf \i,cmmfrf routine \i,call cmmfrf \c,---------------------------------------------------------------------------- FTN5UG FREEING A BLOCK OF MEMORY Screen 1 of 1 After you are through with a CMM block, you can free the block by calling routine CMMFRF. This call has the form: CALL CMMFRF (fwa) The input argument fwa is the first word address of the block (the value returned by CMMALF when the block was created). When a CMM block is released by CMMALF, your execution field length is reduced, if possible, and the block is available to the operating system for other uses. Any data stored in the block is lost and cannot be recovered. Press RETURN to read about the Common Memory Manager Example. \c,---------------------------------------------------------------------------- \s,ft_dibd \u,ft_dib \c,---------------------------------------------------------------------------- \i,common memory manager example \i,cmm example \i,example of cmm \i,symlib \i,library symlib \i,cmm interface routines \i,ldset statement \i,ldset \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER EXAMPLE Screen 1 of 3 The figure on the following screen shows the use of CMM in a FORTRAN program. CMMALF is called to allocate a fixed-position block with a length of 10 words, a value is stored in each word of the block, and CMMFRF is called to free the block. In the example, the main program is used for allocating and freeing the block; the subroutine is used for manipulating data within the block. The main program calculates an offset IOFF by subtracting the location of CMMAR(1) from IFWA. The first word of the block is given by CMMAR(IOFF+1), which is passed to the subroutine. Within the subroutine,the first element of array CMMBLK is the first word of the block. Words in the block are referenced as elements of the array; therefore, no complicated subscript calculations are necessary. For programs that manipulate matrices or other multi-dimensional arrays, CMMBLK can be defined as a multi-dimensional array. All CMM interface routines for NOS are in the library SYMLIB. For any FORTRAN run using the CMM interface routines, the statement LDSET(LIB=SYMLIB) must be included in the loader directives or the statement CALL SYMLIB must be included in the FORTRAN program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER EXAMPLE Screen 2 of 3 PROGRAM CMMEX DIMENSION CMMAR(1) C ATTACH CMM INTERFACE ROUTINES. CALL SYMLIB C ALLOCATE A FIXED-POSITION BLOCK OF MEMORY 10 WORDS LONG. ILEN = 10 CALL CMMALF(ILEN, 0, 0, IFWA) C CALCULATE THE OFFSET. IOFF = IFWA - LOCF(CMMAR(1)) C PASS THE ADDRESS OF THE FIRST WORD IN THE BLOCK C TO SUBROUTINE TWIDDLE. CALL TWIDDLE(CMMAR(IOFF+1), ILEN) C FREE THE BLOCK OF MEMORY. CALL CMMFRF(IFWA) END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \n,ft_dib \c,---------------------------------------------------------------------------- FTN5UG COMMON MEMORY MANAGER EXAMPLE Screen 3 of 3 FORTRAN CMM Example (continued): C SUBROUTINE TWIDDLE LOOPS TO PUT A VALUE INTO C A WORD OF THE BLOCK AND PRINT IT. C THE LOOP CONTINUES UNTIL THE BLOCK IS FILLED. SUBROUTINE TWIDDLE(CMMBLK, ILEN) DIMENSION CMMBLK(ILEN) C PUT A VALUE INTO A CMMBLK WORD, THEN PRINT IT. DO 10 I = 1,ILEN CMMBLK(I) = I PRINT*, CMMBLK(I) 10 CONTINUE C END OF SUBROUTINE TWIDDLE. C RETURN TO THE MAIN PROGRAM. RETURN END Press RETURN to return to the Common Memory Manager menu. \c,---------------------------------------------------------------------------- \s,ft_dic \u,ft_dib \p,ft_dib \c,---------------------------------------------------------------------------- \i,sort\merge \i,sort \i,merge \i,sort a file \i,merge a file \i,sorting \i,merging \i,sort records \i,merge records \i,combine files \i,sort/merge subroutine calls \c,---------------------------------------------------------------------------- FTN5UG SORT/MERGE Screen 1 of 5 Sort/Merge is a generalized utility program that is used to rearrange the records of a file in a specified sequence. The sort feature of Sort/Merge allows you to sort records into a desired order. Data to be sorted can be any of the FORTRAN data types. The sort can be based either on one of the four standard collating sequences or on a collating sequence which you create. The merge feature allows you to combine the contents of two or more previously sorted files into a single file. You can invoke Sort/Merge directly from a FORTRAN 5 program by using the Sort/Merge subroutine calls. These calls are described in the FORTRAN 5 reference manual. Detailed information on the use of Sort/Merge is contained in the Sort/Merge reference manual and the Sort/Merge user's guide. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- FTN5UG SORT/MERGE Screen 2 of 5 To sort a file by using Sort/Merge, you must as a minimum: Specify whether the file to be sorted is on magnetic tape or mass storage. Specify the file to be sorted. Define an output file to receive the sorted records. Define a key within the records on which the sort is to be based. This information is passed to Sort/Merge through the subroutine calls. Other subroutine calls allow you to specify collating sequence options, special record handling options, owncode exits, and various other processing options. The program shown on the following screen uses Sort/Merge to sort a file containing employee data so that the employee names are in alphabetical order. The program consists entirely of Sort/Merge calls. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- \i,call smsort \i,smsort \c,---------------------------------------------------------------------------- FTN5UG SORT/MERGE Screen 3 of 4 PROGRAM SRTMRG CALL SMSORT (80) CALL SMFILE ('SORT','CODED',L"SRTIN",'REWIND) CALL SMFILE ('OUTPUT',CODED',L"OUTPUT") CALL SMKEY (1,1,20,0,'DISPLAY','A') CALL SMEND END The following calls are used in the above program: CALL SMSORT (80) Specifies that a mass storage file is to be sorted and that the maximum record length of the file to be sorted is 80 characters. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- \i,call smfile \i,smfile \i,call smkey \i,smkey \c,---------------------------------------------------------------------------- FTN5UG SORT/MERGE Screen 4 of 5 SORT/MERGE calls used in program SRTMRG (continued): CALL SMFILE ('SORT','CODED',L"SRTIN",'REWIND') Identifies the file to be sorted. The file is named SRTIN, is a coded (formatted) file, and is to be rewound after the sort. CALL SMFILE ('OUTPUT','CODED',L"OUTPUT") Defines the output file to receive the sorted records. File OUTPUT is designated as the output file. CALL SMKEY (1, 1, 20, 0,'DISPLAY','A') Describes the sort key to be used. The key begins in the first bit position of the first character of each record, and is 20 characters in length. The format of the key is internal display code. The default collating sequence (internal display) is used, and the records are to be arranged in ascending order. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ft_dib \c,---------------------------------------------------------------------------- \i,call smend \i,smend \c,---------------------------------------------------------------------------- FTN5UG SORT/MERGE Screen 5 of 5 SORT/MERGE calls used in program SRTMRG (continued): CALL SMEND Terminates the sequence of Sort/Merge calls and initiates Sort/Merge processing. Press RETURN to read about the FORTRAN Database Facility. \c,---------------------------------------------------------------------------- \s,ft_did \u,ft_di \n,ft_di \c,---------------------------------------------------------------------------- \i,fortran data base facility \i,data base facility \i,data base \i,dms-170 \i,dms-170 data management system \i,fdbf \i,data definition language \i,ddl \i,data manipulation language \i,dml \c,---------------------------------------------------------------------------- FTN5UG FORTRAN DATABASE FACILITY Screen 1 of 1 The DMS-170 data management system provides for defining, maintaining, and controlling a data base in an environment totally independent of the programs that are accessing it. The FORTRAN Data Base Facility (FDBF) enables you to write a FORTRAN program to access a data base within the DMS-170 environment. FDBF consists of a data definition language and a data manipulation language. The data definition language is similar in format to standard FORTRAN specification statements; it allows you to describe a portion of a data base to be used by a FORTRAN program. The data manipulation language is similar in format to standard FORTRAN input/output statements. The data manipulation language is used to perform input/output operations on files within a data base. Refer to the FORTRAN Data Base Facility reference manual for detailed information on FDBF. Press RETURN to return to the Introduction to Product Interfaces menu. \c,---------------------------------------------------------------------------- \s,db_e \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,db_ea \m=b,db_eb \m=c,db_ec \m=d,db_ed \m=e,db_ee \m=f,db_ef \m=g,db_eg \c,---------------------------------------------------------------------------- \i,debugging \i,debug a program \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING Screen 1 of 1 This topic describes utilities and programming techniques that can help you debug a FORTRAN program. When debugging a program, you are generally concerned with compile-time errors, load-time errors, execution-time errors, and logic errors. The following topics emphasizes the detection of execution-time and logic errors because most debugging time is spent on these types of errors; also included is a brief description of FTN5 control statement options that can assist with compile-time debugging. Enter one of the following letters to learn more about debugging: a. Overview b. Programming Techniques c. Compile-Time Debugging d. Cyber Interactive Debug e. Post Mortem Debugging f. Arithmetic Mode Errors g. Conditional Compilation Press RETURN to read the Overview. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,db_ea \u,db_e \c,---------------------------------------------------------------------------- \i,debugging overview \i,cid,1 \i,cyber interactive debug,1 \i,interactive debugging,1 \i,pmd,1 \i,post mortem dump,1 \i,batch debugging,1 \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING OVERVIEW Screen 1 of 2 Two utilities can help you detect and correct execution-time errors: the CYBER Interactive Debug facility and Post Mortem Dump facility. These utilities are easy and convenient to use, and provide debugging information in a readable symbolic format that requires no tedious interpretation. Thus, it is unlikely that you will need to analyze complicated memory dumps or repeatedly compile your program with PRINT statements inserted at various locations. CYBER Interactive Debug is intended primarily for interactive usage, although it can be used in a batch job; Post Mortem Dump is primarily a batch debugging aid, but can be used interactively. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_e \c,---------------------------------------------------------------------------- \i,efficient progamming,1 \i,programming style,1 \i,style,1 \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING OVERVIEW Screen 2 of 2 Debugging a program can be costly in terms of both programmer time and computer time. (You must often execute a program many times before it is completely debugged.) CYBER Interactive Debug and Post Mortem Dump can reduce these costs by making the debugging process easier for you and by decreasing the number of times you must execute a program. However, these utilities involve costs of their own. In particular, CYBER Interactive Debug (the more flexible of the two utilities for interactive use) increases both execution time and memory utilization. For this reason, you should not overlook other considerations involved in debugging a program. Probably the most important of these considerations is the writing of efficient, clear, error-free code. If your program contains no errors to begin with, you do not have to spend your time and the computer's time debugging. It is, of course, unreasonable to expect to write error-free code. However, you can minimize the time spent debugging by developing a clear and efficient programming style. A well-written program is not only likely to contain fewer errors, but is easier to debug and maintain. Press RETURN to read about Programming Techniques. \c,---------------------------------------------------------------------------- \s,db_eb \u,db_e \c,---------------------------------------------------------------------------- \m=a,db_eba \m=c,db_ebb \m=b,db_ebc \c,---------------------------------------------------------------------------- \i,programming techniques \i,techniques \i,efficient programming \i,programming style \i,style \i,structured programming \i,structure \c,---------------------------------------------------------------------------- FTN5UG PROGRAMMING TECHNIQUES Screen 1 of 1 The most important programming techniques are those which enhance the readability of a program. Two of these techniques are modularity and the use of FORTRAN 5 block IF structures to produce a structured program. Enter one of the following letters to learn more about programming techniques: a. Modularity b. Block IF Structures c. Additional Programming Techniques Press RETURN to read about Modularity. Enter UP to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,db_eba \u,db_eb \c,---------------------------------------------------------------------------- \i,mod \i,modularity \i,modules \i,limiting program size \i,program size \i,modular program \i,program modules \i,efficient object code \i,advantages of modular structure \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 1 of 13 Modularity means limiting the size of program units (modules) and ensuring that each performs a single well-defined function. A modular program is easier to debug, since each module can be debugged separately, and is more conducive to use with CYBER Interactive Debug and Post Mortem Dump. In addition, modular programs generate more efficient object code. Modular programs are also easier to maintain using the techniques described under topic Maintain (enter MAINTAIN?). Another advantage of a modular structure is that modules can often be shared by several programs, thereby reducing the total amount of memory required. For example, an appropriately written module that calculated a square root could be shared by any number of programs requiring a square root. (Enter UPDATE? to read about the technique for sharing modules.) With these considerations in mind, you should limit the size of modules to less than 60 lines of source code wherever possible. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- \i,program sales \i,sales \i,modularity example \i,example of modularity \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 2 of 13 Program SALES illustrates a program that could be greatly improved by modularization. (Enter SALES? to see the listing.) Program SALES reads monthly or weekly sales data from the terminal and prints the data in chronological order and in order of decreasing sales. The program assumes the data is input in chronological order and uses the following algorithm to sort the data. The input values in array MSALES (monthly data) or array WSALES (weekly data) are copied to array NSORT, and the values in array MONTH or array IWEEK, representing the number of each month or week of the year, are copied to array ISORT. NSORT is then searched for the largest value. When this value is found, it is interchanged with the first value in the array. The remaining unsorted elements (starting at word 2) are then searched for the largest value; when this value is found, it is interchanged with the second value of the array. The corresponding values in array ISORT, containing the number of each week or month, are also interchanged. This process of searching and switching continues until the entire array has been sorted. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 3 of 13 Program SALES performs the following distinct functions: Reads input data Performs a sort Prints a report The sort portion of the program can be further subdivided into the following functions: Search the array Switch the positions of two values in the array The latter function is performed twice: once for the array containing the sales data and once for the array containing the number of each month or week. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 4 of 13 The program shown following the listing for SALES performs the same tasks, but it is modularized into separate program units based on these tasks (enter SALES2 to see the listing): The main program reads input data and calls subroutine REPORT. Subroutine REPORT calls subroutine SORT and prints the monthly or weekly figures in chronological and decreasing order. Subroutine SORT locates the largest value in an unsorted array and calls subroutine SWITCH to interchange the largest value with the first value in the array. Subroutine SWITCH switches the values of the two input variables. Although this program is too small to gain much efficiency by modularization, the new version is much more readable than the original version. Furthermore, subroutines SORT and SWITCH are generalized; that is, they could be used by any program requiring a sort. Press RETURN to see the program listing for the unmodularized version of SALES. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- \i,sales \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 5 of 13 Program SALES unmodularized: PROGRAM SALES CHARACTER IPER*7, YEAR*4 INTEGER MSALES(12), WSALES(52), NSORT(52), ISORT(52) 5 PRINT*, 'YEAR?' READ '(A4)', YEAR IF (YEAR .EQ. 'END') STOP PRINT*, 'WEEKLY OR MONTHLY?' READ '(A7)', IPER IF (IPER .EQ. 'WEEKLY') GO TO 25 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 6 of 13 Program SALES unmodularized (continued): C TABULATE MONTHLY FIGURES. PRINT*, 'MONTHLY SALES FIGURES?' READ*, MSALES PRINT 1000, YEAR 1000 FORMAT(//'MONTHLY SALES FIGURES FOR ',A4,//,'CHRONOLOGICAL', + 14X,'BEST TO WORST',/2('MONTH',9X,'SALES',6X)) N = 12 DO 10 I = 1,12 ISORT(I) = I 10 NSORT(I) = MSALES(I) C BRANCH TO PERFORM SORT. GO TO 45 15 DO 20 I = 1,12 20 PRINT 1001, I, MSALES(I), ISORT(I), NSORT(I) 1001 FORMAT (1X,2(I2,8X,I6,11X)) GO TO 5 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 7 of 13 Program SALES unmodularized (continued): C TABULATE WEEKLY FIGURES. 25 N = 52 PRINT*, 'WEEKLY SALES FIGURES?' READ*, WSALES PRINT 1002, YEAR 1002 FORMAT (//'WEEKLY SALES FIGURES FOR ',A4,//,'CHRONOLOGICAL', + 14X,'BEST TO WORST',/2('WEEK',10X,'SALES',6X)) DO 30 I = 1,52 ISORT(I) = I 30 NSORT(I) = WSALES(I) C* BRANCH TO SORT FIGURES. GO TO 45 35 DO 40 I = 1,52 40 PRINT 1001, I, WSALES(I), ISORT(I), NSORT(I) GO TO 5 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 8 of 13 Program SALES unmodularized (continued); C SORT SALES FIGURES. 45 DO 55 I = 1,N-1 LARGE = I DO 50 J = I+1,N IF (NSORT(J) .GT. NSORT(LARGE)) LARGE = J 50 CONTINUE ITEMP = NSORT(I) NSORT(I) = NSORT(LARGE) NSORT(LARGE) = ITEMP ITEMP = ISORT(I) ISORT(I) = ISORT(LARGE) ISORT(LARGE) = ITEMP 55 CONTINUE IF (N .EQ. 12) GO TO 15 GO TO 35 END Press RETURN to see the program listing for the modularized version of SALES. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- \i,sales2 \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 9 of 13 Program SALES modularized: PROGRAM SALES CHARACTER IPER*7, YEAR*4 5 PRINT*, 'YEAR?' READ '(A4)', YEAR IF (YEAR .EQ. 'END') STOP PRINT*, 'WEEKLY OR MONTHLY?' READ '(A7)', IPER C N IS THE NUMBER OF SALES PERIODS. N=12 FOR MONTHLY, N=52 FOR WEEKLY. IF (IPER .EQ. 'WEEKLY') THEN N = 52 ELSE N = 12 ENDIF C* SUBROUTINE REPORT PRINTS THE DESIRED REPORT. CALL REPORT(YEAR, N) GO TO 5 END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 10 of 13 Program SALES modularized (continued): C SUBROUTINE REPORT. SUBROUTINE REPORT(Y, N) CHARACTER TYPE(2)*7, Y*4 INTEGER SALES(52), ISORT(52), NSORT(52), T DATA TYPE/' WEEKLY', 'MONTHLY'/ C PROMPT FOR INPUT, READ SALES DATA, PRINT HEADERS. IF (N .EQ. 52) THEN T = 1 ELSE T = 2 ENDIF PRINT*, 'ENTER SALES FIGURES' READ*, (SALES(I), I = 1,N) PRINT 1000, TYPE(T), Y, TYPE(T)(1:5), TYPE(T)(1:5) 1000 FORMAT(//A7,' SALES FIGURES FOR ',A4,//3X,'CHRONOLOGICAL', + 12X,'BEST TO WORST',/2(A5,9X,'SALES',6X)) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 11 of 13 Program SALES modularized: C INITIALIZE ARRAYS FOR SORT ROUTINE. DO 10 I = 1,N ISORT(I) = I 10 NSORT(I) = SALES(I) C ARRANGE FIGURES IN DECREASING ORDER. CALL SORT(N, ISORT, NSORT) DO 20 I = 1,N 20 PRINT 1001, I, SALES(I), ISORT(I), NSORT(I) 1001 FORMAT(1X,2(I2,8X,I6,11X)) RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 12 of 13 Program SALES modularized (continued): C SUBROUTINE SORT. SUBROUTINE SORT(N, IA, IB) DIMENSION IA(N), IB(N) DO 55 I = 1,N-1 LARGE = I DO 50 J = I+1,N IF (IB(J) .GT. IB(LARGE)) LARGE = J 50 CONTINUE CALL SWITCH(IA(I), IA(LARGE)) CALL SWITCH(IB(I), IB(LARGE)) 55 CONTINUE RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- FTN5UG MODULARITY Screen 13 of 13 Program SALES modularized (continued): C SUBROUTINE SWITCH. SUBROUTINE SWITCH(I, J) ITEMP = I I = J J = ITEMP RETURN END Press RETURN to read about Block IF Structures. \c,---------------------------------------------------------------------------- \s,db_ebb \u,db_eb \c,---------------------------------------------------------------------------- \i,blkif \i,block if structures \i,block if \i,block if statement \i,eliminate branching \i,conditionally execute \i,if blocks \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 1 of 2 The block IF structures of FORTRAN 5 allow you to simplify a program by eliminating branches. Normally, to execute a sequence of statements based on the outcome of an IF statement, you must branch to those statements using a GO TO statement. Block IF structures, however, allow you to conditionally execute groups of statements (called if blocks) without using GO TO statements. A program written with block IF structures is easier to read because execution flows logically from top to bottom, and the sequences of statements are close to the IF test. For this reason, you should use block IF structures wherever possible to avoid unnecessary branches. Block IF structures generate the same machine instructions as GO TO statements, and therefore do not affect program optimization. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eb \c,---------------------------------------------------------------------------- \i,block if structure example \i,example of block if structure \i,block if example \i,example of block if \c,---------------------------------------------------------------------------- FTN5UG BLOCK IF STRUCTURES Screen 2 of 2 The program segment in example 1 is a candidate for block IF implementation: Example 1 Example 2 IF (A .GT. B) GO TO 30 IF (A .GT. B) THEN IF (A .LT. B) GO TO 20 A = A + 1.0 GO TO 40 B = B + 1.0 20 A = A - 1.0 ELSE IF (A .LT. B) THEN B = B - 1.0 A = A - 1.0 GO TO 40 B = B - 1.0 30 A = A + 1.0 END IF B = B + 1.0 40 CONTINUE This program segment compares two variables and executes a different block of statements depending on the outcome of the test. The program segment can be rewritten to use block IF structures as shown in example 2. Press RETURN to read about Additional Programming Techniques. \c,---------------------------------------------------------------------------- \s,db_ebc \u,db_eb \n,db_eb \c,---------------------------------------------------------------------------- \i,additional programming techniques \i,comments \i,indent block if \i,use of blanks \i,blank use \i,statement labels \i,label statements \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL PROGRAMMING TECHNIQUES Screen 1 of 1 Program modularity and the use of block IF structures are just two of many possibilities for improving the appearance of a program. Following are some additional suggestions for programming style: Use comments liberally throughout the program. Comments are especially desirable before each major step of a program and wherever the program does something that is not obvious. Indent IF blocks and the bodies of DO loops by at least two spaces. Use blanks to set off the components of a statement. For example, IF(A.EQ.B.OR.A.EQ.C)GOTO25 should be written, IF (A .EQ. B .OR. A .EQ. C) GO TO 25 Arrange statement labels in numerical order. Use labels of different sizes for FORMAT statements and executable statements; for example, 3-digit labels for executable statements and 5-digit labels for FORMAT statements. Press RETURN to return to the Programming Techniques menu. \c,---------------------------------------------------------------------------- \s,db_ec \u,db_e \p,db_e \c,---------------------------------------------------------------------------- \m=a,db_eca \m=b,db_ecb \m=c,db_ecc \m=d,db_ecd \m=e,db_ece \m=f,db_ecf \m=g,db_ecg \m=h,db_ech \m=i,db_eci \m=j,db_ecj \m=k,db_eck \c,---------------------------------------------------------------------------- \i,compile time debugging \i,controlling compiler output \i,compiler output \i,output \i,error messages \i,examining error messages \c,---------------------------------------------------------------------------- FNT5UG COMPILE-TIME DEBUGGING Screen 1 of 1 Compile-time debugging is basically self-evident. Compiler-produced diagnostics, along with the explanations given in the FORTRAN 5 reference manual, should provide enough information to enable you to correct most compile-time errors. However, there are some problems that can arise during compilation, notably the unintentional production of a large volume of output. The following topics describe some techniques for controlling the output that is displayed at the terminal and for examining error messages. Enter one of the following letters to learn more about compile-time debugging: a. Compiling and Executing g. Writing Error Messages to a as a Single Step Separate File b. Rewinding the Input File h. Selecting Error Level c. Quick Syntax Check i. Detecting Non-ANSI Usage d. Supressing Output Listing j. Producting a Cross-Reference e. Selecting Compiler Output Options Listing f. Displaying Compiler Output k. Listing Control Directives Press RETURN to read about Compiling and Executing as a Single Step. Enter UP to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,db_eca \u,db_ec \c,---------------------------------------------------------------------------- \i,compiling and executing as a single job step \i,go parameter \i,go \c,---------------------------------------------------------------------------- FTN5UG COMPILING AND EXECUTING AS A SINGLE JOB STEP Screen 1 of 1 While debugging interactively, it is often convenient to specify a GO parameter on each FTN5 control statement. If the program compiles successfully, the GO parameter causes execution to begin; if fatal compilation errors occur, execution does not begin. The GO parameter precludes the necessity of entering separate FTN5 and LGO statements each time you compile and execute. Press RETURN to read about Rewinding the Compiler Input File. \c,---------------------------------------------------------------------------- \s,db_ecb \u,db_ec \c,---------------------------------------------------------------------------- \i,rewinding the compiler input file \i,compiler input file \i,input file \i,rewind input file \i,rewind \i,repositioning the input file \i,i option of rew parameter \i,rew parameter \i,rew \c,---------------------------------------------------------------------------- FTN5UG REWINDING THE COMPILER INPUT FILE Screen 1 of 1 Many operations you will perform on the file containing the FORTRAN source program leave the file at the current position, rather than repositioning it at the beginning-of-information. If you attempt to compile a file that is not positioned at the beginning-of-information, the compilation will not be successful. To ensure that the compiler input file is always rewound, you can specify the I option for the REW parameter on the FTN5 control statement. If the file is not already rewound, the REW parameter rewinds it. For example: FTN5,I=COMP,REW=I. rewinds file COMP and then compiles it. Other options for the REW parameter allow you to rewind the various output files written by the compiler. (See the FORTRAN 5 reference manual.) Press RETURN to read about Quick Syntax Check. \c,---------------------------------------------------------------------------- \s,db_ecc \u,db_ec \c,---------------------------------------------------------------------------- \i,quick syntax check \i,syntax check \i,syntax \i,qc parameter \i,qc \i,qc compilation \i,qc mode \c,---------------------------------------------------------------------------- FTN5UG QUICK SYNTAX CHECK Screen 1 of 1 You can cause the compiler to perform a quick syntax check of a program by specifying the QC parameter on the FTN5 control statement. When you specify the QC parameter, the compiler performs a full syntactic scan of your program but does not produce any object code. QC compilation is significantly faster than normal compilation. This option is recommended for compiling a new program, especially if it is large, because compilation errors that preclude execution are likely to occur, and several compilations are often necessary to eliminate all the errors. Of course, you cannot execute a program after compiling it in QC mode. Press RETURN to read about Suppressing the Compiler Output Listing. \c,---------------------------------------------------------------------------- \s,db_ecd \u,db_ec \c,---------------------------------------------------------------------------- \i,suppressing compiler output listing \i,suppressing compiler output \i,suppressing output \i,suppressing listing \i,l parameter \i,l \i,compiler output listing \i,output listing \i,l=0 \i,l=filename \i,listing to a separate file \i,output to a file \i,compiler output to a file \c,---------------------------------------------------------------------------- FTN5UG SUPPRESSING THE COMPILER OUTPUT LISTING Screen 1 of 1 If the L parameter is omitted from the FTN5 control statement, the complete compiler output listing, including error messages, is displayed at the terminal. This listing usually contains a large amount of information, even for smaller programs. The L parameter allows you to suppress this listing. A specification of L=0 suppresses the output source listing and all other compiler-produced information, except for error messages. Any erroneous statements, along with the error message, are still displayed at the terminal. Alternatively, you can cause the compiler listing to be written to a separate file by specifying L=filename. The specified file contains all compiler-produced information, including the source listing, diagnostics, statistics, and cross-reference listing. You can display this file at the terminal, route it to a printer, or make it permanent. Because of the volume of output produced by most compilations, either L=0 or L=filename is recommended when compiling interactively. Press RETURN to read about Selecting Compiler Output Options. \c,---------------------------------------------------------------------------- \s,db_ece \u,db_ec \c,---------------------------------------------------------------------------- \i,selecting compiler output options \i,compiler output options \i,output options \i,compiler output \i,lo parameter \i,lo \i,source listing \i,cross-reference map,1 \i,attributes,1 \i,st{orage map \i,object listing \c,---------------------------------------------------------------------------- FTN5UG SELECTING COMPILER OUTPUT OPTIONS Screen 1 of 3 Information appearing on the compiler output listing can be helpful in detecting programming errors. The various types of information are controlled by the LO parameter on the FTN5 control statement. The options you can select are: S Source listing R Cross-reference map A List of variables and their attributes M Storage map O Object listing Multiple selections are separated by slashes as in the following example: FTN5,LO=S/R/A. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \c,---------------------------------------------------------------------------- FTN5UG SELECTING COMPILER OUTPUT OPTIONS Screen 2 of 3 If you omit the LO parameter, the effect is the same as the specification LO=S/A; a source listing and attributes list are displayed. Furthermore, regardless of which LO options you select (except for LO=0) S and A are always automatically selected. Thus, for example, LO=R implies LO=S/A/R. For most programs, this results in a large amount of compiler output. In situations where a large volume of compiler output is expected, you can send the output to a separate file (using the L parameter). However, you can reduce the amount of output displayed by suppressing any of the various types. You suppress an output type by preceding the option specification by a hyphen (-). For example, you might want to display the source listing only, while suppressing the attributes list. This is accomplished with the control statement: FTN5,LO=S/-A. This particular specification is especially useful because the attributes list often contains a large amount of information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \c,---------------------------------------------------------------------------- \i,c$ list directive,1 \i,c$,1 \i,c$ directive,1 \c,---------------------------------------------------------------------------- FTN5UG SELECTING COMPILER OUTPUT OPTIONS Screen 3 of 3 A specification of LO=0/opt/opt... suppresses the default S/A options and selects the specified options. You can further reduce the size of the output listing by using C$ LIST directives. (Enter LCD? if you wish to read about the C$ LIST directives at this time.) Press RETURN to read about Displaying Compiler Output at the Terminal. \c,---------------------------------------------------------------------------- \s,db_ecf \u,db_ec \c,---------------------------------------------------------------------------- \i,displaying compiler output at terminal \i,pw parameter \i,page width parameter \i,page width \c,---------------------------------------------------------------------------- FTN5UG DISPLAYING COMPILER OUTPUT AT THE TERMINAL Screen 1 of 1 By default, information written to the file specified by the L parameter is formatted for a printer with a page width of 136 characters. If you anticipate displaying this file at the terminal, you can cause the file to be formatted for the smaller screen width by specifying the PW (Page Width) parameter on the FTN5 control statement. For example, if a terminal has a screen width of 80 characters, then the suggested specification is: PW=80 so that the compiler formats the output file for a maximum page width of 80 characters. If the compiler output is sent directly to the terminal (L=OUTPUT), PW defaults to the terminal screen width. Press RETURN to read about Writing Error Messages to a Separate File. \c,---------------------------------------------------------------------------- \s,db_ecg \u,db_ec \c,---------------------------------------------------------------------------- \i,error messages to separate file \i,e parameter \i,e \i,e=filename \c,---------------------------------------------------------------------------- FTN5UG WRITING ERROR MESSAGES TO A SEPARATE FILE Screen 1 of 3 If you anticipate that your program will produce a large number of compiler diagnostics, you can direct the compiler to write all error messages to a separate file by specifying the E parameter on the FTN5 control statement. This parameter has the form E=filename. The E parameter does not suppress error messages at the terminal, however. To prevent the error messages from appearing at the terminal, you must specify L=0 along with E=filename. Normally, a specification of L=0 suppresses all output except error messages. However, if L=0 is specified together with E=filename, no compiler error messages are displayed at the terminal; only the number of each level of errors is displayed. For example, the statement: FTN5,I=PROG,E=ERRF,L=0. compiles the program on file PROG and writes error messages, if any, to file ERRF. A display similar to the following appears at the terminal (all other output is suppressed): 5 TRIVIAL ERRORS IN PROG 2 FATAL ERRORS IN PROG Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \c,---------------------------------------------------------------------------- FTN5UG WRITING ERROR MESSAGES TO A SEPARATE FILE Screen 2 of 3 The file produced by the E parameter is a local file; you can send it to a printer, display it at the terminal, or make it permanent. A suggested method of examining this file is to use a text editor, such as XEDIT, to display successive levels of errors. For example, knowing that all fatal error messages are prefixed by the string FATAL, you can use the XEDIT command: L/FATAL/* to locate and display all fatal error messages in the file. The command: L/TRIVIAL/* locates all trivial error messages. Proceeding in this manner, you can conveniently display the various levels of errors at the terminal. Enter XEDIT? for a discussion of XEDIT. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \c,---------------------------------------------------------------------------- FTN5UG WRITING ERROR MESSAGES TO A SEPARATE FILE Screen 3 of 3 Alternatively, if you expect that a long program will generate few compiler diagnostics, you can use the E and L parameters to display error messages while suppressing the output listing. The specifications E=OUTPUT and L=0 together direct the compiler to send all error messages to file OUTPUT (terminal display) and to suppress all other output. Press RETURN to read about Selecting Error Level. \c,---------------------------------------------------------------------------- \s,db_ech \u,db_ec \c,---------------------------------------------------------------------------- \i,selecting error level \i,error level \i,severity level of errors \i,error severity level \i,el parameter \i,error level parameter \c,---------------------------------------------------------------------------- FTN5UG SELECTING ERROR LEVEL Screen 1 of 1 You can select the severity level of errors to be displayed at the terminal (or written to an output file) by specifying the EL (error level) parameter on the FTN5 control statement. This option can help reduce the volume of output displayed at the terminal when a program generates a large number of error messages. If you anticipate that your program contains a large number of errors, a suggested procedure is to make a separate compilation run for each error level, starting with the highest level (fatal). When following this procedure, you should specify the QC parameter for fastest compilation. Press RETURN to read about Detecting Non-ANSI Usages. \c,---------------------------------------------------------------------------- \s,db_eci \u,db_ec \c,---------------------------------------------------------------------------- \i,detecting non-ansi usages \i,american national standards institute \i,ansi \i,cdc extension \i,non-ansi use \i,ansi parameter \i,ansi=t \i,ansi=f \c,---------------------------------------------------------------------------- FTN5UG DETECTING NON-ANSI USAGES Screen 1 of 1 The American National Standards Institute (ANSI) has established a set of standards for the implementation of the FORTRAN language. FORTRAN 5 consists of those features and constructs set forth in the ANSI standards and, in addition, certain features that are unique to CDC. The CDC exten- sions to ANSI standard FORTRAN provide many useful capabilities; however, a program that uses these extensions can be run only in a CDC environment. Therefore, if you anticipate that a program will be run on a non-CDC system, you should avoid using CDC extensions in the program. You can cause the compiler to diagnose all non-ANSI usages in a program by specifying the ANSI parameter on the FTN5 control statement. Specifying ANSI=T causes an informative message to be displayed or written when a non-ANSI usage is detected. Specifying ANSI=F causes non-ANSI usages to be treated as fatal errors (a nonexecutable binary file is produced). Press RETURN to read about Producing a Cross-Reference Listing. \c,---------------------------------------------------------------------------- \s,db_ecj \u,db_ec \c,---------------------------------------------------------------------------- \i,producing a cross-reference listing \i,cross-reference listing \i,cross-reference \i,lo=r \i,lo parameter \i,lo \c,---------------------------------------------------------------------------- FTN5UG PRODUCING A CROSS-REFERENCE LISTING Screen 1 of 1 You can obtain a cross-reference listing by specifying the LO=R parameter on the FTN5 control statement. This listing contains information that is helpful in detecting many programming errors. Refer to the FORTRAN reference manual for a detailed description of the cross-reference listing. The cross-reference listing generally contains a large amount of information, even for smaller programs. Therefore, when selecting this option, you should specify a compiler output file with the L parameter, so that a large amount of output is not displayed at the terminal. You can route this file to a printer or display portions of it at the terminal. Press RETURN to read about the Listing Control Directives. \c,---------------------------------------------------------------------------- \s,db_eck \u,db_ec \c,---------------------------------------------------------------------------- \i,lcd \i,listing control directives \i,c$ directives \i,c$ \i,enable listing options \i,disable listing options \c,---------------------------------------------------------------------------- FTN5UG LISTING CONTROL DIRECTIVES Screen 1 of 3 FORTRAN 5 provides special statements, called C$ directives, that allow you to control various aspects of compiler processing. You can include C$ directives in a program along with the FORTRAN 5 source statements. These directives are not executable, however; they provide instructions only to the FORTRAN 5 compiler. The listing control directive allows you to suppress compiler listing options (selected by the LO parameter on the FTN5 control statement) for portions of a program. Only the source listing option (LO=S) is discussed here. Refer to the FORTRAN Version 5 reference manual for more information on listing control and other C$ directives. The listing control directive acts as a switch that allows you to enable or disable a listing option that you have initially selected with the LO parameter. The listing control directive has the form: C$ LIST(S=c) where c is a constant or symbolic constant (defined by a PARAMETER statement) having the value 0 or 1. C$ must appear in columns 1 and 2, and LIST must begin in column 7. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \c,---------------------------------------------------------------------------- FTN5UG LISTING CONTROL DIRECTIVES Screen 2 of 3 When you begin program compilation, the source listing option is initially enabled (unless you have disabled it by specifying LO=0); the compiler lists all statements up to and including the first listing control directive. When the compiler encounters a listing control directive with a value of 0 for c, the source listing option is disabled; subsequent source statements do not appear in the output listing until either the end of the program unit or another listing control directive enabling the listing option is detected. A listing control directive with a value of 1 for c enables the source listing. You can insert a listing control directive anywhere in your program you want to change the status of the listing control switch. Thus, for a given compilation, you can select the portions of your program that will appear in the compiler output listing. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ec \n,db_ec \c,---------------------------------------------------------------------------- \i,example of c$ directives \i,c$ directives example \c,---------------------------------------------------------------------------- FTN5UG LISTING CONTROL DIRECTIVES Screen 3 of 3 For example, the sequence: X = 1.0 C$ LIST(S=0) DO 10 I=1,50 A(I) = 0.0 10 CONTINUE C$ LIST(S=1) Y = 1.0 would appear in the compiler output listing as follows: X = 1.0 C$ LIST(S=0) C$ LIST(S=1) Y = 1.0 Press RETURN to return to the Compile-Time Debugging menu. \c,---------------------------------------------------------------------------- \s,db_ed \u,db_e \p,db_e \c,---------------------------------------------------------------------------- \m=a,db_eda \m=b,db_edb \m=c,db_edc \m=d,db_edd \m=e,db_ede \c,---------------------------------------------------------------------------- \i,cyber interactive debug \i,cid \i,interactive debug \i,interactive debugging \c,---------------------------------------------------------------------------- FTN5UG CYBER INTERACTIVE DEBUG Screen 1 of 1 CYBER Interactive Debug (CID) is a supervisory program that allows you to monitor and control the execution of a FORTRAN program. CID provides features that allow you to: Suspend program execution at specified locations called breakpoints or on the occurrence of specific events, such as the storing of a variable; these events are called traps. Display or alter the contents of program variables. Resume program execution. No special statements are required in the source program to use CID. Enter one of the following letters to learn more about CID: a. Establishing Debug Mode d. Additions Features b. Initiating a Debug Session e. CID Example c. Using Cyber Interactive Debug Press RETURN to read about Establishing Debug Mode. Enter UP to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,db_eda \u,db_ed \c,---------------------------------------------------------------------------- \i,establishing debug mode \i,debug mode \i,debug on \i,debug off \i,debug field length \i,field length \i,cid field length \c,---------------------------------------------------------------------------- FTN5UG ESTABLISHING DEBUG MODE Screen 1 of 1 To use all of the features of CID, you must compile, load, and execute your program in debug mode. Debug mode is established by the control statement: DEBUG Debug mode can be subsequently turned off by the statement: DEBUG(OFF) Compiling a program in debug mode can significantly increase the size of the binary program. Moreover, when the program is loaded in debug mode, the CID program module is loaded into the program's field length; this increases the field length requirement by about 4000 octal words. (The minimum field length for a program using CID is 54000 octal words.) A program that was compiled in debug mode executes in a normal manner when debug mode is turned off. Programs compiled with debug mode off can be executed in debug mode, but they cannot use the symbolic address features of CID. Press RETURN to read about Initiating a Debug Session. \c,---------------------------------------------------------------------------- \s,db_edb \u,db_ed \c,---------------------------------------------------------------------------- \i,initiating a debug session \i,debug session \i,initiate debug \i,initiate cid \c,---------------------------------------------------------------------------- FTN5UG INITIATING A DEBUG SESSION Screen 1 of 1 You initiate a debug session after compiling in debug mode. To initiate a debug session, you must first ensure that debug mode has been turned on. You then enter the name of the binary object file (usually LGO). When debug mode is off, this initiates execution of your program. When debug mode is on, however, control transfers immediately to CID, which displays the message: CYBER INTERACTIVE DEBUG ? The ? character is a prompt signifying that CID is waiting for your input. At this point you can enter CID commands. Typically, at the beginning of a debug session, you will provide for receiving control at some point during execution of your program (by establishing breakpoints or traps), and then enter the command to begin execution of your program. Press RETURN to read about Using Cyber Interactive Debug. \c,---------------------------------------------------------------------------- \s,db_edc \u,db_ed \c,---------------------------------------------------------------------------- \m=a,db_edca \m=b,db_edcb \m=c,db_edcc \m=d,db_edcd \m=e,db_edce \m=f,db_edcf \m=g,db_edcg \m=h,db_edch \c,---------------------------------------------------------------------------- \i,using cyber interactive debug \i,using cid \i,cid usage \i,cyber interactive debug usage \c,---------------------------------------------------------------------------- FTN5UG USING CYBER INTERACTIVE DEBUG Screen 1 of 1 Debugging a FORTRAN program with CID involves the following steps: 1. Activate debug mode with the DEBUG control statement. 2. Compile your program in a normal manner. 3. Enter the name of the binary object file. This initiates the debug session. 4. Provide for suspending program execution by setting traps or breakpoints. 5. Initiate program execution. When a trap or breakpoint is detected, execution is suspended and you receive control. 6. Enter commands to display or alter the values of program variables. 7. Either resume program execution or terminate the session. Enter one of the following letters to learn more about using CID: a. Command Summary e. Altering Program Variables b. Suspending Program Execution f. Terminating a Debug Session c. Initiating Program Execution g. Detecting Execution-Time Errors d. Displaying Program Variables h. Debugging Multiple Program Units Press RETURN to see the Command Summary. Enter UP to return to the CID menu. \c,---------------------------------------------------------------------------- \s,db_edca \u,db_edc \c,---------------------------------------------------------------------------- \i,cid command summary \i,cid commands \c,---------------------------------------------------------------------------- FTN5UG CID COMMAND SUMMARY Screen 1 of 2 A significant feature of CID is that most of its power exists in a few commands. The table on the next screen describes a few of the most important commands that you can use to debug a program. These commands allow you to conduct simple but useful debug sessions. More information on these and other CID commands and features can be found in the CYBER Interactive Debug reference manual and the CYBER Interactive Debug Guide for Users of FORTRAN. (CID allows you to substitute an abbreviated form for many commands; however, only the full command forms are used here. The abbreviated forms are given in the CID reference manual.) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ecd \c,---------------------------------------------------------------------------- \i,set breakpoint \i,set trap \i,set trap store \i,set trap line \i,print* \i,assignment command \i,go \i,quit \i,set home \i,set breakpoint command \i,set trap command \i,set trap store command \i,set trap line command \i,print command \i,assignment command \i,go command \i,quit command \i,set home command \c,---------------------------------------------------------------------------- FTN5UG CID COMMAND SUMMARY Screen 2 of 2 Command Format | Function ------------------------|----------------------------------------------------- SET,BREAKPOINT,L.n | Sets a breakpoint at the specified line | SET,TRAP,STORE,variable | Sets a STORE trap for the specified variable | SET,TRAP,LINE,P.prog | Sets a LINE trap in the specified program unit | PRINT*,list | Prints the listed variables | variable=expression | Evaluates the expression and stores the | result in the specified variable | GO | Initiates or resumes program execution | QUIT | Terminates the debug session | SET,HOME,P.prog | Changes the home program to the specified | program unit ------------------------|---------------------------------------------------- Press RETURN to read about Suspending Program Execution. \c,---------------------------------------------------------------------------- \s,db_edcb \u,db_edc \c,---------------------------------------------------------------------------- \m=a,db_edcba \m=b,db_edcbb \c,---------------------------------------------------------------------------- \i,suspending program execution \i,suspending execution \c,---------------------------------------------------------------------------- FTN5UG SUSPENDING PROGRAM EXECUTION Screen 1 of 1 CID provides two features that allow you to gain control during execution of your program: traps and breakpoints. You will typically establish traps or breakpoints as the first step in a debug session, after initiating the session. In most cases, breakpoints are the most useful means of suspending execution; traps are useful in a limited number of situations. Enter one of the following letters to learn more about breakpoints and traps: a. Breakpoints b. Traps Press RETURN to read about Breakpoints. Enter UP to return to the Using Cyber Interactive Debug menu. \c,---------------------------------------------------------------------------- \s,db_edcba \u,db_edcb \c,---------------------------------------------------------------------------- \i,breakpoints \i,establish a breakpoint \i,set a breakpoint \i,set breakpoint \i,set breakpoint command \c,---------------------------------------------------------------------------- FTN5UG BREAKPOINTS Screen 1 of 2 A breakpoint is a location within a program where execution is to be suspended. The format of the command to establish a breakpoint is: SET,BREAKPOINT,L.n For sequenced programs, n is the sequence number of the statement where the breakpoint is to be established. For nonsequenced programs, n is the number appearing on the compiler-generated source listing. When a breakpoint is reached in the flow of execution, CID displays a message and prompt of the form: \*B #m at L.n ? and gives control to you before the line has been executed; m is a breakpoint number assigned by CID and L.n is the line number where the breakpoint is located. At this point you can enter any CID command. Typically you will display or alter program variables before resuming execution. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edcb \c,---------------------------------------------------------------------------- \i,delete a breakpoint \i,clear a breakpoint \i,remove a breakpoint \i,clear breakpoint command \i,clear breakpoint \c,---------------------------------------------------------------------------- FTN5UG BREAKPOINTS Screen 2 of 2 If you decide you no longer need a breakpoint at a particular location, you can remove it with the command: CLEAR,BREAKPOINT,L.n where n is the number of the FORTRAN line containing the breakpoint. Press RETURN to read about Traps. \c,---------------------------------------------------------------------------- \s,db_edcbb \u,db_edcb \c,---------------------------------------------------------------------------- \i,traps \i,set a trap \i,establish a trap \i,store trap \i,line trap \i,set trap line command \i,set trap command \i,set trap \c,---------------------------------------------------------------------------- FTN5UG TRAPS Screen 1 of 4 A trap is a CID device that detects the occurrence of a specified event during program execution and transfers control to you. There are several events for which you can establish traps. The two most useful traps to the FORTRAN programmer are the LINE and STORE traps. The command to establish a LINE trap is: SET,TRAP,LINE,P.prog where prog is a program unit name. The LINE trap gives control to you immediately before execution of each FORTRAN statement in the specified program unit. This trap allows you to step through your program one line at a time. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edcb \c,---------------------------------------------------------------------------- \i,delete a trap \i,clear a trap \i,remove a trap \i,clear trap command \i,clear trap \i,clear trap line \i,clar trap line command \c,---------------------------------------------------------------------------- FTN5UG TRAPS Screen 2 of 4 When a LINE trap is in effect, CID displays the following message and prompt immediately before execution of each statement: \*T #m LINE IN L.n ? where m is a trap number assigned by CID and n is the source line where execution is suspended. You can then enter commands to examine or alter the status of the program, or resume program execution. You can remove a LINE trap with the command: CLEAR,TRAP,LINE.P.prog where prog is the program unit containing the LINE trap. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edcb \c,---------------------------------------------------------------------------- \i,store trap \i,set trap store \i,set trap store command \c,---------------------------------------------------------------------------- FTN5UG TRAPS Screen 3 of 4 The command to establish a STORE trap is: SET,TRAP,STORE,variable This trap gives control to you whenever a value is stored into the specified variable. When a STORE trap is set and a value is stored into the specified variable, CID displays the message and prompt: \*T #m STORE IN variable ? You can then enter any CID command. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edcb \n,db_edcb \c,---------------------------------------------------------------------------- \i,delete a trap \i,clear a trap \i,remove a trap \i,clear trap command \i,clear trap \i,clear trap store \i,clear trap store command \c,---------------------------------------------------------------------------- FTN5UG TRAPS Screen 4 of 4 In larger programs, the STORE trap is extremely useful in determining where a particular variable is being changed. For example, assume a program contains a variable A that is passed to many subroutines. You can enter the command: SET,TRAP,STORE,A before the first subroutine is called. Then whenever A is modified in any subroutine, execution suspends and you get control. The trap message indicates the subroutine name and line number where the variable was modified. To remove a STORE trap you no longer need, enter the command: CLEAR,TRAP,STORE,variable Press RETURN to return to the Suspending Program Execution menu. \c,---------------------------------------------------------------------------- \s,db_edcc \u,db_edc \p,db_edc \c,---------------------------------------------------------------------------- \i,initiating program execution \i,go command \i,go \i,resume execution \c,---------------------------------------------------------------------------- FTN5UG INITIATING PROGRAM EXECUTION Screen 1 of 1 To begin execution of your program after initiating a debug session, or to resume execution after suspension because of a trap or breakpoint, enter the command: GO Execution begins at the point of suspension and continues until the next trap or breakpoint is detected or until the program terminates. Press RETURN to read about Displaying Program Variables. \c,---------------------------------------------------------------------------- \s,db_edcd \u,db_edc \c,---------------------------------------------------------------------------- \i,display program variables \i,display variables \i,display values \i,display program values \i,program variables \i,program values \i,values \i,variables \i,print command \i,print \c,---------------------------------------------------------------------------- FTN5UG DISPLAYING PROGRAM VARIABLES Screen 1 of 1 You can display the values of program variables whenever you have control with the command: PRINT*,list where list is a list of variables separated by commas. The PRINT command is identical in form and function to the FORTRAN list-directed PRINT statement. This command displays the current values of the listed variables in the format that is explicitly or implicitly declared in the program. Some examples of valid PRINT commands are as follows: PRINT*,A,B,C PRINT*,'VALUES ARE',X,Y PRINT*,(ARR(I),I=1,10) In each case, CID displays the values of the specified variables as they exist at the time of suspension. Press RETURN to read about Altering Program Variables. \c,---------------------------------------------------------------------------- \s,db_edce \u,db_edc \c,---------------------------------------------------------------------------- \i,altering program variables \i,altering variables \i,altering values \i,altering program values \i,assignment command \i,assignment \i,variable=expression \c,---------------------------------------------------------------------------- FTN5UG ALTERING PROGRAM VARIABLES Screen 1 of 3 You can change the value of any variable used in your program with the assignment command. This command has the form: variable=expression where expression is any valid FORTRAN expression not involving exponentiation or function references. This command is identical in form and function to the FORTRAN assignment statement. The expression on the right of the equals sign is evaluated, and this value replaces the current value of the variable on the left of the equals sign. When program execution is resumed, the new value is used. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edc \c,---------------------------------------------------------------------------- FTN5UG ALTERING PROGRAM VARIABLES Screen 2 of 3 The assignment command is useful because it allows you to make changes to your program as execution proceeds without terminating the debug session and recompiling. For example, assume a program begins as follows: PROGRAM ONE DO 6 I=1,100 6 A=A+1.0 Since the variable A is not initialized, it will contain a meaningless value when the DO loop is complete. This program can be correctly executed in debug mode by entering the following assignment command before initiating execution of the program: A=0.0 When you initiate execution (with the GO command), A will have the value 0.0 and the loop will compute a valid value. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edc \c,---------------------------------------------------------------------------- FTN5UG ALTERING PROGRAM VARIABLES Screen 3 of 3 Any changes you make to a program during a debug session exist only for the duration of that session. When you terminate the session, all changes are lost and the program reverts to its original compiled version, so remember to correct the source program to incorporate changes made while debugging. Press RETURN to read about Terminating a Debug Session. \c,---------------------------------------------------------------------------- \s,db_edcf \u,db_edc \c,---------------------------------------------------------------------------- \i,terminating a debug session \i,terminating debug \i,ending a debug session \i,ending a session \i,quit \i,quit command \c,---------------------------------------------------------------------------- FTN5UG TERMINATING A DEBUG SESSION Screen 1 of 1 You can terminate a debug session any time you have control with the command: QUIT When you enter a QUIT command, CID displays the message: DEBUG TERMINATED and control of your job returns to the operating system which prompts for the next control statement. You cannot reenter the session and resume execution of your program. Note, however, that debug mode remains on until you enter DEBUG(OFF). Press RETURN to read about Detecting Execution-Time Errors. \c,---------------------------------------------------------------------------- \s,db_edcg \u,db_edc \c,---------------------------------------------------------------------------- \i,detecting execution time errors \i,execution errors \i,abort trap \c,---------------------------------------------------------------------------- FTN5UG DETECTING EXECUTION-TIME ERRORS Screen 1 of 1 CID provides a feature, called the ABORT trap, that allows you to get control when a fatal error occurs during program execution. The ABORT trap is always in effect for every debug session; you do not need to enter a command to establish this trap. Whenever an error occurs that would normally cause your program to abort, CID displays the message: \*T #18 ABORT message IN L.n ? where message briefly describes the reason for the abort and n is the line number where the abort occurred. The ABORT trap is useful because it allows you to examine the status of your program as it exists at the precise time of an abort. It is possible to resume execution of the program with a special form of the GO command. Refer to the CYBER Interactive Debug reference manual for more information. Press RETURN to read about Debugging Multiple Program Units. \c,---------------------------------------------------------------------------- \s,db_edch \u,db_edc \c,---------------------------------------------------------------------------- \i,debugging multiple program units \i,multiple program units \i,more that one program unit \i,home program \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING MULTIPLE PROGRAM UNITS Screen 1 of 3 You can use the techniques presented in this section to debug FORTRAN programs containing any number of program units. However, if your program contains more than one program unit, you must be familiar with the home program concept. The problem with multiple program units is that whenever you enter a command, CID must know which program unit you are referring to. For example, if you enter PRINT*,X, CID must know which program unit X belongs to, since X might be defined in more than one program unit. To solve this problem, CID establishes a home program. Whenever you reference a variable or a line number, CID assumes the variable or line number belongs to the home program. The home program established by CID is the program unit where execution is currently suspended. Thus, the initial home program in any debug session is the main program. When execution is suspended by a trap or breakpoint, the home program is the program unit containing that trap or breakpoint. When you subsequently enter a command that references a variable or a line number, CID searches the home program for that variable or line number; if it is not found in the home program, an error results. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edc \c,---------------------------------------------------------------------------- \i,set home command \i,set home \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING MULTIPLE PROGRAM UNITS Screen 2 of 3 As an example, assume a program contains subroutines SUB1 and SUB2, and that SUB1 and SUB2 each contain a variable X and a source line numbered 5. If execution is suspended in SUB1, the commands PRINT*,X and SET,BREAKPOINT,L.5 refer to locations in SUB1. Similarly, if execution is suspended in SUB2, the preceding commands refer to locations in SUB2. In many cases, you will want to specify a variable or line number in a program unit other than the home program designated by CID. For example, if execution is suspended in subroutine SUB1, you might want to set a breakpoint or print a variable in subroutine SUB2. You can do this by first designating a new home program with the command: SET,HOME,P.prog where prog is the program unit to be designated as the home program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_edc \n,db_edc \c,---------------------------------------------------------------------------- FTN5UG DEBUGGING MULTIPLE PROGRAM UNITS Screen 3 of 3 Subsequent commands refer to locations in the new home program. For example, assume a program contains subroutine SUB1 and SUB2 and that execution is suspended in SUB1. The following commands set a breakpoint at line 15 of SUB2 and print the value of the variable X defined in SUB2: ? SET,HOME,P.SUB2 ? SET,BREAKPOINT,L.15 ? PRINT*,X You can enter any number of SET,HOME commands in a debug session. When you enter a GO command, however, execution always resumes at the point of suspension regardless of any previous SET,HOME commands. Thus, in the preceding example, a GO command resumes execution of SUB1 even though SUB2 has been declared the home program. Also, when a trap or breakpoint is detected and execution is suspended, the home program always reverts to the program unit where execution is suspended, regardless of any previous SET,HOME specification. Press RETURN to return to the Using Cyber Interactive Debug menu. \c,---------------------------------------------------------------------------- \s,db_edd \u,db_ed \p,db_ed \c,---------------------------------------------------------------------------- \i,additional features \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL FEATURES Screen 1 of 1 CID provides many additional features, including: A trap to suspend execution when an overlay is loaded. The capability of defining sequences of CID commands to be executed automatically on the occurrence of a trap or breakpoint. The capability of saving trap and breakpoint definitions on a separate file. The capability of suspending a debug session, returning control to the operating system, and later resuming the debug session. Refer to the CYBER Interactive Debug reference manual or to the CYBER Interactive Debug Guide for Users of FORTRAN 5 for information on these and other CID features. Press RETURN to see the CID Example. \c,---------------------------------------------------------------------------- \s,db_ede \u,db_ed \c,---------------------------------------------------------------------------- \m=a,db_edea \m=b,db_edeb \m=c,db_edec \c,---------------------------------------------------------------------------- \i,cid example \i,example of cid \i,cyber interactive debug example \i,example of cyber interactive debug \c,---------------------------------------------------------------------------- FTN5UG CID EXAMPLE Screen 1 of 1 Enter one of the following letters to see the CID example: a. Sample Program b. Debug Session c. Corrected Program Listing Press RETURN to see the Sample Program. Enter UP to return to the Cyber Interactive Debug menu. \c,---------------------------------------------------------------------------- \s,db_edea \u,db_ede \c,---------------------------------------------------------------------------- \i,sample program \c,---------------------------------------------------------------------------- FTN5UG CID SAMPLE PROGRAM Screen 1 of 2 The program listing on the next screen is used to illustrate CID usage. Subroutine SQROOT calculates the square root of a number by using an iterative process. Input to SQROOT consists of the number and an initial approximation to the square root of the number. SQROOT calculates successive approximations to the square root of the input number until the desired degree of accuracy is reached, and passes the result to the main program. The main program, TEST, calls SQROOT to calculate the square root of 1275.0 with an initial approximation of 50.0. Subroutine SQROOT contains an error; after each iteration, it is necessary to store the current value of the solution, XNEW, in the variable XOLD, so that the current value can be used to calculate a new value. However, when the program was written, the required assignment statement was omitted. Press RETURN to see the sample program. \c,---------------------------------------------------------------------------- \s \u,db_ede \c,---------------------------------------------------------------------------- \i,program test \i,test \c,---------------------------------------------------------------------------- FTN5UG CID SAMPLE PROGRAM Screen 2 of 2 PROGRAM TEST A = 1275.0 GUESS = 50.0 CALL SQROOT (A,GUESS,ROOT) PRINT 50,A,ROOT 50 FORMAT ('SQRT OF ',F8.3,' IS ',F8.3) END SUBROUTINE SQROOT (A,XO,XNEW) ITS = 1 XOLD = XO 2 XNEW = XOLD + 5*(A-XOLD*XOLD)/XOLD IF (ABS(XNEW - XOLD) .LE. .001) RETURN ITS = ITS + 1 IF (ITS .GE. 100) THEN PRINT*, 'SOLUTION HAS NOT CONVERGED IN 100 ITERATIONS' STOP ENDIF GOTO 2 END Press RETURN to see the Sample Debug Session. \c,---------------------------------------------------------------------------- \s,db_edeb \u,db_ede \c,---------------------------------------------------------------------------- \i,sample debug session \c,---------------------------------------------------------------------------- FTN5UG SAMPLE DEBUG SESSION Screen 1 of 3 The debug session following this discussion shows how CID can help find the error in the program shown on the previous screen. To prepare for the debug session, debug mode is turned on and the program is compiled. When execution begins, control transfers immediately to CID. The purpose of the debug session is to suspend execution in subroutine SQROOT after each pass through the loop and to examine the current and previous values of the solution. Before a breakpoint can be set in SQROOT, however, the SET,HOME command must be entered to make SQROOT the home program. This is necessary because execution is currently suspended at the beginning of the main program; if SET,HOME is not entered, the subsequent SET,BREAKPOINT command refers to line 11 in the main program, and not in SQROOT. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ede \c,---------------------------------------------------------------------------- FTN5UG SAMPLE DEBUG SESSION Screen 2 of 3 After the breakpoint is set, execution is initiated. The breakpoint message indicates that execution is suspended at the desired location. The PRINT command prints the desired values, and the GO command resumes execution. Execution continues until the breakpoint is again reached. After two passes through the loop, it is apparent that the solution value is remaining constant rather than converging toward a correct solution. The debug session is then ended. Press RETURN to see the session. \c,---------------------------------------------------------------------------- \s \u,db_ede \c,---------------------------------------------------------------------------- \i,debug session \c,---------------------------------------------------------------------------- FTN5UG SAMPLE DEBUG SESSION Screen 3 of 3 /debug,on DEBUG,ON. /ftn5,i=sqroot,rew,l=0 0.021 CP SECONDS COMPILATION TIME. /lGO CYBER INTERACTIVE DEBUG ? set,home,p.sqroot ? set,breakpoint,L.11 ? go *B #1, AT L.11 ? print*,xold,xnew,its 50. 37.75 2 ? go *B #1, AT L.11 ? print*,xold,xnew,its 50. 37.75 3 ? quit DEBUG TERMINATED Press RETURN to see the Corrected Program Listing. \c,---------------------------------------------------------------------------- \s,db_edec \u,db_ede \c,---------------------------------------------------------------------------- \i,corrected program listing \c,---------------------------------------------------------------------------- FTN5UG CORRECTED PROGRAM LISTING Screen 1 of 2 The following listing shows the corrected version of program TEST. The statement XOLD = XNEW has been inserted after the ENDIF statement. PROGRAM TEST A = 1275.0 GUESS = 50.0 CALL SQROOT (A,GUESS,ROOT) PRINT 50,A,ROOT 50 FORMAT ('SQRT OF ',F8.3,' IS ',F8.3) END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ede \n,db_ede \c,---------------------------------------------------------------------------- FTN5UG CORRECTED PROGRAM LISTING Screen 2 of 2 Continued from previous screen: SUBROUTINE SQROOT (A,XO,XNEW) ITS = 1 XOLD = XO 2 XNEW = XOLD + 5*(A-XOLD*XOLD)/XOLD IF (ABS(XNEW - XOLD) .LE. .001) RETURN ITS = ITS + 1 IF (ITS .GE. 100) THEN PRINT*, 'SOLUTION HAS NOT CONVERGED IN 100 ITERATIONS' STOP ENDIF GOTO 2 END Press RETURN to return to the CID Example menu. \c,---------------------------------------------------------------------------- \s,db_ee \u,db_e \p,db_e \c,---------------------------------------------------------------------------- \m=a,db_eea \m=b,db_eeb \m=c,db_eec \m=d,db_eed \m=e,db_eee \m=f,db_eef \c,---------------------------------------------------------------------------- \i,post mortem dump \i,pmd \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP Screen 1 of 1 Post Mortem Dump (PMD) is a software facility designed to analyze the cause of execution time errors in FORTRAN programs. Although PMD is primarily intended for batch usage, it can be used interactively, and is recommended for use in situations where CYBER Interactive Debug is not available or cannot be used. Enter one of the following letters to learn more about PMD: a. Overview b. Initiating Post Mortem Dump c. Control of Post Mortem Dump d. Post Mortem Dump Subroutines e. Post Mortem Dump Example f. Summary of Post Mortem Dump Usage Press RETURN to read the Overview. Enter UP to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,db_eea \u,db_ee \c,---------------------------------------------------------------------------- \i,post mortem dump overview \i,overview of post mortem dump \i,pmd field length \i,field length \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP OVERVIEW Screen 1 of 3 PMD provides interpreted output in a form which is more easily understood than the octal dump normally output following a fatal error. PMD prints a readable summary of the error condition and the state of the program at the precise time of failure in terms of the names and values of variables used in the program. If a fatal error occurs in a subroutine, PMD traces back through the calling sequence of routines, printing variable names and values in each routine, until the main program is reached. PMD also provides an option that allows you to initiate a dump at selected points in your program. Although PMD requires a special compilation, it requires no modifications to your source program and does not significantly alter the compiler-generated code. PMD does not significantly increase your program's execution time, and only increases the program's field length by approximately 3008 words. PMD can, however, produce a large amount of output for longer programs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,pmd output \i,ouput \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP OVERVIEW Screen 2 of 3 PMD produces output either when a fatal execution error occurs or when the appropriate PMD subroutine is called. Information provided by the dump includes the following (where applicable): Variable names and values at the time of the abort or PMD call Names of all common blocks in the traceback chain Error description or name of PMD routine that caused the dump Routine name and line number where the error occurred, if these can be determined Overlays in memory at the time of the abort or PMD call Status of files used by the program For certain errors, register contents at the time of the abort Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP OVERVIEW Screen 3 of 3 Variable names are listed in alphabetical order and are grouped according to the program unit in which they are defined. Variable values are formatted according to the variable type. Press RETURN to read about Initiating Post Mortem Dump. \c,---------------------------------------------------------------------------- \s,db_eeb \u,db_ee \c,---------------------------------------------------------------------------- \i,initiating post mortem dump \i,initiating pmd \i,db=pmd \c,---------------------------------------------------------------------------- FTN5UG INITIATING POST MORTEM DUMP Screen 1 of 1 To use PMD, you must compile your program with DB=PMD specified on the FTN5 control statement. PMD output will be produced if a fatal error occurs during execution of the program. In addition, calls to any of the PMD subroutines can be included in the program. Press RETURN to read about Control of Post Mortem Dump. \c,---------------------------------------------------------------------------- \s,db_eec \u,db_ee \c,---------------------------------------------------------------------------- \i,control of post mortem dump \i,control of pmd \i,pmd options \i,*op=opt \i,op parameter \i,op=t \i,condensed dump \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 1 of 9 PMD provides several options to control the destination and content of the dump. These options are specified by a parameter of the form *OP=opt on the execution control statement (typically LGO). You can direct PMD to either display output at the terminal or write it to a separate file. To cause PMD output to appear at the terminal, you must initiate execution of your program with the following form of the execution control statement: LGO,*OP=T. The parameter *OP=T causes a condensed form of the dump to appear at the terminal. If you omit this parameter, a full form of the dump is written to a local file named PMDUMP. In most cases, it is more convenient to have the output displayed at the terminal. However, if you expect PMD to produce a large amount of output, you should allow the output to be written to file PMDUMP. You can then list this file at the terminal or route it to a batch printer. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,op=a \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 2 of 9 Normally, the dump displays only those variable names and values defined in the routine where the fatal error occurred and in all routines in the traceback chain. However, PMD provides an option that causes variables in all other previously called routines to be displayed as well. This option is specified on the execution control statement, as follows: LGO,*OP=A. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 3 of 9 The following program illustrates the function of the A option: PROGRAM MAIN In this example, the main program calls : subroutines SUB1 and SUB2. Subroutine CALL SUB2 SUB1 calls subroutine SUB3. If a fatal CALL SUB1 error occurs in SUB3, the PMD output : includes variables in subroutine SUB3 and END SUB1 as well as in the main program. In SUBROUTINE SUB1 addition, if the A option is specified on CALL SUB3 the execution control statement, the variables : in SUB2 are printed. END SUBROUTINE SUB2 : RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,pmd example \i,example of pmd \i,post mortem dump example \i,example of post mortem dump \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 4 of 9 You can specify multiple options on the execution control statement. For example, the statement: LGO,*OP=AT. displays a condensed dump at the terminal. The dump includes common blocks and variable names and values in all previously called routines. The sample program on the next screen illustrates PMD error detection. The program consists of a main routine and four subroutines. Subroutine SUB4 contains an error: the statement A/(A-B), with both A and B equal to 1.0, causes a division by zero. The terminal dialog to compile and execute the program and the PMD output produced during execution is shown following the listing. Press RETURN see the program listing for TESTPMD. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,program testpmd \i,testpmd \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 5 of 9 PROGRAM TESTPMD A = 1.0 B = 2.0 CALL SUB1 (A,B,C1) CALL SUB2 (A,B,C2) CALL SUB3 (A,B,C3) END SUBROUTINE SUB1 (R,S,T) T = R + S - 3.0 RETURN END SUBROUTINE SUB2 (R,S,T) T = R + S - 3.0 RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 6 of 9 Listing for TESTPMD (continued): SUBROUTINE SUB3 (R,S,T) R = R + 1.0 S = S + 1.0 CALL SUB5 (R,S,T) RETURN END SUBROUTINE SUB4 (X,Y,Z) Z = X**2 + Y**2 A = 1.0 B = 1.0 C = A/(A-B) D = C + 1.0 RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,pmd output \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 7 of 9 The PMD output produced during execution is shown below. The program, assumed to reside on file TESTPMD, is compiled with the PMD option selected. The LGO statement initiates execution; the T option causes the subsequent dump to be formatted for terminal display. The dump is generated when the result of a division by zero is used, causing an overflow. /ftn5,i=testpmd,db=pmd,l=o 0.031 CP SECONDS COMPILATION TIME. /lgo,*op=t /// EXECUTION WAS TERMINATED BECAUSE YOUR <-- Brief description of the PROGRAM FAILED WITH ERROR CONDITION OVERFLOW error. /// THE ERROR OCCURRED IN SUBROUTINE SUB4 <-- Routine name and line -ABOUT 2 WORDS AFTER LINE 5 number where error ocurred. (2 WORDS BEFORE LINE 6) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 8 of 9 PMD output (continued): ... VARIABLES IN SUBROUTINE SUB4 <-- Variable names and values for all A 1.0 routines in the traceback chain. B 1.0 Note that variables are listed C POSITIVE INFINITE <---| alphabetically and are grouped D NOT INITIALIZED | according to the routine in which they X 2.0 | are defined. The most recently called Y 3.0 | routine is listed first. Z 13. | |------ The variable C contains a positive ... CALLED FROM LINE NUMBER 4 infinite value because the computation OF SUBROUTINE SUB3 <---------| to calculate a value for C yielded an | infinite result. The variable D was ... VARIABLES IN SUBROUTINE SUB3 | not initialized because the program R 2.0 | terminated before a value could be S 3.0 | stored in D. T 13. | |-- Routine name and line number from which the listed routine was called. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG CONTROL OF POST MORTEM DUMP Screen 9 of 9 PMD output (continued): ... CALLED FROM LINE NUMBER 6 OF PROGRAM TESTPMD ... VARIABLES IN PROGRAM TESTPMD A 2.0 B 3.0 C1 0. C2 0. C3 13 ... TRACEBACK SUCCESSFULLY COMPLETED Press RETURN to read about Post Mortem Dump Subroutines \c,---------------------------------------------------------------------------- \s,db_eed \u,db_ee \c,---------------------------------------------------------------------------- \m=a,db_eeda \m=b,db_eedb \m=c,db_eedc \m=d,db_eedd \c,---------------------------------------------------------------------------- \i,post mortem dump subroutines \i,pmd subroutines \i,db=pmd \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP SUBROUTINES Screen 1 of 1 Post Mortem Dump provides an optional set of user-callable subroutines that allows you to control various aspects of Post Mortem Dump operation. You must specify DB=PMD on the FTN5 control statement in order to use any of these routines. Enter one of the following letters to learn more about the Post Mortem Dump subroutines: a. PMDARRY - Specifies the size of arrays to be dumped. b. PMDLOAD - Initiates dump of variables in calling routine. Execution continues after the call. c. PMDSTOP - Initiates dump of variables in calling routine and traceback chain. Execution terminates after call. d. PMDDUMP - Causes variables in calling routine to be included in dump. Press RETURN to read about PMDARRY. Enter UP to return to the Post Mortem Dump menu. \c,---------------------------------------------------------------------------- \s,db_eeda \u,db_eed \c,---------------------------------------------------------------------------- \i,pmdarray \i,pmdarray subroutine \i,subroutine pmdarray \i,call pmdarray \i,array elements \i,array,1 \c,---------------------------------------------------------------------------- FTN5UG PMDARRY Screen 1 of 4 Subroutine PMDARRY is used to control the number of array elements printed for all arrays in a program. The subroutine call is especially useful for programs that contain large arrays. The format of the call to PMDARRY is: CALL PMDARRY(i,j,k,l,m,n,o) where i through o determine the number of array elements to be printed in the dump produced by PMD; one to seven arguments can be specified. Each argument represents an array dimension: the first argument represents the first dimension, the second argument represents the second dimension, and so forth. Each argument establishes a limit on the array subscript corresponding to the represented dimension. When an array is dumped following a call to PMDARRY, only elements whose subscripts do not exceed the specified limits are printed. In addition, arrays where the number of dimensions exceeds the number of arguments passed to PMDARRY are not dumped at all. Thus, PMDARRY provides a method of either reducing or increasing the number of array elements dumped. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eed \c,---------------------------------------------------------------------------- FTN5UG PMDARRY Screen 2 of 4 The following sequence illustrates the use of PMDARRY: DIMENSION RAYA(10,10,10), RAYB(100), +RAYC(10,10,5,5,5) . . . CALL PMDARRY (3,4,1) The following 12 words of RAYA will be printed: (1,1,1),(2,1,1) (3,1,1) (1,2,1) (2,2,1) (3,2,1) (1,3,1) (2,3,1) (3,3,1) (1,4,1) (2,4,1) (3,4,1) Words (1), (2), and (3) of array RAYB will be printed, and no words of RAYC will be printed. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eed \c,---------------------------------------------------------------------------- FTN5UG PMDARRY Screen 3 of 4 If you do not include a call to PMDARRY in your program, the effect is the same as if you had included the following call: CALL PMDARRY (20,2,1,1,1,1,1) Thus, the default condition is to dump all arrays (1 through 7 dimensions) but to dump only array elements with subscripts not exceeding (20,2,1,1,1,1,1). You can include any number of calls to PMDARRY in your program. Each call overrides a previous call. Once PMDARRY has been called, the established limits apply to all program units in the program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_eed \c,---------------------------------------------------------------------------- FTN5UG PMDARRY Screen 4 of 4 An alternate method of controlling the number of array elements to be dumped is provided by a special form of the LGO statement. This method allows you to specify different limits for different executions without the need for replacing the PMDARRY calls in the source program and recompiling. The LGO option to specify array limits has the form: LGO,*DA=i+j+k+l+m+n+o. where i through o are as described for the PMDARRY call. The specified limits are passed to the program at execution time and override any PMDARRY calls in the program. Press RETURN to read about PMDLOAD. \c,---------------------------------------------------------------------------- \s,db_eedb \u,db_eed \c,---------------------------------------------------------------------------- \i,pmdload \i,pmdload subroutine \i,subroutine pmdload \i,initiate a dump \i,call pmdload \c,---------------------------------------------------------------------------- FTN5UG PMDLOAD Screen 1 of 1 Normally, PMD produces a dump when a fatal execution error occurs. If no errors occur, no dump is produced. However, you can initiate a dump at selected points in your program by inserting a call to subroutine PMDLOAD wherever you want the dump to occur. When PMDLOAD is called, PMD immediately produces a dump of all variables in the calling program and, if PMDLOAD is called from a subroutine, in all routines in the traceback chain. The dump lists the value of each variable as it exists at the time of the call. After the call to PMDLOAD is complete, your program continues to execute normally. The format of the call to PMDLOAD is: CALL PMDLOAD Note that PMD provides a dump either when PMDLOAD is called or when a fatal error occurs. PMDLOAD can be called up to 10 times; the 10th call is treated as a call to PMDSTOP. Press RETURN to read about PMDSTOP. \c,---------------------------------------------------------------------------- \s,db_eedc \u,db_eed \c,---------------------------------------------------------------------------- \i,pmdstop \i,pmdstop subroutine \i,subroutine pmdstop \i,call pmdstop \c,---------------------------------------------------------------------------- FTN5UG PMDSTOP Screen 1 of 1 Subroutine PMDSTOP causes an immediate dump of variables in the calling routine, in the same manner as PMDLOAD. However, execution terminates immediately after the call to PMDSTOP. The format of the call to PMDSTOP is: CALL PMDSTOP Press RETURN to read about PMDDUMP. \c,---------------------------------------------------------------------------- \s,db_eedd \u,db_eed \n,db_eed \c,---------------------------------------------------------------------------- \i,pmddump \i,pmddump subroutine \i,subroutine pmddump \i,call pmddump \c,---------------------------------------------------------------------------- FTN5UG PMDDUMP Screen 1 of 1 Subroutine PMDDUMP is used in conjunction with PMDLOAD and PMDSTOP. When PMDDUMP is called, no action is taken immediately. However, when PMDLOAD or PMDSTOP is subsequently called, PMD produces a dump of variables both in the routine that called PMDLOAD or PMDSTOP and in any routines that have called PMDDUMP. PMDDUMP thus provides a method of concurrently inducing dumps of variables in multiple subroutines. All variables in the dump have values that existed at the time of the call to PMDLOAD. Your program can include up to 10 calls to PMDDUMP; excess calls are ignored. The format of the call to PMDDUMP is: CALL PMDDUMP Press RETURN to return to the Post Mortem Dump Subroutines. \c,---------------------------------------------------------------------------- \s,db_eee \u,db_ee \p,db_ee \c,---------------------------------------------------------------------------- \i,post mortem dump example \i,example of post mortem dump \i,pmd example \i,example of pmd \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 1 of 6 A program containing calls to PMDLOAD and PMDDUMP is shown on the next screen. The program consists of a main routine and four subroutines. The main routine calls subroutines SUB1, SUB2, and SUB3. Subroutine SUB3 calls subroutine SUB4. The main program contains a call to PMDLOAD as the last executable statement so that a dump will occur immediately before the program terminates. Subroutines SUB1, SUB3, and SUB4 each contain a call to PMDDUMP as the first executable statement so that when PMDLOAD is called, variables in these subroutines will appear in the dump. Press RETURN to see the program listing. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- \i,program testpmd \i,testpmd \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 2 of 6 PROGRAM TESTPMD A = 1.0 B = 2.0 CALL SUB1 (A,B,C1) CALL SUB2 (A,B,C2) CALL SUB3 (A,B,C3) CALL PMDLOAD END SUBROUTINE SUB1 (R,S,T) CALL PMDDUMP T = R + S - 3.0 RETURN END SUBROUTINE SUB2 (R,S,T) T = R + S - 3.0 RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 3 of 6 Listing for TESTPMD (continued): SUBROUTINE SUB3 (R,S,T) CALL PMDDUMP R = R + 1.0 S = S + 1.0 CALL SUB5 (R,S,T) RETURN END SUBROUTINE SUB4 (X,Y,Z) CALL PMPDUMP Z = X**2 + Y**2 RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 4 of 6 The the PMD output for the program on the previous two screens is shown below. The dump lists variables and values from subroutines SUB1, SUB3, and SUB4, as well as the main program. The dump does not include variables from SUB2, because that subroutine did not call PMDDUMP. /ftn5,i=testpmd,db=pmd,l=o 0.029 CP SECONDS COMPILATION TIME. /lgo,*op=t /// EXECUTION WAS INTERRUPTED BECAUSE YOUR PROGRAM CALLED *PMDLOAD* AT LINE NUMBER 7 OF PROGRAM TESTPMD ... VARIABLES IN PROGRAM TESTPMD A 2.0 B 3.0 C1 0. C2 0. C3 13 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 5 of 6 PMD output (continued): ... VARIABLES IN SUBROUTINE SUB1 R 2.0 S 3.0 T 0. ... CALLED FROM LINE NUMBER 4 OF PROGRAM TESTPMD ... VARIABLES IN SUBROUTINE SUB3 R 2.0 S 3.0 T 13. ... CALLED FROM LINE NUMBER 6 OF PROGRAM TESTPMD Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \c,---------------------------------------------------------------------------- FTN5UG POST MORTEM DUMP EXAMPLE Screen 6 of 6 PMD output (continued): ... VARIABLES IN SUBROUTINE SUB4 X 2.0 Y 3.0 Z 13. ... CALLED FROM LINE NUMBER 5 OF SUBROUTINE SUB3 Press RETURN to read the Summary of Post Mortem Dump Usage. \c,---------------------------------------------------------------------------- \s,db_eef \u,db_ee \c,---------------------------------------------------------------------------- \i,summary of post mortem dump usage \i,summary of pmd usage \i,pmd summary \i,summary of pmd \i,post mortem dump summary \i,summary of post mortem dump \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF POST MORTEM DUMP USAGE Screen 1 of 2 Following is a summary of the procedures for using Post Mortem Dump: Compile your program with DB=PMD specified on the FTN5 control statement. Initiate execution in a normal manner. If you want the dump to be displayed at the terminal, specify *OP=T on the execution control statement. Otherwise, the dump is written to file PMDUMP. If a fatal execution error occurs, an immediate dump is written. The dump includes an error summary and a list of variable names and values in the routine where the error occurred and in all routines in the traceback chain. To cause a dump at selected points in your program, insert a call to PMDLOAD at the desired points. When PMDLOAD is called, an immediate dump occurs. The dump includes all variables in the calling routine and in all routines in the traceback chain. To include variables in the dump from any other previously called routines, insert a call to PMDDUMP at the desired points. When PMDLOAD is called, routines that have called PMDDUMP are dumped. Program execution continues after the call to PMDLOAD. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ee \n,db_ee \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF POST MORTEM DUMP USAGE Screen 2 of 2 Summary of PMD usage (continued): To cause an immediate dump followed by program termination, insert a call to PMDSTOP at the desired point. When PMDSTOP is called, an immediate dump occurs and execution terminates. The dump lists variable names and values in the calling routine and in all routines in the traceback chain. To include variables from other previously called routines in the dump, insert a call to PMDDUMP in the desired routine. When PMDSTOP is called, any routines that have called PMDDUMP are also dumped. To increase or decrease the number of array elements dumped, insert a call to PMDARRY in your program. (PMDARRY must be called before the dump is initiated.) To cause variables from all previously called routines to be included in the dump (regardless of what causes the dump) initiate execution of your program with the statement: LGO,*OP=A. Press RETURN to return to the Post Mortem Dump menu. \c,---------------------------------------------------------------------------- \s,db_ef \u,db_e \p,db_e \c,---------------------------------------------------------------------------- \m=a,db_efa \m=b,db_efb \m=c,db_efc \c,---------------------------------------------------------------------------- \i,arithmetic mode errors \i,mode errors \i,errors \c,---------------------------------------------------------------------------- FTN5UG ARITHMETIC MODE ERRORS Screen 1 of 1 Arithmetic mode errors occur during program execution when instruction is encountered that cannot be executed. Such instructions usually contain an invalid operand or an improperly formatted instruction. When a mode error occurs, the program aborts and an error message is displayed. Enter one of the following letters to learn more about arithmetic mode errors: a. Mode Errors Summary c. Indefinite Value b. Infinite Value If a mode error occurs while a program is executing under CID control, execution is suspended and CID gives control to you. In most cases, you can determine the cause of the error by examining the values of program variables as they exist at the time of suspension. If a mode error occurs while a program is executing with Post Mortem Dump enabled, the program aborts and a dump occurs. The dump shows the values of program variables and contains a brief explanation of the error and its probable cause. Press RETURN to see the Mode Errors Summary. Enter UP to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,db_efa \u,db_ef \c,---------------------------------------------------------------------------- \i,mode errors summary \i,arithmetic mode error 0 \i,mode error 0 \i,illegal instruction \c,---------------------------------------------------------------------------- FTN5UG MODE ERRORS SUMMARY Screen 1 of 4 The table on this and the following screens lists the mode errors and some possible causes for the errors. Error Number and Message: 0 ILLEGAL INSTRUCTION Explanation: A branch to location zero has occurred or an illegal instruction has been executed. Possible Causes: Machine instructions destroyed by array overflow; mismatch between number of arguments in CALL and SUBROUTINE statements. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ef \c,---------------------------------------------------------------------------- \i,arithmetic mode error 1 \i,mode error 1 \i,cm out of range \c,---------------------------------------------------------------------------- FTN5UG MODE ERRORS SUMMARY Screen 2 of 4 Error Number and Message: 1 CM OUT OF RANGE Explanation: Program has referenced a location outside the user's field length. Possible Causes: Program attempted to fetch or store data outside program field length; probably caused by incorrect subscript. Program attempted to jump to an address outside program field length; probably caused by missing function or subroutine, or misspelled function or subroutine name. Program executed a word that did not contain an instruction; probably due to array overflow. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ef \c,---------------------------------------------------------------------------- \i,arithmetic mode error 2 \i,mode error 2 \i,arithmetic overflow \i,arithmetic mode error 4 \i,mode error 4 \i,arithmetic indefinite,1 \c,---------------------------------------------------------------------------- FTN5UG MODE ERRORS SUMMARY Screen 3 of 4 Error Number and Message: 2 ARITHMETIC OVERFLOW Explanation: Infinite value used as operand. Possible Causes: Nonzero number divided by zero; very large number divided by very small number; very large number multiplied by very large number; numbers very near 10**322 in absolute value added or subtracted; large number raised to a large power; at some installations, undefined value used in a calculation. Error Number and Message: 4 ARITHMETIC INDEFINITE Explanation: Indefinite value used as operand. Possible Causes: Zero divide by zero; zero multiplied by an infinite value; infinite value divided by an infinite value; infinite values added or subtracted; at some installations, undefined value used in a calculation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_ef \c,---------------------------------------------------------------------------- \i,arithmetic mode error 3 \i,mode error 3 \i,arithmetic mode error 5 \i,mode error 5 \i,arithmetic mode error 6 \i,mode error 6 \i,arithmetic mode error 7 \i,mode error 7 \c,---------------------------------------------------------------------------- FTN5UG MODE ERRORS SUMMARY Screen 4 of 4 Error Number: 3 Explanation: Combination of errors 1 and 2. Error Number: 5 Explanation: Combination of errors 1 and 4. Error Number: 6 Explanation: Combination of errors 2 and 4. Error Number: 7 Explanation: Combination of errors 1, 2, and 4. Press RETURN to read about Infinite Values. \c,---------------------------------------------------------------------------- \s,db_efb \u,db_ef \c,---------------------------------------------------------------------------- \i,infinite values \i,positive infinite \i,negative infinite \i,mode error 2 \i,arithmetic mode error 2,1 \c,---------------------------------------------------------------------------- FTN5UG INFINITE VALUES Screen 1 of 1 When the central processor attempts to execute an instruction with an operand containing an infinite value, a mode 2 error occurs. An infinite value results when a number is generated that is larger than the central processor can represent. You can recognize a variable containing an infinite value by displaying it with the appropriate CID command. The values displayed are R (positive infinite) and -R (negative infinite). Press RETURN to read about Indefinite Values. \c,---------------------------------------------------------------------------- \s,db_efc \u,db_ef \n,db_ef \c,---------------------------------------------------------------------------- \i,indefinite values \i,positive indefinite \i,negative indefinite \i,mode error 4 \i,arithmetic mode error 4 \c,---------------------------------------------------------------------------- FTN5UG INDEFINITE VALUES Screen 1 of 1 When the central processor attempts to execute an instruction with an operand containing an indefinite value, a mode 4 error occurs. An indefinite value is generated when a calculation cannot be resolved, such as a division where both dividend and divisor are zero. In some cases, undefined variables are set to an indefinite value. You can recognize a variable containing an indefinite value by displaying it with the appropriate CID command. The value displayed is an installation option; the default values are I (positive indefinite) and -I (negative indefinite). Press RETURN to return to the Arithmetic Mode Errors menu. \c,---------------------------------------------------------------------------- \s,db_eg \u,db_e \p,db_e \c,---------------------------------------------------------------------------- \i,parm \i,condtional compilation \i,compiling conditionally \i,conditional compilation directives \i,compilation directives \i,c$ directives \i,c$ \c,---------------------------------------------------------------------------- FTN5UG CONDITIONAL COMPILATION Screen 1 of 5 In situations where you cannot use CYBER Interactive Debug or Post Mortem Dump to debug a program, you can resort to the traditional debugging method of inserting PRINT statements at various locations within the program to print selected values during execution. Although this method tends to be time-consuming, you can eliminate the necessity of repeatedly inserting and removing these PRINT statements through the use of conditional compilation directives. Conditional compilation directives are C$ directives that cause the compiler to compile selected portions of a program while ignoring other portions. These directives can be inserted anywhere in your program. They provide instructions to the compiler and are not executable. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_e \c,---------------------------------------------------------------------------- \i,if directive \i,else directive \i,endif directive \i,if compilation directive \i,else compilation directive \i,endif compilation directive \i,c$ if \i,c$ endif \i,c$ else \c,---------------------------------------------------------------------------- FTN5UG CONDITIONAL COMPILATION Screen 2 of 5 The conditional compilation directives have the following forms: C$ IF(e) C$ ELSE C$ ENDIF where e is a logical constant expression. This expression is similar to a FORTRAN logical expression, except that all values in the expression must be either constants or symbolic constants (previously defined in a PARAMETER statement). C$ must appear in card image columns 1 and 2, and the directive keyword must begin in column 7. The IF and ENDIF directives must appear in pairs within a program unit, and can be separated by any number of FORTRAN source statements. The statements following an IF directive and preceding the associated ENDIF directive are called a conditional sequence. If the expression in the IF directive is true, the conditional sequence is compiled; if the expression is false, the conditional sequence is ignored by the compiler. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_e \c,---------------------------------------------------------------------------- FTN5UG CONDITIONAL COMPILATION Screen 3 of 5 The following program segment illustrates the IF and ENDIF directives: PARAMETER (M=0) . . A = 1.0 B = 1.0 C$ IF (M .EQ .0) A = A + 1.0 B = B + 1.0 C$ ENDIF C = A + B In this example, the statements A=A+1.0 and B=B+1.0 constitute a conditional sequence. These statements will be compiled since the constant M is defined to be 0, and the logical expression is true. When the program is executed, the final value of C will be 4.0. If the PARAMETER statement is changed to read PARAMETER (M=1), the conditional sequence will not be compiled; the final value of C after execution will be 2.0. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_e \c,---------------------------------------------------------------------------- FTN5UG CONDITIONAL COMPILATION Screen 4 of 5 The ELSE directive can be used to provide an alternative path for an IF/ENDIF pair as follows: C$ IF(e) seq1 C$ ELSE seq2 C$ ENDIF If e is true, conditional sequence seq1 is compiled and conditional sequence seq2 is ignored. If e is false, seq1 is ignored and seq2 is compiled. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,db_e \n,db_e \c,---------------------------------------------------------------------------- \i,parameter statement \i,parameter \c,---------------------------------------------------------------------------- FTN5UG CONDITIONAL COMPILATION Screen 5 of 5 You can use conditional compilation directives in the debugging process to conditionally compile PRINT statements. Using this method, it is not necessary to physically remove these PRINT statements from your program when you are temporarily through with them. By including the appropriate directives and PARAMETER statements in the source program, you can control whether the PRINT statements are included in the executable object program simply by changing a single PARAMETER statement and recompiling. It does no harm to leave the PRINT statements in the source program permanently, since these statements, when not compiled, have no effect on execution time efficiency. Press RETURN to return to the Debugging menu. \c,---------------------------------------------------------------------------- \s,op_f \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,op_fa \m=b,op_fb \m=c,op_fc \c,---------------------------------------------------------------------------- \i,optimization \i,optimizing a program \i,cost reduction \i,reducing cost \i,program cost \i,cost of a program \c,---------------------------------------------------------------------------- FTN5UG OPTIMIZATION Screen 1 of 1 The purpose of optimizing a program is to reduce the cost to the site of executing that program. Because the cost of a program depends on the use of several kinds of system resources, the cost can be reduced by decreasing the use of one or more of these resources. These resources include execution time, central memory field length, and the various resources used in input/output operations. Enter one of the following letters to learn more about optimization: a. Overview b. Reducing Execution Time c. Reducing Memory Use Press RETURN to read the Overview. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,op_fa \u,op_f \c,---------------------------------------------------------------------------- \i,optimization overview \i,overview of optimization \i,resource cost \i,programmer time \c,---------------------------------------------------------------------------- FTN5UG OPTIMIZATION OVERVIEW Screen 1 of 3 Frequently a reduced expenditure of one resource requires an increased expenditure of another. For example, you can reduce the amount of memory required by a program by using overlays, OVCAPs, or segments, but the program's execution time is increased. Conversely, certain optimization techniques, such as loop unrolling decrease execution time at the expense of increased field length. Only the requirements of a particular application can determine whether specific optimizations are worthwhile. A resource cost that you can frequently overlook when considering optimization is programmer time. Program development, debugging, and maintenance often contribute more to the overall cost of a program than the computer resources required to execute it. Therefore, you should be cautious about spending a great deal of time optimizing a program, and about performing optimizations that make the program less comprehensible or maintainable. A recommended practice is to optimize a program only when absolutely necessary and to avoid optimizations that sacrifice clarity. If it is not necessary to reduce a program's execution time or field length, you should concentrate your programming efforts on producing a clear, maintainable, and correct program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_f \c,---------------------------------------------------------------------------- \i,comments \c,---------------------------------------------------------------------------- FTN5UG OPTIMIZATION OVERVIEW Screen 2 of 3 If you do perform optimizations that reduce a program's clarity, you should document the change by inserting appropriate descriptive comments; and always keep in mind that a program that produces correct results is more desirable than an optimized program. Most of the optimizations presented in here involve very simple manipulations of your source code; they are not sophisticated tricks and they do not require a knowledge of COMPASS instructions. Once you learn these optimization techniques, you can apply them at the initial writing of a program, thus precluding any need for rewriting the program at a later time. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_f \c,---------------------------------------------------------------------------- \i,optimization levels \i,opt \i,opt parameter \c,---------------------------------------------------------------------------- FTN5UG OPTIMIZATION OVERVIEW Screen 3 of 3 The FORTRAN compiler has the ability to perform certain optimizations affecting execution time when compiling a program. You can select the level of optimization performed by the compiler by specifying the OPT parameter on the FTN5 control statement. The optimization levels are OPT=0, 1, 2, and 3. (The actual optimizations performed at each level are described in the FORTRAN 5 reference manual.) Little optimization is performed at levels 0 and 1; level 2 optimization can result in a significant decrease in execution time. Level 3 performs the most optimization, but in rare cases, where certain nonstandard features are used, it can lead to potential execution errors. You should not be discouraged from using OPT=3, but you should be aware of the possibility for error. Refer to the FORTRAN 5 reference manual for recommended precautions when compiling under OPT=3. A recommended procedure is to debug your program at OPT=0 to ensure maximum compilation speed. (OPT=0 is required for CYBER Interactive Debug). After your program executes correctly at OPT=0, you can compile under OPT=2 or 3 for maximum optimization. Press RETURN to read about Reducing Execution Time. \c,---------------------------------------------------------------------------- \s,op_fb \u,op_f \c,---------------------------------------------------------------------------- \m=a,op_fba \m=b,op_fbb \m=c,op_fbc \c,---------------------------------------------------------------------------- \i,reducing execution time \i,execution time reduction \i,execution time \i,efficient code \c,---------------------------------------------------------------------------- FTN5UG REDUCING EXECUTION TIME Screen 1 of 1 The most beneficial optimizations you can incorporate into your source program are those which help the compiler perform its own optimizations. With this in mind, the single most important consideration is to keep program units short (less than about 100 lines) and simple, and to avoid complex, intricate logic and practices that depend on system idiosyncrascies. A program that is short and straightforward will result in much more efficient code than one that is not. Enter one of the following letters to learn more about reducing execution time: a. Loop Optimization b. Common and Equivalence Usage c. Additional Optimization Techniques Certain optimizations decrease the readability or maintainability of a program. With this caution in mind, you can decide which of the source code optimizations described here are worthwhile for your application. Press RETURN to read about Loop Optimization. Enter UP to return to the Optimization menu. \c,---------------------------------------------------------------------------- \s,op_fba \u,op_fb \c,---------------------------------------------------------------------------- \m=a,op_fbaa \m=b,op_fbab \m=c,op_fbac \m=d,op_fbad \m=e,op_fbae \m=f,op_fbaf \m=g,op_fbag \c,---------------------------------------------------------------------------- \i,loop optimization \i,loops \i,do loops \i,if loops \c,---------------------------------------------------------------------------- FTN5UG LOOP OPTIMIZATION Screen 1 of 1 When optimizing a program, you should devote most of your time to loops within the program, since most of a program's execution time is taken up in the execution of loops. The primary consideration for all loops is to keep them short and simple in order to maximize the amount of optimization performed by the compiler. This consideration applies to IF loops as well as DO loops. Enter one of the following letters to learn more about loop optimization: a. Invariant Code e. Loop Unrolling b. Common Subexpression Elimination f. Combining Loops c. Constant Evaluation g. IF Loops d. Strength Reduction In the examples appearing in these topics, the symbols R1, R2, and so forth, imply machine registers rather than actual locations in memory. Moving values among registers is much faster. The use of registers, instead of memory, to temporarily store values is an important aspect of compiler-performed optimization. Press RETURN to read about Invariant Code. Enter UP to return to the Reducing Execution Time menu. \c,---------------------------------------------------------------------------- \s,op_fbaa \u,op_fba \c,---------------------------------------------------------------------------- \i,invariant code \i,invariant \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 1 of 11 If the result of the execution of a sequence of instructions within a loop does not depend on any variable whose value changes within the loop, the instructions are said to be invariant. The FORTRAN optimizer removes invariant code from loops whenever possible. For example, in the program segment: DO 100 I=1,10 K(I) = J/L + I**2 100 CONTINUE neither J nor L changes in value during execution of the loop; therefore, J/L is invariant. When this program segment is compiled, the optimizer removes the instructions generated by the invariant code from the loop. After optimization, the loop is equivalent to the following: R1 = J/L DO 100 I=1,N K(I) = R1 + I**2 100 CONTINUE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 2 of 11 Invariant code often extends for several statements, as in the following example: 100 A = P(I) + S/Q Y = X/Z + D I = I + 1 IF(I .LT. 12) GO TO 100 The term S/Q and the statement Y = X/Z + D are invariant. After optimization this sequence is equivalent to: R1 = S/Q Y = X/Z + D 100 A = P(I) + R1 I = I + 1 IF(I .LT. 12) GO TO 100 This example also shows that IF loops are optimized in the same manner as DO loops. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 3 of 11 Invariant code can exist in a form that is not readily apparent in a FORTRAN source program. For example, in the sequence: DIMENSION B(10,10,10) DO 10 I=1,N B(I,7,K) = I 10 CONTINUE the relative locations of elements of array B are calculated by the formula: I - 1 + 10 x (6 + 10 x (K-1)) The value of I is the only value in this expression that changes during execution of the loop. Thus, the following subexpression is invariant: -1 + 10 x ((6 + 10 x (K - 1)) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 4 of 11 The FORTRAN optimizer recognizes the invariant code and moves the instructions out of the loop. Without optimization, the entire calculation would be performed once for each execution of the loop. After optimization, however, the invariant part of the calculation is performed before the loop is entered. The optimizer only moves code out of a loop when it is certain that the code is actually invariant. There are circumstances in which this determination cannot be made at compile time. These circumstances include the following: When a call is made to a subprogram within the loop, and the code being considered for invariancy uses the value of a variable that is either in common or is an actual parameter to the subroutine. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 5 of 11 For example, in the sequence: COMMON X DO 100 I=1,N A(I) = X**2 B(I) = Y/Z CALL MYSUB (Q,R,Z) 100 CONTINUE neither X**2 nor Y/Z can be moved out of the loop, because subroutine MYSUB might change the value of X or Z. However, if the call to MYSUB was: CALL MYSUB (Q,R,Z+2) then the optimizer would move Y/Z out of the loop, since, in this case, it knows that MYSUB cannot change the value of Z. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 6 of 11 The optimizer cannot determine if code is invariant (continued): When a conditional branch within the loop introduces the possibility that the code might never be executed. For example, in the sequence: LOGICAL L DO 100 I=1,N IF(L) GO TO 110 J = K + M 110 A(I) = B(I) + C(I) 100 CONTINUE the expression K + M is invariant and will be moved out of the loop so that it is executed only once, but the store into J must be left in the loop. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 7 of 11 The optimizer cannot determine if code is invariant (continued): When the value of an expression depends on a variable whose value can change in successive iterations of the loop. For example, in the sequence: DO 100 I=1,N J = I + . . . K = J*. . . L = K + . . . M = L/N1 + N2*N3 100 CONTINUE the division L/N1 cannot be moved out of the loop because the value of L ultimately depends on the value of I, which changes each time the loop is executed. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- \i,invariaent subexpressions \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 8 of 11 You can write expressions within loops so that invariant subexpressions are easier for the optimizer to recognize. For example, in the sequence: DO 100 I=1,N A(I) = 1.0 + B(I) + X 100 CONTINUE the optimizer does not recognize 1.0 + X as an invariant expression. However, if the loop is rewritten as follows: DO 100 I=1,N A(I) = 1.0 + X + B(I) 100 CONTINUE the optimizer recognizes 1.0 + X as an invariant expression and moves it out of the loop. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 9 of 11 In cases where the optimizer cannot determine whether a code sequence is invariant, you can sometimes make this determination yourself and rewrite the code accordingly. For example, in the sequence: DO 100 I=1,N B(I) = Y/Z CALL MYSUB (Q,R,Z) 100 CONTINUE the compiler cannot move Y/Z out of the loop because MYSUB might change the value of Z. However, if you know that MYSUB does not change the value of Z, you can move the invariant expression yourself. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 10 of 11 Moving invariant code does not always result in more efficient code. For example, you should not rewrite a program so that it performs its own subscript calculation for a multidimensional array. Thus, the sequence: DIMENSION B(10,10,10) DO 10 I=1,N B(I,7,K) = I 10 CONTINUE should not be rewritten as: DIMENSION B(10,10,10),B1(1000) EQUIVALENCE (B,B1) ITEM = -1 + 10*(6 + 10*(K-1)) DO 10 I=1,N B1(I + ITEMP) = I 10 CONTINUE because the this version is unclear and yields less efficient object code. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- \i,do=ot parameter \i,do=ot \i,c$ directive \i,c$ \c,---------------------------------------------------------------------------- FTN5UG INVARIANT CODE Screen 11 of 11 Moving invariant code sometimes requires the creation of temporary variables to hold the values of subexpressions; you should not place these variables in common or use them as actual parameters, since this causes the compiler to generate unnecessary stores. Another condition influencing the optimizing of DO loops is the treatment of zero trip DO loops. If the terminal conditions of a DO loop are satisfied before the loop is initially entered, the DO loop is not executed. This occurs because the compiler inserts code to test the loop termination conditions at the beginning of the loop. This zero trip DO loop behavior can adversely affect execution speed, especially with the OPT=2, because if a loop might be executed zero times, the compiler cannot move invariant code out of the loop. Also, the initial test requires additional time. However, if you know there are no zero trip DO loops in a program, you can improve execution time either by specifying DO=OT on the FTN5 control statement or by inserting C$ DO(OT=1) directives at appropriate points in the program. Either of these options directs the compiler to omit the initial test and perform full OPT=2 optimizations. Press RETURN to read about Common Subexpression Elimination. \c,---------------------------------------------------------------------------- \s,op_fbab \u,op_fba \c,---------------------------------------------------------------------------- \i,common subexpression elimination \i,subexpression elimination \i,common subexpression \i,subexpression \c,---------------------------------------------------------------------------- FTN5UG COMMON SUBEXPRESSION ELIMINATION Screen 1 of 4 A common subexpression is an expression that occurs more than once in the source code. In unoptimized code, the expression is evaluated each time it occurs. The FORTRAN optimizer, however, tries to save the result of the expression in a register whenever possible and to use that result instead of reevaluating the expression. For example, in the sequence: X = A*B*C S(A*B) = (A*B)/C the optimizer recognizes A*B as a common subexpression occurring three times; in the optimized code, A*B is evaluated once, and the result is used three times. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG COMMON SUBEXPRESSION ELIMINATION Screen 2 of 4 Common subexpression elimination can take place only when all of the following conditions are satisfied: The compiler can recognize the subexpressions as the same expression. The compiler reorders each expression into a standard order and then compares expressions term-by-term. Only expressions that match exactly are recognized. For example, A+B, A+B+C, C+D, and so forth, are recognized as subexpressions of A+B+C+D, but A+C is not recognized. B+A can be matched with A+B, however, because they are rearranged into the same order. When a subexpression contains more than one operator of equal precedence, as in A*B/C, the expression is usually evaluated from left to right. Since the operators are associative, however, the compiler might reorder the operations. You can use parentheses to ensure the desired grouping of subexpressions. For example: X = C*(A*B)/D Y = (A*B)/C ensures that A*B will be recognized as a common subexpression. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG COMMON SUBEXPRESSION ELIMINATION Screen 3 of 4 No code occurs between occurrences of the same expression that might cause it to change in value. The closer together occurrences of the same expression are, the greater the probability that they will be matched. For example, consider the sequence: X = A(2)/B(2) -Q A(I) = 4.5 Z = A(2)/B(2) + 13.4 A(2)/B(2) cannot be matched as a common subexpression because of the possibility that I will be equal to 2 at execution time, changing the value of the expression. In this example, if you are sure that I will not be equal to 2, you should place the assignment to A(I) after the assignment to Z. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG COMMON SUBEXPRESSION ELIMINATION Screen 4 of 4 Keeping these restrictions in mind, you can write expressions so as to maximize the chance that the optimizer will recognize common subexpressions. For example: AA = X*A/Y BB = X*B/Y is not likely to result in subexpression elimination, but the following sequence will do so: AA = A*(X/Y) BB = B*(X/Y) Press RETURN to read about Constant Evaluation. \c,---------------------------------------------------------------------------- \s,op_fbac \u,op_fba \c,---------------------------------------------------------------------------- \i,constant evaluation \i,evaluation of constants \c,---------------------------------------------------------------------------- FTN5UG CONSTANT EVALUATION Screen 1 of 2 At all optimization levels, the compiler attempts to evaluate as many constant subexpressions as possible, so that these subexpressions need not be evaluated at execution time. This results in time savings, since programs are usually executed many more times than they are compiled. For example, when processing the statement: X = 3.5 + 4.0*2 the compiler evaluates the expression and replaces it with the constant 11.5. You can evaluate some constant subexpressions yourself; others improve readability and should remain in the program. This is particularly true when one of the components of the expression is a standard constant, such as pi or e. Because the expressions are evaluated at compile time at minimal expense, it is better to let the compiler evaluate them. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG CONSTANT EVALUATION Screen 2 of 2 You can help the compiler by grouping constant subexpressions within an expression. For example, the compiler will recognize the constant subexpression in the statement: W=X*Y*Z*3.1415926/2.0 but not in the statement: W=X*3.1415926*Y*Z/2.0 Press RETURN to read about Strength Reduction. \c,---------------------------------------------------------------------------- \s,op_fbad \u,op_fba \c,---------------------------------------------------------------------------- \i,strength reduction \c,---------------------------------------------------------------------------- FTN5UG STRENGTH REDUCTION Screen 1 of 5 Strength reduction is the replacement of slower operations by faster operations. In FORTRAN, the relative speeds of the arithmetic operations are (slowest first): ** Exponentiation / Division * Multiplication + - Addition and Subtraction In strength reduction, exponentiations are replaced by multiplications and multiplications are replaced by additions. The FORTRAN compiler performs certain strength reductions in OPT=0 mode. For example, any exponentiation by a small integer constant (less than about 12) is replaced by a series of multiplications. Exponentiation by larger integers results in a call to a library routine which also uses multiplications for exponentiations by any integer up to about 100. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG STRENGTH REDUCTION Screen 2 of 5 Another example is multiplication by 2, which the compiler replaces by addition of the variable to itself. Thus: J = 2*I becomes: J = I + I When you specify OPT=2, the compiler also performs strength reduction in other situations. One such situation occurs when a subscript expression has the following form: n*I+m where n and m are integer constants, and I is a variable that varies only linearly in the loop (such as the control variable). In this case, an addition replaces the multiplication. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG STRENGTH REDUCTION Screen 3 of 5 For example, in the loop: DO 50 I=1,100 B(4*I+3) = 2.5 50 CONTINUE the compiler generates code equivalent to: R1 = 3 DO 50 I=1,100 R1 = R1 + 4 B(R1) = 2.5 50 CONTINUE so that an addition replaces the multiplication. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG STRENGTH REDUCTION Screen 4 of 5 In certain situations, you can apply strength reduction yourself. For example, in the sequence: DO 6 I=1,1000 J = I*5 . . 6 CONTINUE if the control variable I is not used anywhere within the loop, you can rewrite this loop as: DO 6 J=5,5000,5 . . 6 CONTINUE eliminating a multiply and a store, and making the loop much more efficient. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG STRENGTH REDUCTION Screen 5 of 5 Other possibilities exist for simplifying the structure of loops. For example, to index backward through an array you can use a negative indexing parameter to simplify the subscript calculation. Thus, the statement: PRINT*, (B(11-I),I=1,10) can be rewritten as: PRINT*, (B(I),I=10,1,-1) Press RETURN to read about Loop Unrolling. \c,---------------------------------------------------------------------------- \s,op_fbae \u,op_fba \c,---------------------------------------------------------------------------- \i,unroll \i,loop unrolling \i,unrolling loops \c,---------------------------------------------------------------------------- FTN5UG LOOP UNROLLING Screen 1 of 3 You can reduce the amount of time required to execute a DO loop through a technique called loop unrolling. The purpose of loop unrolling is to reduce or eliminate the overhead resulting from incrementing and testing the loop control variable by reducing the number of times the loop is executed, or by replacing the loop with an equivalent straight-line sequence of statements. For example, the loop: DO 100 I=1,4 X(I) = A(I) + B(I) 100 CONTINUE can be completely unrolled as follows: X(1) = A(1) + B(1) X(2) = A(2) + B(2) X(3) = A(3) + B(3) X(4) = A(4) + B(4) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG LOOP UNROLLING Screen 2 of 3 In the example on the previous screen, the loop is completely replaced by a sequence of assignment statements, and the time required to increment and test the control variable and branch to the top of the loop is eliminated. Loop unrolling makes programs longer and more complicated, and is clearly not practical if the number of loop iterations is large. In many cases, however, you can partially unroll the loop. For example, the loop: DO 100 I=1,10000 X(I) = Z(I)**2 100 CONTINUE can be replaced by the loop: DO 100 I=1,10000,2 X(I) = Z(I)**2 X(I+1) = Z(I+1)**2 100 CONTINUE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG LOOP UNROLLING Screen 2 of 3 In the partially unrolled loop, only half as many increment, test, and branch instructions are executed. Another limitation of loop unrolling is that you must know how many times the loop will be executed. For example, if the DO statement is: DO 6 I=1,J unrolling does not produce correct results unless J is an even number (assuming each assignment statement is unrolled into two statements). Press RETURN to read about Combining Loops. \c,---------------------------------------------------------------------------- \s,op_fbaf \u,op_fba \c,---------------------------------------------------------------------------- \i,combining loops \i,loop combining \c,---------------------------------------------------------------------------- FTN5UG COMBINING LOOPS Screen 1 of 2 If adjacent loops are executed the same number of times, you can often combine the loops. As with loop unrolling, combining loops reduces the time required for incrementing, testing, and branching. For example, in the sequence: DO 100 I=1,K A(I) = B(I) + C(I) 100 CONTINUE DO 110 J=1,K E(J) = F(J) + G(J) 110 CONTINUE you can combine the loops into a single loop, thus reducing by half the amount of overhead associated with the loops: DO 100 I=1,K A(I) = B(I) + C(I) E(I) = F(I) + G(I) 100 CONTINUE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \c,---------------------------------------------------------------------------- FTN5UG COMBINING LOOPS Screen 2 of 2 Combining loops not only reduces execution time, but also makes programs shorter and easier to understand. However, the requirement that loops must perform the same number of iterations limits the usefulness of this technique. Press RETURN to read about IF loops. \c,---------------------------------------------------------------------------- \s,op_fbag \u,op_fba \c,---------------------------------------------------------------------------- \i,if loops \c,---------------------------------------------------------------------------- FTN5UG IF LOOPS Screen 1 of 2 The optimizer processes IF loops in much the same manner as DO loops. However, the more closely an IF loop resembles a DO loop, the more kinds of optimizations are performed. (The implication of this is that DO loops should be used wherever possible.) For example, the IF loop: I = 1 100 A(I) = B(I) + C(I) I = I + 1 IF (I .LE. 12) GO TO 100 generates code essentially identical to that generated by the following DO loop: DO 100 I=1,12 A(I) = B(I) + C(I) 100 CONTINUE and all of the same optimizations are performed. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fba \n,op_fba \c,---------------------------------------------------------------------------- FTN5UG IF LOOPS Screen 2 of 2 However, if the IF loop is changed to the following equivalent form: I = 1 100 A(I) = B(I) + C(I) I = I + 1 IF (I+5 .LE. 17) GO TO 100 the compiler cannot perform certain optimizations. Press RETURN to return to the Loop Optimization menu. \c,---------------------------------------------------------------------------- \s,op_fbb \u,op_fb \p,op_fb \c,---------------------------------------------------------------------------- \i,common and equivalence usage \i,common usage \i,equivalence usage \i,common \i,equivalence \i,usage of common \i,usage of equivalence \c,---------------------------------------------------------------------------- FTN5UG COMMON AND EQUIVALENCE USAGE Screen 1 of 2 A primary consideration in helping the compiler to optimize is to avoid the unnecessary use of common blocks and equivalence classes. With variables in common, every subroutine or function reference requires the compiler to store the variable before the reference, because the compiler cannot determine whether the variable is used in the referenced subprogram. (The value would normally remain in a register.) You should particularly avoid the practice of allocating local scratch variables in unused portions of common blocks to save space, because this increases execution time and can actually cause space to be wasted. For example, in the sequence: COMMON I, A(1000), B(1000) DO 111 I=1,1000 A(I) = 4.0*B(I) CALL SUB1 (C,D) 111 CONTINUE CALL SUB2 END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fb \c,---------------------------------------------------------------------------- \i,inhibit \c,---------------------------------------------------------------------------- FTN5UG COMMON AND EQUIVALENCE USAGE Screen 2 of 2 Because I is in common, its value must be stored before each call to SUB1 or SUB2. These two stores (30 bits each) occupy the same amount of space as the variable itself, thus negating any savings in storage. If I was not in common, the stores would be eliminated, speeding execution considerably. Equivalence classes can inhibit optimization in less obvious ways. The following example is typical: DIMENSION X(100) EQUIVALENCE (X(1),W) : W = Y PRINT*, X(I) END Without the EQUIVALENCE statement, the compiler would remove the statement W = Y because the value of W is not used again in the program. However, because W is equivalenced to X(1), and the PRINT statement might reference X(1), the assignment statement cannot be eliminated. Press RETURN to read about Additional Optimization Techniques. \c,---------------------------------------------------------------------------- \s,op_fbc \u,op_fb \c,---------------------------------------------------------------------------- \i,additional optimization techniques \i,mixed mode arithmetic \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL OPTIMIZATION TECHNIQUES Screen 1 of 4 Following are some additional optimization techniques that can be helpful for certain applications: Avoid mixed mode arithmetic. Each conversion from one mode to another requires extra instructions. (An exception is exponentiation; use integers for exponents wherever possible, regardless of the mode of the base.) When a choice among modes is possible for an expression, choose according to the following hierarchy (from fastest to slowest): Integer Real Double Precision Double precision is especially inefficient and should be avoided. A single precision floating point number provides sufficient accuracy for most applications. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fb \i,computed go to statement \i,computed go to \i,block if statement \i,block if \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL OPTIMIZATION TECHNIQUES Screen 2 of 4 If a program is to be relocated only once but executed many times, use DATA statements, instead of assignment statements, to initialize variables and arrays. The computed GO TO statement makes a program harder to read and debug, and should be used with caution. When more than four or five branches can be taken from a given point, a computed GO TO is faster than IF statements. However, a computed GO TO with only two or three branches should be replaced by an IF statement. Block IF statements generate the same code as arithmetic IF statements; however, block IF statements greatly improve readability and should be used wherever possible. More efficient code is generated if one branch of an arithmetic IF immediately follows the IF statement, because a branch to that path is not required. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fb \c,---------------------------------------------------------------------------- \i,intrinsic functions \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL OPTIMIZATION TECHNIQUES Screen 3 of 4 Consolidate references to intrinsic functions whenever possible. For example: A = ALOG(C) + ALOG(D) should be rewritten as: A = ALOG(C*D) Try to minimize the number of subroutine and function references in a program. (You must weigh the advantages of this technique against the advantages of increased program modularity.) In some cases, you can substitute a statement function for an external function. Since statement functions are expanded in-line, the overhead associated with passing param- eters, saving registers, and branching to and from the function is eliminated for each function reference. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fb \n,op_fb \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL OPTIMIZATION TECHNIQUES Screen 4 of 4 Factor expressions whenever possible to reduce the number of operations required for evalu ating the expression. For example: X = A*C + B*C + A*D + B*D should be rewritten as: X = (A + B)*(C + D) The first version requires four multiplications and three additions; the second requires only one multiplication and two additions. Press RETURN to return to the Reducing Execution Time menu. \c,---------------------------------------------------------------------------- \s,op_fc \u,op_f \p,op_f \c,---------------------------------------------------------------------------- \m=a,op_fca \m=b,op_fcb \m=c,op_fcc \c,---------------------------------------------------------------------------- \i,reducing memory use \c,---------------------------------------------------------------------------- FTN5UG REDUCING MEMORY USE Screen 1 of 1 Enter one of the following letters to learn more about reducing memory use: a. Overview b. Eliminating Unnecessary Instructions c. Data Storage Press RETURN to read the Overview. Enter UP to return to the Optimization menu. \c,---------------------------------------------------------------------------- \s,op_fca \u,op_fc \c,---------------------------------------------------------------------------- \i,reducing memory use overview \i,overview of reducing memory use \c,---------------------------------------------------------------------------- FTN5UG REDUCING MEMORY USE OVERVIEW Screen 1 of 2 An efficient program minimizes the total amount of memory required. Good programming practice dictates that you maintain an awareness of efficient programming techniques and that you strive to make optimal use of available resources. However, you should keep in mind the previously mentioned trade-offs: reducing the size of a program often means increasing execution time, and it might also mean sacrificing program clarity and maintainability, not to mention programmer time required to incorporate memory saving techniques. The most important considerations in any program depend on the particular application and the resources available to it. For example, if you have written a program that exceeds available memory, you must search for ways to reduce the program's memory requirements. A good programmer never wastes resources. With experience, you will reach a point where you automatically use good judgment in the writing of efficient programs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fc \c,---------------------------------------------------------------------------- \i,ovcap,1 \i,overlays,1 \i,segments,1 \c,---------------------------------------------------------------------------- FTN5UG REDUCING MEMORY USE OVERVIEW Screen 2 of 2 You can achieve sizable reductions in program field length through use of OVCAPs, overlays, or segments. These methods enable you to divide a program into smaller units, not all of which need be in memory at the same time. Different units can occupy the same memory locations at different times. Only those units required for execution at a particular time must be in memory. When a particular unit is needed for execution, it can be called into memory, replacing units currently in memory. Units reside on disk when not in memory. If the use of OVCAPs, segments, or overlays is not practical, or if your program requires a further reduction in size, there are other, less effective methods available. These methods are of two types: those that reduce the number of instructions in your program and those that reduce the area required by your program for the storage of data. These elements are discussed in the following paragraphs. Press RETURN to read about Eliminating Unnecessary Instructions. \c,---------------------------------------------------------------------------- \s,op_fcb \u,op_fc \c,---------------------------------------------------------------------------- \m=a,op_fcba \m=b,op_fcbb \m=c,op_fcbc \c,---------------------------------------------------------------------------- \i,eliminating unnecessary instructions \i,unnecessary instructions \c,---------------------------------------------------------------------------- FTN5UG ELIMINATING UNNECESSARY INSTRUCTIONS Screen 1 of 1 There are a number of programming techniques you can use to reduce the number of instructions in your program. It is unlikely, however, that these techniques will allow you to significantly reduce the size of your program. The methods described in these paragraphs are good programming practice, and you should consider them when writing FORTRAN programs. But in most cases, it would probably not be worth the programmer time required to search through a large program for areas where unnecessary instructions exist. In any case, the number of instructions in a program is usually not a significant factor compared to the total area within the program required for data storage. Enter one of the following letters to learn more about eliminating unnecessary instructions: a. Modularizing a Program b. Eliminating Unnecessary Function References c. Initializing Variables Press RETURN to read about Modularizing a Program. Enter UP to return to the Reducing Memory Use menu. \c,---------------------------------------------------------------------------- \s,op_fcba \u,op_fcb \c,---------------------------------------------------------------------------- \i,modularizing a program \i,modules \i,subprogram \c,---------------------------------------------------------------------------- FTN5UG MODULARIZING A PROGRAM Screen 1 of 1 Program modularity has already been discussed (enter MOD?) as a means of reducing the size of a program. This technique involves placing duplicated code within a program into a function or subroutine. In many cases, a subprogram that performs the desired task might already exist either in the FORTRAN library or in some other library available at your installation. However, you must weigh the advantage gained by modularizing a program against the increased execution time resulting from the additional function or subroutine calls. As an alternative to using a subprogram for duplicated code, you can include the code in your program only once, and branch to the code whenever you want to execute it. The disadvantage of this method is that other subprograms cannot use the code. Press RETURN to read about Eliminating Unnecessary Function References. \c,---------------------------------------------------------------------------- \s,op_fcbb \u,op_fcb \c,---------------------------------------------------------------------------- \i,eliminating unnecessary function references \i,unnecessary function references \i,function references \i,intrinsic functions \c,---------------------------------------------------------------------------- FTN5UG ELIMINATING UNNECESSARY FUNCTION REFERENCES Screen 1 of 3 Intrinsic functions cause the compiler to insert instructions directly into your program each time the function is referenced. Functions generating in-line code include INT, REAL, MOD, DIM, MAX, MIN, SHIFT, and LOCF. Refer to the FORTRAN reference manual for a complete list of intrinsic functions. The mathematical intrinsic functions are more economical in their use of memory. These functions are included only once in your program's field length. Each time a mathematical intrinsic function is referenced, the compiler generates instructions that allow your program to branch to the function, execute the function, and return to the statement in your program following the function reference. In either case, you should attempt to minimize the number of function references in your program. For example, the statement: A = X*AMIN(R,S,T) + Y*AMIN(R,S,T) can be shortened to: A = (X+Y)*AMIN(R,S,T) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcb \c,---------------------------------------------------------------------------- FTN5UG ELIMINATING UNNECESSARY FUNCTION REFERENCES Screen 2 of 3 If you reference a function more than once, and the values of the arguments do not change, you can assign the functional value to a variable and substitute the variable name for subsequent function references. (This also decreases execution time.) For example, N = SHIFT(1,56) .AND. II . . M = SHIFT(1,56) .OR. JJ can be expressed as: MSK = SHIFT(1,56) . . N = MSK .AND. II . . M = MSK .OR. JJ Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcb \c,---------------------------------------------------------------------------- FTN5UG ELIMINATING UNNECESSARY FUNCTION REFERENCES Screen 3 of 3 You can eliminate the execution-time function reference in the preceding example by substituting the following statements: BOOLEAN MSK PARAMETER (MSK=SHIFT(1,56)) In this case, the SHIFT function is evaluated at compile time. Press RETURN to read about Initializing Variables. \c,---------------------------------------------------------------------------- \s,op_fcbc \u,op_fcb \c,---------------------------------------------------------------------------- \i,initializing variables \i,data statements \i,initialize variables \i,variable initialization \c,---------------------------------------------------------------------------- FTN5UG INITIALIZING VARIABLES Screen 1 of 2 Wherever possible, you should use DATA statements, rather than assignment statements, to initialize variables. Unlike assignment statements, DATA statements generate no machine instructions and the actual initialization is performed when the program is loaded, rather than when it is executed. Thus, substituting DATA statements for assignment statements reduces both the number of machine instructions generated and the execution time required. For example, the statements at the beginning of a program: A = 1.0 B = 2.0 C = 3.0 can be replaced by the single DATA statement: DATA A,B,C/1.0,2.0,3.0/ Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcb \n,op_fcb \c,---------------------------------------------------------------------------- FTN5UG INITIALIZING VARIABLES Screen 2 of 2 Situations exist, however, where DATA statements cannot be substituted for assignment statements. For example, the following subroutines are not equivalent: SUBROUTINE SUB(B,C,N) SUBROUTINE SUB(B,C,N) SAVE A SAVE A DIMENSION B(N) DIMENSION B(N) A = 0 DATA A/0.0/ DO 10 I=1,10 DO 10 I=1,N 10 A = A+B(I) 10 A=A+B(I) C = A C=A RETURN RETURN END END In the first example, the variable A is initialized on each entry into SUB. In the second example, A is initialized when the program is loaded. The first time SUB is called, A has the correct value. However, on subsequent calls to SUB, A will not be initialized; A retains the value it had on the last exit from SUB. Press RETURN to return to the Eliminating Unnecessary Instructions menu. \c,---------------------------------------------------------------------------- \s,op_fcc \u,op_fc \p,op_fc \c,---------------------------------------------------------------------------- \m=a,op_fcca \m=b,op_fccb \m=c,op_fccc \c,---------------------------------------------------------------------------- \i,data storage \i,storage of data \c,---------------------------------------------------------------------------- FTN5UG DATA STORAGE Screen 1 of 1 In many applications, it is the amount of memory required for storing data, and not the number of instructions, that causes programs to become excessively large. It is not unusual for certain scientific applications to operate on extremely single array exceeds the area occupied by the program's instructions. Arrays can be deceptively large. For example, an array dimensioned (100,100) requires 10,000 words of memory. Since FORTRAN permits arrays of up to seven dimensions, extremely large arrays are possible. An array dimensioned (10,10,10,10,10,10,10) requires 10 million words of memory, far beyond the capacity of most computers. Enter one of the following letters to learn more about Data Storage: a. Equivalence Classes b. Storing Matrices c. Packing Data Press RETURN to read about Equivalence Classes. Enter UP to return to the Reducing Memory Use menu. \c,---------------------------------------------------------------------------- \s,op_fcca \u,op_fcc \c,---------------------------------------------------------------------------- \i,equivalence classes \i,equivalence \i,equivalence statement \c,---------------------------------------------------------------------------- FTN5UG EQUIVALENCE CLASSES Screen 1 of 1 The EQUIVALENCE statement allows variables and arrays to share areas of memory. You should exercise care in the use of equivalence classes because they can inhibit certain compiler optimizations, as described earlier in this section. However, the savings in the amount of memory used can be significant. For example, if a program contains the following arrays: DIMENSION AR(10,10,10),BR(50,100) then the equivalence class: EQUIVALENCE (AR(1),BR(1)) reduces the program's memory requirement by 1,000 words. When using equivalence classes, you should be sure the original data is no longer needed at the time you overwrite it with new data. Press RETURN to read about Storing Matrices. \c,---------------------------------------------------------------------------- \s,op_fccb \u,op_fcc \c,---------------------------------------------------------------------------- \i,storing matrices \i,matrices \c,---------------------------------------------------------------------------- FTN5UG STORING MATRICES Screen 1 of 4 Many scientific applications involve the use of large arrays to store matrices. In many of these matrices, only a small percentage of the elements have nonzero values; such a matrix is called a sparse matrix. In these instances, you can develop methods for eliminating the space occupied by the zero-valued elements, storing only the nonzero elements. For example, suppose a program stores the following sparse matrix in an array A(6,6): 0 0 2 0 0 0 5 0 0 3 0 0 0 0 0 0 0 4 0 6 0 0 0 0 0 0 0 2 0 0 0 0 1 0 0 5 A total of 36 words is allocated for this array, but only 8 words contain nonzero values. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- FTN5UG STORING MATRICES Screen 2 of 4 An alternate method of storing this array is to define three one-dimensional arrays, and to store the nonzero elements into one of the arrays, and the row and column positions of the elements into the corresponding positions of the other two arrays. Thus, the preceding matrix can be stored as: Value: 2.0 5.0 3.0 4.0 6.0 2.0 1.0 5.0 Row: 1 2 2 3 4 5 6 6 Column: 3 1 4 6 2 4 3 6 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- FTN5UG STORING MATRICES Screen 3 of 4 The following sequence shows a method for accessing element I,J of a matrix stored in the preceding manner. Assume that array B contains the nonzero elements, array NR contains the row positions of the elements, and array NC contains the column positions: VALUE = 0.0 DO 10 K=1,8 IF (NR(K) .EQ. I .AND. NC(K) .EQ. J) THEN VALUE = B(K) GO TO 15 ENDIF 10 CONTINUE 15 CONTINUE In this example, 21 words are required to store the matrix, instead of the original 36. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- FTN5UG STORING MATRICES Screen 4 of 4 Note that for this method to yield a net savings, the number of nonzero elements must not exceed one-third of the total number of matrix elements. Also, this method significantly increases execution time. You can develop similar techniques for storing other matrix types, such as symmetric matrices and upper and lower triangular matrices. Press RETURN to read about Packing Data. \c,---------------------------------------------------------------------------- \s,op_fccc \u,op_fcc \c,---------------------------------------------------------------------------- \i,packing data \i,data packing \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 1 of 6 Data packing is a method of storing data in which more than one value is stored in a single word. This method can significantly reduce the amount of memory required for a program. Its disadvantages are that it increases execution time, it is highly machine dependent, and in the case of type REAL values, some significance is lost. For type REAL values, it is probably not practical to consider storing more than two values into a single word because of the consequent loss of significance. (The method involves using the SHIFT function and Boolean operators .AND. and .OR. to pack the upper 30 bits of each value into a 30-bit field of a single word.) When two values are packed into one word, the exponent and high-order 18 bits of each value are retained. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- \i,packing real numbers \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 2 of 6 Consider a program that contains two arrays, A(100) and B(100). The following DO loop packs the values in these arrays into a single array: Begin DO loop: DO 10 I=1,100 Clear lower 30 bits of an element of B: B(I) = B(I) .AND. MASK(30) Clear lower 30 bits of A and shift upper 30 to lower: A(I) = SHIFT(A(I) .AND. MASK(30),30) Pack A into lower 30 bits of B: B(I) = B(I) .OR. A(I) 10 CONTINUE Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- \i,unpacking \i,unpacking real numbers \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 3 of 6 Before a value from the packed array is used in a subsequent calculation, it must be unpacked. The statement: X = B(I) .AND. MASK(30) unpacks the value in the upper half of B(I). The statement: Y = SHIFT (B(I),30) .AND. MASK(30) unpacks the value in the lower half of B(I) and shifts it to the proper position. Note that truncating the lower 30 bits of a floating point number significantly reduces the level of accuracy attainable in floating point calculations. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- \i,packing integers \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 4 of 6 You can achieve an even greater reduction in memory usage if you are storing integers, since for most integer values only a few low-order bits of a word are used. If you know the maximum length of each integer value, you can usually pack several values into a single word. For example, if integer variables I, J, K, L, M contain the values 6, 123, 756, 25, and 32, respectively, the internal representations of these values are: I 00000000000000000006 J 00000000000000000173 K 00000000000000001364 L 00000000000000000031 M 00000000000000000040 Since the largest value has a length of 12 bits (the binary representation of 1364 octal is 001011110100), these values can be packed into a single word with each value occupying a 12-bit field: IPACK = I .OR. SHIFT(J,12) .OR. SHIFT(K,24) .OR. *SHIFT(L,36) .OR. SHIFT(M,48) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \c,---------------------------------------------------------------------------- \i,packing integers \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 5 of 6 If negative values are a possibility, an extra bit must be reserved in each field for a sign bit. The preceding values are unpacked as follows: I = IPACK .AND. 0"7777" J = SHIFT(IPACK,-12) .AND. 0"7777" K = SHIFT(IPACK,-24) .AND. 0"7777" L = SHIFT(IPACK,-36) .AND. 0"7777" M = SHIFT(IPACK,-48) .AND. 0"7777" Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,op_fcc \n,op_fcc \c,---------------------------------------------------------------------------- \i,unpacking negative numbers \c,---------------------------------------------------------------------------- FTN5UG PACKING DATA Screen 6 of 6 Because of the way negative integers are stored (one's complement with sign extension), unpacking negative integers requires an additional SHIFT operation to extend the sign. If I, J, K, L, and M are negative integers, then the preceding unpacking operations are performed as follows: I = SHIFT(SHIFT(IPACK,48),-48) J = SHIFT(SHIFT(IPACK,36),-48) K = SHIFT(SHIFT(IPACK,24),-48) L = SHIFT(SHIFT(IPACK,12),-48) M = SHIFT(IPACK,-48) These statements shift each integer first to the leftmost positions of the word so that the sign bit is at the highest bit position, and then to the rightmost positions, which extends the sign bit and stores the integer in its proper format. Because of the previously mentioned disadvantages, the techniques of data packing are recommended only if it is essential that you reduce a program's memory requirement. Press RETURN to return to the Data Storage menu. \c,---------------------------------------------------------------------------- \s,mn_g \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,mn_ga \m=b,mn_gb \m=c,mn_gc \m=d,mn_gd \c,---------------------------------------------------------------------------- \i,maintain \i,program maintenance \i,maintaining programs \c,---------------------------------------------------------------------------- PROGRAM MAINTENANCE This topic describes methods for creating, storing, and modifying source and object programs. These techniques are especially useful for programs that are to be saved, repeatedly executed, and frequently updated over an extended period. The methods presented in here enable you to minimize the execution time and the space required for storing and maintaining programs. Enter one of the following letters to learn more about program maintenance: a. Overview b. Source Program Maintenance Using XEDIT c. Source File Maintenance Using Update d. Object Program Maintenance Using LIBGEN Press RETURN to read the Overview. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,mn_ga \u,mn_g \c,---------------------------------------------------------------------------- \i,program maintenance overview \i,overview of program maintenance \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 1 of 7 The simplest method for maintaining a program over an extended period is to store the entire source program (main program and all its subprograms) as a permanent file. However, this is expensive in terms of execution time, since the program must be recompiled each time it is executed. Another disadvantage of this method is that routines in the program cannot be accessed by other programs. The inability to share routines that perform a commonly required function can significantly increase both memory required for execution and space required for permanent storage of programs. A second alternative is to store both the source program and the compiled binary program as permanent files. In this case, you must recompile only when you introduce changes into the source program. The disadvantage of this method is that a change to a single routine in the source program necessitates recompiling the entire program, and as with the previous alternative, routines in the program cannot be used by other programs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 2 of 7 A third alternative is to store each compiled program unit as a separate file. Then when a change is made to the source program, you extract the affected routine from the source file and compile only that routine. The disadvantages here are that you must keep track of many different files, and the loading and executing of these files can become complicated. A fourth, and recommended, alternative is to maintain a single source file in a format known as a program library, and to store the compiled program (with all its subprograms) in a collection of compiled programs called a user library. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- \i,program library \i,user library \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 3 of 7 The terms program library and user library have the following meanings: A program library is a file containing source programs. Information on a program library consists of lines of FORTRAN source code. Individual routines can be easily copied to a separate file for input to the FORTRAN compiler. A user library is a file containing compiled binary modules that can be used by the loader to satisfy external references or name call references. It must be created by a library-creating utility. All records on a user library must be binary modules. A user library is efficient to maintain because only changed routines need be recompiled. The library-creating utility is then used to replace the changed routine in the library. Individual records (routines) in the library can be accessed by programs not in the library. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 4 of 7 With modules on a user library, the process of loading and executing is simplified because you need to declare only the main program name and the library name. The loader examines the main program to determine what subroutines are required, then searches the library for those routines. Only the required routines are actually loaded into your program's field length. Several utilities are available for maintaining source and object programs. You can use these utilities either interactively or in a batch job. The primary difference between interactive and batch program maintenance is in the initial creation of the source program. For batch execution, your program is generally in the form of a card deck; to create programs interactively, you must use a text editor such as XEDIT. The Update utility, used for source program maintenance, accepts as input either a card deck or a file of card images such as the file created by XEDIT. In either batch or interactive execution, you can use the LIBGEN, COPYL or LIBEDIT, and GTR utilities to create and maintain user libraries. Enter BATCH? for examples of using Update, LIBGEN, COPYL, and GTR in a batch environment. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 5 of 7 For small programs (approximately 100 or fewer lines) to be run interactively, it is sufficient to create and maintain a file of source programs by using XEDIT. This file can be input directly to the FORTRAN compiler, and the resulting binary can be input to LIBGEN to create a user library (although LIBGEN is seldom used with smaller programs). For larger programs, however, you should use Update to create a specially-formatted Update program library. Line images on Update libraries are stored in a compressed format, thereby reducing the size of the library, and the Update utility offers advantages for processing large amounts of information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- \i,create a user library \i,user library creation \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 6 of 7 To create a user library: 1. Use XEDIT to enter your source program into the system. 2. For larger programs, use Update to convert the source program to an Update program library. For smaller programs, you can omit this step and use the XEDIT source file. 3. Compile the entire program. If you are using an Update library, you must first direct Update to create a compile file from the compressed line images in the library. 4. Use LIBGEN to create a user library. Prior to executing routines in the library, you direct the loader to load the desired routines by using techniques described under index topic LOAD?. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_g \c,---------------------------------------------------------------------------- \i,modify a user library \i,user library modification \c,---------------------------------------------------------------------------- FTN5UG PROGRAM MAINTENANCE OVERVIEW Screen 7 of 7 To modify routines in a user library: 1. If you are maintaining an Update library, use Update to make desired changes to routines in the library. If you are maintaining an XEDIT file, use XEDIT to make the desired changes. 2. Compile the changed routines. 3. Use GTR, COPYL or LIBEDIT, and LIBGEN to create a new, corrected user library. Press RETURN to read about Source Program Maintenance Using XEDIT. \c,---------------------------------------------------------------------------- \s,mn_gb \u,mn_g \c,---------------------------------------------------------------------------- \m=a,mn_gba \m=b,mn_gbb \m=c,mn_gbc \m=d,mn_gbd \m=e,mn_gbe \m=f,mn_gbf \c,---------------------------------------------------------------------------- \i,xedit \i,source program maintenance using xedit \i,program maintenance using xedit \i,using xedit \i,xedit use \i,maintenance using xedit \i,using xedit \i,text editor \i,editing \c,---------------------------------------------------------------------------- FTN5UG SOURCE PROGRAM MAINTENANCE USING XEDIT Screen 1 of 1 XEDIT is a text editor that enables you to interactively perform editing functions on files containing FORTRAN source programs. Files operated on by XEDIT are sequential files of text lines (up to 150 characters of display code data per line). You can use XEDIT to create a new file or alter an existing one. After altering an existing file, XEDIT allows you to create a new copy of the file or to replace the file. You can input a file created by XEDIT directly to the FORTRAN compiler, or you can input it to Update to create a program library. Enter one of the following letters to learn more about XEDIT: a. Overview b. Creating a Program c. Tabulation Control d. Modifying a Source Program e. Saving Editing Changes and Terminating XEDIT f. Summary of XEDIT Processing Press RETURN to read the Overview. Enter UP to return to the Program Maintenance menu. \c,---------------------------------------------------------------------------- \s,mn_gba \u,mn_gb \c,---------------------------------------------------------------------------- \i,xedit overview \i,overview of xedit \i,xedit control statement \c,---------------------------------------------------------------------------- FTN5UG XEDIT OVERVIEW Screen 1 of 2 XEDIT is called by the following control statement: XEDIT,options The specified options control various aspects of XEDIT operation. In response to this statement, XEDIT displays two question marks (??) and waits for you to enter an XEDIT command. The XEDIT commands described in the following topics are summarized in the table on the next screen. XEDIT provides a shorthand notation that allows you to substitute an abbreviation for the full command form. The table shows the short command forms. However, for increased clarity, the following discussions use only the full forms. Press RETURN to see the table of XEDIT commands. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,input command,1 \i,input,1 \i,xedit input command,1 \i,replace command,1 \i,replace,1 \i,xedit replace command,1 \i,delete command,1 \i,delete,1 \i,xedit delete command,1 \i,insert command,1 \i,insert,1 \i,xedit insert command,1 \i,print command,1 \i,print,1 \i,xedit print command,1 \i,locate command,1 \i,locate,1 \i,xedit locate command,1 \i,change command,1 \i,change,1 \i,xedit change command,1 \c,---------------------------------------------------------------------------- FTN5UG XEDIT OVERVIEW Screen 2 of 2 XEDIT commands: +----------+-------+---------------------------------------+ | | Short | | | Command | Form | Description | +----------+-------+---------------------------------------+ | INPUT | | Enter an arbitrary number of lines. | | | | | | REPLACE | R | Replace a specified number of lines. | | | | | | DELETE | D | Delete a specified number of lines. | | | | | | INSERT | I | Insert a specified number of lines. | | | | | | PRINT | P | Print a specified number of lines. | | | | | | LOCATE | L | Locate a character string. | | | | | | CHANGE | C | Replace a character string. | +----------+-------+---------------------------------------+ Press RETURN to read about Creating a Program Using XEDIT. \c,---------------------------------------------------------------------------- \s,mn_gbb \u,mn_gb \c,---------------------------------------------------------------------------- \i,creating a program \i,creating a program using xedit \i,create a file \i,create a file using xedit \i,xedit file creation \i,input command \i,input \i,xedit input command \i,input mode \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM USING XEDIT Screen 1 of 5 To create a file through XEDIT, enter the following form of the XEDIT control statement: XEDIT,file,C where file is the name to be assigned to the file you are creating, and C indicates that you are creating a new file. This statement causes XEDIT to begin execution in creation mode. XEDIT issues a ?? prompt and waits for you to enter the command to begin file creation. To begin creation of a program, enter the command: INPUT This statement activates input mode. XEDIT echos the INPUT command and on a separate line displays a single question mark (?), indicating that you can now enter a source line. After you enter a line and press carriage return, XEDIT issues another ? prompt and waits for your input. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,edit mode \i,list a program \i,print command \i,print \i,xedit print command \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM USING XEDIT Screen 2 of 5 You can terminate input mode at any time by pressing carriage return in response to a ? prompt. XEDIT displays the message EDIT to indicate that you are now in edit mode. XEDIT then issues a ?? prompt and waits for the next command. You must terminate input mode before entering XEDIT commands; all information entered while XEDIT is in input mode is considered part of the file you are creating. To list the program you have just created, enter the commands: TOP PRINT* XEDIT displays each line exactly as you have entered it, with tabs converted to the proper number of blanks. Enter TOP? for an explanation of the TOP command. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,correcting error \i,xedit error correction \i,modifying a program,1 \i,program modification,1 \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM USING XEDIT Screen 3 of 5 If you enter a line incorrectly, you can correct the error as follows: 1. Leave input mode. 2. Correct the error using the appropriate XEDIT commands. 3. Resume input mode and continue entering your program. This process is described in greater detail later in the topic Modifying a Program (enter MOD?) However, the following steps outline a quick procedure that enables you to replace a source line you have just entered: 1. Leave input mode (press carriage return). 2. Enter REPLACE. XEDIT responds with a ? prompt. 3. Reenter the incorrect line. 4. Resume input mode (by entering INPUT) and continue entering your program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,terminate xedit,1 \i,xedit termination,1 \i,end command,1 \i,end,1 \i,xedit end command,1 \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM USING XEDIT Screen 4 of 5 When you finish creating your program and are out of input mode, you can terminate XEDIT with the command: END XEDIT saves your program in a local file having the name you specified when you initiated XEDIT, displays the message: file IS A LOCAL FILE and returns control to the operating system, which prompts for the next control statement. The figure on the next screen illustrates the creation of a FORTRAN program using XEDIT. A programming error is corrected using the REPLACE command, the program is listed with the PRINT command, and XEDIT is terminated with the END command. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,xedit example \i,example of xedit \i,example of xedit file creation \i,xedit file creation example \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM USING XEDIT Screen 5 of 5 /xedit,sfile,c <------------------------- Call XEDIT and create file SFILE XEDIT ?? input <------------------------------- Enter INPUT mode. INPUT ? program report ? character iper*7, year*4 ? data year/'1980'/ ? print*,'weekly or monthly?' ? read '(a7)),iper <-------------- This statement contains an error ? <------------------------------------- Enter carriage return to leave EDIT INPUT mode ?? replace <----------------------------- Replace the incorrect statement ? read '(a7)', iper ?? input <------------------------------- Resume INPUT mode INPUT ? if (iper .eq. 'weekly') then : ?? end <--------------------------------- Terminate XEDIT SFILE IS A LOCAL FILE Press RETURN to read about Tabulation Control. \c,---------------------------------------------------------------------------- \s,mn_gbc \u,mn_gb \c,---------------------------------------------------------------------------- \i,tabulation control \c,---------------------------------------------------------------------------- \i,tabulation \i,tabs \i,tabbing \i,xedit tabs \i,tab character \i,xedit tab character \i,deftab command \i,deftab \i,xedit deftab command \i,tabs command \i,xedit tabs command \c,---------------------------------------------------------------------------- FTN5UG TABULATION CONTROL Screen 1 of 2 XEDIT provides a tabulation control feature that can simplify the process of creating a FORTRAN program. To use this feature, you must first define a tab character with the command: DEFTAB char where char is the tab character. (To avoid confusion, you should select a character that is not likely to appear in a normal FORTRAN statement.) You can then establish the tab positions to be associated with the tab character by entering the command: TABS\t1\t2...tn where ti represents a column position on the input line. Then, whenever you include the tab character in an input line, tabulation of the edit file occurs. The first appearance of the character causes tabulation to position t1; the second appearance causes tabulation to position t2, and so forth. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- FTN5UG TABULATION CONTROL Screen 2 of 2 A recommended procedure is to define at least one tab position, at column 7. This eliminates the need for spacing over seven columns when entering FORTRAN lines. You might also want to define other tab positions to be used for indenting DO loops and block IF structures. Press RETURN to read about Modifying a Source Program Using XEDIT. \c,---------------------------------------------------------------------------- \s,mn_gbd \u,mn_gb \c,---------------------------------------------------------------------------- \m=a,mn_gbda \m=b,mn_gbdb \m=c,mn_gbdc \m=d,mn_gbdd \m=e,mn_gbde \m=f,mn_gbdf \m=g,mn_gbdg \c,---------------------------------------------------------------------------- \i,modifying a source program using xedit \i,modifying a source program \i,source program modification using xedit \i,source program modification \i,program modification \i,modify a program \i,modify a program using xedit \c,---------------------------------------------------------------------------- FTN5UG MODIFYING A SOURCE PROGRAM USING XEDIT Screen 1 of 1 XEDIT provides several commands for altering a text file. You can use these commands for making changes to a file you are creating (in creation mode), as well as to an existing file. To change a program with XEDIT, you must first retrieve the file containing the program (if a local copy does not already exist). You then call XEDIT with the statement: XEDIT,lfn where lfn is the name of the file to be edited. XEDIT copies the specified file into the edit file, issues a ?? prompt, and waits for you to enter a command. Any changes made to the edit file do not affect the original file. Enter one of the following letters to learn about modifying a program: a. Line Pointer e. Listing Lines b. Replacing Lines f. Locating Lines c. Inserting Lines g. Replacing a String Within a Line d. Deleting Lines Press RETURN to read about the Line Pointer. Enter UP to return to the Source Program Maintenance Using XEDIT menu. \c,---------------------------------------------------------------------------- \s,mn_gbda \u,mn_gbd \c,---------------------------------------------------------------------------- \i,top \i,line pointer \i,top command \i,xedit top command \i,current line \i,next command \i,next \i,xedit next command \c,---------------------------------------------------------------------------- FTN5UG LINE POINTER Screen 1 of 2 In order to edit a program with XEDIT, you must understand the function of the line pointer. XEDIT maintains and updates a line pointer; the current line in the edit file is defined as the line pointed to by the line pointer. When you call XEDIT, the line pointer is initially positioned at the first line of the edit file. All editing functions are performed with respect to the current line of the edit file. For example, the command REPLACE replaces the current line; the command INSERT inserts a new line after the current line. Thus, whenever you perform any editing function, you must be sure that the line pointer is positioned at the correct line. XEDIT provides several commands for moving the line pointer: TOP Positions the line pointer at the first line of the edit file. NEXT n Advances the line pointer n lines from its current position. NEXT -n moves the line pointer n lines backwards (towards the beginning-of-information) from its current position. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gbd \c,---------------------------------------------------------------------------- FTN5UG LINE POINTER Screen 2 of 2 After the NEXT command moves the line pointer, XEDIT prints the current line. Certain editing commands automatically update the line pointer after the editing function is complete; other commands do not affect the line pointer. Occasionally, after processing a command, XEDIT displays the message: END OF FILE This means that the end of the file was reached during processing and that the line pointer is now positioned at the first line of the file. Press RETURN to read about Replacing Lines. \c,---------------------------------------------------------------------------- \s,mn_gbdb \u,mn_gbd \c,---------------------------------------------------------------------------- \i,replacing lines \i,replace lines \i,xedit line replacement \i,line replacement \i,replace command \i,replace \i,xedit replace command \c,---------------------------------------------------------------------------- FTN5UG REPLACING LINES Screen 1 of 1 You can replace lines in the edit file with the command: REPLACE n where n is the number of consecutive line to be replaced. Line replacement begins with the current line. Before entering a REPLACE command, you can use the NEXT command to position the line pointer to the first line you wish to replace. If n is omitted from the REPLACE command, only the current line is replaced. In response to a REPLACE command, XEDIT issues a ? prompt. You then enter a replacement line. XEDIT continues to issue ? prompts until you have replaced the specified number of lines. XEDIT then displays a ?? prompt, and you can enter another XEDIT command. Any information you enter in response to a ? prompt is placed in the edit file. Thus, you cannot enter XEDIT commands until REPLACE processing is complete. However, you can terminate REPLACE processing before the specified number of lines has been entered by entering a carriage return in response to the ? prompt. Press RETURN to read about Inserting Lines \c,---------------------------------------------------------------------------- \s,mn_gbdc \u,mn_gbd \c,---------------------------------------------------------------------------- \i,inserting lines \i,line insertion \i,xedit line insertion \i,insert lines \i,insert command \i,insert \i,xedit insert command \c,---------------------------------------------------------------------------- FTN5UG INSERTING LINES Screen 1 of 1 You can insert lines into the edit file with the command: INSERT n where n is the number of lines to be inserted. The lines are inserted immediately after the current line. In response to an INSERT command, XEDIT issues a ? prompt and allows you to enter a line. XEDIT continues to issue ? prompts until you have inserted the specified number of lines. You can terminate INSERT processing before you have entered the specified number of lines by pressing carriage return in response to a ? prompt. After INSERT processing has ended, the line pointer is positioned at the last line inserted. Before entering an INSERT command, you can use NEXT to position the line pointer at the desired line. You can also insert lines into the edit file by entering input mode. The function of the INPUT command is identical to that of the INSERT command except that INPUT allows you to insert an arbitrary number of lines. Press RETURN to read about Deleting Lines. \c,---------------------------------------------------------------------------- \s,mn_gbdd \u,mn_gbd \c,---------------------------------------------------------------------------- \i,deleting lines \i,line deletion \i,xedit line deletion \i,delete command \i,delete \i,xedit delete command \c,---------------------------------------------------------------------------- FTN5UG DELETING LINES Screen 1 of 1 You can delete a specified number of lines from the edit file with the command: DELETE n where n is the number of lines to be deleted. The DELETE command removes n lines starting with the current line. XEDIT displays each line as it is deleted. When the specified number of lines has been deleted, XEDIT prompts for the next command. The line pointer is positioned at the line after the last line deleted. Before deleting lines, use the NEXT command to position the line pointer at the first line to be deleted. If n is omitted, only the current line is deleted. Press RETURN to read about Listing Lines. \c,---------------------------------------------------------------------------- \s,mn_gbde \u,mn_gbd \c,---------------------------------------------------------------------------- \i,listing lines \i,line listing \i,xedit line listing \i,print command \i,print \i,xedit print command \i,print* \c,---------------------------------------------------------------------------- FTN5UG LISTING LINES Screen 1 of 1 You can list lines within the edit file with the command: PRINT n where n is the number of consecutive lines to be listed. Listing begins with the current line. The command: PRINT * prints lines starting with the current line and continuing through the end of the file. If the line pointer is initially positioned at the beginning of the file, this form lists the entire edit file. After making changes to the edit file, it is advisable to use PRINT to verify the changes you have made. In some cases, you can substitute a LOCATE command for one or more PRINT commands. Press RETURN to read about Locating Lines. \c,---------------------------------------------------------------------------- \s,mn_gbdf \u,mn_gbd \c,---------------------------------------------------------------------------- \i,locating lines \i,line location \i,xedit line location \i,locate command \i,locate \i,xedit locate command \c,---------------------------------------------------------------------------- FTN5UG LOCATING LINES Screen 1 of 2 In many editing situations, you will want to locate all the occurrences of a particular string within the edit file, such as a variable name or statement label. You can do this with the command: LOCATE/string/n where string is the character string to be searched for and n is the number of lines to be located. This command causes XEDIT to list the first n lines containing at least one occurrence of string, starting with the current line. After the LOCATE command has completed, the line pointer is positioned at the last line that contained the specified string, unless less than n occurrences of string exist, in which case the pointer is positioned at the first line of the file. If n is omitted, the search stops after the first occurrence is detected. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gbd \c,---------------------------------------------------------------------------- FTN5UG LOCATING LINES Screen 2 of 2 For example, the command: LOCATE/SUBROUTINE/100 begins searching at the current line, and displays each line containing the word SUBROUTINE, until 100 lines have been displayed or until an end-of-file is reached. In many cases, you can use LOCATE to advance the line pointer instead of NEXT, and thereby avoid the need for counting lines. For example, in LOCATE/C SUBW/ XEDIT would search lines until it detected the first occurrence of the string C SUBW. The line pointer would then be correctly positioned. You can use the LOCATE command together with the CHANGE command to locate and change specified strings within a program. Press RETURN to read about Replacing a String Within a Line. \c,---------------------------------------------------------------------------- \s,mn_gbdg \u,mn_gbd \c,---------------------------------------------------------------------------- \i,replacing a string within a line \i,replacing a string \i,string replacement \i,xedit string replacement \i,change command \i,change \i,xedit change command \c,---------------------------------------------------------------------------- FTN5UG REPLACING A STRING WITHIN A LINE Screen 1 of 3 Within a line, you can replace a character string with a different string by using the command: CHANGE/string1/string2/n where string1 is the string to be replaced, string2 is the replacement string, and n is the number of lines containing string1 in which replacement is to occur. String1 and string2 can be of different lengths. XEDIT replaces all occurrences of string1 with string2 in the current line and in the next n-1 lines that contain string1. XEDIT displays each line in which replacement occurs. After CHANGE processing is complete, the line pointer is positioned at the last line in which replacement occurred unless the end of the file is reached, in which case the pointer is positioned at the beginning of the file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gbd \c,---------------------------------------------------------------------------- FTN5UG REPLACING A STRING WITHIN A LINE Screen 2 of 3 You can often substitute a CHANGE command for one or more REPLACE commands. However, you should exercise care when using the CHANGE command since, in a given line, each occurrence of the specified string is replaced; this can result in unexpected replacements. For example, assume the current line of the edit file is: READ (5,100) A,B,ACC and the command: CHANGE/A/ZZ/1 is entered. The current line becomes: REZZD (5,100) ZZ,B,ZZCC Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gbd \n,mn_gbd \c,---------------------------------------------------------------------------- FTN5UG REPLACING A STRING WITHIN A LINE Screen 3 of 3 You can cause XEDIT to search through the end of the edit file with the command: CHANGE/string1/string2/* If you enter this form, XEDIT begins replacement at the current line and continues through the end-of-information. If the line pointer is initially positioned at the beginning of the file, the entire file is searched. After the search, the line pointer is positioned at the beginning of the file. Press RETURN to return to the Modifying a Source Program menu. \c,---------------------------------------------------------------------------- \s,mn_gbe \u,mn_gb \c,---------------------------------------------------------------------------- \i,saving editing changes \i,saving xedit changes \i,copying changes \i,copying \i,copy command \i,copy \i,xedit copy command \c,---------------------------------------------------------------------------- FTN5UG SAVING EDITING CHANGES AND TERMINATING XEDIT Screen 1 of 3 Any editing functions you perform with the preceding commands exist only in the edit file; this file is lost when you terminate XEDIT. To save the changes, you must direct XEDIT either to create a new file containing the changes, or to replace an existing one. Furthermore, if you will be using the altered program to update a user library, the changed routines must exist on a separate file so that they can be compiled separately. You can then use the resulting binary file to update a user library by using the methods described in the topic Object Program Maintenance (enter OPM?). You can copy a portion of the edit file into a separate file with the command: COPY,lfn,n where lfn is the name of the local file into which the lines are to be copied and n is the number of consecutive lines to be copied. Copying begins with the current line. The file created by the COPY command is a local file. You can use the COPY command to copy any changed routines in the edit file to a local file which can be input to the FORTRAN compiler. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- \i,terminating xedit \i,xedit termination \i,leaving edit \i,quit \i,stop \i,bye \i,end command \i,end \i,xedit end command \c,---------------------------------------------------------------------------- FTN5UG SAVING EDITING CHANGES AND TERMINATING XEDIT Screen 2 of 3 After you have made the desired changes to the edit file and created a separate file of changed routines (if necessary), you can save the entire edit file and terminate XEDIT with the command: END,filename,opt where filename is the name of the file on which the changes are to be saved, and opt is one of the following: SAVE Saves the edit file as a new indirect access permanent file. REPLACE Replaces the existing indirect access file named filename with the edit file. LOCAL Saves the edit file as a local file. If filename already exits, it is replaced. COPY Saves the edit file as a direct access file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gb \c,---------------------------------------------------------------------------- FTN5UG SAVING EDITING CHANGES AND TERMINATING XEDIT Screen 3 of 3 END options (continued): RL Combines the REPLACE and LOCAL options. SL Combines the SAVE and LOCAL options. When you enter an END command, XEDIT responds with an informative message verifying the action taken and returns control to the operating system, which issues a prompt for the next control statement. Press RETURN to read the Summary of XEDIT Processing. \c,---------------------------------------------------------------------------- \s,mn_gbf \u,mn_gb \n,mn_gb \c,---------------------------------------------------------------------------- \i,summary of xedit processing \i,summary of xedit \i,xedit summary \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF XEDIT PROCESSING Screen 1 of 1 Following is a step-by-step summary of XEDIT usage: 1. Call XEDIT with the XEDIT control statement. Enter XEDIT,lfn,C if you are creating a new program; enter XEDIT,lfn if you are modifying an existing program. 2. If you are creating a new program, enter INPUT. You can then enter any number of FORTRAN lines. Press carriage return to leave input mode. 3. If you are altering an existing program, make the desired changes with the REPLACE, INSERT, DELETE, and CHANGE commands. 4. If you will be using LIBGEN to update a user library, use the COPY command to copy the changed routines to a separate file for input to the FORTRAN compiler. 5. Terminate XEDIT with the END command. Press RETURN to return to the Source Program Maintenance Using XEDIT. \c,---------------------------------------------------------------------------- \s,mn_gc \u,mn_g \p,mn_g \c,---------------------------------------------------------------------------- \m=a,mn_gca \m=b,mn_gcb \m=c,mn_gcc \m=d,mn_gcd \m=e,mn_gce \m=f,mn_gcf \c,---------------------------------------------------------------------------- \i,update \i,source file maintenance using update \i,using update \i,update usage \c,---------------------------------------------------------------------------- FTN5UG SOURCE FILE MAINTENANCE USING UPDATE Screen 1 of 1 Update is a utility designed to store and maintain files of card images on mass storage. Update is especially useful for maintaining and updating large FORTRAN programs. Update can be used in either an interactive or a batch environment. Enter one of the following letters to learn more about Update: a. Overview b. Update Control Statement c. Directives d. Decks e. Creation Run f. Correction Run Press RETURN to read the Overview. Enter UP to return to the Program Maintenance menu. \c,---------------------------------------------------------------------------- \s,mn_gca \u,mn_gc \c,---------------------------------------------------------------------------- \i,update overview \i,overview of update \i,update program library \i,program library \c,---------------------------------------------------------------------------- FTN5UG UPDATE OVERVIEW Screen 1 of 3 Update allows you to create a specially-formatted file of FORTRAN source programs called an Update program library. Once you have created a program library, you can use Update to: Permanently or temporarily modify programs within the library. Remove permanent sets of modifications. Add programs to or remove programs from the library. Files in Update format cannot be input directly to the FORTRAN compiler. However, you can use Update to create a separate file consisting of selected portions of the program library restored to their original format. This file is suitable for input to the FORTRAN compiler. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE OVERVIEW Screen 2 of 3 Most Update runs require an input file consisting of the source programs to be included in the new or updated program library, individual FORTRAN statements to update programs in an existing library, and directives providing detailed processing instructions to Update. This input can exist either as a card deck or as a sequential file of text lines stored on disk. Only the latter type is discussed in this section. (Enter BATCH RUN? for an example of an Update run in a batch environment.) You can create an Update input file by using a text editor such as XEDIT. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,new program libraray \i,creation run,1 \i,correction run,1 \c,---------------------------------------------------------------------------- FTN5UG UPDATE OVERVIEW Screen 3 of 3 Update produces the following three types of output, according to optional parameters specified on the UPDATE control statement: A new program library, or an updated version of an existing program library. A file containing source code, suitable for for input to the FORTRAN compiler. Listable output that includes diagnostic messages and a summary of action taken by Update. This output is displayed at the terminal in an interactive environment, and written on the output listing in a batch environment. Update can perform two types of operations. The first is called a creation run, which creates a new program library. The second is called a correction run, which creates a new, updated version of an existing program library. A compiler input file can be created during either of these runs. Press RETURN to read about the Update Control Statement. \c,---------------------------------------------------------------------------- \s,mn_gcb \u,mn_gc \c,---------------------------------------------------------------------------- \i,update control statement \c,---------------------------------------------------------------------------- FTN5UG UPDATE CONTROL STATEMENT Screen 1 of 4 Update is called by the following control statement: UPDATE,I=lfn1,P=lfn2,N=lfn3,C=lfn4,O=lfn5,L=list,mode. The parameters on the UPDATE statement are optional and have the following meanings: lfn1 File containing Update directives and FORTRAN text. Default is INPUT. lfn2 File containing existing program library to be updated. Default OLDPL. lfn3 File to which the new program library is to be written. Default is NEWPL. N=0 suppresses new program library generation. lfn4 File to which routines from the existing program library are to written, for input to the FORTRAN compiler. Default is COMPILE. C=0 suppresses compile file generation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE CONTROL STATEMENT Screen 2 of 4 Update Control Statement Parameters (continued): lfn5 File to which Update informative listing is written. Default is OUTPUT (terminal screen in interactive environment, or printed listing in batch environment). O=0 is the same as O=OUTPUT. list List of option codes specifying output listing options. If omitted, extensive output is produced. L=1 suppresses all output except error messages, and is useful for interactive sessions. Refer to the Update reference manual for a complete list of output listing options. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,update mode \c,---------------------------------------------------------------------------- FTN5UG UPDATE CONTROL STATEMENT Screen 3 of 4 Update Control Statement Parameters (continued): mode Update mode, which determines the decks written to the compile file and the new program library. Q Only decks specified by COMPILE directives are written to the compile file and the new program library. F All decks in the old program library are written to the new program library and to the compile file. If the mode option is omitted, all decks in the old program library are written to the new program library. Only corrected decks and decks specified by COMPILE directives are written to the compile file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE CONTROL STATEMENT Screen 4 of 4 The preceding parameters allow you to create and modify a program library. Other parameters exist to control output listing contents, change file organization, merge file contents, and change characteristics of input or output files. Refer to the Update reference manual for information on these parameters. Press RETURN to read about Update Directives. \c,---------------------------------------------------------------------------- \s,mn_gcc \u,mn_gc \c,---------------------------------------------------------------------------- \i,directives \i,update directives \c,---------------------------------------------------------------------------- FTN5UG UPDATE DIRECTIVES Screen 1 of 3 Update processing is controlled by directives. Update directives have the following general format: *name params where name is the directive name and params is a list of parameters specifying various processing options. The directive begins in column one. The table on the following screen lists the most commonly used Update directives. These directives perform insertions and deletions by individual statements, decks, or correction sets. Other directives are described in the Update reference manual. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,addfile directive,1 \i,addfile,1 \i,*addfile,1 \i,update addfile directive,1 \i,call directive,1 \i,call,1 \i,*call,1 \i,update call directive,1 \i,comdeck directive,1 \i,comdeck,1 \i,*comdeck,1 \i,update comdeck directive,1 \i,compile directive,1 \i,compile,1 \i,*compile,1 \i,update compile directive,1 \i,deck directive,1 \i,deck,1 \i,*deck,1 \i,update deck directive,1 \i,delete directive,1 \i,delete,1 \i,*delete,1 \i,update delete directive,1 \c,---------------------------------------------------------------------------- FTN5UG UPDATE DIRECTIVES Screen 2 of 3 Directive Format | Directive Function ------------------------+----------------------------------------------------- *ADDFILE | Adds the subsequent decks to the program library | *CALL deck | Writes a common deck to the compile file | *COMDECK deck | Defines a common deck to be included in the program | library | *COMPILE deck1,..,deckn | Writes the specified decks to the compile file and | to the new program library | *DECK deck | Defines a deck to be included in the program | library | *DELETE deck.seqnum | Deletes the specified line | *DELETE deck.seqnum1, | Deletes the specified range of lines deck.seqnum2 | Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,ident directive,1 \i,ident,1 \i,*ident,1 \i,update ident directive,1 \i,insert directive,1 \i,insert,1 \i,*insert,1 \i,update insert directive,1 \i,purdeck directive,1 \i,purdeck,1 \i,*purdeck,1 \i,update purdeck directive,1 \i,purge directive,1 \i,purge,1 \i,*purge,1 \i,update purge directive,1 \c,---------------------------------------------------------------------------- FTN5UG UPDATE DIRECTIVES Screen 3 of 3 Directive Format | Directive Function ------------------------+----------------------------------------------------- *IDENT idname | Defines a correction set | *INSERT deck.seqnum | Inserts subsequent text lines after the specified | line in the new program library | *PURDECK deck1,..,deckn | Removes the specified decks from the program | library | *PURGE idname | Removes the specified correction set from the | program library ------------------------+---------------------------------------------------- Press RETURN to read about Update Decks. \c,---------------------------------------------------------------------------- \s,mn_gcd \u,mn_gc \c,---------------------------------------------------------------------------- \i,update decks \i,decks \i,deck directive \i,deck \i,*deck \i,update deck directive \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 1 of 6 Update places groups of FORTRAN statements into the new program library in units called DECKS. A deck, in Update terminology, is a grouping of cards (batch) or text lines (interactive) identified by a DECK directive. A DECK directive specifies a name to be associated with all the text lines that follow it until either another directive is encountered or the end of the input file occurs. Update treats each deck as a single unit. The DECK directive has the form: *DECK deckname where deckname is the name to be associated with the deck that follows. You use this name when referencing the deck in other Update directives. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,regular deck \i,common deck \i,comdeck directive \i,comdeck \i,*comdeck \i,update comdeck directive \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 2 of 6 A deck is the only unit that can be extracted from the program library and written to a compile file. Therefore, it is usually convenient to give a separate deck name to each routine that can be compiled separately. (The deck can have the same name as the routine.) Including a group of routines in a single deck is recommended only when recompilation of one routine forces recompilation of the others. For example, subroutines SALES, REPORT, SORT, and SWITCH (enter SALES? to see the program) could be created as a program library with any number of decks, but using five decks allows each routine to be handled separately. Decks written to a program library can be either regular decks or common decks. These differ in that common decks can be called from regular decks or other common decks. Regular decks are designated with the DECK directive described in the preceding paragraph. A common deck is designated with the directive: *COMDECK deckname Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,call directive \i,call \i,*call \i,update call directive \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 3 of 6 Common decks are used for groups of text lines that are common to more than one regular deck. One physical copy of these text lines exists in the library as a common deck, but you can insert the common deck into any number of regular decks when you extract these decks from the existing program library and write them to the compile file. You can instruct Update to insert a common deck into a regular deck by specifying a CALL directive in the input file at the desired point of insertion. This directive has the form: *CALL deckname where deckname is the name of the common deck to be inserted. When Update encounters a CALL directive while writing a compile file, the specified deck is inserted at the point of the call. By using common decks, you can ensure that a set of statements required by several routines never deviates among the routines. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 4 of 6 Common decks are typically used for declarative statements that are common to several routines. For example, assume the statements: INTEGER ARR COMMON /BLOCKA/ARR(50) are required by two subroutines, SUB1 and SUB2. You could define a common deck consisting of these statements and call the common deck from the decks for SUB1 and SUB2. The statements would appear only once in the program library, but would be inserted in both SUB1 and SUB2 when those decks are written to the compile file. The figure on the next screen illustrates this procedure. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,common deck example \i,example of common deck \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 5 of 6 Common Deck Example: *COMDECK ARYDEF INTEGER ARR COMMON /BLOCKA/ ARR(50 *DECK SUB1 SUBROUTINE SUB1 *CALL ARYDEF . Source statements for SUB1 . END *DECK SUB2 SUBROUTINE SUB2 *CALL ARYDEF . Source statements for SUB2 . END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE DECKS Screen 6 of 6 The directive *COMDECK ARYDEF identifies the common deck. Decks SUB1 and SUB2 each include the directive *CALL ARYDEF. When decks SUB1 and SUB2 are written to a compile file, the statements in deck ARYDEF will be inserted at the point of the CALL directive. Subroutine SUB1 will expand to: SUBROUTINE SUB1 INTEGER ARR COMMON /BLOCKA/ARR(50) . . . Subroutine SUB2 will expand to: SUBROUTINE SUB2 INTEGER ARR COMMON /BLOCKA/ARR(50) . . . Press RETURN to read about the Update Creation Run. \c,---------------------------------------------------------------------------- \s,mn_gce \u,mn_gc \c,---------------------------------------------------------------------------- \i,update creation run \i,creation run \i,create a program library \i,program library creation \i,sequence number \c,---------------------------------------------------------------------------- FTN5UG UPDATE CREATION RUN Screen 1 of 5 A creation run performs the original processing of a file containing a FORTRAN source program and Update directives to create a program library. During a creation run, Update examines each text line in the FORTRAN program, compresses blank columns to minimize space occupied by the line in the library, and assigns a unique identifier to the line. This identifier has the form: deck.seqnum where deck is the deck to which the line belongs and seqnum is the sequence number of the line within the deck. The identifier assigned to a line is permanent; no other line throughout the existence of the library will receive the same identifier. You must know the line identifiers in order to add lines to or delete lines from a program library. The figure on the next screen shows an example of an Update input file followed by the terminal dialog for a creation run. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- \i,creation run example \i,example of a creation run \c,---------------------------------------------------------------------------- FTN5UG UPDATE CREATION RUN Screen 2 of 5 Update Directives Contained in File INFILE: *DECK TEST PROGRAM TEST A=1.0 B=1.0 CALL ADD (A,B,C) CALL SUB (A,B,C) END *DECK ADD SUBROUTINE ADD (X,Y,Z) Z=X+Y RETURN END *DECK SUB SUBROUTINE SUB (X,Y,Z) Z=X-Y RETURN END Press RETURN to see the terminal dialogue for the creation run. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE CREATION RUN Screen 3 of 5 Terminal Dialog: /get,infile /update,i=infile,n=newpl,c=compile,l=1 UPDATE COMPLETE. /save,newpl=pl1 /ftn5,i=compile,l=x,qc 0.011 CP SECONDS COMPILATION TIME. The input file, named INFILE, contains three decks, one each for routines TEST, ADD, and SUB. The input file is retrieved and Update execution is initiated. The following parameters are specified on the UPDATE control statement: I=INFILE Directives and decks are on file INFILE. N=NEWPL A program library called NEWPL is to be created. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE CREATION RUN Screen 4 of 5 C=COMPILE A compile file called COMPILE is to be created. This file will contain all the routines in the library. L=1 Error messages are displayed and all other listable output is suppressed. Because Update sometimes generates extensive output, this option is useful for interactive processing. After Update execution is complete, the library NEWPL is saved on permanent file PL1, and the compile file is input to the FORTRAN compiler. The next screen lists the compile file, showing the complete FORTRAN program with text line identifiers. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gc \c,---------------------------------------------------------------------------- FTN5UG UPDATE CREATION RUN Screen 5 of 5 Compile File Listing From Creation Run: PROGRAM TEST TEST 2 A=1.0 TEST 3 B=1.0 TEST 4 CALL ADD (A,B,C) TEST 5 CALL SUB (A,B,C) TEST 6 END TEST 7 SUBROUTINE ADD (X,Y,Z) ADD 2 Z=X+Y ADD 3 RETURN ADD 4 END ADD 5 SUBROUTINE SUB (X,Y,Z) SUB 2 Z=X-Y SUB 3 RETURN SUB 4 END SUB 5 Press RETURN to read about the Update Correction Run. \c,---------------------------------------------------------------------------- \s,mn_gcf \u,mn_gc \c,---------------------------------------------------------------------------- \m=a,mn_gcfa \m=b,mn_gcfb \m=c,mn_gcfc \m=d,mn_gcfd \m=e,mn_gcfe \m=f,mn_gcff \c,---------------------------------------------------------------------------- \i,update correction run \i,correction run \c,---------------------------------------------------------------------------- FTN5UG UPDATE CORRECTION RUN Screen 1 of 1 Enter one of the following letters to learn about the correction run: a. Overview b. Creating a Compile File c. Deleting, Inserting, and Replacing Lines d. Adding and Removing Decks e. Deleting a Correction Set f. Update Output Listing Press RETURN to read the Overview. Enter UP to return to the Source File Maintenance Using Update menu. \c,---------------------------------------------------------------------------- \s,mn_gcfa \u,mn_gcf \c,---------------------------------------------------------------------------- \i,correction run overview \i,overview of the correction run \i,correction set \i,ident directive \i,ident \i,*ident \i,update ident directive \c,---------------------------------------------------------------------------- FTN5UG CORRECTION RUN OVERVIEW Screen 1 of 2 A correction run uses an existing program library to create a new, updated program library or a compile file. During a correction run, you can add or delete individual statements, groups of statements, or entire routines. Changes made during a correction run are incorporated in both the new program library and in the compile file. Note that Update does not alter an existing program library. In a correction run, a new program library is created and the old program library remains unchanged. The input file for a correction run generally consists of one or more correction sets. A correction set is a group of text lines and Update directives identified by an IDENT directive. The IDENT directive has the form: *IDENT idname where idname is a name you assign to the correction set. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG CORRECTION RUN OVERVIEW Screen 2 of 2 During the correction run, Update labels each text line with the correction set name and a sequence number in the form: idname.seqno The sequence number indicates the line's position within the correction set. The text lines are then permanently associated with that correction set. Directives within the correction set specify detailed processing to be performed during the run. The correction set itself becomes a part of the new program library. On subsequent correction runs, you can alter or completely reverse the effects of existing correction sets. The following paragraphs describe some of the editing operations you can perform during correction runs. Note that in the examples, the parameter L=1 is specified on the UPDATE control statements. This option suppresses all listable output except error messages, and thereby reduces the amount of information displayed at the terminal. In most Update runs, you should omit this parameter, which allows output messages to be displayed. Press RETURN to read about Creating a Compile File. \c,---------------------------------------------------------------------------- \s,mn_gcfb \u,mn_gcf \c,---------------------------------------------------------------------------- \i,creating a compile file \i,comile file \i,compile directive \i,compile \i,*compile \i,update compile directive \c,---------------------------------------------------------------------------- FTN5UG CREATING A COMPILE FILE Screen 1 of 3 The simplest type of correction is one which extracts one or more decks from an existing program library and writes them to a compile file; none of the decks are changed and a new program library is not created. The binary file produced by the FORTRAN compilation can be used to update a library file described later in this section under Object Program Maintenance). (enter OPM? for a description of this process.) You can select routines within the old program library to be copied to the compile file with the directive: *COMPILE deck1,...,deck2 where deck1 is the name of a deck to be copied. If you wish to write all the decks in the old program library to the compile file you can specify the F parameter on the UPDATE control statement and omit the COMPILE directive. The figure on the next screen illustrates a correction run in which a single deck is written to the compile file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- \i,compile file creation example \i,example of compile file creation \c,---------------------------------------------------------------------------- FTN5UG CREATING A COMPILE FILE Screen 2 of 3 Update Directive: *COMPILE ADD Terminal Dialogue: /get,oldpl=pl1 /update,i=infile,p=oldpl,c=compf,l=1 UPDATE COMPLETE. /ftn5,i=compf,l=0 0.004 CP SECONDS COMPILATION TIME. The input file contains a single COMPILE directive specifying the name of the deck to be copied. The terminal dialog shows the statements necessary to perform the run. The permanent file PL1 is retrieved and copied to local file OLDPL to be used as the old program library. On the UPDATE control statement, N=0 is specified so that no new program library is created. When Update execution is complete, the compile file COMPILE is input to the FORTRAN compiler. The compile file listing is shown on the next screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG CREATING A COMPILE FILE Screen 3 of 3 Compile File Showing Subroutine ADD: SUBROUTINE ADD (X,Y,Z) ADD 2 Z=X+Y ADD 3 RETURN ADD 4 END ADD 5 Press RETURN to read about Deleting, Inserting, and Replacing Lines. \c,---------------------------------------------------------------------------- \s,mn_gcfc \u,mn_gcf \c,---------------------------------------------------------------------------- \i,deleting inserting and replacing lines \i,deleting lines \i,inserting lines \i,line deletion \i,update line deletion \i,line insertion \i,update line insertion \i,delete directive \i,delete \i,*delete \i,update delete directive \i,insert directive \i,insert \i,*insert \i,update insert directive \c,---------------------------------------------------------------------------- FTN5UG DELETING, INSERTING, AND REPLACING LINES Screen 1 of 5 You can delete or insert text lines within a library with the following directives: *DELETE deck.seqnum deletes the line identified by the specified deck name and sequence number. *DELETE deck.seqnum1,deck.seqnum2 deletes the specified range of lines. *INSERT deck.seqnum inserts subsequent text lines after the specified line. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- \i,replacing lines \i,line replacement \i,update line replacement \c,---------------------------------------------------------------------------- FTN5UG DELETING, INSERTING, AND REPLACING LINES Screen 2 of 5 You can replace lines by deleting the lines and following the DELETE directive with the replacement lines. For example: *DELETE SUB.2,SUB.4 DO 14 I=1,100 A(I)=B(I)+C(I) 14 CONTINUE replaces lines 2 through 4 of deck SUB with the lines following the DELETE directive. The figure on the next screen illustrates line deletion, insertion, and replacement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- \i,update correction run example \i,example of update correction run \c,---------------------------------------------------------------------------- FTN5UG DELETING, INSERTING, AND REPLACING LINES Screen 3 of 5 Update Directives: *IDENT CORR2 *DELETE TEST.3,TEST.4 A=3.0 B=4.00 *INSERT ADD.3 PRINT 100, X,Y,Z 100 FORMAT ('VALUES ARE ',3F10.4) The directive *IDENT CORR1 identifies the correction set to follow. The DELETE directive deletes lines 3 and 4 of deck TEST. These lines are replaced by the lines A=3.0 and B=4.0. The INSERT directive inserts a PRINT statement and a FORMAT statement after line 3 of deck ADD. Press RETURN to see the terminal dialog for the correction run. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG DELETING, INSERTING, AND REPLACING LINES Screen 4 of 5 Terminal Dialog: /get,oldpl=pl1 /update,i=infile,p=oldpl,n=newpl,c=compile,l=1 UPDATE COMPLETE. /save,newpl=pl2 /ftn5,i=compile,l=0 0.011 CP SECONDS COMPILATION TIME. Before the correction run is initiated, the old program library on file PL1 is retrieved. The UPDATE control statement selects the following options: I=INFILE Directives are read from file INFILE. P=OLDFILE The program library to be updated is OLDPL. N=NEWPL The new program library to be created is NEWPL. C=COMPILE Changed routines are written to file COMPILE. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG DELETING, INSERTING, AND REPLACING LINES Screen 5 of 5 After the run is complete, the new program library is saved on permanent file PL2 and the compile file is input to the FORTRAN compiler. The following figure illustrates a listing of the compile file, showing the changed routines with identifiers. PROGRAM TEST TEST 2 A=3.0 CORR2 1 B=4.0 CORR2 2 CALL ADD (A,B,C) TEST 5 CALL SUB (A,B,C) TEST 6 END TEST 7 SUBROUTINE ADD (X,Y,Z) ADD 2 Z=X+Y ADD 3 PRINT 100, X,Y,Z CORR2 3 100 FORMAT (' VALUES ARE ',3F10.4) CORR2 4 RETURN ADD 4 END ADD 5 Press RETURN to read about Adding and Removing Decks. \c,---------------------------------------------------------------------------- \s,mn_gcfd \u,mn_gcf \c,---------------------------------------------------------------------------- \i,adding and removing decks \i,adding decks \i,removing decks \i,addfile directive \i,addfile \i,*addfile \i,update addfile directive \i,purdeck directive \i,purdeck \i,*purdeck \i,update purdeck directive \c,---------------------------------------------------------------------------- FTN5UG ADDING AND REMOVING DECKS Screen 1 of 4 You can add or remove decks within a program library with the following directives: *ADDFILE adds the decks that follow this directive in the input file. Each deck must be preceded by a DECK directive. *PURDECK deck removes the specified deck from the program library. The ADDFILE and PURDECK directives are illustrated on the following screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- \i,adding and removing decks example \i,example of adding and removing decks \c,---------------------------------------------------------------------------- FTN5UG ADDING AND REMOVING DECKS Screen 2 of 4 The purpose of the following correction run is to add a subroutine to the new program library, remove an existing subroutine, and replace the call to the deleted subroutine with a call to the new subroutine. The following input file listing shows the directives used to accomplish this. Update Directives: *IDENT CORR3 <------------- Assigns the name CORR3 to the correction set *DELETE TEST.6 <------------ Replaces line 6 of deck TEST with the new CALL MPY (A,B,C) call statement *PURDECK SUB <-------------- Removes deck SUB *ADDFILE <------------------ Adds deck MPY which contains the new *DECK MPY subroutine MPY SUBROUTINE MPY (X,Y,Z) Z=X+Y RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG ADDING AND REMOVING DECKS Screen 3 of 4 The terminal following dialog shows the statements needed to perform the correction run: /get,oldpl=pl2 /update,i=infile,p=oldpl,n=newpl,c=compile,l=1 UPDATE COMPLETE. /save,newpl=pl3 /ftn5,i=compile,l=0 0.010 CP SECONDS COMPILATION TIME. The compile file, containing the altered deck, is shown on the next screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG ADDING AND REMOVING DECKS Screen 4 of 4 Compile File With New Deck: PROGRAM TEST TEST 2 A=3.0 CORR 1 B=4.0 CORR 2 CALL ADD (A,B,C) TEST 5 CALL MYP (A,B,C) CORR3 1 END TEST 7 SUBROUTINE MPY (X,Y,Z) MPY 2 Z=X*Y MPY 3 RETURN MPY 4 END MPY 5 Press RETURN to read about Deleting a Correction Set. \c,---------------------------------------------------------------------------- \s,mn_gcfe \u,mn_gcf \c,---------------------------------------------------------------------------- \i,deleting a correction set \i,correction set deletion \i,purge directive \i,purge \i,*purge \i,update purge directive \c,---------------------------------------------------------------------------- FTN5UG DELETING A CORRECTION SET Screen 1 of 3 Update allows you to delete entire correction sets from program libraries. When you delete a correction, none of the corrections contained in that set are included in the new program library. The directive to remove a correction set has the form: PURGE idname where idname is the name of the correction set to be removed. The ability to remove sets of changes is especially useful when you are developing and testing various portions of a program. For example, if you are adding a new option to a program, you could include all the coding changes required for that option in a single correction set. If, at a later time, you decide on a different programming approach, or desire to remove the option, you could do so simply by removing the correction set. This capability also makes it easier to revert to an earlier version of a program if the need should arise. The PURGE directive is illustrated in on the next screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- \i,deleting a correction set example \i,example of deleting a correction set \c,---------------------------------------------------------------------------- FTN5UG DELETING A CORRECTION SET Screen 2 of 3 Update Directive: *PURGE CORR2 Terminal Dialog: /get,oldpl=pl3 /update,f,i=infile,p=oldpl,n=newpl,c=compile,l=0 UPDATE COMPLETE /save,newpl=pl4 In this example, the correction set CORR2 is removed. The input file for this correction run contains the single directive *PURGE CORR2. The library named PL3 is the old program library, and the new program library is saved on permanent file PL4. The F parameter is specified on the UPDATE control statement, so that a full update is performed: all decks in the new program library are written to the compile file. The contents of the compile file are shown on the next screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gcf \c,---------------------------------------------------------------------------- FTN5UG DELETING A CORRECTION SET Screen 3 of 3 Compile File With Correction Set Removed: PROGRAM TEST TEST 2 A=1.0 TEST 3 B=2.0 TEST 4 CALL ADD (A,B,C) TEST 5 CALL MYP (A,B,C) CORR3 1 END TEST 7 SUBROUTINE ADD (X,Y,Z) ADD 2 Z=X+Y ADD 3 RETURN ADD 4 ADD ADD 5 SUBROUTINE MPY (X,Y,Z) MPY 2 Z=X*Y MPY 3 RETURN MPY 4 END MPY 5 Press RETURN to read about the Update Output Listing. \c,---------------------------------------------------------------------------- \s,mn_gcff \u,mn_gcf \n,mn_gcf \c,---------------------------------------------------------------------------- \i,update output listing \i,output listing \c,---------------------------------------------------------------------------- FTN5UG UPDATE OUTPUT LISTING Screen 1 of 1 The output listing produced by Update describes the results of the Update run. The contents of this listing is controlled by the L parameter on the UPDATE control statement. Omitting this parameter results in a nearly complete listing which is sometimes extensive. A suggested specification for interactive processing is L=1, which suppresses all output except error messages. The destination of the listing is controlled by the O parameter on the UPDATE control statement. Normally, you will omit this parameter, in which case Update displays the listing at the terminal. However, if you expect the listing to be extremely long, you can direct Update to write it to a separate file. You can display this file at a later time or route it to a printer. Press RETURN to return to the Update Correction Run menu. \c,---------------------------------------------------------------------------- \s,mn_gd \u,mn_g \p,mn_g \c,---------------------------------------------------------------------------- \m=a,mn_gda \m=b,mn_gdb \m=c,mn_gdc \m=d,mn_gdd \c,---------------------------------------------------------------------------- \i,opm \i,object program maintenance using libgen \i,object program maintenance \i,libgen \c,---------------------------------------------------------------------------- FTN5UG OBJECT PROGRAM MAINTENANCE USING LIBGEN Screen 1 of 1 Enter one of the following letters to learn more about LIBGEN: a. Overview b. Calling LIBGEN c. Creating a New User Library d. Creating an Updated User Library Press RETURN to read the Overview. Enter UP to return to the Program Maintenance menu. \c,---------------------------------------------------------------------------- \s,mn_gda \u,mn_gd \c,---------------------------------------------------------------------------- \i,libgen overview \i,overview of libgen \i,user library \c,---------------------------------------------------------------------------- FTN5UG LIBGEN OVERVIEW Screen 1 of 2 The most efficient method of maintaining compiled programs over an extended period is to store them on a user library created by the LIBGEN utility. Whenever you make a change to a program, you can create a new, updated version of the user library by using the GTR and COPYL or LIBEDIT utilities in conjunction with LIBGEN. These utilities can be used in either batch or interactive environments. Input to LIBGEN consists of a single sequential format file containing the object modules to be included in the user library. You can input the binary file created by a compilation directly to LIBGEN. This file can contain any number of object modules. If necessary, you can use the COPYBR utility to copy separately compiled routines to a single file. Programs to be stored in the user library can be in any language; all need not be FORTRAN programs. Routines input to LIBGEN cab be relocatable (produced by a compiler or assembler call) or they can be absolute (a binary module that has been processed by the loader); they can also be capsule, OVCAP, overlay programs, and CCL procedures. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gd \c,---------------------------------------------------------------------------- FTN5UG LIBGEN OVERVIEW Screen 2 of 2 Output from LIBGEN consists of a user library that the CYBER Loader can use to satisfy external references. Each record of the user library comprises one binary module. You can load selected routines from a user library by specifying the appropriate load sequence prior to execution, as described under index topic LOAD?. Press RETURN to read about Calling LIBGEN. \c,---------------------------------------------------------------------------- \s,mn_gdb \u,mn_gd \c,---------------------------------------------------------------------------- \i,calling libgen \i,libgen control statement \c,---------------------------------------------------------------------------- FTN5UG CALLING LIBGEN Screen 1 of 1 LIBGEN is called by the following control statement: LIBGEN,F=lfn1,P=lfn2,N=libname. The control statement parameters have the following meanings: lfn1 Local file containing binary modules to be made into a user library. Default is LGO. lfn2 Local file to contain the user library. Default is ULIB. libname Name of the user library being created. Default is the name specified by the P parameter. Because a user library created by LIBGEN is usually large, you should save it as a direct access permanent file (using the DEFINE control statement). Press RETURN to read about Creating a New User Library. \c,---------------------------------------------------------------------------- \s,mn_gdc \u,mn_gd \c,---------------------------------------------------------------------------- \i,creating a new user library \i,new user library \i,itemize control statement \c,---------------------------------------------------------------------------- FTN5UG CREATING A NEW USER LIBRARY Screen 1 of 3 The following terminal dialog in illustrates the creation of a user library. File SOURCE contains source programs TEST, ADD, and SUB. This file is input to the FORTRAN compiler to create the binary file required by LIBGEN. /get,source=testf /ftn5,i=source,b=bin,l=0 0.013 CP SECONDS COMPILATION TIME. /define,libfil /libgen,f=bin,p=libfil,n=mylib LIBRARY GENERATION COMPLETE. /itemize,libfil,u The parameter B=BIN on the FTN5 control statement assigns the name BIN to the binary output file. This file is input to LIBGEN, which creates a user library named MYLIB on file LIBFILE. The DEFINE control statement makes the library a direct access permanent file. The ITEMIZE control statement lists information about the user library. (The U parameter must appear on this statement to specify that the file to be listed is in user library format.) Information in this listing is shown on the next screen. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gd \c,---------------------------------------------------------------------------- FTN5UG CREATING A NEW USER LIBRARY Screen 2 of 3 ITEMIZE OF LIBFILE FILE 1 REC NAME TYPE LENGTH CKSUM DATE 1 MYLIB ULIB 11 2675 2 TEST REL 70 5060 3 ADD REL 34 0000 4 SUB REL 34 3637 5 MYLIB OPLD 11 1166 6 * EOF 8 SUM = 202 REC is the record number assigned by LIBGEN. NAME is the record name. The first record is the file directory, and has the same name as the library (as specified by the N parameter). Object programs incorporated as records in the library have the names assigned in the source program (program TEST, subroutine ADD, and so forth). The last record is the file index, and has the same name as the library. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gd \c,---------------------------------------------------------------------------- FTN5UG CREATING A NEW USER LIBRARY Screen 3 of 3 TYPE is the record type. The file directory record is listed as type ULIB. The object programs are type REL, indicating that they are relocatable binary programs. The file index is listed as type OPLD. LENGTH is the record length in octal words. CKSUM is a unique bit sum, assigned to each record, that can be used to determine if errors occurred while writing the record. DATE Date of compilation of the routine. Other information in the list includes the name and version of the operating system, the name and version of the compiler that created the record, and the program unit type of each binary record (main program, subroutine, and so forth). Press RETURN to read about Creating an Updated User Library. \c,---------------------------------------------------------------------------- \s,mn_gdd \u,mn_gd \c,---------------------------------------------------------------------------- \m=a,mn_gdda \m=b,mn_gddb \m=c,mn_gddc \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY Screen 1 of 1 Enter one of the following letters to learn about updating a user library: a. Overview b. Creating a Binary File Using GTR c. Editing a Binary File Using LIBEDIT Press RETURN to read the Overview. Enter UP to return the Program Maintenance menu. \c,---------------------------------------------------------------------------- \s,mn_gdda \u,mn_gdd \c,---------------------------------------------------------------------------- \i,creating an updated user library overview \i,overview of creating an updated user library \i,gtr utility,1 \i,gtr,1 \i,libedit utility,1 \i,libedit,1 \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY OVERVIEW Screen 1 of 3 You cannot modify an existing user library. Therefore, whenever you change a program, you must use LIBGEN to create a new user library from a sequential file containing all the binary modules to be on the library. One alternative is to recompile the entire source program and to input the resulting binary file to LIBGEN. The recommended alternative, however, is to recompile only the changed routines, and to use these compiled routines to create an updated user library as follows: 1. If the sequential file of binary modules originally used to create the user library exists, proceed to step 2. If this file does not exist, as is usually the case, use the GTR utility to create a sequential format binary file from the existing user library. 2. Use the LIBEDIT utility to create an updated sequential binary file from the existing binary file and the file containing the changed routines. 3. Use LIBGEN to create a new, updated user library from the new binary file created in step 2. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gdd \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY OVERVIEW Screen 2 of 3 LIBEDIT allows you to add, replace, and delete records within a sequential file of binary records. The file produced by a FORTRAN compilation or by the GTR utility is such a file, with each compiled program unit (binary module) comprising one record on the file. The record name is the same as the program unit name. In the following discussions of file manipulations, the terms binary module and binary record are used interchangeably when referring to the contents of the files. For the simplest LIBEDIT run, only a LIBEDIT control statement is required. More complicated operations require the specification of special LIBEDIT directives. If the only changes to be made to the existing sequential file are the addition of new programs or the replacement of existing programs with programs of the same name, and if all the new programs reside on the same file, LIBEDIT control statement parameters identify the file to be updated and the file containing the new or replacement modules. Modules in the existing file are replaced by modules of the same name from the replacement file; remaining modules from the replacement file are added to the end of the existing file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gdd \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY OVERVIEW Screen 3 of 3 Other LIBEDIT operations require directives providing detailed instructions to LIBEDIT. For example, deleting modules from a file, inserting new modules at specified locations within a file, and performing operations where the new or replacement modules reside on multiple files, all require LIBEDIT directives. Press RETURN to read about Creating a Binary File User GTR. \c,---------------------------------------------------------------------------- \s,mn_gddb \u,mn_gdd \c,---------------------------------------------------------------------------- \i,creating a binary file using gtr \i,gtr \i,gtr utility \i,gtr control statement \c,---------------------------------------------------------------------------- FTN5UG CREATING A BINARY FILE USING GTR Screen 1 of 1 The GTR utility allows you to create a sequential file of binary records from an existing user library. This capability eliminates the need for saving the binary file used to create the library. You can add, replace, and delete records within the file created by GTR using LIBEDIT. You can then use LIBGEN to create a new user library from the updated binary file. The file created by GTR is a sequential file of binary records in the same format as the binary file created by a FORTRAN compilation. Records on this file are relocatable binary modules (type REL). Although you can use GTR to copy selected records from the existing user library, for most applications it is easier to copy all the binary records from the library, using GTR as a vehicle for converting a user library to a sequential file. The following form of the GTR control statement can be used to perform this operation: GTR,file1,file2.REL/* where file1 is the file containing the user library (default is OLD) and file2 is the sequential format output file (default is NEW). This form of the GTR statement copies all relocatable records from file1 to file2. Press RETURN to read about Editing a Binary File Using LIBEDIT. \c,---------------------------------------------------------------------------- \s,mn_gddc \u,mn_gdd \c,---------------------------------------------------------------------------- \i,editing a binary file using libedit \i,libedit \i,libedit utility \c,---------------------------------------------------------------------------- FTN5UG EDITING A BINARY FILE USING LIBEDIT Screen 1 of 4 You can use the LIBEDIT utility to perform record insertion, deletion, and replacement on a sequential format file of binary records. The file to be updated can be created by a FORTRAN compilation or by the GTR utility. LIBEDIT creates an updated version of the input file which you can input to LIBGEN to create a new user library. LIBEDIT can process records of many different types, including type REL (relocatable), type ABS (absolute), and type OVL (absolute overlay). You can optionally specify detailed processing instructions to LIBEDIT through directives. For interactive processing, these directives are placed on a separate file that can be created by XEDIT; for batch jobs, you can include the directives in the job input stream (file INPUT). The table on the next screen lists the most useful LIBEDIT directives. (The symbol rec refers to a record in the existing file, and rep refers to a record in the update file.) Note that you can insert, delete, or replace records anywhere in the input file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gdd \c,---------------------------------------------------------------------------- \i,type directive \i,type \i,*type \i,libedit type directive \i,before directive \i,before \i,*before \i,libedit before directive \i,after directive \i,after \i,*after \i,libedit after directive \i,delete directive \i,delete \i,*delete \i,libedit delete directive \i,replace directive \i,replace \i,*replace \i,libedit replace directive \c,---------------------------------------------------------------------------- FTN5UG EDITING A BINARY FILE USING LIBEDIT Screen 2 of 4 Directive Format | Function -----------------------------+----------------------------------------------- *TYPE,REL | Indicates that all subsequent directives | refer to type REL (relocatable) records. | This must be the first directive in the | directive file when processing a | FORTRAN-created binary file. | *BEFORE,rec,rep1,...,repn | Inserts replacement records rep1,...,repn | immediately before existing record rec. | *AFTER,rec,rep1,...,repn | Inserts replacement records rep1,...,repn | immediately after existing record rec. | *DELETE,rec1,...,recn | Deletes existing records rec1,...,recn. | *REPLACE,rec1,...,recn | Replaces existing records rec1,...,recn | with records of the same name from the | update file. -----------------------------+----------------------------------------------- Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gdd \c,---------------------------------------------------------------------------- \i,libedit control statement \c,---------------------------------------------------------------------------- FTN5UG EDITING A BINARY FILE USING LIBEDIT Screen 3 of 4 LIBEDIT is called by the following control statement: LIBEDIT,I=lfn1,P=lfn2,N=lfn3,B=lfn4. The control statement parameters have the following meanings: lfn1 Local file containing directives. Default is INPUT. If no directives exist, I=0 must be specified. lfn2 Existing local file to be edited. Default is OLD. lfn3 Updated local file to be created. Default is NEW. lfn4 Local file containing new or replacement records. This file is usually created by a FORTRAN compilation. Default is LGO. If an update file does not exist, B=0 should be specified. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,mn_gdd \n,mn_gdd \c,---------------------------------------------------------------------------- FTN5UG EDITING A BINARY FILE USING LIBEDIT Screen 4 of 4 Directives are not required if the only editing operation to be performed is record replacement. In this case, LIBEDIT processes the input file in the same manner as COPYL. Press RETURN to return to the Creating an Updated User Library menu. \c,---------------------------------------------------------------------------- \s,ld_h \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,ld_ha \m=b,ld_hb \m=c,ld_hc \m=d,ld_hd \m=e,ld_he \m=f,ld_hf \m=g,ld_hg \m=h,ld_hh \c,---------------------------------------------------------------------------- \i,load \i,loading fortran programs \i,loading programs \i,loader \i,cyber loader \c,---------------------------------------------------------------------------- FTN5UG LOADING FORTRAN PROGRAMS Screen 1 of 1 After you have compiled a FORTRAN program, it must be converted to the proper format and placed in memory before it can be executed. These functions are performed by a system utility called the CYBER Loader. Enter one of the following letters to learn more about the loader: a. Overview b. Types of Loading c. The Loading Process d. Load Sequence e. Entering Load Sequences f. Basic Loading g. OVCAPS h. Segment Loading Press RETURN to read the Overview. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,ld_ha \u,ld_h \c,---------------------------------------------------------------------------- \i,loading fortran programs overview \i,overview of loading fortran programs,1 \i,loader input \i,input to the loader \i,loader output \i,load map,1 \i,loader features \i,features of the loader \c,---------------------------------------------------------------------------- FTN5UG LOADING FORTRAN PROGRAMS OVERVIEW Screen 1 of 2 Input to the loader consists of compiled programs and statements specifying various loader options. Loader output consists of an executable program and, optionally, a load map. You can direct the loader either to write the executable program to a disk file or to load the program into memory and begin execution. The simplest type of load occurs when you enter a control statement specifying the name of a file containing the compiled FORTRAN program. (LGO is the default name.) The loader converts the binary program to executable format, loads it into memory, and initiates execution of the loaded program. Additional loader features provide you with the following capabilities: Reduction of execution time field length requirements by dividing large programs into smaller units that need not all be in memory at the same time. Increased program modularity by accessing routines stored on user libraries. (Enter OPM? for a description of user libraries.) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- FTN5UG LOADING FORTRAN PROGRAMS OVERVIEW Screen 2 of 2 Loader features (continued): Faster execution time for repeatedly executed programs by eliminating the necessity for relocation each time the program is loaded and executed. Useful information for program debugging by producing a load map. The loader can be used in a batch as well as an interactive environment. The decision of which loader features to use should be based on the requirements of the particular application. In particular, methods used to reduce field length requirements can increase execution time because of the time required to move programs into and out of central memory. Press RETURN to read about Types of Loading. \c,---------------------------------------------------------------------------- \s,ld_hb \u,ld_h \c,---------------------------------------------------------------------------- \i,types of loading \i,loading types \i,basic loading,1 \i,common type of load \i,overlay loading \i,loading overlays \i,overlay directive \c,---------------------------------------------------------------------------- FTN5UG TYPES OF LOADING Screen 1 of 2 The following types of loading are of particular interest to the FORTRAN programmer: Basic loading. This is accomplished through control statements and consists of loading all the routines required for execution into central memory at the same time. This is the most common type of load, because most programs are small compared to the amount of central memory available. Overlay loading. This is accomplished by OVERLAY directives in the source program. Programs are divided into smaller units called overlays. Overlays are loaded at execution time as directed by calls to the OVERLAY subroutine that you insert in the source program. Because overlays are fully described in the FORTRAN reference manual, they are not described here. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- \i,ovcap loading,1 \i,overlay capsules,1 \i,segment loading,1 \i,loading segments,1 \i,segments,1 \i,field length \i,reducing field length \i,recommended loading method \c,---------------------------------------------------------------------------- FTN5UG TYPES OF LOADING Screen 2 of 2 Loading types of interest of the FORTRAN programmer (continued): OVCAP loading. This is accomplished by OVERLAY and OVCAP directives. Programs are divided into smaller units called OVCAPs (overlay capsules). OVCAPs are loaded and unloaded as needed during execution by special subroutine calls in the source program. The program's field length is dynamically adjusted when an OVCAP is loaded or unloaded. Segment loading. This is accomplished by the SEGLOAD control statement in conjunction with segment directives. Programs are divided into smaller units, called segments, which are organized into tree structures. At execution time, when a segment not already in memory is required, it is loaded automatically. Overlays, segments, and OVCAPs each provide a method of reducing a program's field length requirements; each method has comparative advantages and disadvantages. For most applications, however, OVCAPs is the recommended method because it is the fastest, most flexible, and easiest to use. Press RETURN to read about The Loading Process. \c,---------------------------------------------------------------------------- \s,ld_hc \u,ld_h \c,---------------------------------------------------------------------------- \i,relocate \i,the loading process \i,loading process \i,relocation \i,process of loading \i,relocatable format \i,absolute loads \i,absolute address \i,relative address \c,---------------------------------------------------------------------------- FTN5UG THE LOADING PROCESS Screen 1 of 3 Two processes take place for any kind of loading: relocation and the satisfaction of external references. The object code produced by a FORTRAN compilation is in relocatable format; that is, the addresses of variables and instructions are only temporary and are defined relative to the beginning of the program unit or of a common block. Before the program can be executed, the addresses must be made absolute; that is, defined relative to the beginning of the program's field length. The process of calculating absolute addresses is called relocation, and is performed by the loader. Relocation occurs in different ways, depending on the type of load. For absolute loads, relocation is performed only during the initial load, reducing the time required for subsequent loads. For overlays, OVCAPs, and segments, relocation is performed during the generation process; the overlays, OVCAPs, or segments are loaded without the need for relocation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- \i,external reference \i,calling sequence \i,entry point \i,satisfying external references \c,---------------------------------------------------------------------------- FTN5UG THE LOADING PROCESS Screen 2 of 3 An external reference is a reference by one program unit to an entry point in another program unit. In a FORTRAN program, external references include calls to subroutines and references to function subprograms. (The subroutines and functions can be either user-defined or retrieved from a library.) In addition, input/output statements generate references to FORTRAN Common Library and Record Manager routines. For each external reference encountered, the compiler generates a code sequence, called a calling sequence, which includes a branch to the referenced routine. The compiler, however, does not know the addresses of the referenced entry points. It is the function of the loader to determine the absolute addresses of the referenced entry points and to insert the addresses in the calling sequences of the referencing routines. This process is known as satisfying external references. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- FTN5UG THE LOADING PROCESS Screen 3 of 3 The loader satisfies external references in a file by matching them with entry points within other program units on the same file. If unsatisfied external references remain after this process, the loader attempts to satisfy them by searching available libraries until a matching entry point is found. When a duplicate entry point exists on the same file, or on different files, the loader follows an established search order to determine which entry point to use to satisfy the external reference. (Enter LIB SEARCH? for a description of the process of satisfying external references.) Press RETURN to read about Load Sequences. \c,---------------------------------------------------------------------------- \s,ld_hd \u,ld_h \c,---------------------------------------------------------------------------- \i,load stmts \i,load sequences \i,completion statement \c,---------------------------------------------------------------------------- FTN5UG LOAD SEQUENCES Screen 1 of 2 A load sequence is a sequence of loader control statements that defines the processing for a complete load operation. For any type of load, you must specify a load sequence containing information required by the loader. The simplest load sequence consists of a single statement, such as LGO. However, many operations require a number of statements that provide such information as selected binary modules to be loaded, load map options, and so forth. The following loader statements are described in following topics: name call Loads program and initiates execution. EXECUTE Completes loading process and initiates execution. LOAD Loads contents of specified files. SLOAD Loads specified program units. NOGO Completes loading process but does not initiate execution. LDSET Specifies various loader options. SEGLOAD Specifies that the load is to be a segment load. A load sequence is terminated by a completion statement (EXECUTE, NOGO, or name call statement). Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- \i,load process \i,process of loading \c,---------------------------------------------------------------------------- FTN5UG LOAD SEQUENCES Screen 2 of 2 When the system encounters the first loader statement, the loading process begins. This process involves the following sequence of events: All statements in the load sequence are read. The loader statements are processed in order. Libraries are searched to satisfy external references. Execution field length is determined. The load map is written. Program execution is initiated (unless the sequence is terminated by NOGO). Press RETURN to read about Entering Load Sequences From the Terminal. \c,---------------------------------------------------------------------------- \s,ld_he \u,ld_h \c,---------------------------------------------------------------------------- \i,entering load sequences from the terminal \i,entering load sequences \i,ldr> \i,ldr prompt \i,loader prompt \c,---------------------------------------------------------------------------- FTN5UG ENTERING LOAD SEQUENCES FROM THE TERMINAL Screen 1 of 2 The rules for entering load sequences from the terminal are essentially the same as for specifying them in a batch job. (Enter BLOAD? for a description of batch jobs containing load sequences.) A load sequence begins with the first loader statement and is ended by a loader completion statement; no non-loader statements can intervene (except for MAP and REDUCE). A load sequence is processed as a single unit; that is, the loader first reads all the statements and then processes them in sequential order. When you enter a loader statement (other than a completion statement), the loader reads the statement and issues the following request for another statement: LDR>? You can then enter another loader statement. The loader continues to issue this prompt in response to your entries until you enter a completion statement, at which time processing of the load sequence begins. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_h \c,---------------------------------------------------------------------------- \i,load sequence example \i,example of load sequence \c,---------------------------------------------------------------------------- FTN5UG ENTERING LOAD SEQUENCES FROM THE TERMINAL Screen 2 of 2 The following figure shows a terminal dialog in which a typical load sequence is entered. A FORTRAN program on file SRCE is compiled, and the compiled program is written to file LGO. A load sequence is then entered in which LDSET options are requested, programs are loaded from file BFILE, the program on file LGO is loaded, and execution is initiated. /ftn5,i=srce,l=0 0.004 CP SECONDS COMPILATOIN TIME. /ldset,map=sb,lib=mylib LDR>? load,bfile LDR>? lgo An alternate method of load sequence entry, useful for longer load sequences that are to be executed repeatedly, is to store the sequence on a procedure file and to invoke the procedure file when it is necessary to execute the sequence. Procedure files are described in the NOS reference manual. Press RETURN to read about Basic Loading. \c,---------------------------------------------------------------------------- \s,ld_hf \u,ld_h \c,---------------------------------------------------------------------------- \m=a,ld_hfa \m=b,ld_hfb \m=c,ld_hfc \m=d,ld_hfd \m=e,ld_hfe \m=f,ld_hff \c,---------------------------------------------------------------------------- \i,basic loading \i,basic load \c,---------------------------------------------------------------------------- FTN5UG BASIC LOADING Screen 1 of 1 A basic load has all the object code required for execution placed in memory at the same time; the object code is not divided into smaller units as in overlay, capsule, or segment loading. A basic load is accomplished entirely through control statements, without the need for special loader directives. The load with which most FORTRAN programmers are familiar, performed by the LGO statement, is one form of a basic load. Other more complicated forms of the basic load allow you to load selected program units from any number of files or from libraries. These forms require load sequences containing additional loader control statements. Enter one of the following letters to learn more about basic loading: a. Name Call Loading d. Loading Programs From Libraries b. Loading Programs From Multiple e. Library Search Order Files f. Additional Loader Options c. Terminating a Load Sequence Press RETURN to read about Name Call Loading. Enter UP to return to the Loading FORTRAN Programs menu. \c,---------------------------------------------------------------------------- \s,ld_hfa \u,ld_hf \c,---------------------------------------------------------------------------- \i,name call loading \i,name call \i,name call load \i,simplest type of load \i,simplest load \i,name call statement \i,lgo \i,log statement \c,----------------------------------------------------------------------------- FTN5UG NAME CALL LOADING Screen 1 of 2 The name call load is the simplest type of load. This load is initiated by a name call statement having the following form: name,p1,...,pn. where name is the name of the binary file to be loaded and pi are optional parameters to be passed to the loaded program. The name call statement loads the program units on the specified file into memory, searches libraries to resolve external references, and initiates program execution. If the file contains end-of-partition boundaries, only the first partition is loaded. The file to be loaded must contain at least one main program; if the file contains more than one main program, all are loaded and execution begins with the last one loaded. The LGO statement is the most common form of the name call load. (LGO is the default name of the binary file created by a FORTRAN compilation.) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG NAME CALL LOADING Screen 2 of 2 The optional parameters on the name call statement allow you to: Establish a limit on the maximum number of records that can be written at execution time. Specify values that can be accessed from the program at execution time. Specify Post Mortem Dump output options. (Enter PMD?) Refer to the FORTRAN reference manual for full details on the format and function of these parameters. Press RETURN to read about Loading Programs From Multiple Files. \c,---------------------------------------------------------------------------- \s,ld_hfb \u,ld_hf \c,---------------------------------------------------------------------------- \i,loading programs from multiple files \i,multiple file load \i,loading multiple files \i,load statement \i,load \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM MULTIPLE FILES Screen 1 of 5 The name call load loads and executes programs from a single file. You can load programs from multiple files into a single executable module with the LOAD statement. This statement has the form: LOAD,lfn1,...,lfnn. where lfni is a local file containing program units to be loaded. The LOAD statement loads the entire contents of each of the specified files into your program's field length. Files from which programs are to be loaded must be sequential format binary files, such as the binary file produced by a FORTRAN compilation. Loading stops when an end-of-record, end-of-file, or end-of-information is encountered. The file cannot be a library file. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,execute,1 \i,execute statement,1 \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM MULTIPLE FILES Screen 2 of 5 Unlike the name call load, the LOAD statement does not attempt to satisfy external references within loaded programs and does not initiate execution. These functions are performed by the completion statement in the load sequence. For example, the load sequence: LOAD,LGO. EXECUTE. is equivalent to the name call: LGO. Both sequences load program units from file LGO and begin execution. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,sload statement \i,sload \i,loading selected program units \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM MULTIPLE FILES Screen 3 of 5 You can load selected program units from sequential files with the SLOAD statement. The SLOAD statement has the format: SLOAD,lfn,name1,...,namen. where lfn is the local file from which program units are to be loaded and namei is a program unit to be loaded. As with LOAD, the specified file must be a sequential format binary file. SLOAD does not attempt to satisfy external references and does not initiate program execution. With a name call load, all program units in the program must be on the same file. The LOAD and SLOAD statements are provided so that you can write a program to use other programs that exist on different files; the programs are merged into a single executable unit during the load. For example, if a program unit MAIN calls a subroutine SUBA, a name call requires the compiled versions of MAIN and SUBA to exist on the same file; however, if MAIN and SUBA are on separate files, you can load them into a single executable program with a LOAD or SLOAD statement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM MULTIPLE FILES Screen 4 of 5 Before executing a program, you must be sure that all needed program units that are not in libraries are explicitly loaded by LOAD, SLOAD, or name call, and that at least one main program is loaded. You can include any number of SLOAD or LOAD statements in a load sequence, and you must terminate the sequence with a completion statement (EXECUTE, NOGO, or name call). The following sequence loads all program units on files ABLE, BAKER, and CHARLIE, and begins execution. LOAD,ABLE,BAKER,CHARLIE. EXECUTE. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM MULTIPLE FILES Screen 5 of 5 The following sequence loads program units MAIN and SUB1 from file BB, loads program units SUB2 and SUB3 from file CC, loads the entire contents of file DD, performs a name call load for file BINF, and begins execution. SLOAD,BB,MAIN,SUB1. SLOAD,CC,SUB2,SUB3. LOAD,DD. BINF. Press RETURN to read about Terminating a Load Sequence. \c,---------------------------------------------------------------------------- \s,ld_hfc \u,ld_hf \c,---------------------------------------------------------------------------- \i,terminating a load sequence \i,load sequence terminations \i,completion statement \i,execute \i,execute statement \i,nogo \i,nogo statement \c,----------------------------------------------------------------------------- FTN5UG TERMINATING A LOAD SEQUENCE Screen 1 of 5 You must terminate every load sequence with a completion statement. These statements complete the loading process and specify whether the loaded program is to be executed. The completion statements are: name call EXECUTE. NOGO. The completion statements all perform the following functions: Search libraries to resolve external references. Generate absolute addresses in the loaded programs. Set execution time field length. Write the load map. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,name call statement \i,name call \c,---------------------------------------------------------------------------- FTN5UG TERMINATING A LOAD SEQUENCE Screen 2 of 5 In batch jobs, the completion statements must contain a period as the last character; the period is optional in interactive sessions. When used as a completion statement, the name call statement performs the preceding functions, loads the contents of the named file, and initiates execution of the resulting program. If the load sequence contains two or more statements, the name call can be an entry point name. In this case, the loader searches for the program containing the named entry point. The following example illustrates a load sequence terminated by a name call statement: LOAD,F1,F2. LGO. This sequence loads object programs from files F1 and F2. If LGO is a load file, the modules on LGO are loaded; if LGO is an entry point in a load file, the module containing LGO is loaded. In either case, the completion functions are performed and execution begins. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,execute statement \i,execute \c,---------------------------------------------------------------------------- FTN5UG TERMINATING A LOAD SEQUENCE Screen 3 of 5 The EXECUTE statement performs the preceding completion functions and initiates execution of the resulting absolute program. This statement has the form: EXECUTE,eptname,p1,...,pn. where eptname is the optional name of an entry point where execution is to begin, and pi is an optional parameter having the same format and function as the parameters for the name call statement. Unlike the name call statement, EXECUTE is only used to terminate a load sequence; it cannot be specified by itself. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,nogo statement \i,nogo \c,---------------------------------------------------------------------------- FTN5UG TERMINATING A LOAD SEQUENCE Screen 4 of 5 The process of searching libraries and generating absolute addresses can be time-consuming. The NOGO statement provides a means of reducing the amount of load time required for multiple executions of the same program by saving the loaded program on a separate file. This statement has the form: NOGO,lfn. The NOGO statement performs the same functions as the EXECUTE statement except that NOGO does not initiate execution. Upon completion of the load, the absolute program is written to the specified file. This file can subsequently be loaded into memory (usually by a name call statement) and executed; however, the time required to load this absolute file is much less than that required for a relocatable file. The NOGO statement is especially useful for programs that are to be executed many times. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG TERMINATING A LOAD SEQUENCE Screen 5 of 5 For example, the load sequence: LOAD,PROG. NOGO,SAVEF. loads programs on file PROG and writes the resulting absolute program to file SAVEF. The saved program can subsequently be executed by the following name call: SAVEF. Press RETURN to read about Loading Programs From Libraries. \c,---------------------------------------------------------------------------- \s,ld_hfd \u,ld_hf \c,---------------------------------------------------------------------------- \i,load lib \i,loading programs from libraries \i,libraries \i,system library \i,system libraries \i,system interface routines \i,interface routines \i,default system library \i,syslib \i,local library set \i,local library \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 1 of 7 You can load and execute binary programs from user libraries and from system libraries. Unlike routines on files, you do not need to load library routines explicitly; the loader searches libraries and loads the required routines in the process of satisfying external references. However, you must be sure that the needed libraries are available to the loader before you initiate the loading process. System libraries contain system interface routines commonly required by most FORTRAN and other programs. The default system library, SYSLIB, is a permanent part of the operating system and is, by default, always available to the loader. Other system libraries, such as FTN5LIB, reside on mass storage; these libraries are read into memory as needed and automatically become part of the local library set. The central library directory is a system library that contains many commonly used programs such as the FORTRAN 5 compiler. The set of system libraries that exists on a system is a site option. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,user library \i,user libraries \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 2 of 7 User libraries are created from sequential files of binary modules using the LIBGEN utility (enter OPM?). You must explicitly establish user libraries before they can be accessed by the loader. When the completion statement in the load sequence initiates the loading completion process, the loader satisfies as many external references as possible with routines that have already been loaded into memory (by LOAD or SLOAD statements). If any unsatisfied external references remain, the loader searches for the referenced routines on the libraries that are available to it. If you have not explicitly made any libraries available to the loader, only the system libraries are searched. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,library control statement \i,library statement \i,library \i,adding libraries \i,deleting libraries \i,replace global library \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 3 of 7 You can make user libraries available to the loader with the LIBRARY control statement and with the LDSET loader statement. The LIBRARY control statement has the form: LIBRARY,lfn1,...,lfnn/p. where lfni is a local file containing a user library. The P parameter specifies one of the following options: A Add the specified library or libraries to the global library set D Delete the specified library or libraries from the global library set R Replace the global library set with the library set specified on the control statement. R is the default option. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,global library set \i,clear global library set \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 4 of 7 The LIBRARY statement is a system control statement, and not a loader statement; you cannot use it in a load sequence. The libraries specified in a LIBRARY statement are called the global library set; these libraries remain in effect until you either end the terminal session or enter another LIBRARY statement. When you enter a LIBRARY statement, the effects of a previous LIBRARY statement are canceled unless you use options A or D. The maximum number of libraries that can be contained in the global library set is two user and two system libraries, one user and 13 system libraries, or 0 user and 24 system libraries. You can clear the global library set by entering a LIBRARY statement with no parameters: LIBRARY. After you enter this statement, the only libraries available to the loader are SYSLIB and any libraries in the local library set. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 5 of 7 The following example illustrates LIBRARY statements used with name call loads. This example assumes the existence of libraries ALIB, BLIB, and CLIB, and binary files LGO1, LGO2, and LGO3: LIBRARY,ALIB,CLIB. LGO1. LIBRARY,CLIB. LGO2. LIBRARY. LGO3. The name call LGO1 searches libraries ALIB and BLIB and the default system library SYSLIB to satisfy external references. The name call LGO2 searches library CLIB and SYSLIB. The name call LGO3 searches only SYSLIB. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,local library set \i,ldset statement \i,ldset \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 6 of 7 The LDSET statement has the form: LDSET,LIB=lfn1/.../lfnn. where lfni is the local file name of a file containing a user library. The LDSET statement is a loader statement and can only be used within a load sequence. Libraries specified in LDSET statements comprise the local library set and are available only to the load sequence in which the LDSET statements appear. You can include any number of LDSET statements in a load sequence; all libraries specified in the statements become part of the local library set. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG LOADING PROGRAMS FROM LIBRARIES Screen 7 of 7 LDSET statements can appear anywhere within a load sequence. When the completion statement is encountered, the libraries are searched in the order of their appearance. For example, in the load sequence: LDSET,LIB=LIB1/LIB2. LOAD,LGO. LOAD,BIN. EXECUTE. binary programs from LGO and BIN are loaded, libraries LIB1, LIB2, and SYSLIB are searched, and execution is initiated. Press RETURN to read about Libraray Search Order. \c,---------------------------------------------------------------------------- \s,ld_hfe \u,ld_hf \c,---------------------------------------------------------------------------- \i,lib search \i,library search order \i,satisfying external references \i,external references \i,satisfy external reference \i,search order \i,library search order \c,---------------------------------------------------------------------------- FTN5UG LIBRARY SEARCH ORDER Screen 1 of 4 In the process of satisfying external references or locating an entry point for a name call statement, ambiguity can arise when the same entry point or program name occurs more than once within libraries available to the loader. For this reason, a rigorous search order has been established. Thus, in the event of duplicate entry points, you can usually determine which entry point will be used to satisfy a given external reference. The search order for external references is: Global library set (includes libraries specified in LIBRARY statements) Local library set (includes libraries specified in LDSET statements and certain system libraries) SYSLIB (system default library) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,search order \c,---------------------------------------------------------------------------- FTN5UG LIBRARY SEARCH ORDER Screen 2 of 4 The search order for the name call statement is: Local files Global library set Local library set Central library directory Within each library set, libraries are searched in the order that they were included in the set. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- FTN5UG LIBRARY SEARCH ORDER Screen 3 of 4 If the loading of programs from libraries produces new external references that must be satisfied from the library set, these references are satisfied when the appropriate entry point or program is encountered during the search. If the end of all the library sets is encountered, and unsatisfied references remain, the search begins again. This circular search continues until either all references have been satisfied, or the entire library set has been searched once with no new satisfaction of references. If unsatisfied external references exist at the completion of a load, an informative message is displayed. A fatal execution error results if a statement containing an unresolved external reference is executed. The next screen illustrates two examples of library search order. These examples show terminal dialog in which a LIBRARY statement and a load sequence are entered. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,search order example \i,example of search order \c,---------------------------------------------------------------------------- FTN5UG LIBRARY SEARCH ORDER Screen 4 of 4 In example 1, the global library set consists of ALIB and BLIB. No user libraries are explicitly assigned to the local library set; however, if any system libraries are required by the program, they will automatically be included in the local library set. In example 2, the global library set contains ULIB and the local library set contains ZLIB (and any system libraries required). The default system library is SYSLIB. Example 1 Example 2 ----------- ----------- LIBRARY,ALIB,BLIB. LIBRARY,ULIB. LOAD,BIN1,BIN2. LDSET,LIB=ZLIB. EXECUTE LOAD,LGO. EXECUTE. Search Order: Search Order: ALIB ULIB BLIB ZLIB SYSLIB SYSLIB Press RETURN to read about Additional Loader Options. \c,---------------------------------------------------------------------------- \s,ld_hff \u,ld_hf \c,---------------------------------------------------------------------------- \i,additional loader options \i,loader options \i,ldset \i,ldset statement \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL LOADER OPTIONS Screen 1 of 4 Additional loader and control statements allow you to specify various loader options. One of the most useful loader statements is the LDSET statement. This statement controls a number of loader options, including presetting unused memory, selectively loading or omitting routines, setting the default rewind indicator, controlling the load map, and establishing a local library set. These capabilities are described in detail in the Loader reference manual; two particularly useful options are described here. The general form of the LDSET statement is: LDSET,option1,...,optionn. LDSET is a loader statement and can only be specified within a load sequence. The MAP and ERR options are described in the following paragraphs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,map \i,map option \i,load map \i,load map options \i,lsdet map \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL LOADER OPTIONS Screen 2 of 4 The MAP option controls the contents and destination of the load map produced by the loader. (Default load map options are established by the site. In most cases, you must enter the MAP control statement in order to obtain a load map. The map is displayed at the terminal in an interactive environment, or printed on the output listing in a batch environment.) The LDSET,MAP option is useful because it allows you to write the load map to a separate file instead of displaying it at the terminal. This is a practical alternative for interactive sessions since the map generally contains a large volume of information, even for smaller programs. The option to write a load map to a file has the form: LDSET,MAP=SB/lfn. where lfn is the local file to receive the map. You can make this file permanent, send it to a batch printer, or display portions of it using a text editor such as XEDIT. If you omit /lfn, the map is written to file OUTPUT (interactive terminal display or batch output listing). The load map can be voluminous; refer to the Loader reference manual for LDSET specifications to limit the size of the map. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \c,---------------------------------------------------------------------------- \i,cyber interactive debug \i,cid \i,list map \i,load map summary \i,err parameter \i,error severity level \i,severity level of errors \i,ldset err \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL LOADER OPTIONS Screen 3 of 4 If you want to view the load map at the terminal, CYBER Interactive Debug provides a helpful feature. Initiate debug mode and begin the debug session, and enter the command LIST,MAP. CID displays a load map summary formatted for terminal display. Refer to the Loader reference manual for a detailed description of load map contents. The ERR parameter on the LDSET statement controls the error severity level that will prevent the loaded program from executing. This option has the form: LDSET,ERR=p. where p is one of the following: ALL Program aborts for catastrophic, fatal, and nonfatal errors. FATAL Program aborts for catastrophic and fatal errors. NONE Program aborts only for catastrophic errors. The default is a site option. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hf \n,ld_hf \c,---------------------------------------------------------------------------- FTN5UG ADDITIONAL LOADER OPTIONS Screen 4 of 4 The loader diagnoses three levels of errors. An error that would completely preclude correct execution is diagnosed as a catastrophic error. Errors for which there is a chance of correct execution, or for which the loader can take corrective action, are diagnosed as fatal or nonfatal. The ALL option is recommended for programs that are time-consuming to execute or that change files in a manner difficult to reconstruct. If a fatal or nonfatal loader error occurs for such a program, the program might begin execution and then abort because of a condition diagnosed by the loader as fatal or nonfatal. If you select the ALL option, however, the program does not begin execution; no execution time is wasted and no files are altered. Although most nonfatal loader errors are not likely to affect execution, some can have adverse effects. For example, an unsatisfied external reference is a nonfatal error. However, this error causes the program to abort only if the statement containing the error is actually executed. Press RETURN to return to the Basic Loading menu. \c,---------------------------------------------------------------------------- \s,ld_hg \u,ld_h \p,ld_h \c,---------------------------------------------------------------------------- \m=a,ld_hga \m=b,ld_hgb \m=c,ld_hgc \m=d,ld_hgd \m=e,ld_hge \m=f,ld_hgf \c,---------------------------------------------------------------------------- \i,ovcaps \i,overlay capsule \c,---------------------------------------------------------------------------- FTN5UG OVCAPS Screen 1 of 1 An OVCAP (overlay capsule) is a collection of one or more binary modules specially formatted to allow rapid loading and unloading at execution time. Like overlays and segments, OVCAPs allow you to divide a program into smaller units, store the units on a disk file, and bring them into central memory when they are required during execution. When an OVCAP in memory is no longer needed, it can be unloaded; the area in memory formerly occupied by the unloaded OVCAP is available for other uses. Individual OVCAPs are loaded, executed, and unloaded by explicit calls to special subroutines. Enter one of the following letters to learn more about OVCAPs: a. Overview b. Creating OVCAPs c. Common Blocks and OVCAPs d. Summary of OVCAP Generation e. Loading, Executing, and Unloading OVCAPs f. Structuring and OVCAP Program Press RETURN to read the Overview. Enter UP to return to the Loading FORTRAN Programs menu. \c,---------------------------------------------------------------------------- \s,ld_hga \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcaps overview \i,overview of ovcaps,1 \i,ovcap advantages \i,advantages of ovcaps \i,using ovcaps,1 \i,ovcap use,1 \c,---------------------------------------------------------------------------- FTN5UG OVCAPS OVERVIEW Screen 1 of 4 You can use OVCAPs as a supplement or as an alternative to overlays; in fact, you can easily modify an existing overlay program to use OVCAPs. An OVCAP is similar to a primary overlay in that it requires the presence of a main overlay in memory. Unlike overlays, however, OVCAPs do not overwrite existing code when loaded in to memory, and they can be unloaded when no longer needed. A primary advantage of OVCAPs is that the method is easy to learn and incorporate into a FORTRAN program. To use OVCAPs, you must make the following changes to your source program: Precede the PROGRAM statement by an OVERLAY directive to designate a main overlay. Include OVCAP directives at desired points. These directives determine which routines are placed in a particular OVCAP during OVCAP generation. Include special subroutine calls, as desired, to load, execute, and unload the OVCAPs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG OVCAPS OVERVIEW Screen 2 of 4 OVCAPs, overlays, and segments each allow you to reduce the amount of memory required by a program. Each method has comparative advantages; however, for most applications, OVCAPs are recommended. Some additional advantages of OVCAPs are: Flexible memory structure. OVCAPs offer a much less restrictive memory structure than either overlays or segments. Overlays are restricted to three levels which must be loaded in a predetermined order. Segments provide more flexibility than overlays, but impose a hierarchical tree structure which can become unwieldy. OVCAPs, however, require no complicated program structure nor do they have any special interrelationships. You can load any number of OVCAPs into memory at any time and in any order. An OVCAP can load, execute, and unload other OVCAPs, and the only limit to the number of OVCAPs that can be in memory at a given time is the amount of available memory. Further, a routine in an OVCAP can reference a routine in any other OVCAP; the only restriction is that both OVCAPs must be in memory. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,field length \i,cmm \i,common memory manager \i,dynamic relocation \i,relocatable unit \c,---------------------------------------------------------------------------- FTN5UG OVCAPS OVERVIEW Screen 3 of 4 Advantages of OVCAPs (continued): More efficient use of central memory. Unlike segments or overlays, you can unload an OVCAP that is no longer required for execution. Execution time field length is controlled dynamically by Common Memory Manager (CMM). When you unload an OVCAP, the vacated area of memory is immediately available to the program. If the unloaded OVCAP resided at the end of the field length, the field length is reduced by the length of the OVCAP and the vacated area is available to the operating system. With overlays, the program's field length must be large enough to accommodate the largest overlay. Dynamic relocation. Each OVCAP is a relocatable unit and can be loaded at an arbitrary address during execution. Both overlays and segments are absolute and must be loaded at a specific address. Can be used with existing programs. Segments, overlays, and OVCAPs can be built from previously compiled programs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap disadvantages \i,disadvantages of ovcaps \c,---------------------------------------------------------------------------- FTN5UG OVCAPS OVERVIEW Screen 4 of 4 There are several disadvantages to using OVCAPs. As with either overlays or segments, you achieve reduced field length at the expense of increased execution time. Whether the tradeoff is worthwhile depends on the particular application. Also, like overlays, OVCAPs must be called into memory explicitly; segments are loaded automatically as needed. Press RETURN to read about creating OVCAPs. \c,---------------------------------------------------------------------------- \s,ld_hgb \u,ld_hg \c,---------------------------------------------------------------------------- \i,creating ovcaps \i,ovcap creation \i,overlay directive,1 \i,overlay,1 \i,ov parameter \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 1 of 11 OVCAPs require a main overlay to be in memory at all times. The main overlay must contain one and only one main program, but it can contain multiple subprograms. As with a normal overlay program, the OVERLAY directive must appear immediately before the PROGRAM statement in the load file. The following special form of the OVERLAY directive is used to generate a main overlay for an OVCAP program: OVERLAY(file,0,0,OV=n) where file is the file to which the main overlay and subsequent OVCAPs are to be written, and n is the number of OVCAPs to be generated. The presence of the OV parameter causes the overlay to be generated in a format suitable for use with OVCAPs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap directive \i,ovcap \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 2 of 11 An OVCAP is generated when the loader encounters an OVCAP directive in a load file. This directive has the form: OVCAP. The period is a required part of the directive. The OVCAP includes all routines following the OVCAP directive, until either the end of the last load file or another OVCAP directive is encountered. Routines are placed in the OVCAP in the order of their occurrence in the load file. Routines to be placed in an OVCAP must be subroutines or function subprograms; main programs are not allowed. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,external references \i,satisfying external references \i,search order \i,relocation process \i,relocation \i,relocating \i,relocate \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 3 of 11 External references are resolved during OVCAP generation in a manner similar to a basic load. For each OVCAP, the loader attempts to satisfy external references by searching for the entry points within the OVCAP. If unsatisfied external references remain after this process is completed, the local and global library sets are searched. The search order is the same as for a basic load. You can force load routines directly from libraries with LIBLOAD statements; as with LOAD and SLOAD statements, routines specified on LIBLOAD statements are placed in the OVCAP currently being built. If any external references remain unsatisfied after the library search, the loader attempts to satisfy them at execution time with entry points in other OVCAPs. Unlike an overlay or a segment, an OVCAP is a relocatable unit. However, the relocation process for OVCAPs differs from that of a basic load. During OVCAP generation, individual routines within an OVCAP are relocated with respect to the beginning of the particular OVCAP. A special relocation table is generated for each OVCAP, which allows the OVCAP to be loaded at an arbitrary address when it is called into memory at execution time. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,load sequence \i,load sequence for ovcap \i,ovcap load sequence \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 4 of 11 After an OVCAP is built, it is written to the same file as the main overlay. A load sequence for an OVCAP generation does not require any special statements; the entire OVCAP generation process is controlled by the presence of the single OVERLAY directive and the OVCAP directives in the load files. If all the binary routines to be included in the OVCAPs are on a single load file, you can generate the OVCAPs and initiate program execution with a name call statement specifying the name of the load file. The OVCAPs are generated according to the OVCAP directives contained in the load file, the main overlay and OVCAPs are written to the file specified in the OVERLAY directive, the main overlay is loaded into memory, and execution begins at the main entry point of the main overlay. To initiate subsequent executions of the same program (without repeating the OVCAP generation process), you must name call the file containing the main overlay and OVCAPs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 5 of 11 You can build OVCAPs from multiple files by specifying LOAD and SLOAD statements in the load sequence. Routines on binary files specified in LOAD, SLOAD, and name call statements are always placed in the OVCAP currently being built. Whenever the loader encounters an OVCAP directive while processing a load file, the current OVCAP terminates and a new one begins. The load sequence must be terminated by a NOGO, an EXECUTE, or a name call statement. If a name call is used, the specified file is included in the OVCAP generation process, the main overlay is loaded into memory, and execution is initiated at the main entry point of the main overlay. If the sequence is terminated by EXECUTE, the main overlay is loaded, and execution begins at the specified entry point or at the main entry point if none is specified. If the sequence is terminated by NOGO, or for subsequent executions following a name call or EXECUTE, execution is initiated by name calling the file (specified on the OVERLAY directive) containing the main overlay and OVCAPs. You cannot specify a file name on a NOGO statement that terminates a load sequence for an OVCAP generation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap generation example \i,example of ovcap generation \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 6 of 11 The figure on the next screen illustrates a simple OVCAP generation example. The single load file LGO contains a main program and three subroutines. An OVERLAY directive, preceding the PROGRAM statement, identifies the main overlay and specifies that the overlay and OVCAPs are to be written to file OVFILE and that the structure is to contain two OVCAPs. The first OVCAP is to contain subroutine SUB1, and the second OVCAP is to contain subroutines SUB2 and SUB3. Execution of the load sequence causes the OVCAPs to be generated. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 7 of 11 Load File: OVERLAY (OVFILE,0,0,OV=2) PROGRAM MAIN : END OVCAP. SUBROUTINE SUB1 : END OVCAP. SUBROUTINE SUB2 : END SUBROUTINE SUB3 : END Load Sequence: LGO Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap generation example \i,example of ovcap generation \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 8 of 11 The figure on this and the next screens shows a more complicated example of OVCAP generation. An OVCAP program is generated from three load files. File LGO contains an OVERLAY directive followed by a main program. File BIN1 contains an OVCAP directive followed by subroutine SUB1. File BIN2 contains an OVCAP directive followed by subroutine SUB2. File BIN3 contains subroutines SUB3 and SUB4, and no OVCAP directives. File LGO: OVERLAY(AFILE,0,0,OV=3) PROGRAM MAIN CALL LOVCAP('SUB2') CALL XOVCAP('SUB1') . . . END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 9 of 11 OVCAP Generation Example (continued): File BIN1: OVCAP. SUBROUTINE SUB1 CALL SUB2 . . . END File BIN2: OVCAP. SUBROUTINE SUB2 CALL SUB3 . . . END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 10 of 11 OVCAP Generation Example (continued): File BIN3: SUBROUTINE SUB3 . . . END SUBROUTINE SUB4 . . . END Load Sequence: LOAD(LGO,BIN1,BIN2) SLOAD(BIN3,SUB3) NOGO. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG CREATING OVCAPS Screen 11 of 11 The load sequence causes the following events to occur: 1. A main overlay, containing program MAIN, is generated and written to file AFILE. The call to LOVCAP in MAIN will cause OVCAP SUB2 to be loaded at execution time. The call to XOVCAP will cause OVCAP SUB1 to be loaded and executed. 2. An OVCAP containing subroutine SUB1 is written to file AFILE. SUB1 contains a call to SUB2; however, since SUB2 is in a different OVCAP, the reference is not satisfied until SUB2 is loaded at execution time. 3. An OVCAP containing subroutines SUB2 and SUB3 is written to file AFILE. The SLOAD statement causes SUB3 to be placed into the OVCAP containing SUB2 (because that OVCAP is being built when the SLOAD is encountered). SUB3 satisfies the external reference in SUB2. SUB4 is not placed in the OVCAP. Press RETURN to read about Common Blocks and OVCAPS. \c,---------------------------------------------------------------------------- \s,ld_hgc \u,ld_hg \c,---------------------------------------------------------------------------- \i,common blocks and ovcaps \i,common blocks \i,ovcaps and command blocks \c,---------------------------------------------------------------------------- FTN5UG COMMON BLOCKS AND OVCAPS Screen 1 of 1 Common blocks are linked through the main overlay. Common blocks that have the same name but are in different OVCAPs are local to the containing OVCAP and cannot communicate values among OVCAPs, unless the common blocks reside in the main overlay. If a common block is defined in the main overlay, occurrences of that common block in different OVCAPs are linked and can communicate values. Press RETURN to read the Summary of the OVCAP Generation Process. \c,---------------------------------------------------------------------------- \s,ld_hgd \u,ld_hg \c,---------------------------------------------------------------------------- \i,summary of ovcap generation \i,ovcap generation summary \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF THE OVCAP GENERATION PROCESS Screen 1 of 2 During OVCAP generation, the loader performs the following sequence of steps: 1. Generates a main overlay and writes it to the specified file. 2. Generates OVCAPs according to OVCAP directives contained in the load files specified in the load sequence and writes the OVCAPs to the same file as the main overlay. 3. Generates tables for each OVCAP, to be used by the loader when the OVCAP is loaded at execution time. 4. Links common blocks in the OVCAPs to common blocks of the same name in the main overlay. Common blocks specified in an OVCAP but not in the main overlay are local to the defining OVCAP. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG SUMMARY OF THE OVCAP GENERATION PROCESS Screen 1 of 2 5. Resolves external references within each OVCAP by searching (in the order listed): Entry points within the OVCAP LOAD and SLOAD statements Library set Press RETURN to read about Loading, Executing, and Unloading OVCAPS. \c,---------------------------------------------------------------------------- \s,ld_hge \u,ld_hg \c,---------------------------------------------------------------------------- \m=a,ld_hgea \m=b,ld_hgeb \m=c,ld_hgec \m=d,ld_hged \c,---------------------------------------------------------------------------- \i,loading executing and unloading ovcaps \i,loading ovcaps \i,executing ovcaps \i,unloading ovcaps \i,ovcap loading \i,ovcap executing \i,ovcap unloading \c,---------------------------------------------------------------------------- FTN5UG LOADING, EXECUTING, AND UNLOADING OVCAPS Screen 1 of 1 Enter one of the following letters to learn more about loading, executing, and unloading OVCAPS: a. Overview b. Subroutine XOVCAP - Loads and Executes an OVCAP c. Subroutine LOVCAP - Loads an OVCAP d. Subroutine UOVCAP - Unloads an OVCAP Press RETURN to read the Overview. \c,---------------------------------------------------------------------------- \s,ld_hgea \u,ld_hg \c,---------------------------------------------------------------------------- \i,loading ovcaps overview \i,executing ovcaps overview \i,unloading ovcaps overview \i,overview of loading ovcaps,1 \i,overview of executing ovcaps,1 \i,overview of unloading ovcaps,1 \i,ovcap loading \i,loading ovcaps \i,field length \i,cross linking \c,---------------------------------------------------------------------------- FTN5UG LOADING, EXECUTING, AND UNLOADING OVCAPS OVERVIEW Screen 1 of 3 When an OVCAP is loaded into central memory, the following sequence of events occurs: If necessary, the program's field length is increased by the length of the OVCAP. The OVCAP is loaded into the field length beginning at the first available location. Absolute addresses are generated for modules within the OVCAP. Unsatisfied external references within the OVCAP are satisfied by checking the entry points of all currently loaded OVCAPs. Unsatisfied external references within the currently loaded OVCAPs are satisfied by checking the entry points of the newly loaded OVCAP. This process is known as cross linking, and allows routines within an OVCAP to reference entry points within any other loaded OVCAP. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hge \c,---------------------------------------------------------------------------- \i,common memory manager \i,cmm \c,---------------------------------------------------------------------------- FTN5UG LOADING, EXECUTING, AND UNLOADING OVCAPS OVERVIEW Screen 2 of 3 Field length control during execution is performed by Common Memory Manager (CMM). When an OVCAP is loaded, CMM allocates the required space. If necessary, CMM increases the program's field length by the length of the OVCAP. When an OVCAP is unloaded, the space is returned to CMM; if the space is at the end of the field length, the field length is decreased by the length of the OVCAP. External references to entry points within the unloaded OVCAP become unresolved. A loaded OVCAP can reference entry points within any other loaded OVCAP. For example, if both OVCAPs SUB1 and SUB3 are in memory, then any routine in SUB1 could call any routine in SUB3, and any routine in SUB3 could call any routine in SUB1. An attempt to reference an entry point in an unloaded OVCAP causes a fatal error. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hge \c,---------------------------------------------------------------------------- \i,xovcap,1 \i,xovcap subroutine,1 \i,lovcap,1 \i,lovcap subroutine,1 \i,uovcap,1 \i,uovcap subroutine,1 \c,---------------------------------------------------------------------------- FTN5UG LOADING, EXECUTING, AND UNLOADING OVCAPS OVERVIEW Screen 3 of 3 OVCAPs are loaded, executed, and unloaded by explicit calls to special subroutines provided by FORTRAN. You can call the subroutines at any point in your program where you want to perform one of these operations. Three subroutines are available: XOVCAP Loads and executes an OVCAP LOVCAP Loads an OVCAP UOVCAP Unloads an OVCAP Each subroutine call must specify, as an argument in character string format, the name of the OVCAP for which the operation is to be performed. An OVCAP is always referenced by the name of the first routine on the OVCAP. Thus, in order to use the subroutine calls, you must know which routine is the first one in the OVCAP. Press RETURN to read about Subroutine XOVCAP. \c,---------------------------------------------------------------------------- \s,ld_hgeb \u,ld_hge \c,---------------------------------------------------------------------------- \i,subroutine xovcap \i,xovcap \i,ovcap loading \i,loading ovcaps \i,ovcap execution \i,executing ovcaps \i,call xovcap \c,---------------------------------------------------------------------------- FTN5UG SUBROUTINE XOVCAP Screen 1 of 1 Subroutine XOVCAP begins execution of the first routine in the specified OVCAP. If the specified OVCAP is not in memory, XOVCAP loads it and then transfers control to the first routine in the OVCAP. The call to XOVCAP has the form: CALL XOVCAP('name',p1,...,pn) where name is the OVCAP to be executed (that is, the first routine in the OVCAP), and pi is an optional parameter to be passed to the named routine. (The list of parameters p1 through pn must correspond to the SUBROUTINE argument list.) When execution of the specified routine is complete, control returns to the statement following the call to XOVCAP; the OVCAP remains in memory. A call to XOVCAP can appear in the main overlay or in an OVCAP. Note that XOVCAP allows entry to an OVCAP only through the first routine in the OVCAP. Press RETURN to read about Subroutine LOVCAP. \c,---------------------------------------------------------------------------- \s,ld_hgec \u,ld_hge \c,---------------------------------------------------------------------------- \i,subroutine lovcap \i,lovcap \i,loading ovcaps \i,ovcap loading \i,call lovcap \c,---------------------------------------------------------------------------- FTN5UG SUBROUTINE LOVCAP Screen 1 of 2 Subroutine LOVCAP loads the specified OVCAP into memory but does not begin execution of the OVCAP. The call to LOVCAP has the form: CALL LOVCAP('name') where name is the OVCAP to be loaded. In most cases, you will probably use XOVCAP to load and execute an OVCAP. However, instances can arise where it is desirable to load an OVCAP but not immediately execute it. One reason for doing this is to enter an OVCAP at an entry point other than the first one. You can do this by using LOVCAP to load the OVCAP, and using a normal subroutine call to enter the desired subroutine. For example, OVCAP SUB1 contains subroutine SUB1, and OVCAP SUB2 contains subroutines SUB2 and SUB3. OVCAP SUB2 could be entered at entry point SUB3 by including the following statements in subroutine SUB1: CALL LOVCAP('SUB2') CALL SUB3 Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hge \c,---------------------------------------------------------------------------- FTN5UG SUBROUTINE LOVCAP Screen 2 of 2 This method of entering an OVCAP is valid only from another OVCAP; an OVCAP can be entered from the main overlay only by a call to XOVCAP. The implication of this is that an OVCAP can be entered from the main overlay only through the first entry point of the OVCAP. Note that in the preceding example, the statement CALL XOVCAP('SUB3') would be invalid, because XOVCAP allows entry only through the first entry point of an OVCAP. Another reason for using LOVCAP is that LOVCAP provides more control over the memory layout of your program by allowing you to force load OVCAPs in a specific order before executing them (possibly in a different order). For example, you might load a small OVCAP that is to be in memory for a long period of time before loading a larger OVCAP that is to be in memory for a shorter period of time. When you unload the larger OVCAP, CMM will reduce the field length. Press RETURN to read about Subroutine UOVCAP. \c,---------------------------------------------------------------------------- \s,ld_hged \u,ld_hge \n,ld_hge \c,---------------------------------------------------------------------------- \i,subroutine uovcap \i,uovcap \i,ovcap unloading \i,unloading ovcaps \i,call uovcap \c,---------------------------------------------------------------------------- FTN5UG SUBROUTINE UOVCAP Screen 1 of 1 Subroutine UOVCAP unloads an OVCAP from central memory. The call to UOVCAP has the form: CALL UOVCAP('name') where name is the OVCAP to be unloaded. After an OVCAP is unloaded, the field length of the program is reduced (if the OVCAP is at the end of the field length) and the space is available for other uses. Press RETURN to return to the Loading, Executing, and Unloading OVCAPS menu. \c,---------------------------------------------------------------------------- \s,ld_hgf \u,ld_hg \p,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap prog \i,structuring an ovcap program \i,ovcap program structure \i,guidelines for ovcap use \i,ovcap use guidelines \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 1 of 10 When writing a program to use OVCAPs, you should be aware of some guidelines and restrictions in order to make the best possible use of OVCAPs. In following these guidelines, however, you should keep in mind that the loading and unloading of OVCAPs are expensive operations in terms of execution time (each load operation requires a disk access). The linking or delinking performed during each load or unload does not require a significant amount of time. An extreme example is a long program, consisting of many subprograms, in which each subprogram is made an OVCAP. Such a program would require a minimum amount of memory but would require an extensive amount of load time. Thus, when writing an OVCAP program, you must give careful consideration to the system resources that are available to you. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap restrictions \i,restrictions on ovcap use \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 2 of 10 Some important restrictions for writing a program to use OVCAPs are as follows: You can enter an OVCAP from the main overlay only through the first entry point (by calling XOVCAP); a subroutine call in the main overlay to a routine in an OVCAP is not valid, even if the OVCAP is in memory. If a subroutine within an OVCAP calls a subroutine within another OVCAP, both OVCAPs must be in memory. If an OVCAP transfers control to another OVCAP, the called OVCAP should not attempt to unload the calling OVCAP. The reason for this is that when the RETURN statement in the called OVCAP is executed, the calling OVCAP must be in memory; otherwise, a branch to an unknown address occurs. The figure on the next screen illustrates this type of situation. By extension, in a chain of called OVCAPs, a higher level OVCAP should not attempt to unload a lower level OVCAP. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,ovcap call return conflict example \i,example of ovcap call return conflict \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 3 of 10 OVCAP Call-Return Conflict Example: OVERLAY(XXX,0,0,OV=2) PROGRAM YYY : CALL XOVCAP('A') In this example, the main overlay calls : OVCAP A, and OVCAP A calls OVCAP B. OVCAP B END then unloads OVCAP B. But the RETURN in B OVCAP. attempts to return control to A, which is SUBROUTINE A no longer in memory, and an error results. : END OVCAP. SUBROUTINE B : CALL UOVCAP('A') : RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,optimizing memory use \i,memory use optimization \i,memory use \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 4 of 10 A recommended procedure for optimizing a program's use of memory is to structure the program so that you are unloading OVCAPs from the end of your field length (the last OVCAP loaded is the first one unloaded, and so forth). This implies that OVCAPs that will be in memory for long periods of time should be loaded before OVCAPs that will be in memory for shorter periods. If you do not follow this procedure, there is a possibility of fragmenting your field length, resulting in less efficient memory management. The figure on the next screen shows an example of inefficient memory management. The main overlay calls OVCAP A which, in turn, calls OVCAP B. When control returns to the main overlay, A is unloaded but since B is called again in the main overlay, B is left in memory. The result is a gap in the program's field length. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,inefficient memory management example \i,example of inefficient example \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 5 of 10 Inefficient Memory Management Example: OVERLAY(FF,0,0,OV=2) PROGRAM GG CALL XOVCAP('A') CALL UOVCAP('A') Memory Layout: CALL XOVCAP('B') : +---+ -- END | B | | OVCAP. +---+ | Field Length SUBROUTINE A | | > After A is : +---+-------+ | Unloaded CALL XOVCAP('B') | main | | : +-----------+ -- END OVCAP. SUBROUTINE B : Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 6 of 10 A possible solution to this problem is shown on the next screen. LOVCAP is used to load B before it is actually needed. B can now remain in memory after A is unloaded, and memory is used more efficiently. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,efficient memory management example \i,example of efficient memory management \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 7 of 10 Efficient Memory Management Example: OVERLAY(FF,0,0,OV=2) PROGRAM GG CALL LOVCAP('B') CALL XOVCAP('A') Memory Layout: CALL UOVCAP('A') CALL XOVCAP('B') +---+ __ : | B | | Field Length END +---+--------+ > After A is OVCAP. | Main | | Unloaded SUBROUTINE A +------------+ -- CALL XOVCAP('B') : END OVCAP. SUBROUTINE B : Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 8 of 10 When attempting to influence memory management, you should be aware that throughout execution of the program, system-related capsules that perform functions required by your program are constantly being loaded, executed, and unloaded. This activity has a significant effect on the program's use of memory, and makes it difficult to predict what the execution time field length will be at any given time. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \c,---------------------------------------------------------------------------- \i,structured programs \i,memory efficiency \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 9 of 10 Following are some additional guidelines for structuring programs using OVCAPs. In general, the system-related capsules used by your program are structured according to these guidelines. If you adhere to them, you can significantly improve memory efficiency. Proper application of these guidelines depends on the requirements and restrictions affecting your program. Group routines that perform a logical function, or that require one another, into a single OVCAP. This helps to minimize the amount of loading and unloading that must be performed. Avoid placing shorter routines together with longer routines in an OVCAP, particularly if they are unrelated. Failure to do this often results in unneeded routines occupying large amounts of memory. Avoid leaving unneeded OVCAPs in memory. Use UOVCAP to unload them when they are no longer required by the program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hg \n,ld_hg \c,---------------------------------------------------------------------------- \i,converting to ovcaps \i,ovcap conversion \c,---------------------------------------------------------------------------- FTN5UG STRUCTURING AN OVCAP PROGRAM Screen 10 of 10 An existing overlay program can be converted to use OVCAPs. A simple method of conversion is to make each overlay an OVCAP by replacing the OVERLAY directive with an OVCAP directive and the PROGRAM statement with a SUBROUTINE statement, and to replace each CALL OVERLAY statement with the statement CALL XOVCAP('name') followed by the statement CALL UOVCAP('name'). These statements load the specified OVCAP, begin execution of the first routine in the OVCAP, and unload the OVCAP when control returns to the calling program. The advantage gained by this conversion is that the program's field length is reduced when the OVCAP is unloaded. When converting an existing overlayed program to use OVCAPs, it is not necessary to convert all the overlays to OVCAPs, because OVCAPs can coexist in memory with overlays and can be called from primary and secondary overlays as well as from the main overlay. As a general rule, an overlay that is large relative to the other overlays in a program, and which requires a small proportion of the program's total execution time, should be converted to an OVCAP. Press RETURN to return to the OVCAPs menu. \c,---------------------------------------------------------------------------- \s,ld_hh \u,ld_h \p,ld_h \c,---------------------------------------------------------------------------- \m=a,ld_hha \m=b,ld_hhb \m=c,ld_hhc \m=d,ld_hhd \m=e,ld_hhe \c,---------------------------------------------------------------------------- \i,segment loading \i,loading segments \i,segments \i,segmentation \i,field length \i,trees \i,root segment \i,segment levels \c,---------------------------------------------------------------------------- FTN5UG SEGMENT LOADING Screen 1 of 1 Segmentation allows you to decrease the execution time field length requirements of a program by dividing it into smaller portions called segments. The segments are stored on mass storage and are loaded into memory as needed during execution. (Unlike overlays or OVCAPs, no explicit calls are required.) The area of memory into which segments are loaded is determined during segment generation; if the area into which a segment is loaded already contains a segment, the existing segment is replaced. Segments (each of which contains one or more program units) are grouped into structures called trees, and the trees are grouped into one or more levels. One particular segment, called the root segment, stays in memory at all times. Enter one of the following letters to learn more about Segment Loading: a. Overview d. Common Blocks and Segments b. Segmented Program Structure e. Segment Directives c. Building a Segmented Program Press RETURN to read the Overview. Enter UP to return to the Loading FORTRAN Programs menu. \c,---------------------------------------------------------------------------- \s,ld_hha \u,ld_hh \c,---------------------------------------------------------------------------- \i,segment loading overview \i,overview of segment loading,1 \i,building a segmented program \i,segload directive,1 \i,segload,1 \i,segment advantages \i,advantages of segments \i,trees \c,---------------------------------------------------------------------------- FTN5UG SEGMENT LOADING OVERVIEW Screen 1 of 3 Building a segmented program requires no modifications or additions to a source program. To build a segmented program, you must include a SEGLOAD directive in the load sequence and create a separate file of segment directives which provide a detailed definition of the segment structure. Whenever a subprogram is referenced during execution, the segment containing the subprogram is automatically loaded into memory. The segment might overlay a previously loaded segment. (Whether this occurs depends on the structure of the segmented program.) Segmentation provides several advantages over overlays. With segments, you are less restricted in the structures you can create. While overlays allow only one tree with at most three levels of branching, you can group segments into any number of independent levels, each containing any number of trees. Up to 4096 segments can be arranged into a single tree structure. (However, most trees that you create will contain only a few segments.) Furthermore, segments can be built from previously compiled programs; with overlays, the structure must be specified at compilation time. Finally, loading of segments is automatic and takes place whenever a program unit in an unloaded segment is referenced; overlays must be loaded explicitly. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,advantages of segmentation \i,segment advantages \i,disadvantages of segmentation \i,segment disadvantages \i,field length \c,---------------------------------------------------------------------------- FTN5UG SEGMENT LOADING OVERVIEW Screen 2 of 3 Both segments and OVCAPs offer many of the same advantages. The primary advantage of segmentation as compared with OVCAPs is the automatic loading feature; like overlays, OVCAPs must be loaded explicitly. Segments have several disadvantages, however. The field length of a segmented program is determined during segment generation and remains constant throughout execution; unlike OVCAPs, no dynamic field length adjustment is provided. Also, segments must be loaded into memory in a predefined order; for many applications it is difficult to establish such an order. Furthermore, the automatic loading feature of segments can result in increased execution time if you are not familiar with your program, because of the possibility of an increased number of segment loads. Finally, you cannot use CYBER Interactive Debug with a segmented program. However, none of these disadvantages should be considered as a conclusive objection to the use of segmentation. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- FTN5UG SEGMENT LOADING OVERVIEW Screen 3 of 3 One additional disadvantage applies to segments, overlays, and OVCAPs: moving programs into and out of memory during execution results in an increase in execution time. Whether the savings in memory provided by these methods justifies the increased execution time depends on the specific application. Press RETURN to read about Segmented Program Structure. \c,---------------------------------------------------------------------------- \s,ld_hhb \u,ld_hh \c,---------------------------------------------------------------------------- \i,segmented program structure \i,trees \i,root segment \i,branch segments \c,---------------------------------------------------------------------------- FTN5UG SEGMENTED PROGRAM STRUCTURE Screen 1 of 4 A segmented program consists of one or more levels, each of which contains one or more trees. Each segment contains one or more compiled program units. A tree consists of a root segment and zero or more branch segments, each of which can have zero or more branches of its own. An example of a tree is shown below; A is the root segment and B and C are its branches. C has one branch, D. D - B - - C - - - - - - A Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,segmented program structure \i,example of segmented program \i,segmented program example \c,---------------------------------------------------------------------------- FTN5UG SEGMENTED PROGRAM STRUCTURE Screen 2 of 4 You can group trees into levels. The lowest level can only contain one tree; the root segment of this tree is the root segment of the entire program. The root segment must contain one and only one main program, although it can contain multiple subprograms. Higher levels can contain multiple trees. An example of a segmented program containing three levels is shown below. The first level contains one tree, the second level contains two trees (one of these trees contains only one segment), and the third level contains one tree. Segment A is the root segment of the entire structure. Level 0 D Level 1 Level 2 - B - G I J - C | - - - - | - - - - E F - - A H Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,ancestor \i,segment ancestor \i,segment compatibility \i,compatibility of segments \c,---------------------------------------------------------------------------- FTN5UG SEGMENTED PROGRAM STRUCTURE Screen 3 of 4 If a segment y is in the same tree as segment c and can be reached from x by branching upward, c is called the ancestor of y. For example, in figure on the previous screen segments A and C are ancestors of segment D. Neither B nor C is the ancestor of the other. The structure of a segmented program determines which segments can be in memory at the same time. If segments can be in memory at the same time, they are said to be compatible. Compatibility is determined as follows: Segments in different levels are always compatible. Segments in the same level are compatible only if they are in the same tree, and one of the segments is an ancestor of the other segment. In the figure on the previous screen, C is compatible with D but not with B; E and F are not compatible. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,nearest common ancestor \c,---------------------------------------------------------------------------- FTN5UG SEGMENTED PROGRAM STRUCTURE Screen 4 of 4 Any two segments have a nearest common ancestor, determined as follows: If the segments are in different trees, the root segment of the entire structure is their nearest common ancestor. If one of the segments is the ancestor of the other segment, the lower segment is the nearest common ancestor of the two segments. (Note that a segment can be its own ancestor.) If the segments are in the same tree, but neither is the ancestor of the other, then the nearest common ancestor is the highest segment from which both segments can be reached by branching upward. In other words, the nearest common ancestor is the root of the smallest subtree containing both segments. This process can be applied to determine a nearest common ancestor for more than two segments. Press RETURN to read about Building a Segmented Program. \c,---------------------------------------------------------------------------- \s,ld_hhc \u,ld_hh \c,---------------------------------------------------------------------------- \i,load stmts \i,building a segmented program \i,segload statement \i,segload \i,segment directives \c,---------------------------------------------------------------------------- FTN5UG BUILDING A SEGMENTED PROGRAM Screen 1 of 3 Building a segmented program requires a SEGLOAD loader statement and a file containing segment directives that define the structure of the segmented program. The loader begins creation of a segmented program when it encounters the SEGLOAD control statement in a load sequence. The SEGLOAD statement has the form: SEGLOAD,I=lfn1,B=lfn2. where lfn1 is the file containing the segment directives (default is INPUT) and lfn2 is the file to which the segmented program is to be written (default is ABS). The loader statements described previously can be used in a load sequence that builds a segmented program. LOAD and SLOAD statements specify files from which relocatable program units and common blocks are to be read during the creation of segments. An EXECUTE or name call statement signals the end of the load sequence, loads the root segment into memory, and begins execution of the segmented program. A NOGO statement terminates the load sequence but does not load the root segment into memory or begin execution. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- FTN5UG BUILDING A SEGMENTED PROGRAM Screen 2 of 3 During the segment generation process, the loader reads program units from the load files and places them in segments according to segment directive specifications. Programs are also placed in segments in the process of satisfying external references; these programs are placed in the nearest common ancestor of the referencing segments. To satisfy external references, the loader searches load files and the local and global library sets (in the same manner as for a basic load). Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,segemented program load sequence \c,---------------------------------------------------------------------------- FTN5UG BUILDING A SEGMENTED PROGRAM Screen 3 of 3 The following load sequence illustrates the creation of a segmented program: SEGLOAD,I=CCC,B=DDD. LOAD,AAA. SLOAD,BBB,ABC,DEF,GHI. LDSET,LIB=MYLIB. LGO. In this example, all program units from files AAA and LGO are included in the segmented program, as well as program units ABC, DEF, and GHI from file BBB. External references within each program unit are satisfied by entry points within the other program units, by the global library set, and by the local library MYLIB. Directives defining the segment structure are read from file CCC. After the segmented program is built, it is written to file DDD, the root segment is loaded into memory, and execution begins at the main program of the root segment. Press RETURN to read about Common Blocks and Segmented Programs. \c,---------------------------------------------------------------------------- \s,ld_hhd \u,ld_hh \c,---------------------------------------------------------------------------- \i,common blocks and segmented programs \i,common blocks \i,global directive,1 \c,---------------------------------------------------------------------------- FTN5UG COMMON BLOCKS AND SEGMENTED PROGRAMS Screen 1 of 2 Both blank and labeled common blocks can be used to transmit values between segments. During execution, blank common is accessible by all programs in all segments currently in memory and is not destroyed by the loading of other segments. Labeled common, however, cannot be used to transmit values between segments unless it is declared in a GLOBAL directive (Enter SEGMENT DIRECTIVES?) or in the COMMON parameter of an LDSET statement. In the absence of either of these declarations, a separate copy of a labeled common block is created for each segment that references the block. In this case, the common block cannot be used for communication between segments. The GLOBAL directive enables you to declare that a single copy of a common block is to be kept in a specified segment. During execution, the global block is accessible from all segments currently in memory that branch upward from the segment that defines the block. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hh \c,---------------------------------------------------------------------------- \i,common option \i,ldset statement \i,ldset \i,ldset common \c,---------------------------------------------------------------------------- FTN5UG COMMON BLOCKS AND SEGMENTED PROGRAMS Screen 2 of 2 The COMMON option of the LDSET statement performs a similar function to that of the GLOBAL directive. This option has the form: LDSET,COMMON=name1/.../namen. This statement causes the specified common blocks to be moved to the nearest common ancestor of all the segments that declare them. The common blocks can then be used for communication between all segments currently in memory that reference the blocks. The primary difference between the GLOBAL directive and the LDSET,COMMON statement is that the former requires you to specify the owning segment of a common block; the latter automatically selects the owning segment. Press RETURN to read about Segment Directives. \c,---------------------------------------------------------------------------- \s,ld_hhe \u,ld_hh \c,---------------------------------------------------------------------------- \m=a,ld_hhea \m=b,ld_hheb \m=c,ld_hhec \c,---------------------------------------------------------------------------- \i,segment directives \c,---------------------------------------------------------------------------- FTN5UG SEGMENT DIRECTIVES Screen 1 of 1 To build a segmented program, you must specify a sequence of directives describing the structure of the program. You then input this file to the loader by specifying the file name on the SEGLOAD loader statement. The primary functions of the segment directives are as follows: Assign program units to segments. Define the branching structure of trees. Assign trees to levels. Allow labeled common blocks to be used for communication between segments. Enter one of the following letters to learn more about segment directives: a. Summary of the formats and functions of the more commonly used segment directives b. Tree Expressions c. Naming Segments Press RETURN to see the Summary. Enter UP to return to the Segment Loading menu. \c,---------------------------------------------------------------------------- \s,ld_hhea \u,ld_hhe \c,---------------------------------------------------------------------------- \i,segment directives summary \i,summary of segment directives \i,tree directive \i,tree \i,include directive \i,include \i,level directive \i,level \i,global directive \i,global \i,end directive \i,end \c,---------------------------------------------------------------------------- FTN5UG SEGMENT DIRECTIVES SUMMARY Screen 1 of 1 -------------------------+----------------------------------------------------- Directive Format | Description -------------------------+----------------------------------------------------- name TREE exp | Defines and names a tree structure; exp is a valid | tree expression. | segname INCLUDE prog | Places the specified program in the specified | segment. | LEVEL | Delimits levels within a directive sequence; when | the loader encounters a level directive, a new | level begins. | segname GLOBAL bname | Places a global copy of the specified common block | in the specified segment; a global common block can | be used to pass values among segments currently in | memory. | END | Ends a directive sequence. -------------------------+----------------------------------------------------- Press RETURN to read about Tree Expressions. \c,---------------------------------------------------------------------------- \s,ld_hheb \u,ld_hhe \c,---------------------------------------------------------------------------- \i,tree expressions \i,tree directive \i,tree \i,tree subexpression \i,subexpression \c,---------------------------------------------------------------------------- FTN5UG TREE EXPRESSIONS Screen 1 of 3 Tree expressions are used in TREE directives to define the relationship of the segments within the trees. The expression defines the root of the tree and its branching structure. The expression consists of tree or segment names separated by the characters - , ( and ). The character - indicates that the segment to the left of the hyphen is the nearest common ancestor of the subexpression to the right of the hyphen. A subexpression is an expression within an expression. A subexpression can be a segment name, a tree name, or an expression enclosed in parentheses. A comma indicates that the segments, tree names, or subexpressions separated by the comma are on the same level of branching from a common ancestor. The next screen shows some examples of tree expressions. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hhe \c,---------------------------------------------------------------------------- \i,tree expression example \i,example of tree expressions \c,---------------------------------------------------------------------------- FTN5UG TREE EXPRESSIONS Screen 2 of 3 1. The expression A-(B,C,D) can be diagrammed as follows: B C D - | - - | - - A - 2. The expression A-((B-(C,D)),E) can be diagrammed as follows: C - D - - - - - B - E - - - - - A - Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,ld_hhe \c,---------------------------------------------------------------------------- FTN5UG TREE EXPRESSIONS Screen 3 of 3 3. When a tree name appears in an expression, the entire tree is substituted into the generated structure. For example, the directives: F TREE B-(C,D) TREE A-(F,E) generate the tree: C - D - - - - - B - E - - - - - A - Press RETURN to read about Naming Segments. \c,---------------------------------------------------------------------------- \s,ld_hhec \u,ld_hhe \n,ld_hhe \c,---------------------------------------------------------------------------- \i,naming segments \i,name of a segment \i,segment name \c,---------------------------------------------------------------------------- FTN5UG NAMING SEGMENTS Screen 1 of 1 The name of a segment is the name of the first routine to be placed in a segment. When the loader encounters a name while processing a tree expression, it searches load files for a routine having that name. When the routine is found, a segment is created, the routine is placed in the segment, and the routine name becomes a valid segment name which can be used to reference the segment in subsequent directives. Press RETURN to return to the Segment Directives menu. \c,---------------------------------------------------------------------------- \s,bt_i \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,bt_ia \m=b,bt_ib \m=c,bt_ic \m=d,bt_id \m=e,bt_ie \m=f,bt_if \m=g,bt_ig \m=h,bt_ih \m=i,bt_ii \c,---------------------------------------------------------------------------- \i,batch \i,batch programming examples \i,batch programming \i,batch environment \i,examples of batch jobs \i,batch job examples \c,---------------------------------------------------------------------------- FTN5UG BATCH PROGRAMMING EXAMPLES Screen 1 of 1 This topic presents some examples of batch job decks that use system features described in this guide. The purpose of these examples is to illustrate the use of these features in a batch environment. Detailed explanations of the various features illustrated in here are presented elsewhere. Enter one of the following letters to learn more about batch programming: a. Batch Job Structure b. Compiling and Executing a Batch Program c. Executing an Existing Binary Program d. Using Post Mortem Dump e. Creating a Program Library f. Creating a User Library g. Creating an Updated User Library h. Using the Loader i. Submitting Batch Jobs From a Terminal Press RETURN to read about the Batch Job Structure. Enter UP to return to the main menu. \c,---------------------------------------------------------------------------- \s,bt_ia \u,bt_i \c,---------------------------------------------------------------------------- \i,batch job structure \i,job structure \i,batch processing \i,punched cards \i,batch job \i,charge statement \i,charge \i,user statement \i,user \i,job statement \c,---------------------------------------------------------------------------- FTN5UG BATCH JOB STRUCTURE Screen 1 of 3 A batch job consists of control statements, programs, and data processed by the operating system in sequential order with no intervention by the user. Although you can perform batch processing through an interactive terminal, most batch jobs exist as decks of punched cards. Every batch job must begin with statements containing accounting information required by the operating system. The required statements are the job statement, USER statement, and CHARGE statement. These statements have the following formats: jobname,params. USER,username,passwrd,familyname. CHARGE,chargeno,projno. The job statement assigns a unique name to the job and specifies certain optional parameters affecting job execution. These parameters are explained in the NOS reference manual. The information on the USER and CHARGE statements ensures file security and prevents unauthorized users from using the system. Enter LOGIN? for a description of this information. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,accounting statements \i,period terminator \i,7/8/9 card \i,7/8/9 \i,multipunched card \i,multipunch \i,6/7/8/9 card \i,6/7/8/9 \c,---------------------------------------------------------------------------- FTN5UG BATCH JOB STRUCTURE Screen 2 of 3 The control statements follow the accounting statements in a batch job. The control statements request the operating system to perform certain operations. Whenever you want to retrieve a permanent file, create a permanent file, compile a program, or perform a variety of other operations, you must specify the appropriate control statement. These statements have the same format and function for either batch or interactive execution, except that the period terminator on a control statement is required in a batch job. Any card input required by the control statements follows the control statement portion of a job. The card input must be separated from the last control statement in the job by a 7/8/9 card consisting of the digits 7, 8, and 9 multipunched in column 1. The input decks must be placed in the job deck in the order they will be read by the control statements. Multiple input decks are separated by a 7/8/9 card. The last input deck must be followed by a 6/7/8/9 card (digits 6, 7, 8, and 9 multipunched in column 1). Typically, the card input in a job deck consists of directives read by the system utilities, source programs for input to the FORTRAN compiler, and data cards to be read by the FORTRAN programs. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,last card \i,last card in a job deck \c,---------------------------------------------------------------------------- FTN5UG BATCH JOB STRUCTURE Screen 3 of 3 If the control statements in a job do not require any card input, you must follow the last control statement by a 6/7/8/9 card. The 6/7/8/9 card terminates the job and is always the last card in a job deck. Press RETURN to read about Compiling and Executing a Batch Program. \c,---------------------------------------------------------------------------- \s,bt_ib \u,bt_i \c,---------------------------------------------------------------------------- \i,compiling and executing a program \i,compiling a batch program \i,executing a batch program \i,example of a batch program \i,batch program example \c,---------------------------------------------------------------------------- FTN5UG COMPILING AND EXECUTING A BATCH PROGRAM Screen 1 of 2 The following figure illustrates a job deck to compile and execute a FORTRAN program: Job Statement The GET statements retrieve two files USER Statement to be read by the program. The DEFINE CHARGE Statement statement defines a direct access file GET,DATA1. on which the binary program is to be GET,DATA2. saved. The B parameter on the FTN5 DEFINE,BIN. control statement specifies that the FTN5,B=BIN. compiler is to write the binary BIN. program to file BIN. The name call SAVE,OUT1. statement BIN executes the program. 7/8/9 The SAVE statement saves the file OUT1 FORTRAN Source Program written by the program. The FORTRAN 7/8/9 source deck follows the first 7/8/9 Input Data card, and the input cards required by 6/7/8/9 the program follow the second 7/8/9 card. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- FTN5UG COMPILING AND EXECUTING A BATCH PROGRAM Screen 2 of 2 The following example is similar to the one one the previous screen except that the FORTRAN source program exists on a permanent file instead of on cards: Job Statement The GET statement makes this file available USER Statement to the job. (It is assumed that the source CHARGE Statement file was created and saved in a previous GET,APROG. job.) The I parameter on the FTN5 control FTN5,I=APROG. statement specifies that the compiler is to LGO. read the source input from file APROG. 7/8/9 Because the B parameter is omitted, the Input Data compiler writes the binary program to file 6/7/8/9 LGO. Press RETURN to read about Compiling and Executing an Existing Binary Program. \c,---------------------------------------------------------------------------- \s,bt_ic \u,bt_i \c,---------------------------------------------------------------------------- \i,executing an existing binary program \c,---------------------------------------------------------------------------- FTN5UG EXECUTING AN EXISTING BINARY PROGRAM Screen 1 of 1 The following example illustrates a job deck to retrieve and execute a binary program previously created and saved. Prior to execution, two indirect access files, DATA2 and DATA3, are retrieved for input to the executing program. A name call statement with the name of the binary file initiates execution. Data cards for input to the program follow the 7/8/9 card. Job Statement USER Statement CHARGE Statement ATTACH,BIN. GET,DATA3. GET,DATA4. BIN. 7/8/9 Input Data 6/7/8/9 Press RETURN to read about Using Post Mortem Dump. \c,---------------------------------------------------------------------------- \s,bt_id \u,bt_i \c,---------------------------------------------------------------------------- \i,bpmd \i,using post mortem dump \i,post mortem dump \i,pmd \i,debugging \i,debug \i,debugging facility \i,symbolic dump \i,dump \c,---------------------------------------------------------------------------- FTN5UG USING POST MORTEM DUMP Screen 1 of 4 Post Mortem Dump (PMD) is a debugging facility that produces symbolic dumps of executing programs. PMD is especially useful in a batch environment. PMD produces a dump when either of two events occurs: A fatal execution error is detected. Subroutine PMDLOAD or PMDSTOP is called. The dump lists the values of variables defined in the program, as well as other useful debugging information. To use PMD, you must compile your program with DB=PMD specified on the FTN5 control statement. You then begin execution of the program in a normal manner. Enter PMD? for a detailed information on the PMD subroutines and the contents of the dump produced by PMD. The next screen shows a sample job deck containing a program that uses PMD. (This example is the batch equivalent of the example shown under index topic PMD EXAM?.) Press RETURN to see the sample job deck. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,post mortem dump batch job example \i,example of post mortem batch job \c,---------------------------------------------------------------------------- FTN5UG USING POST MORTEM DUMP Screen 2 of 4 Compile and Execute Using Post Mortem Dump: Job Statement Program TESTPMD uses PMD subroutine USER Statement calls to produce a dump. The PMD CHARGE Statement option is specified on the FTN5 control FTN5,DB=PMD. statement so that the PMD calls can be LGO. included in the program. When 7/8/9 subroutine PMDLOAD is called in the PROGRAM TESTPMD main program, the main program is A = 1.0 dumped along with all routines that B = 2.0 have called PMDDUMP. CALL SUB1 (A,B,C1) CALL SUB2 (A,B,C2) CALL SUB3 (A,B,C3) CALL PMDLOAD END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- FTN5UG USING POST MORTEM DUMP Screen 3 of 4 Compile and Execute Using Post Mortem Dump (Continued): SUBROUTINE SUB1 (R,S,T) CALL PMDDUMP T = 2.0*(R-S) RETURN END SUBROUTINE SUB2 (R,S,T) T = R + S - 3.0 RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- FTN5UG USING POST MORTEM DUMP Screen 4 of 4 Compile and Execute Using Post Mortem Dump (Continued): SUBROUTINE SUB3 (R,S,T) CALL PMDDUMP R = R + 1.0 S = S + 1.0 CALL SUB4 (R,S,T) RETURN END SUBROUTINE SUB4 (X,Y,Z) CALL PMDDUMP X = X**2 + Y**2 RETURN END 6/7/8/9 Press RETURN to read about Creating a Program Library. \c,---------------------------------------------------------------------------- \s,bt_ie \u,bt_i \c,---------------------------------------------------------------------------- \i,batch run \i,creating a program library \i,program library \i,update \i,update library \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM LIBRARY Screen 1 of 2 A program library is a collection of source programs created by the Update utility. Program libraries provide a convenient means of storing and maintaining source programs, because you can use Update to add, delete, and modify individual routines within the library. Input to Update consists of source programs to be placed in the library, source statements to update existing routines in the library, and special directives specifying the operations to be performed by Update. Output consists of a new or updated program library and a listing describing the Update run. You can also request Update to produce a source file for input to the FORTRAN compiler. (The Update library cannot be directly input to the compiler.) Enter UPDATE? for a detailed of description of Update usage. The example on the next shows a job deck that performs an Update creation run. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,update batch job example \i,example of update batch job \c,---------------------------------------------------------------------------- FTN5UG CREATING A PROGRAM LIBRARY Screen 2 of 2 Job Statement The UPDATE control statement specifies the USER Statement name of the library to be created (NEWPL) CHARGE Statement and an output file for input to the FORTRAN UPDATE,N=NEWPL,C=COMPILE. compiler (COMPILE). The SAVE statement SAVE,NEWPL=PL1. saves the new library as an indirect access FTN5,I=COMPILE. permanent file named PL1. The file COMPILE, 7/8/9 created by the Update run, is then input to *DECK TEST the FORTRAN compiler. PROGRAM TEST A = 1.0 The Update input cards follow the 7/8/9 B = 2.0 card. The *DECK directives identify the CALL ADD (A,B,C) routines to be placed in the new program END library. The library is to contain routines *DECK ADD TEST and ADD. SUBROUTINE ADD (X,Y,Z) Z = X + Y RETURN END Press RETURN to read about Creating a User Library. \c,---------------------------------------------------------------------------- \s,bt_if \u,bt_i \c,---------------------------------------------------------------------------- \i,creating a user library \i,user library \i,libgen \i,libgen utility \i,gtr \i,gtr utility \i,copyl \i,libedit utility \i,libedit \c,---------------------------------------------------------------------------- FTN5UG CREATING A USER LIBRARY Screen 1 of 2 A user library is a specially formatted file of object modules that can be used by the loader to satisfy external references. User libraries provide a convenient method of storing and maintaining object modules. User libraries are created by the LIBGEN utility. You can add, delete, and replace routines within an existing user library using LIBGEN in conjunction with the GTR and COPYL or LIBEDIT utilities. Enter OPM? for a detailed discussion of the creation and maintenance of user libraries. In order to create a user library, you must have a sequential-format file of binary modules, such as the file produced by a FORTRAN compilation. If your source programs are stored on an Update program library, you can use Update to create a compile file containing the desired routines, input the compile file to the FORTRAN compiler, and input the resulting binary file to LIBGEN to create a user library. The example on the following screen illustrates a job deck that creates a user library from routines stored on an Update library. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,user library batch job example \i,example of user library batch job \c,---------------------------------------------------------------------------- FTN5UG CREATING A USER LIBRARY Screen 2 of 2 Job Statement The UPDATE control statement specifies the USER Statement program library from which routines are to CHARGE Statement be extracted (PLIB) and the compile file to GET,PLIB=PL1. be created (AAA). The F parameter directs UPDATE,P=PLIB,N=0,C=AAA,F. Update to include all routines from the FTN5,I=AAA,B=BBB. library in the compile file. The parameter DEFINE,LIBFIL. N=0 specifies that no new library is to be LIBGEN,F=BBB,P=LIBFIL. created. Because no special operations are ITEMIZE,LIBFILE,U. desired for this Update run, no directives 6/7/8/9 are specified. The compile file AAA is input to the FORTRAN compiler, which creates the binary file BBB. The DEFINE control statement creates an empty file, called LIBFIL, for the user library to be created. Finally, the binary file BBB is input to LIBGEN, which creates the user library LIBFIL. The ITEMIZE statement is included to produce a description of the new user library. The user library contains binary records (type REL) for routines TEST, ADD, and SUB. The first and last records are the library directory and index, respectively. Press RETURN to read about Creating an Updated User Library. \c,---------------------------------------------------------------------------- \s,bt_ig \u,bt_i \c,---------------------------------------------------------------------------- \i,creating an updated user library \i,updated user library \i,gtr utility \i,gtr \i,libedit utility \i,libedit \i,copyl utility \i,copyl \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY Screen 1 of 4 You cannot make changes directly to a LIBGEN user library. You can, however, make changes to a sequential-format binary file and input this file to LIBGEN to create a new, updated user library. The GTR and COPYL or LIBEDIT utilities, together with LIBGEN, enable you to create updated user libraries without the need for recompiling the entire source program. The updating process is summarized as follows: 1. Use GTR to create a sequential-format file from the existing user library. 2. Compile only those routines that are to be added to the library or that are to replace existing routines on the library. 3. Use LIBEDIT or COPYL to update the binary file created in step 1 with routines from the file created in step 2. 4. Use LIBGEN to create a new user library from the updated file created in step 3. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY Screen 2 of 4 Enter OPM? for a detailed explanation of the use of GTR, COPYL, LIBEDIT, and LIBGEN. The example on the next screen shows a job deck that uses GTR, LIBEDIT, and LIBGEN to create an updated user library from a previously created user library. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,updated user library batch example \i,example of updated user library batch job \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY Screen 3 of 4 Job Statement The GTR utility is called to create a USER Statement sequential-format file from the existing CHARGE Statement library. Parameters on the GTR control ATTACH,LIBFIL. statement specify the name of the library GTR,LIBFIL,OLD.ULIB/*. (LIBFIL) and the name of the file to be FTN5,B=BIN. created (OLD). The parameter ULIB/* LIBEDIT,P=OLDPL,B=BIN,N=NEW. specifies that the input records are from a DEFINE,NEWLIB. user library. LIBGEN,F=NEW,P=NEWLIB. 7/8/9 The FORTRAN compiler is called to compile PROGRAM TEST the routines to update the file created by A = 1.0 GTR. The source decks for these routines B = 2.0 are included in the job deck. Program TEST CALL COMP (A,B,C) is to replace an existing routine having the END same name, and subroutine COMP is to be SUBROUTINE COMP (X,Y,Z) added to the file. The compile routines are Z = X**2 + Y**2 written to file BIN. RETURN END Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- FTN5UG CREATING AN UPDATED USER LIBRARY Screen 4 of 4 7/8/9 At this point, two sequential binary files *TYPE REL exist: a file containing the same routines *REPLACE TEST as the user library and a file containing a *DELETE ADD new routine and a replacement routine. *INSERT TEST,COMP LIBEDIT can now be called to create an 6/7/8/9 updated sequential file. Parameters on the LIBEDIT control statement specify the existing sequential file (OLD), the file containing the new and replacement routines (BIN), and the new file to be created (NEW). The directives required by LIBEDIT follow the FORTRAN source program in the job deck. These directives specify the operations to be performed by LIBEDIT. In this case, routine TEST is to be replaced, routines ADD and SUB are to be deleted, and routine COMP is to be inserted after routine TEST. The first directive specifies that all routines are of type REL (relocatable). After LIBEDIT has completed, the new user library can be created. The DEFINE statement establishes a direct access permanent file for the library, and the LIBGEN statement creates the library. Press RETURN to read about Using the Loader. \c,---------------------------------------------------------------------------- \s,bt_ih \u,bt_i \c,---------------------------------------------------------------------------- \i,bload \i,using the loader \i,loader \c,---------------------------------------------------------------------------- FTN5UG USING THE LOADER Screen 1 of 2 Before a compiled program can be executed, it must be processed by the loader. Most small FORTRAN programs require only a single statement to load and execute the program; usually, this is an LGO statement. The loader, however, provides many additional capabilities. In order to request these capabilities, you must include a sequence of loader control statements in your job deck specifying the desired options. This sequence of statements is called a load sequence. Enter LOADER? for more information on the use and function of the loader and the loader control statements. The next screen shows a job deck containing a typical load sequence. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,loader batch job example \i,example of loader batch job \c,---------------------------------------------------------------------------- FTN5UG USING THE LOADER Screen 2 of 2 Job Statement The deck contains control statements to USER Statement compile, load, and execute a FORTRAN CHARGE Statement program. Several loader options are FTN5. requested. Thus, instead of the single LGO ATTACH,BBB. statement normally used to load and execute LDSET,MAP=SB. a program, a load sequence consisting of LOAD,BBB,LGO. several loader statements is specified. The EXECUTE. first loader statement, the LDSET statement, 7/8/9 requests a load map. The next statement, a FORTRAN Source Program LOAD statement, loads programs from binary 6/7/8/9 files LGO (produced by the preceding compilation) and BIN (produced by a separate compilation within a preceding job) into a single executable file. The EXECUTE statement terminates the load sequence and begins execution of the loaded program. Press RETURN to read about Submitting Batch Jobs From a Terminal. \c,---------------------------------------------------------------------------- \s,bt_ii \u,bt_i \c,---------------------------------------------------------------------------- \i,submitting batch jobs from a terminal \i,submitting batch jobs \i,route control statement \i,route statement \i,route a file \i,batch input queue \i,input queue \i,printer output queue \i,printer queue \c,---------------------------------------------------------------------------- FTN5UG SUBMITTING BATCH JOBS FROM A TERMINAL Screen 1 of 3 Most batch jobs exist as decks of punched cards and are submitted for execution through the card reader. However, you can use the ROUTE control statement to submit batch jobs existing as local files of card images. The ROUTE statement enables you to route a file containing a batch job to the batch input queue, and to route print or punch files to the appropriate queue to be printed or punched. The ROUTE statement has the form: ROUTE,lfn,DC=xx. where lfn is the local file to be routed and xx specifies one of the following queues: IN File is sent to the batch input queue. The file must contain a valid batch-format job. If the file contains invalid accounting information, the terminal is disconnected from the network and the batch job is not routed. PR File is sent to the printer output queue. Any available printer at the central site is used. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \c,---------------------------------------------------------------------------- \i,card punch output queue. \i,card punch output \c,---------------------------------------------------------------------------- FTN5UG SUBMITTING BATCH JOBS FROM A TERMINAL Screen 2 of 3 PU File is sent to the card punch output queue. The PR option is especially useful because it provides an alternative to displaying large amounts of information at the terminal. For example, a normal FORTRAN compilation can produce a large volume of output. However, you can write the compiler listing to a file and then print the file, as in the following example: FTN5,I=FF,L=LIST. ROUTE,LIST,DC=PR. The output listing is written to file LIST; LIST is then printed at the central site. Once you ROUTE a file, you no longer have access to the file. Therefore, if you wish to retain a copy of the routed file, you should save it as a permanent file before you route it. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,bt_i \n,bt_i \c,---------------------------------------------------------------------------- FTN5UG SUBMITTING BATCH JOBS FROM A TERMINAL Screen 3 of 3 Other ROUTE options allow you to specify alternate printer types, to define internal characteristics of files to be printed or punched, and to control various other aspects of file processing. Press RETURN to return to the Batch Programming menu. \c,---------------------------------------------------------------------------- \s,gl_j \u,main \p,main \c,---------------------------------------------------------------------------- \m=a,gl_j+1 \m=b,gl_j+1 \m=c,gl_j+2 \m=d,gl_j+3 \m=e,gl_j+4 \m=f,gl_j+5 \m=g,gl_j+6 \m=h,gl_j+6 \m=i,gl_j+6 \m=j,gl_j+8 \m=k,gl_j+8 \m=l,gl_j+8 \m=m,gl_j+10 \m=n,gl_j+11 \m=o,gl_j+12 \m=p,gl_j+14 \m=q,gl_j+16 \m=r,gl_j+16 \m=s,gl_j+17 \m=t,gl_j+18 \m=u,gl_j+19 \m=v,gl_j+20 \m=w,gl_j+20 \m=x,gl_j+20 \m=y,gl_j+20 \m=z,gl_j+20 \c,---------------------------------------------------------------------------- \i,glossary \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 1 of 21 The following screens define common words and system specific words. To read the definitions of a term, type in the first letter of the term followed by a carriage return. To go directly to a specified term, enter the term followed by two question marks. For example, entering NETWORK?? reaches the definition of network. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+1 \u,gl_j \c,---------------------------------------------------------------------------- \i,a? \i,b? \i,basic load,9 \i,basic load? \i,beginning-of-information,9 \i,boi,9 \i,beginning-of-information? \i,boi? \i,binary module,9 \i,binary module? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 2 of 21 Basic Load Loading one or more binary modules by means of control statements, with all the absolute code in memory at the same time. Beginning-of-Information (BOI) The beginning of the first user-written record on a disk or tape file. System-supplied information exists prior to beginning-of-information. Binary Module A compiled program suitable for use by the loader. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+2 \u,gl_j \c,---------------------------------------------------------------------------- \i,c? \i,cyber interactive debug,9 \i,cyber interactive debug? \i,cid,9 \i,cid? \i,cyber loader,9 \i,cyber loader? \i,cyber record manager,9 \i,cyber record manager? \i,crm,9 \i,crm? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 3 of 21 CYBER Interactive Debug A utility program that enables you to interactively control execution of a program for the purpose of debugging that program. CYBER Loader A utility program that loads one or more binary modules into memory and prepares them for execution. CYBER Record Manager The software facility that performs execution-time input/output for FORTRAN programs as well as other CDC products. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+3 \u,gl_j \c,---------------------------------------------------------------------------- \i,d? \i,dayfile,9 \i,dayfile? \i,direct access,9 \i,direct access? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 4 of 21 Dayfile A terminal session or job history log maintained by the system. You can display the current dayfile with the DAYFILE command. Direct Access As used in this guide, a type of permanent file for which all changes are made directly to the only copy of the file. Direct access is also a CYBER Record Manager Advanced Access Methods file organization. FORTRAN also defines a direct access file language feature; this feature is distinct from the system permanent file type and the CYBER Record Manager direct access file organization. (FORTRAN direct access files are implemented using CYBER Record Manager word addressable files.) Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+4 \u,gl_j \c,---------------------------------------------------------------------------- \i,e? \i,end of information,9 \i,end of information? \i,eoi,9 \i,eoi? \i,entry point,9 \i,entry point? \i,external reference,9 \i,external reference? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 5 of 21 End-of-Information (EOI) The end of the last user-written record on a file. On a tape, trailer labels are past the end-of-information. Entry Point A location within a program unit that can be referenced from other program units. Each entry point has a unique name. External Reference A reference in one program unit to an entry point in another program unit. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+5 \u,gl_j \c,---------------------------------------------------------------------------- \i,f? \i,field length,9 \i,field length? \i,file,9 \i,file? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 6 of 21 Field Length The number of memory words assigned to a program. File A logically related set of information that begins at beginning-of-information and ends at end-of-information. A file is referenced by a unique file name. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+6 \u,gl_j \c,---------------------------------------------------------------------------- \i,g? \i,h? \i,i? \i,indirect access,9 \i,indirect access? \i,interactive,9 \i,interactive? \i,interactive facility,9 \i,interactive facility? \i,iaf,9 \i,iaf? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 7 of 21 Indirect Access A type of permanent file for which a local copy is created when the file is retrieved. Changes are made to the local copy. Interactive Capable of a two-way exchange of information. In interactive processing, you enter a command from the terminal and the command is executed immediately; any output appears at the terminal. Interactive Facility (IAF) The network software component that enables you to communicate directly with the operating system from a terminal. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,gl_j \c,---------------------------------------------------------------------------- \i,interactive terminal,9 \i,interactive terminal? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 8 of 21 Interactive Terminal A terminal that is capable of receiving information from and sending information to the computer. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+8 \u,gl_j \c,---------------------------------------------------------------------------- \i,j? \i,k? \i,l? \i,libgen,9 \i,libgen? \i,load map,9 \i,load map? \i,loader,9 \i,loader? \i,loading,9 \i,loading? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 9 of 21 LIBGEN A system utility program that creates a user library of binary modules. Load Map A listing, produced by the loader, that shows how memory was allocated during a load operation. Loader A utility program that performs the loading process. The CDC version of this utility is called the CYBER Loader. Loading The process of placing a binary module in memory and preparing it for execution. This process is performed by the CYBER Loader. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,gl_j \c,---------------------------------------------------------------------------- \i,local file,9 \i,local file? \i,login procedure,9 \i,login procedure? \i,logout procedure,9 \i,logout procedure? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 10 of 21 Local File Any file that is currently associated with a terminal session. Login Procedure The procedure which you perform to establish a connection between a terminal and the computer. Logout Procedure The procedure that breaks the connection between the terminal and the computer. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+10 \u,gl_j \c,---------------------------------------------------------------------------- \i,m? \i,mode error,9 \i,mode error? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 11 of 21 Mode Error An execution-time error that causes the executing program to abort. A mode error is sometimes called a CPU abort. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+11 \u,gl_j \c,---------------------------------------------------------------------------- \i,n? \i,network,9 \i,network? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 12 of 21 Network A collection of software products that together provide for communication between terminals and the computer. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+12 \u,gl_j \c,---------------------------------------------------------------------------- \i,o? \i,object code,9 \i,object code? \i,optimization,9 \i,optimization? \i,optimizing mode,9 \i,optimizing mode? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 13 of 21 Object Code Binary code produced by the compiler and input to the loader in the form of a binary module. Optimization The process of rearranging or rewriting code to produce the same results in a more efficient way. Optimizing Mode One of the compilation modes of the FORTRAN 5 compiler, as indicated by the control statement options OPT= 0, 1, 2, or 3. Each mode produces a specific level of optimization. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,gl_j \c,---------------------------------------------------------------------------- \i,ovcaps,9 \i,ovcaps? \i,overlays,9 \i,overlays? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 14 of 21 OVCAPs A CYBER Loader capability that enables you to divide a program into independently-executable units called OVCAPs that can be loaded into memory, executed, and unloaded by special subroutine calls. OVCAPs are used to reduce a program's field length. Overlays A CYBER Loader capability that allows you to organize a program into smaller units called overlays for the purpose of reducing the program's field length. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+14 \u,gl_j \c,---------------------------------------------------------------------------- \i,p? \i,partition,9 \i,partition? \i,permanent file,9 \i,permanent file? \i,post mortem dump,9 \i,post mortem dump? \i,pmd,9 \i,pmd? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 15 of 21 Partition A division of a file that ends with a tape mark on a magnetic tape file or with a zero-length level 17 marker on a mass storage file. A partition contains one or more sections. A partition is also known as an operating system end-of-file. Permanent File A mass storage file, saved by the system between terminal sessions. Post Mortem Dump (PMD) A debugging utility that produces a formatted dump containing variable values and other debugging information for an executing program. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s \u,gl_j \c,---------------------------------------------------------------------------- \i,program library,9 \i,program library? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 16 of 21 Program Library A file of source language programs in a format produced by the UPDATE utility. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+16 \u,gl_j \c,---------------------------------------------------------------------------- \i,q? \i,r? \i,record,9 \i,record? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 17 of 21 Record A unit of information within a file that is transmitted by execution of a READ or WRITE statement. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+17 \u,gl_j \c,---------------------------------------------------------------------------- \i,s? \i,section,9 \i,section? \i,segmentation,9 \i,segmentation? \i,sort/merge,9 \i,sort/merge? \i,source listing,9 \i,source listing? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 18 of 21 Section A logical division of a file. A section contains one or more user records. A section is also known as an operating system record. Segmentation The CYBER Loader capability that enables you to divide a program into smaller units called segments that are automatically loaded into memory when needed. Segmentation is used to reduce a program's field length. Sort/Merge A system utility program that sorts or merges the records of files into a specific order. Source Listing A listing of a source program produced by the compiler. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+18 \u,gl_j \c,---------------------------------------------------------------------------- \i,t? \i,terminal session,9 \i,terminal session? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 19 of 21 Terminal Session The sequence of interactions between a terminal and the computer that begins when you establish a connection to the computer and ends when you break the connection. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+19 \u,gl_j \c,---------------------------------------------------------------------------- \i,u? \i,update,9 \i,update? \i,user library,9 \i,user library? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 20 of 21 Update A system utility program that maintains source programs in a compressed format on a file known as a program library. User Library A file of binary modules, created by the LIBGEN utility, from which the loader can load routines and satisfy external references. Press RETURN to continue. \c,---------------------------------------------------------------------------- \s,gl_j+20 \u,gl_j \n,gl_j \c,---------------------------------------------------------------------------- \i,x? \i,xedit,9 \i,xedit? \c,---------------------------------------------------------------------------- FTN5UG GLOSSARY Screen 21 of 21 XEDIT A system utility program that creates and modifies text files. Press RETURN to return to the main menu.