The Task Builder (TKB), a utility program, builds a task image file from one or more object files. The task image may be a shared region or a task; the region does not have a header. The command line syntax is: >TKB file.TSK[/sw],file.MAP[/sw],file.STB=file.OBJ[/sw],file.OBJ[/sw]. . . or >TKB TKB>file.TSK[/sw],file.MAP[/sw],file.STB=file.OBJ[/sw] TKB>file.OBJ[/sw] TKB>/ ENTER OPTIONS: TKB>option TKB>option . . . TKB>// ! or / if another task is to be built Type HELP TKB SWITCHES for a list of available switches or, for the second format above, type HELP TKB OPTIONS for a list of available options. For information about the overlay description language that allows you to build an overlayed task, type HELP TKB ODL. 2 SWITCHES Apply the following switches to input files or output files. The description of each switch tells you where to use the switch. AC:n - Ancillary control processor MP - Specify ODL file AL - Allocate checkpoint space MU - Multiuser task (RSX-11M-PLUS) CC - Concatenate object modules NM - No diagnostic messages CM - Compatible overlays PI - Relocatable task or region CO - Build a common shared region PM - Post mortem Dump CP - Checkpointable PR:n - Privileged task CR - Add a global cross-reference RO - Memory-resident overlays DA - Add a debugging aid SE - Sends to task DL - Default library SG - Segregate PSECTs EA - Extended arthmetic element SH - Short map FP - Floating point SL - Slave task FU - Full search for symbols SP - Spool map output HD - Include task header SQ - Sequential PSECT allocation ID - I- and D-space task (11M-PLUS) SS - Selective search IP - Task maps I/O page TR - Trace task LB - Specify a library file WI - Wide listing LI - Build a library shared region XH - External header task MA - Map file contents XT:n - Exit TKB after n errors MM:n - Memory management; 28 or 30K For information on an individual switch, type HELP TKB SWITCHES followed by the switch name; for example, HELP TKB SWITCHES CP. 3 AC TKB> file.TSK/AC[:n]=file.OBJ The /AC switch marks the task as an Ancillary Control Processor (ACP) and privileged. The variable n specifies the base relocation register and takes the values 0, 4, or 5. If n is not specified, TKB assumes a value of 5. The default is /-AC. 3 AL TKB> file.TSK/AL=file.OBJ The /AL switch marks the task as checkpointable. TKB allocates the checkpoint space in the task image file. The system tries checkpointing into the dynamic checkpoint space before using the task image space. If dynamic checkpointing is not available, the system checkpoints the task into the task image file space. The default is /-AL. 3 CC TKB> file.TSK=file.OBJ/CC The /CC switch identifies the input file as a concatenated object file. TKB includes all modules in the input file to form the task image. /-CC tells TKB to process only the first object module encountered. The default is /CC. 3 CM TKB> file.TSK/CM=file.OBJ The /CM switch causes TKB to align memory-resident overlay segments on 256-word boundaries for compatibility with mapping directives. The default is /-CM. 3 CO TKB> file.TSK/CO=file.OBJ or ,,file.STB/CO=file.OBJ /CO directs TKB to build a shared common. Use the /-HD switch with the /CO switch. If used with the /PI switch, TKB marks the common as relocatable. If used with the /-PI switch, TKB marks the common as absolute. The /PI and /CO switches affect the contents of the .STB file. There is no /-CO form. 3 CP TKB> file.TSK/CP=file.OBJ The /CP switch directs TKB to mark the task as checkpointable. The system checkpoints the task into the system checkpoint file. The default is /-CP. 3 CR TKB> file.TSK,file.MAP/CR=file.OBJ The /CR switch tells TKB to append a global cross-reference listing to the .MAP file. The default is /-CR. 3 DA TKB> file.TSK/DA=file.OBJ or TKB> file.TSK=file.OBJ,file.OBJ/DA The /DA switch directs TKB to include a debugging aid into the task image. If you specify /DA after the .TSK filespec, TKB includes the On-line Debugging Tool LB0:[1,1]ODT.OBJ in your task image. Using /DA with the /ID switch causes TKB to include LB:[1,1]ODTID.OBJ in the task. If you specify /DA on an input file, the .OBJ file to which it is appended is a debugging aid and TKB transfers program control to that aid. The default is /-DA. 3 DL TKB> file.TSK=file.OBJ,file.OLB/DL The /DL switch specifies a default library. The specified library replaces LB0:[1,1]SYSLIB.OLB as the default library for the task-build operation. The default is /-DL. 3 EA TKB> file.TSK/EA=file.OBJ The /EA switch informs TKB that the task uses the Extended Arithmetic Element. The default is /-EA. 3 FP TKB> file.TSK/FP=file.OBJ The /FP switch informs TKB that the task uses the Floating Point Processor. The default is /-FP. 3 FU TKB> file.TSK/FU=file.ODL/MP The /FU switch directs TKB to search all co-tree overlay segments for matching definitions or references when processing modules from the default library. The default is /-FU. 3 HD TKB> file.TSK/-HD,file.MAP,file.STB=file.OBJ or TKB> file.TSK,,file.STB/-HD=file.OBJ /-HD directs TKB to build the task without a header. Use /-HD for building shared regions or drivers. This switch may be applied to either the task image file or the symbol definition file with equal results. The default is /HD. 3 ID TKB> file.TSK/ID=file.OBJ The /ID switch informs TKB that the task uses both user I-space APRs and user D-space APRs. PSECTs in the task must separate instruction space from data space. The default is /-ID. 3 IP TKB> file.TSK/PR/-IP=file.OBJ The /-IP switch informs TKB that the task is over 12K and does not require mapping to the I/O page. The default is /-IP. 3 LB TKB> file.TSK=file.OBJ,file.OLB/LB or TKB> file.TSK=file.OBJ,file.OLB/LB[:mod1:mod2:...:mod8] The /LB switch specifies an input file as an object library. Without arguments, TKB searches the library file to resolve undefined global references. TKB extracts modules that contain definitions for such references. If modules are specified, TKB includes only these modules in the task image. Up to eight such module specifications may be specified on the switch. 3 LI TKB> file.TSK/LI=file.OBJ or TKB> ,,file.STB/LI=file.OBJ The /LI switch directs TKB to build a shared library. Use the /-HD switch with the /LI switch. The /-PI switch with the /LI switch causes an absolute library. The /PI switch with the /LI switch causes a relocatable library. The /LI and /PI switch combinations affect the .STB file contents. There is no /-LI form of this switch. 3 MA TKB> file.TSK,file.MAP/MA=file.OBJ or TKB> file.TSK,file.MAP=file.OBJ/-MA The /MA switch includes in the .MAP file names of routines from SYSLIB, information from the .STB file of shared regions, and from the .OBJ file. When you apply /-MA to an .OBJ file, the switch excludes global symbols from the .OBJ file in the .MAP file. The default for an input file is /MA. The default for the memory allo- cation file is /-MA. 3 MM TKB> file.TSK/-MM[:n]=file.OBJ The /MM switch specifies that the target system (the one on which the task is to run) has memory management. Specify n as 28 or 30 to indicate the highest physical address in K-words of the task being built. n is ignored if specified with /MM. If n is absent with /-MM, the default highest task address is 28K. The default is /MM if the building system has memory management and /-MM if it does not. 3 MP TKB> file.TSK=file.ODL/MP The /MP switch specifies that the input file, rather than being an object file, is an "ODL" file describing the overlay structure of the task. TKB receives all input file specifications from the .ODL file. The .ODL file contains statements in an Overlay Description Language. For help with this overlay description language, see HELP TKB ODL. The default is /-MP. 3 MU TKB> file.TSK/MU=file.OBJ (for RSX-11M-PLUS only) The /MU switch specifies that your task is a multiuser task. The default is /-MU. 3 NM TKB> file.TSK/NM=file.OBJ The /NM switch directs TKB not to print two diagnostic messages: Module module-name multiply defines P-section p-sect-name and u Undefined symbols segment-name The default is /-NM. 3 PI TKB> file.TSK/PI=file.OBJ or TKB> file.TSK,,file.STB/PI=file.OBJ The /PI switch specifies that the shared region being built contains only position-independant code or data. Use /PI with the /-HD switch for a common or library. Append this switch to either the .TSK file or the .STB file. The /PI switch alone, without /CO or /LI, builds a shared common. The default is /-PI, which builds a shared library. 3 PM TKB> file.TSK/PM=file.OBJ The /PM switch sets a flag in the task that causes a Postmortem Dump to be generated if the task terminates with an SST abort. The default is /-PM. 3 PR TKB>file.TSK/PR[:n]=file.OBJ The /PR switch marks the task as privileged. The octal argument n specifies the first relocation register that maps the task. Valid values are 0, 4, and 5. Without n, TKB assumes a value of 5. The default is /-PR. 3 RO TKB> file.TSK/RO=file.ODL The /RO switch enables TKB to recognize the memory-resident overlay operator (!). The task will have memory-resident overlays. Specifying /-RO causes TKB to build disk-resident overlays. The default is /RO. 3 SE TKB> file.TSK/SE=file.OBJ The /SE switch specifies that the task be allowed to receive messages by means of the SEND directive. The /-SE form inhibits queuing messages to your task. The default is /SE. 3 SG TKB> file.TSK/SG=file.OBJ The /SG switch directs TKB to allocate virtual address space to all read-write program sections before all read-only program sections. With both the /SG and /SQ switches, TKB allocates space in input order by access code. /-SG causes interleaved read-write and read-only sections, but in alphabetical order. The default is /SG. 3 SH TKB> file.TSK,file.MAP/SH=file.OBJ The /SH switch directs TKB to produce the short form of the .MAP file. The default is /SH. 3 SL TKB> file.TSK/SL=file.OBJ The /SL directs TKB to mark your task as a slave to an initiating task. The default is /-SL. 3 SP TKB> file.TSK,file.MAP/SP=file.OBJ The /SP switch directs TKB to spool the .MAP file to the line printer. The default is /SP. 3 SQ TKB> file.TSK/SQ=file.OBJ The /SQ switch directs TKB to group program sections in input order by access code (read-write followed by read-only). /-SQ directs TKB to construct the task with the program sections in alphabetical order. The default is /-SQ. 3 SS TKB> file.TSK=file.OBJ,file.OBJ/SS or TKB> file.TSK-file.OBJ,file.STB/SS or TKB> file.TSK=file.OBJ,file.OLB/LB/SS The /SS switch directs TKB to do a selective search for global symbols. TKB does not include in its internal symbol table the input file global definitions unless a previously undefined reference to the symbol exists. The default is /-SS. 3 TR TKB> file.TSK/TR=file.OBJ The /TR switch directs TKB to set the T-bit for the task and causes a trace trap at the end of each instruction. The default is /-TR. 3 WI TKB> file.TSK,file.MAP/WI=file.OBJ The /WI switch directs TKB to produce the .MAP file in 132-column format. /-WI produces an 80-column map. The default is /WI. 3 XH TKB> file.TSK/XH=file.OBJ The /XH switch directs TKB to build the task with an external header. This switch is for RSX-11M-PLUS only. For RSX-11M-PLUS the default is /XH. Whether /XH is defaulted or specified, or /-XH is specified, the INSTALL command /XHR switch in RSX-11M-PLUS overrides the use of the /XH switch in TKB. 3 XT TKB> file.TSK/XT[:n]=file.OBJ The /XT switch directs TKB to exit after n errors. Specify n in either octal or decimal. If you do not specify n, TKB assumes a 1. The default is /-XT. 2 OPTIONS ABORT - Abort task build MAXBUF - Declares extension to the ABSPAT - Absolute patch value FORTRAN record buffer ACTFIL - Number of simultane- ODTV - Declares address and size ously open files of debugging aid SST vector ASG - Device assignment to PAR - Partition name and size logical units PRI - Task priority CLSTR - Group of shared regions in RESCOM - Task to access user-owned same virtual address space resident common CMPRT - Completion routine address RESLIB - Task to access user-owned for supervisor-mode library resident library COMMON - Task to access system-owned RESSUP - Task to access user-owned shared resident common supervisor library EXTSCT - Extend program section ROPAR - Partition for read-only EXTTSK - Extend task memory portion of multiuser-task FMTBUF - Extension to buffer that STACK - Stack size for task processes format strings SUPLIB - Task to access system-owned, GBLXCL - Exclude global symbols supervisor-mode library from .STB file TASK - Task name GBLDEF - Global symbol definition TSKV - Task SST vector GBLINC - Global symbol inclusion UIC - User ident. code into .STB file UNITS - Logical units usage GBLPAT - Global relative patch VSECT - Allocates base address, GBLREF - Global symbol reference space, and length for a from .STB file virtual P-section LIBR - Task to access system-owned WNDWS - Number of address shared resident library windows For more information type HELP TKB OPTION option. @TKBOPT 2 ODL #OVERLAY 2 OVERLAY The Overlay Description Language allows you to describe the overlay structure of a task. You enter the language into a text file with a .ODL file-type. The text consists of a series of directives with one directive per line. Each line can have as many as 132 characters. You enter the name of this file in a TKB command line. The file has a file-type of .ODL and you identify the file with the /MP switch. This file can be the only input file in the TKB command line. All the other files (object modules and libraries) can be described in the .ODL file. The format for an ODL line is: label: directive argument-list ;comment LABEL: only necessary in .FCTR directives. DIRECTIVES: .ROOT .END .FCTR .PSECT .NAME segname[,attr][,attr] OPERATORS: - concatenate arguments , delimit overlay tree ! memory-resident overlay () group segments * autoload segment For specific information on directives, type HELP TKB ODL followed by the directive; for example, HELP TKB ODL ROOT. For specific information on operators, type HELP TKB ODL followed by the name of the operator. For example: HELP TKB ODL HYPHEN HELP TKB ODL EXCLAMATION_POINT HELP TKB ODL COMMA HELP TKB ODL PARENTHESES HELP TKB ODL ASTERISK 3 ROOT Each overlay description must begin with the .ROOT directive. The .ROOT directive tells TKB where to start building the tree. For example: .ROOT X-(Y,Z-(Z1,Z2)) .END where: X, Y, Z, Z1, and Z2 represent input modules and libraries. In this example, the X module is the root (or control) segment. The other modules (Y, Z, Z1, and Z2) are overlay segments. 3 END Each overlay description in the .ODL file must end with the .END directive. The .END directive tells TKB where the input ends. For example: .ROOT ... .NAME ... .FCTR ... .END 3 FCTR You can build large complex overlay trees and represent them clearly by using the .FCTR directive. A reference in a .ROOT or other .FCTR statement can point to a label in a .FCTR statement. Thus, the .FCTR statement allows you to extend the overlay tree description beyond a single line. The labelled .FCTR statement is additionally useful because only one .ROOT statement is allowed. You can nest the .FCTR statement to a level of 16. An example of using the .FCTR statement is: .ROOT CNTRL-(AFCTR,BFCTR,C) AFCTR: .FCTR A0-(A1,A2-(A21,A22)) BFCTR: .FCTR B0-(B1,B2) .END 3 PSECT The .PSECT directive directly places the global program section in the overlay structure where you want it. The name of the program section and its attributes are given in the .PSECT directive. You use the name in the .ROOT or .FCTR directive to inform TKB where to put the psect. An example of the use of .PSECT follows: .PSECT DATA3,RW,GBL,REL,OVR .ROOT CNTRL-DATA3-(AFCTR,BFCTR,C) AFCTR: .FCTR A0-(A1,A2-(A21,A22)) BFCTR: .FCTR B0-(B1,B2) .END In the example above, the psect DATA3 is placed in the root of the overlay structure above the space allocated for the CNTRL module. 3 NAME The .NAME directive specifies a name and assigns attributes to a segment. The name must be unique; not a file name, program-section name, .FCTR label, or other segment name. You can use the .NAME directive to: 1. Name uniquely a segment to be loaded through the manual load facility 2. Permit a segment that does not contain executable code to be loaded through the autoload mechanism. The .NAME directive format is: .NAME segname[,attr][,attr] segname A 1- to 6-character name that consists of the Radix-50 characters A to Z, 0 to 9, and $ only. attr One of the following: GBL Enters the name in the segment's global symbol table. Enables the loading of nonexecutable segments by the autoload mechanism. NODSK No allocated disk space for the named segment. If a data overlay segment has no initial values, but will have its contents established by the running task, no space for the named segment on disk need be reserved. If the code attempts to establish initial values for data in a segment for which no disk space is allocated ( a segment with the NODSK attribute), TKB gives a fatal error. NOGBL Name not entered in the segment's global symbol table. If the GBL attribute is not present, NOGBL is assumed. DSK named segment has disk storage allocated to it. If NODSK is not present, DSK is assumed. TKB does not attach the described attributes to a segment until the name is used in a .ROOT or .FCTR statement that defines an overlay segment. If you use multiple-segment names, TKB uses the attributes of the last name given. In the following example, you give names to the three main branches, A0, B0, and C, by specifying them in the .NAME directive and using them in the .ROOT directive. The default attributes NOGBL and DSK are in effect for BRNCH1 and BRNCH3, but BRNCH2 has the complementary attributes (GBL and NODSK) that cause TKB to enter the name BRNCH2 into the segment's global symbol table, and to suppress allocated disk space for the segment. .NAME BRNCH1 .NAME BRNCH2,GBL,NODSK .NAME BRNCH3 .ROOT CNTRL-!(BRNCH1-AFCTR,*BRNCH2-BFCTR,BRNCH3-C) AFCTR: .FCTR A0-(A1,A2-(A21,A22)) BFCTR: .FCTR B0-*!(B1,B2) .END The asterisk indicates autoload. The exclamation point indicates memory residency. 3 HYPHEN The hyphen (-) operator indicates the concatenation of virtual address space. For example, X-Y means that TKB allocates sufficient virtual address space to contain module X and module Y at the same time. TKB allocates segment X and segment Y in sequence to produce one segment. 3 EXCLAMATION_POINT The exclamation point (!) operator indicates memory-residency of overlays. Apply an exclamation point immediately before the left parenthesis enclosing the segments to be made memory resident. The exclamation point operator applies to that segment immediately to the right of the left parenthesis and those segments farther from the root on the same level with that segment. In other words, all parellel segments must be of the same residency type. The operator applies to the first segment encountered within the parentheses; segments in parentheses nested within that level but farther from the root are not affected. Example: .ROOT A-!(B-!(C-D),E-(F-G)) In this example, B and E are on the same level emanating from A and thus are memory resident as specified by the outermost !. C and D are memory resident as specified by the inner !, and F and G are disk resident. 3 COMMA The comma (,) operator indicates the overlaying of virtual address space. For example, (X,Y) means that virtual address space can contain either segment X or segment Y. If no exclamation point precedes the left parenthesis, segments X and Y also share physical memory. Including the comma operator outside all parentheses delimits overlay trees. The first overlay tree thus defined is the main tree. For example: .ROOT X,Y X: .FCTR X0-(X1,X2,X3) Y: .FCTR Y0-(Y1,Y2) .END Two overlay trees are specified in the example: 1. A main tree containing the root segment X0 and three overlay segments 2. A co-tree consisting of root segment Y0 and two overlay segments A co-tree must have a root to establish linkage between its own segments. However, the co-tree may be of zero length. 3 PARENTHESES You use parentheses (()) to delimit a group of segments that start at the same virtual address. The number of nested parenthetical groups cannot exceed 16. 3 ASTERISK The autoload indicator marks as autoloadable the segment or other task element. If you apply the autoload indicator immediately before an ODL statement enclosed in parentheses, TKB marks every task element within the parentheses as autoloadable. Placing the autoload indicator at the outermost level of parentheses in the ODL description marks every module in the overlay segments as autoloadable.