CHAPTER 1 BUILD COMMAND IMPLEMENTATION NOTES 1.1 ABSTRACT This distribution contains a Fortran program which is implemented as a command to simplify the use of the task builder options. Most of the task builder options can be supplied on a single line. The program parses the command line to determine options, libraries, etc., and generates a task builder command file, then spawns the task builder. It may optionally compile the program first too, and will use the fast task builder if it thinks it is possible. Commonly used libraries and resident libraries are automatically in- cluded. This program is considerably faster and more flexi- ble than some of the command file driven parsers. It should work on any recent RSX-11M or M-Plus system, with either Fortran-IV or Fortran-77. 1.2 AUTHOR If you have any (polite) comments or suggestions, please feel free to contact me. Dr. David Villeneuve Division of Physics M23A National Research Council Ottawa Ont. K1A 0R6 Canada 613-993-9975 BUILD COMMAND IMPLEMENTATION NOTES Page 1-2 This program is the property of the Government of Ca- nada, and as such may not be sold or copied commercially, etc., etc. 1.3 IMPLEMENTATION The syntax of the command is given in the second chapter of this writeup. This writeup is taken from the users guide for our system, so a lot of it is specific to our site, in particular where we keep our libraries. The program retrieves its command line, parses it into either positional or keyword parameters, and creates a task builder command file. The syntax comes from an little known IBM operating system, TSS, but it seems to be quite effec- tive here where you use the first two parameters most of the time, but use the keyword defined ones less often. The program then spawns the task builder (choosing FTB if possible, i.e. no CLSTR), and then STOPFRs, which means that it does not compete for memory while the task builder is active, and only comes back when the task builder is fin- ished. It then deletes the command file, and optionally the object file if it compiled first. The program will be generated by the BUI.CMD command file, which will ask for which Fortran compiler you are us- ing, where the Fortran OTS library is, and if you have FCSRES. If you also have a FORRES (as we do), you will have to modify BUI.CMD accordingly. On our system, with Fortran IV, FCSRES and FORRES, this task is only 3456 words long. The BUI.CMD file works in any UIC, and does not require pri- vilege unless it needs to install a utility. It is recommended that you install BUI, rather than use CCL, since it is one of the most commonly used tasks on our system. You will almost certainly have to modify the code, in BUI.FTE, before you compile it, since parts of it are imple- mentation dependent, particularly where you put libraries. This should not be too difficult since the code is modular. Note that it is coded in an extended Fortran, the preproces- sor of which is included. If you know any structured lang- uages, it should be clear to you, otherwise look at the writeup in FTE.FTN. BUILD COMMAND IMPLEMENTATION NOTES Page 1-3 Subroutine SECT contains the keywords which are recog- nized. You can add or modify these as you wish. Subroutine BUILD1 generates the part of the task builder command file up to the slash; you should modify this part to link to your most common libraries automatically (as our FTNLIB is), and to translate the leading $ to your system account. Su- broutine BUILD2 generates the options part of the command file, and you will probably want to change the resident li- brary choices. Note that the command added after the BUI command name must by recognized by your system, and must accept a single parameter consisting of the file name without extension. In our system we use CCL to understand commands like FTN, FTNLIST, FTNCREF. If you don't have this, you can modify the part where the compiler is spawned, in subroutine TKB. CHAPTER 2 BUILD COMMAND SYNTAX This chapter comes from the users guide for our system, so a lot of stuff will make no sense on yours, particularly where we keep libraries and what resident libraries we sup- port. However it describes how the command works, and may give you some ideas on how it should be customized for your system. 2.1 BUILD COMMAND The task builder is a complicated program which is des- cribed fully in the DEC manuals. It allows a number of ob- ject modules to be bound together from object files or libraries. It has options which set the number of I/O units required by the program, etc. The BUILD command is designed to simplify the use of the task builder. It produces a command file which is given to the task builder, which then follows the contained in- structions. If the BUILD command doesn't provide the fea- tures you require, you may have to use the task builder directly. The full BUILD syntax is: BUILD FILE=(...), LIB=(...), MAP=Y, PRI=n, ACTFIL=n, MAXBUF=n, FMTBUF=n, COMMON=(...), LIBR=(...), CLSTR=(...), ASG=(...), UNITS=n, TASK=name, SIZE=n, DEBUG=Y or BUILD/compiler ... The syntax allows arguments to be specified either po- sitionally, or by specifying the keyword of the argument. If more than one item is specified for an argument, they are enclosed in parentheses and separated by commas. If more than one line is required, a hyphen is placed as the last BUILD COMMAND SYNTAX Page 2-2 character of the first line, and a second line may be entered. Examples of BUILD commands are shown at the end of this section, and serve to illustrate the syntax. FILE = list of input files. The first one named is to be the name of the task file, and must exist as an object file. The others may be object files or object modules extracted from libraries, such as HPALIB/LB:SWCHAR:SPACE1. Options may be appended to the first name, such as /DA for debugging aid (ODT), or /PR for privileged. LIB = list of object libraries to be searched. These libraries will be searched for required object modules in the order they are listed. If your current account has a USERLIB.OLB, it is automati- cally included at the top of the list. The gen- eral Fortran library SF:[5,3]FTNLIB is also always included between USERLIB and the listed libraries. If a library name is preceeded by $, the specified library will be found in system account SF:[5,3], such as NPLIB, HPLIB, INENLIB, and CAMACLIB. MAP = Y If this is specified, a map file is produced by the task builder to show how the task was put to- gether. This may be printed. SIZE =0-2 Determines the maximum size of the task through the number of resident libraries which it links to. SIZE=0 is the default, and uses two resident libraries to produce the most compact task size; the maximum task size is 24K (not counting all the code in the resident libraries). SIZE=1 uses the same two libraries but "clustered" so they use the same address space; the maximum task size is now 28K; the larger available task size is slightly offset by somewhat slower execution and longer task build time. SIZE=2 does not use any resident libraries, so that all the code is contained in the task image; the maximum task size is 32K, but since all the code that was in the resident li- braries is now in the task, this never results in more space for the program; it also takes longer to task build. PRI = decimal number defining the priority given to the task when it is run. The default is 50. If your task requires a lot of CPU time, be kind to others and set its priority down, say to PRI=8. BUILD COMMAND SYNTAX Page 2-3 ACTFIL = the number of files which will be open concur- rently in a Fortran program. Default is 4, but reducing this number will save space. MAXBUF = maximum buffer length allowed in a Fortran pro- gram. If you use files with long records, you may have to increase this. Default is 132 bytes. FMTBUF = length of the buffer used by run time format statements. Default is 64 bytes. COMMON = list of external common blocks to be linked to. This permits several independent tasks to share data, such as COCO-II tasks through COCOCM. They must each be followed by the access attribute, ei- ther RO or RW. For example COMMON=COCOCM:RO. LIBR = list of core resident libraries to be linked to. We have FORRES, which contains much of the code used by Fortran tasks, and FCSRES, which contains the file control services. These libraries are used automatically, and reduce each task by about 4K words. If this option is explicitly used, FORRES and FCSRES will not be referenced automati- cally. CLSTR = list of core resident libraries to be linked to. Unlike LIBR however, the libraries are "clustered" together so they use the same address space. See SIZE=1 above and the task builder manual. UNITS = number of logical units available for use by a Fortran program. Default is 6. TASK = name of task when it is installed, specified as 6 characters. ASG = list of device assignments at task build time. These may be changed at run time, using CALL ASNLUN. Default is ASG=(SY:1:4,TI:5,CL:6). DEBUG = Y is specified if you wish to see the command file produced by BUILD. Useful if you wish to learn about the task builder. This full description appears complicated, but most of the options are rarely used. Some examples are shown below: BUILD COMMAND SYNTAX Page 2-4 BUILD MYPROG Uses the object file MYPROG.OBJ to build task MYPROG.TSK. Automatically searches USERLIB.OLB if the user has one, and SF:[5,3]FTNLIB, and automatically saves 4K of memory by linking to FORRES and FCSRES resident libraries. BUILD MYPROG,$PFLIB As above, but also searches SF:[5,3]PFLIB for the plotting routines. BUILD MYPROG,($INENLIB,$NPLIB) As above, but searches SF:[5,3]INENLIB before NPLIB. Note the use of parentheses to include more than one library in the LIB section. BUILD (MYMAIN,MYSUB) Uses two object files MYMAIN.OBJ and MYSUB.OBJ to build the task. Presumably MYMAIN contains the main program, and MY- SUB the subroutines. BUILD MYPROG,$HPLIB,PRI=8,ACTFIL=2,UNITS=5,DEBUG=Y Shows a mixture of positional location of arguments (the first two) and keyword location (the rest). The error message "Task has illegal memory limits" me- ans that the program is too large. Try SIZE=1 or reduce some arrays. As a last resort, the subroutines may be over- laid, but this is complicated. The command SIZE myprog will show the task size. The build command can also compile your program first if you wish; this save entering an extra line. To do so, at the end of the BUILD command name, add a slash and the command name you would normally use to compile your program, e.g., FTN or FTCLIST, etc. For example, BUILD/FTN myprog. The object file will be deleted at the end. If the compiler returns severe error messages, the task build phase will be skipped. Fortran 77 users have a slightly different command name which must include the numbers "77" somewhere in the name, for example BUILD77, BUI77, or BUILD/FTN77. This will then task build using the Fortran 77 runtime library, and FTNLIB77 instead of FTNLIB. Any other libraries you choose should also be the Fortran 77 version, such as PFLIB77. Also, since we don't have a Fortran 77 resident library, it will only link to FCSRES, so that maximum task size is 28K words, and there is no difference between SIZE=0 and 1. Generally you will not be able to build as large a program BUILD COMMAND SYNTAX Page 2-5 with Fortran 77 as with Fortran IV. If you require a complicated BUILD command for a par- ticular program, you may imbed the command in the comments at the beginning of the source program. The line must start with (exactly) C--BUILD with the rest of the line containing the usual options; a compiler name is not allowed. To use this feature, issue a BUILD command (with a compiler name if desired) and the name of the source file with a preceeding at-sign. If the extension is not given, it will try FTN and then FTE. For example, BUILD @MYPROG, BUI/FTC @HISPROG.FTE.