LINK[/qualifier[s]] filespec[s][/qualifier[s]] The LINK command invokes the Task Builder to build a runnable task from object modules you have previously compiled (or assembled). The unadorned LINK command includes a number of defaults that will produce a standard task image file, file type .TSK. The Task Builder, however, provides you with many choices that are not included in the defaults. The simple command: LINK filespec[.OBJ] will built a runnable task image from an object file (the output of the MACRO-11 assembler or of a high-level language compiler). The task image file will have the same name as the object file, with the file type .TSK. If more than one filespec is specified, the task image file will have the same name as the last filespec, with the file type .TSK. To see a list of all the valid LINK qualifiers, type HELP LINK QUALIFIERS. For a description of any particular qualifier, type HELP LINK qualifiername. 2 ANCILLARY_PROCESSOR LINK/ANCILLARY_PROCESSOR[:n] filespec The /ANCILLARY_PROCESSOR qualifier identifies the task as an Ancillary Control Processor (ACP). The parameter 'n' specifies the base relo- cation register. Acceptable values are 0, 4, or 5. The default is 5. This qualifer corresponds to the /AC switch in TKB format. 2 BASIC LINK/BASIC filespec The /BASIC qualifier identifies the input file as a command file produced by the BASIC-PLUS-2 compiler. The BUILD command to the compiler creates a file of commands for the Task Builder along with an object file. You should not modify the command file generated by BASIC-PLUS-2. This qualifier cannot be used with any other qualifier. 2 NOCHECKPOINT #CHECKPOINT 2 CHECKPOINT LINK/CHECKPOINT[:SYSTEM] filespec LINK/CHECKPOINT:TASK filespec The /CHECKPOINT qualifier specifies that the task is to be built checkpointable. By default, tasks are built noncheckpointable. Checkpointing of tasks is useful in heavily burdened systems. When a higher priority task wants to be loaded into memory, and sufficient free memory does not exist, one or more lower priority checkpointable tasks will be checkpointed, or "rolled out to disk" in order to free up room for the higher priority task. When the proviously checkpointed task can be brought back into memory, it will continue executing where it left off. The SYSTEM parameter is the default and specifies that the task is to be checkpointed to the system checkpoint file. This is the default, if checkpointing is required. The TASK parameter specifies that the task be checkpointed into its own checkpoint space. Tasks built with the /CHECKPOINT:TASK qualifier will take up about twice as much as disk space than they would have otherwise because space is allocated in the task image file for checkpointing. This qualifier corresponds to the /AL and /CP switches in TKB format. 2 COMPATIBLE LINK/COMPATIBLE filespec The /COMPATIBLE qualifier specifies the memory-resident overlay segments to be aligned on 256-word boundaries for compatibility with other implementations of the mapping directives. Normally, the memory-resident overlay segments are aligned on 32-word boundaries. This qualifier corresponds to the /CM switch in TKB format. 2 CONCATENATE LINK filespec/CONCATENATE The /CONCATENATED qualifier identifies the input file as a concatenated object file. All modules in the file will be processed to form the task image. Normally, only the first object module encountered will be processed, regardless of how many are present. This qualifier corresponds to the /CC switch in TKB format. 2 NOCROSS_REFERENCE #CROSS_REFERENCE 2 CROSS_REFERENCE LINK/[N0]CROSS_REFERENCE filespec The /CROSS_REFERENCE qualifier specifies that a listing of symbol cross-references is to be appended to the Task Builder map file. If you include this qualifier, you automatically include the /MAP qualifier as well. You do not need to specify the /MAP qualifier unless you wish to specify a name for the map file. This qualifier corresponds to the /CR switch in TKB format. 2 DEBUG LINK/DEBUG[:debugspec] filespec The /DEBUG qualifier specifies the inclusion of a debugging aid in the task image. If you do not specify a debugging aid, your task will be linked with the Online Debugging Tool (ODT), a DIGITAL utility included in most RSX-11M and RSX-11M-PLUS systems. If you have a user-written debugger, you may specify it in the quali- fier. This file should be an object module. This qualifier corresponds to the /DA switch in TKB format. See also HELP DEBUG on RSX-11M-PLUS systems. 2 NOSEGREGATE #SEGREGATE 2 SEGREGATE LINK/[NO]SEGREGATE filespec[s] The /SEGREGATE qualifier causes the Task Builder to order program sections alphabetically by name within access code (RO followed by RW). If you also specify /SEQUENTIAL, TKB orders program section in their input order by access code. On RSX-11M-PLUS systems, /SHAREABLE:TASK defaults to /SEGREGATE. Otherwise, /NOSEGREGATE is the default. TKB interleaves RO and RW program sections. When combined with /SEQUENTIAL, /NOSEGREGATE results in a task with program sections allocated in input order with its RW and RO sections interleaved. If you use /NOSEQUENTIAL and /NOSEGREGATE together, which is the default situation, TKB orders program sections alphabetically with RO and RW sections interleaved. This qualifier corresponds to the /[-]SG switch in TKB format. See also HELP LINK SEQUENTIAL. 2 DEFAULT_LIBRARY LINK filespec,filespec/DEFAULT_LIBRARY The /DEFAULT_LIBRARY qualifier specifies that the object library to which it is applied, rather than LB0:[1,1]SYSLIB.OLB, be used as the default library that is searched to resolve unresolved global references. This qualifier corresponds to the /DL switch in TKB format. 2 DUMP #POSTMORTEM 2 POSTMORTEM LINK/POSTMORTEM filespec The /POSTMORTEM qualifier specifies that a Postmortem Dump (PMD) be generated should the task terminate abnormally. See HELP PMD. This qualifier corresponds to the /PM switch in TKB format. 2 FAST LINK/FAST filespec The /FAST qualifier specifies that the Fast Task Builder be used to build the task. The Fast Task Builder is considerably faster than the default Task Builder. Several restrictions apply to tasks which are to be built by the Fast Task Builder: Tasks may not be overlaid Tasks may not be privileged Tasks may not link to resident libraries A symbol table file cannot be produced A resident library cannot be created The LINK command is limited to the following qualifiers: /CROSS_REFERENCE, /[NO]CHECKPOINT[:SYSTEM] /DEBUG[:debugspec], /CODE:FPP, /LONG /MAP[:filespec], /[NO]MEMORY_MANAGEMENT, /WIDE The Task Builder is limited to the following options: ACTFIL, ASG, EXTSCT, MAXBUF, STACK, UNITS In addition, the map format is non-standard and undocumented. 2 FULL_SEARCH LINK/FULL_SEARCH filespec The /FULL_SEARCH qualifier specifies that when processing modules from the default object module library, the Task Builder should search all co-tree (overlay) segments for a matching definition or reference. This qualifier corresponds to the /FU switch in TKB format. 2 GLOBALS LINK filespec/GLOBALS LINK filespec/NOGLOBALS The /GLOBALS qualifier specifies that global symbols referenced and defined by the input file be included in map output. The /NOGLOBALS qualifier specifies that these global symbols be excluded from the map output. The default is /GLOBALS. This qualifier corresponds to the /MA switch in TKB format. 2 NOHEADER #HEADER 2 HEADER LINK/NOHEADER filespec The /NOHEADER qualifier specifies that the task should be built without a task header. This is used for building shared regions or drivers. This qualifier corresponds to the /-HD switch in TKB format. The /HEADER qualifier specifies that the task be built with a task header. A task header is necessary if the task is to run. This is the default. 2 LONG LINK/LONG filespec The /LONG qualifier specifies that the map file produced by the Task Builder include additional file information on modules used in the task build. The long map will not include file information on modules from the system library. If you include this qualifier, you automatically include the /MAP qualifier as well. You will not need to explicitly specify the /MAP qualifier unless you wish to supply a name for the map file. This qualifier corresponds to the /-SH switch in TKB format. 2 MAP LINK/MAP[:filespec] filespec The /MAP qualifier specifies that a map file is to be produced. This file will appear in your UFD and will be printed on the line printer. If you specify a filespec for the map file other than the name of the last input file, the file will appear in your UFD, but will not be printed on the line printer. 2 NOMEMORY_MANAGEMENT #MEMORY_MANAGEMENT 2 MEMORY_MANAGEMENT LINK/MEMORY_MANAGEMENT filespec LINK/NOMEMORY_MANAGEMENT[:n] filespec The /MEMORY_MANAGEMENT qualifier specifies that the task is to be built to run on hardware with the memory management hardware. This is the default. Most systems with DCL have memory management hardware. The /NOMEMORY_MANAGEMENT qualifier specifies that the task is to be built to run on hardware without the memory management hardware. This is useful if you are are building tasks to be run on unmapped RSX-11M systems. n specifies the highest physical address of a task on the target system and can be 28 (the default) or 30. This qualifier corresponds to the /MM switch in TKB format. 2 MULTIUSER #SHAREABLE 2 SHAREABLE LINK/SHAREABLE[:arg] filespec COMMON LIBRARY TASK The /SHAREABLE qualifier identifies the task as multiuser, or shareable. Multiuser tasks allow more than one user to share the read only portions of a single task. This qualifier is for RSX-11M-PLUS systems only. The TASK argument is the default, and identifies a multiuser task. In TKB format this corresponds to the /MU switch. When you use this argument, the Task Builder divides the task into two regions: Region 0 contains the read-write portion of the task and region 1 contains the read-only portion. The COMMON argument identifies a multiuser common. In TKB format, apply the /CO switch to the .TSK filespec. The LIBRARY argument identifies a multiuser library. In TKB format, apply the /LI switch to the library filespec. 2 OPTIONS LINK/OPTIONS[:filespec] The /OPTIONS qualifier indicates that you wish to use one or more of the Task Builder options. If you do not specify a filespec, you will be prompted for the options. You may specify one option per line. When you are through entering options, close them off by entering a carriage return on a line by itself. Here is a list of the options recognized by the Task Builder. For information on a particular switch, type HELP LINK OPTION option. ABORT ABSPAT ACTFIL ASG COMMON CLSTR CMPRT EXTSCT EXTTSK FMTBUF GBLDEF GBLPAT GBLREF GBLXCL LIBR MAXBUF ODTV PAR PRI RESCOM RESLIB RESSUP ROPAR STACK SUPLIB TASK TSKV UIC UNITS VSECT WNDWS @TKBOPT 2 OVERLAY_DESCRIPTION LINK filespec/OVERLAY_DESCRIPTION The /OVERLAY_DESCRIPTION qualifier names an overlay description file (type .ODL) that will control the linking of the task. No other input file can be specified if you use this qualifier. The .ODL file will specify input files to LINK. This qualifier corresponds to the /MP switch in TKB format. 2 PRIVILEGED LINK/PRIVILEGED[:n] filespec The /PRIVILEGED qualifier indicates that the task will be privileged. The optional parameter 'n' specifies the base relocation register. Acceptable values are 0, 4, or 5. The default, if 'n' is not specified, is 5. This qualifier corresponds to the /PR switch in TKB format. 2 QUALIFIERS Command qualifiers: /ANCILLARY_PROCESSOR[:n] /BASIC /[NO]CHECKPOINT:arg /CODE:arg SYSTEM DATA_SPACE TASK EAE /COMPATIBLE FPP /[NO]CROSS_REFERENCE PIC /[NO]DEBUG[:filespec] POSITION_INDEPENDENT /ERROR_LIMIT:n /[NO]EXECUTABLE[:filespec] /[NO]EXTERNAL /FAST /FULL_SEARCH /[NO]HEADER /IO_PAGE /LONG /MAP[:filespec] /[NO]MEMORY_MANAGEMENT[:n] /OPTIONS /OVERLAY_DESCRIPTION /POSTMORTEM /[NO]PRIVILEGED[:n] /[NO]RECEIVE /[NO]RESIDENT_OVERLAYS /SAVE /SELECTIVE_SEARCH /[NO]SEGREGATE /SEQUENTIAL /SHAREABLE[:arg] /SLAVE COMMON /SLOW LIBRARY /SYMBOL_TABLE[:filespec] TASK /[NO]SYSTEM_LIBRARY_DISPLAY /[NO]TASK[:filespec] /TKB /TRACE /[NO]WARNINGS /WIDE Filespec Qualifiers /[NO]CONCATENATE /DEFAULT_LIBRARY /[NO]GLOBALS /LIBRARY /INCLUDE:(module1,...modulen) /OVERLAY_DESCRIPTION /SELECTIVE_SEARCH 2 DATA_SPACE #CODE 2 EXTENDED_ARITHMETIC #CODE 2 EAE #CODE 2 FLOATING_POINT #CODE 2 FPP #CODE 2 PIC #CODE 2 POSITION_INDEPENDENT #CODE 2 CODE LINK/CODE:(arg[,s]) filespec DATA_SPACE EAE FPP PIC POSITION_INDEPENDENT The /CODE qualifier describes the source code for the task being built. The DATA_SPACE argument is for RSX-11M-PLUS only, and specifies that the task employs user-mode I- and D-space. In TKB format, use the /ID switch on the .TSK filespec. The EAE argument specifies that the code assumes the presence of the optional Extended Arithmetic Element hardware. In TKB format, use the /EA switch on the .TSK filespec. The FPP argument specifies that the code assumes the presence of the optional Floating Point Processor hardware. In TKB format, use the /FP switch on the .TSK filespec. The PIC and POSITION_INDEPENDENT arguments are synonomous and specify that the resident common or library being built is position-independent. In TKB format, use the /PI switch on the .TSK or .STB filespec. If you combine arguments, enclose them in parentheses and separate them with commas. 2 NOIO_PAGE #IO_PAGE 2 IO_PAGE LINK/IO_PAGE filespec The /NOIO_PAGE qualifier indicates to the Task Builder that the task is over 12K words and purposely does not map to the I/O page. This qualifier is for building privileged tasks only. The default is /IO_PAGE. 2 SAVE LINK/SAVE filespec The /SAVE qualifier states that you wish to preserve the indirect command file created by LINK to pass commands to the Task Builder. This file, named ATLNK.TMP, consists of your LINK command as translated into TKB commands. You can use this file to duplicate the task build, using a LINK command in the form >LINK @filespec You should rename ATLNK.TMP if you wish to save it. A new file called ATLNK.TMP is created each time you issue a LINK command. 2 NOEXTERNAL #EXTERNAL 2 EXTERNAL LINK/NOEXTERNAL filespec The /NOEXTERNAL qualifier specifies that you wish the task being built to run with its header in pool. The default is /EXTERNAL. This qualifier is for RSX-11M-PLUS systems only. The /EXTERNAL qualifier corresponds to the /XH switch in TKB format. 2 NORECEIVE #RECEIVE 2 RECEIVE LINK/RECEIVE filespec LINK/NORECEIVE filespec The /RECEIVE qualifier specifies that the task may receive messages via the Executive directive SEND. This is the default. The /NORECEIVE qualifier specifies that the task may not recieve messages via the Executive directive SEND. 2 NORESIDENT_OVERLAYS #RESIDENT_OVERLAYS 2 RESIDENT_OVERLAYS LINK/RESIDENT_OVERLAYS filespec/OVERLAY_DESCRIPTION LINK/NORESIDENT_OVERLAY filespec/OVERLAY_DESCRIPTION The /RESIDENT_OVERLAY qualifier enables recognition of the memory resident overlay operator (!) in an overlay description file. This is the default. The /NORESIDENT_OVERLAY qualifier disables recognition of the memory-resident overlay operator. This qualifier corresponds to the /RO switch in TKB format. 2 SELECTIVE_SEARCH LINK filespec,filespec/SELECTIVE_SEARCH The /SELECTIVE_SEARCH qualifier instructs the Task Builder to search the file only for undefined references to global symbols. This qualifier is most useful when building an Ancillary Control Processor or other privileged task that will map into the Executive. If you do not use this qualifier, all global symbols from the input file will be included in the task image. This qualifier corresponds to the /SS switch in TKB format. 2 SEQUENTIAL LINK/SEQUENTIAL filespec The /SEQUENTIAL qualifier directs the Task Builder to construct a task image from program segments in the order in which they appear. Normally the Task Builder finds all program sections referenced in all modules in an overlay segment and then builds the task with those program sections in alphabetical order. Do not use this qualifier to build tasks that rely on alphabetical allocation of program sections, such as FORTRAN I/O handling modules and FCS modules from SYSLIB. This qualifier corresponds to the /SQ switch in TKB format. The /SEGREGATE qualifier interacts with /SEQUENTIAL. See also HELP LINK SEGREGATE 2 SLAVE LINK/SLAVE filespec The /SLAVE qualifier specifies that the task will be slaved to a sending task. When a slaved task successfully executes the RECEIVE DATA Executive directive, it is given the UIC and TI: of the sending task. A slaved task cannot be run with a RUN command. It must be run by the sending task. A slaved task running on a virtual terminal cannot receive data. This qualifier corresponds to the /SL switch in TKB format. 2 SLOW LINK/SLOW filespec The /SLOW qualifier specifies that the Slow Task Builder be used to build the task. You should specify the Slow Task Builder only if your link or task build produces the following error message: LIN -- No virtual memory storage available The default Task Builder and the Fast Task Builder use a symbol table structure which can be searched quickly, but which requires more workfile space than the Slow Task Builder. If you receive the error message shown, you have the choice of reducing workfile size as described in the Task Builder Manual or of using the Slow Task Builder. Except for the use of the different symbol table structure, the default Task Builder and the Slow Task Builder are identical. All qualifiers to LINK and all TKB options are available for the Slow Task Builder. 2 STOP #ERROR_LIMIT 2 ERROR_LIMIT LINK/ERROR_LIMIT:n filespec The /ERROR_LIMIT qualifier directs the Task Builder to abort the build after 'n' error diagnostics have been produced. This qualifier corresponds to the /XT switch in TKB format. 2 SYMBOL_TABLE LINK/SYMBOL_TABLE[:filespec] filespec The /SYMBOL_TABLE qualifier specifies that a symbol table file be produced. If the 'filespec' argument is not specified, the symbol table file will have the same name as that of the first input file and the type .STB. 2 SYSTEM_LIBRARY_DISPLAY LINK/SYSTEM_LIBRARY_DISPLAY filespec The /SYSTEM_LIBRARY_DISPLAY qualifier directs the Task Builder to produce a map that displays global symbols defined or referenced by the task that appear in LB0:[1,1]SYSLIB.OLB or in any shared regions linked to using Task Builder options. This map will usually be con- siderably longer than the default map. The information displayed illuminates the contributions that SYSLIB or the shared regions make to the task. If you include this qualifier, you automatically include the /MAP qualifier as well. You do not explicitly have to specify /MAP unless you wich to supply a name for the map file. This qualifier corresponds to the /MA switch in TKB format. 2 NOEXECUTABLE #TASK 2 EXECUTABLE #TASK 2 NOTASK #TASK 2 TASK LINK/TASK[:filespec] filespec LINK/NOTASK filespec The /TASK qualifier specifies that the Task Builder should generate a task image file. This is the default. If a filespec is not specified, the task image file will have the same name as the first input file, with the type .TSK. The /NOTASK qualifier specifies that the Task Builder not produce a task image file. This qualifier is useful when you wich to use some facility of the Task Builder without building a task, for example, generating a new map file. /[NO]EXECUTABLE is a synonym. 2 TKB LINK/[TKB] filespec The /TKB qualifier specifies that the default Task Builder be used to build the task. This qualifier is the default and is included for completeness only. 2 TRACE LINK/TRACE filespec The /TRACE qualifier specifies that the task will be traceable. When you use this qualifier, a trace trap occurs on the completion of each instruction when the task is run. This qualifier corresponds to the /TR switch in TKB format. 2 NOWARNINGS #WARNINGS 2 WARNINGS LINK/WARNINGS filespec LINK/NOWARNINGS filespec The /NOWARNINGS qualifier suppresses diagnostic messages issued by the Task Builder. 2 WIDE LINK/WIDE filespec LINK/NOWIDE filespec The /WIDE qualifier specifies that the Task Builder generate a map file in 132-column format. This is the default map format. The /NOWIDE qualifer specifies that the Task Builder generate a map file in narrow format. This is the default. This qualifier corresponds to the /WI switch in TKB format. 2 LIBRARY #INCLUDE 2 INCLUDE LINK filespec[s], filespec/LIBRARY[/INCLUDE(:module1,module2,...,modulen)] The /LIBRARY qualifier identifies the file as an object module library. This qualifier is required for any input file that is a library and is prohibited for any other type of file. If you do not use the /INCLUDE qualifier, the Task Builder searches the library file to resolve all undefined global symbol references from files appearing to the left of the library file in the LINK command line. The Task Builder then extracts any and all modules that resolve undefined references and includes them in the task image. You can use /INCLUDE to specify up to eight module names, enclosed in parentheses and separated by commas. In this case, TKB takes only those modules from the library. The default filetype for these modules is .OBJ. The module names are defined at assembly time. In TKB format, apply the /LB switch to an input library file.