

VERSION 2.00                CAROUSEL TOOLKITS (tm)                  MS-DOS 2.x


                                HOW TO USE THE
                        CAROUSEL BUILDER TOOLBOOK (tm)


Some  of  the files described here are (C) Copyright 1984 Carousel MicroTools,
Inc. -- All Rights Reserved.  They may be used only in accordance with a  duly
executed license from Carousel MicroTools, Inc. 


                                   ABSTRACT


This is a detailed description of the Carousel Builder ToolBook, release 2.00,
for  MS-DOS  and  PC-DOS  versions  2.x.  It explains the purpose of the files
included and teaches how to use them to rebuild or  to  modify  the  Tools  in
Carousel's Use-a-ToolKit (tm) or to build new Tools. 

The  reader is assumed to be acquainted with general programming concepts; the
Ratfor language; the use of Carousel's Tools including AR, CAT,  FORM,  FSORT,
MV,  RATFOR,  and  RM;  the MS-DOS utilities MASM, EXE2BIN, and the linker and
librarian; and the IBM Fortran Compiler.  You will be  instructed  to  examine
certain   files  included  with  the  Builder  ToolBook  while  reading  these
instructions. 


                               GENERAL WARNINGS


1) This edition of the Builder ToolBook  requires  the  IBM  Fortran  Compiler
     version  1.00.   No other compilers or runtime libraries have been tested
     as of July 13, 1984.  This compiler is not included  as  a  part  of  the
     Builder ToolBook:  you must purchase it separately. 

2) To  completely rebuild the Tools from source code, you will also need MASM,
     MS-LINK (or compatible linker), and  EXE2BIN.   MS-LIB  or  a  compatible
     librarian  is  necessary if you wish to modify any of the routines in the
     libraries. 

3) Major portions of the code (in the .OBJ and .LIB  files)  are  regarded  as
     proprietary to Carousel MicroTools, Inc.  Source for most of this code is
     not included. 

4) You  must  use  a working copy of the Use-a-ToolKit to rebuild these Tools.
     Some of the Tools used by the batch files perform jobs that you can do by
     hand, but you probably need RATFOR, FSORT, and perhaps FORM at  the  very
     least. 

5) The runtime routines in the libraries rely on certain assumptions about the
     construction  of  the  finished  programs.   It  is  best  to  follow the
     prescribed source and  batch  files  as  closely  as  possible  to  avoid
     violating  these  assumptions.   Be  particularly  careful when including
     modules written in assembler.  See the instructions below. 

6) Ordinary Fortran I/O (for  example,  READ  and  WRITE  statements)  is  not
     supported.   Use  the  Software  Tools  library routines described in the
     manual, all of which are based on Carousel's implementation of GETCH  and


                                      1




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


     PUTCH. 

7) Your  license  agreement  restricts  distribution  of  the applications you
     build.  You may distribute complete, executable programs only  to  people
     licensed  to  run  the  Carousel  Use-a-ToolKit  for MS-DOS 2.x.  You may
     distribute high-level (Ratfor) code without restriction unless  the  file
     is  marked  with a Carousel copyright notice.  (Most of the Ratfor source
     code in this package is already available in the public domain  from  the
     Software Tools Users Group, Inc.) 

8) Consult  Carousel  if  you have questions about modifying or redistributing
     this code. 


                                     OVERVIEW


THE TOOLS' STRUCTURE AS IMPLEMENTED

The code for the Tools can be considered in three different portions.   First,
there  is  the  particular  Ratfor  code  that implements each Tool's specific
functions.  Each Tool's source code is kept in a .AR file.  For  example,  the
code  for  the CAT Tool is all together in file CAT.AR.  Inside CAT.AR is file
CAT.RAT, which is the main source module for the CAT Tool.  CAT.RAT is written
in Ratfor.  To make CAT into a  working  program,  the  Ratfor  compiler  must
convert  CAT.RAT  into  a  Fortran  version  called  CAT.FOR; then the Fortran
compiler must convert CAT.FOR into an object module  called  CAT.OBJ;  finally
the linker must link CAT.OBJ with the runtime libraries. 

(Although the .RAT files usually contain all of their Tool's source code, they
are not always complete in themselves.  Sometimes they refer to other files by
using  the  Ratfor "include" statement.  CAT.AR, like all of the Tools' source
archives, contains an archive element called LIST.  This file lists all of the
elements of CAT.AR which must be extracted in  order  to  recompile  CAT.   Of
course, LIST mentions CAT.RAT.) 

Second,  there  is  the  code  in  the libraries and in the .OBJ files.  These
routines implement the Software Tools primitive routines  for  basic  I/O  and
other  functions, as described in the Library section of the manual.  They are
invoked when starting any Tool and provide the  low-level  interface  to  DOS.
They also provide the usual Fortran runtime support.  They must be linked with
each executable Tool program. 

Third,  there  is  the  code  implementing  the  Carousel "Toolbox" structure.
Carousel's Tools on MS-DOS and PC-DOS are bundled together  in  groups  called
Toolboxes.   When  an individual Tool is run, CAT for example, DOS first finds
and starts the CAT.COM file.  This little loader program then finds  and  runs
the proper Toolbox containing the CAT Tool, and passes it a message containing
the  command line and a request for the CAT Tool.  The main program inside the
Toolbox is rather simple:  it just examines the message from CAT.COM and  sees
whether  CAT  is  one  of the Tools in this Toolbox; if so, CAT is called as a
subroutine.  It is possible to build a stand-alone  CAT.EXE,  containing  only
the  CAT  Tool,  which just runs as an ordinary application and doesn't have a
special CAT.COM loader program. 




                                      2




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


BIGFILES OPTION

Most of the Tools store data in memory in arrays having fixed sizes.  In  some
cases  this  restricts  the  size of files that may be processed.  Nine of the
Tools (AR, DIFF, ED(E), MACRO, OLDAR, RATFOR, SEDIT, SORTMRG(SORT), and  XREF)
are  provided  with  extra-large  data  arrays in a special version called the
BigFiles ToolBook.  (Standard Tools require about 100K bytes  of  memory,  not
counting DOS; the BigFiles versions require about 200K bytes.) 

The  same  source code files for these nine Tools can generate either version.
You just need to edit the standard symbols definition file  RATDEF  to  define
(or  leave  undefined)  the  symbol  BIGTOOLS;  then  the usual procedure will
produce standard or BigFiles Tools as desired. 

The same .COM loader programs serve both standard and BigFiles versions.  When
they start, they search for the entry

     BIGTOOLS=on

in the environment; then they load one of two  Toolboxes,  depending  on  what
they  find.   (Actually, that happens even for the Tools which lack a BigFiles
version.  For those Tools, the changes they perform on the name of the Toolbox
file result in the same filename whether BIGTOOLS=on or not.) 

There are seventeen different Toolboxes in all.  The standard versions of  the
Toolboxes are numbered from 1 to 12, counting CMTBOX12, which contains the MAN
Tool  only.   The  BigFiles  versions  are  numbered from 27 to 31 paralleling
Toolboxes 7 to 11. 


                           HOW TO REBUILD THE TOOLS


HOW TO READ THESE INSTRUCTIONS

This discussion will proceed in distinct steps, beginning from the "low-level"
routines, up to the final executable Toolbox and loader.  You should read  the
overview  above  and  this  entire  discussion before trying anything, because
principles outlined in one section may cause problems in another if ignored. 

At each step a few specific files will be named.  These examples will tell you
much about how you may  use  the  delivered  source  and  binary  files.   For
example,  the  batch  files demonstrate how to extract required source modules
from an archive, how to invoke the compiler(s), assembler, and/or linker,  and
how  to  clean up the temporary files.  Once you understand what is happening,
you may revise these source archives and batch files to your taste. 

As you examine the batch files, keep in mind the usage  and  function  of  the
Tools  AR,  CAT, FORM, FSORT, MV, RATFOR, RM, the MS-DOS utilities MASM, LINK,
EXE2BIN, and the Fortran compiler.  This information will help you  understand
what each batch file does. 

Most  of the steps are explained in terms of a specific example:  the Tool CAT
and its Toolbox CMTBOX02.  This specific case  is  discussed  in  a  way  that
applies equally well to any other Tool and Toolbox in the Use-a-ToolKit. 



                                      3




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


REMINDERS PERTAINING TO ALL STAGES OF REBUILDING

1) Every Fortran routine linked with the Tools' library must begin with a copy
     of  the file MSHEAD.  This sets two options for the IBM Fortran compiler:
     "$nodebug" and "$storage:2".  These must be set in order for the Tools to
     run. 

2) None of the batch files provided do any error checking.  Therefore you must
     watch them as they run, or revise them to capture error messages  into  a
     log file. 

THE OBJECT MODULES

          Files to study as examples:
               cmt1.obj
               cmt2.obj
               cmt3.obj
               ldbox.bat
               cmtbox02.lrf (inside boxlrfs.ar)

These  .OBJ  files  are not for you to rebuild.  You must link them with every
Tool as shown in LDBOX.BAT.  Do not alter the order:  the first  four  modules
linked  in  each  Tool  must  be  CMT1.OBJ,  CMT2.OBJ,  the  main program, and
CMT3.OBJ.  Other modules must be linked in after these four. 

THE LIBRARIES

          Files to study as examples:
               mshead
               port.lib
               prim.lib
               stub.lib
               port.ar
               mcall.asm
               pubprim.ar
               Your MS-LIB-compatible librarian
               ldbox.bat
               cmtbox02.lrf (inside boxlrfs.ar)

PORT.LIB consists of dozens of separate modules.  All of  the  source  modules
are in PORT.AR.  (Beware:  a few assembly-language routines are included among
those  written  in  Ratfor!   They  refer to MCALL.ASM by means of the INCLUDE
pseudo-op.)  If you modify  any  routine  in  PORT.LIB,  you  must  separately
compile  or  assemble  it and then separately insert it into the library.  See
your librarian's manual for how to examine, decompose,  or  modify  a  library
file. 

Most  of the routines in PRIM.LIB are proprietary to Carousel MicroTools, Inc.
and source code is not provided.  Source for the public-domain routines within
PRIM.LIB is in PUBPRIM.AR.  Again, if you modify any of  these  routines,  you
must  compile  it separately and then re-insert it into the library by using a
librarian program. 

STUB.LIB is a modified version of the standard Fortran  runtime  library.   It
specifically  excludes  some  of  the usual I/O initialization routines.  (For
this reason Fortran-style I/O using READ and WRITE statements is  prohibited.)


                                      4




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


It  includes  a  routine to route Fortran arithmetic errors through the Tools'
ERROUT file descriptor.  Carousel does not provide the source for STUB.LIB. 

RECOMPILING A SINGLE TOOL

          Files to study as examples:
               mshead
               cat.ar (perhaps packaged inside another archive file)
               rcfctool.bat
               ratdef

To recompile CAT, first find the CAT.AR file  containing  all  of  the  Tool's
source  code.  CAT.AR may be archived inside another file; if so, you must use
the AR Tool to extract it before running RCFCTOOL.BAT. 

The standard definitions file RATDEF must be in the current  directory  before
running  RCFCTOOL.BAT.   As  shipped  with  the  Builder  ToolBook,  RATDEF is
configured for rebuilding the standard, non-BigFiles Tools.  If  you  want  to
make  a  BigFiles  version, edit RATDEF to define the symbol BIGTOOLS.  If you
want to build a Tool that will stand alone outside of a Toolbox,  edit  RATDEF
to leave the symbol INBOX undefined. 

With  CAT.AR and RATDEF present in the current directory, you are ready to run
RCFCTOOL.BAT.  It produces CAT.OBJ ready to link into a program. 

This CAT.OBJ file may conflict with the CAT.OBJ that gets made into the loader
program CAT.COM.  So you may want to compile and  link  Tools  in  a  separate
directory from where the loader programs get built. 

RECOMPILING A TOOLBOX MAIN PROGRAM

          Files to study as examples:
               cmtbox02.rat (inside boxmains.ar)
               prfx
               rcfcbox.ar
               mshead

The seventeen Toolbox main programs such as CMTBOX02.RAT are archived together
in BOXMAINS.AR. 

Do not change the initialization code with which the main programs begin. 

The  main  body  of  each  main program is a chain of "if ... else if" choices
generated by the macro BOXCHOICE.  At each stage along this chain the name  of
the  Tool invoked is compared against a string naming one of the Tools in this
box.  If they match, a subroutine is called to perform the Tool's actions.  If
none of the strings matches, the macro BOXDEFAULT announces that the  Tool  is
unknown, hence that perhaps the wrong Toolbox was loaded. 

(Note  that  the macro BOXCHOICE has three arguments:  the name of a Tool, the
name of a string to contain that name, and the name of a subroutine  to  call.
These three arguments may all differ.  The subroutine name must match the name
defined by the DRIVER macro inside each Tool's source code.) 





                                      5




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


Recompiling   a   main   program   for  a  Toolbox  is  straightforward.   Use
RCFCBOX.BAT.  The symbols INBOX and BIGTOOLS defined in RATDEF are  irrelevant
at  this  point.  A copy of the file PRFX must be present.  (This file defines
the common block which contains the name  of  the  particular  tool  invoked.)
Each  Fortran  file  such as CMTBOX02.FOR must begin with a copy of MSHEAD, as
usual. 

RELINKING A TOOLBOX

          Files to study as examples:
               ldbox.bat
               cmtbox02.lrf (inside archive file boxlrfs.ar)

To link a Toolbox, first you must recompile all of the Tools it  includes  and
the  Toolbox main program.  (When recompiling the Tools for a Toolbox, be sure
that INBOX is defined in the copy of RATDEF that you use.)  These .OBJ  files,
as well as the libraries, must be present before you run LDBOX.BAT. 

LDBOX.BAT commands the linker by passing it the name of an "automatic response
file" such as CMTBOX02.LRF. 

By naming STUB.LIB as the last library searched by the linker, LDBOX.BAT makes
sure  that  all  the usual Fortran runtime support is linked into the program.
FORTRAN.LIB is not absolutely necessary, but you may want to have  it  in  the
current  directory  to save time, because of the following process:  The first
time you link new code, the linker may find an undefined external name.  After
searching for it in all of the libraries you name, the linker's next  step  is
to  search  FORTRAN.LIB.   If  FORTRAN.LIB  can't  be  found, the linker quits
without telling you the missing name.  Therefore  it's  often  handy  to  keep
FORTRAN.LIB  in  the current directory when linking new code, in order to find
the names of missing externals.  When the code is complete you  can  link  the
program without having FORTRAN.LIB present. 

REBUILDING A .COM LOADER PROGRAM

          Files to study as examples:
               toolcom.asm
               cat.frm (inside cmtforms.ar)
               makecom.bat

TOOLCOM.ASM  is  the  template  from which all of the .COM loader programs are
built.  The FORM Tool is used to convert it into particular  assembler  source
modules  such as CAT.ASM.  FORM substitutes the individual differences for the
six items

     {version}
     {date}
     {initials}
     {small box number}
     {toolname}
     {big box number}

which are placeholders for the actual values which vary  from  Tool  to  Tool.
CAT.FRM  contains  the  particular  replacement  values  used by the CAT Tool.
These values  are  the  only  differences  between  the  various  .COM  loader
programs. 


                                      6




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


Once  FORM  has built CAT.ASM, further processing to build CAT.COM proceeds in
the normal manner.  As usual for .COM files, the linker's message

     Warning: No STACK segment

is to be expected (and ignored). 

Of course, one of the intermediate files created by  MAKECOM.BAT  is  CAT.OBJ.
This  may clobber a copy of CAT.OBJ waiting to be linked into a .EXE file.  So
you may want to set aside  a  separate  directory  for  building  .COM  loader
programs, to avoid conflict with the Tools themselves. 

HOW TO TEST A REBUILT TOOL

          Files to study as examples:
               cat.com
               cmtbox02.exe

(Of course, this procedure assumes that none of the steps taken while building
these files has reported any errors.) 

If  you  are rebuilding a Tool without any changes, begin by comparing the new
.EXE and .COM files against the ones included in the Use-a-ToolKit.  It is  to
be  hoped  that they are identical.  However, you may observe differences that
are harmless because they have no effect on how the  programs  load  and  run.
For  instance,  sometimes  DOS  linkers  generate .EXE files with extra header
fields whose meanings are not documented.  Different versions  of  the  PC-DOS
linker  can  from  the  same input generate .EXE files of different length but
containing identical  header  tables  and  load  images.   Such  files  appear
different but are functionally identical as .EXE files. 

Begin  testing  by  setting the current directory to be one containing none of
the other Tools or Toolboxes, and copy the new CAT.COM and  CMTBOX02.EXE  into
the current directory.  Enter as commands

     path ;
     set toolpath=

to  clear  PATH  and  TOOLPATH  from the environment so that none of the other
Tools can be found and invoked inadvertently.  (Check that PATH is  empty  and
that TOOLPATH is gone by entering just "set".) 

Next enter

     cmtbox02 jjj

The Toolbox CMTBOX02.EXE should respond

     jjj:  not in this box

demonstrating  that the Toolbox main program can start up the I/O routines and
give an error message. 

Next enter

     cmtbox02 cat ?


                                      7




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


which should give the message

     usage:  cat [file ]

demonstrating that CAT has been found inside the Toolbox and can give its  own
usage message. 

If  those  tests work, then the Toolbox has probably been built properly.  Now
test CAT.COM in isolation as follows.  With TOOLPATH  still  absent  from  the
environment, enter "cat".  CAT.COM should complain

     no TOOLPATH entry in environment

verifying that CAT.COM can at least give a coherent message.  Now set TOOLPATH
to  point to some directory which doesn't contain any file named CMTBOX02.EXE.
Enter "cat" again; this time it should complain

     can't load cmtbox02.exe from TOOLPATH directory

(If you are testing a Tool having a separate BigFiles version, try  that  last
experiment  first  with  BIGTOOLS=on  in  the  environment, then with BIGTOOLS
removed from the environment.  Check the different Toolbox numbers that appear
in each case.) 

Finally set TOOLPATH  to  point  at  the  directory  containing  the  copy  of
CMTBOX02.EXE under test.  This time enter

     cat ?

which should give this Tool's usage message as we saw it above. 

If  the  Tool and Toolbox pass all of these tests then they probably have been
put together correctly.  If you have changed any of the code  or  construction
procedures  then  there  is much more that you should check.  Start by testing
the functions you intended to change.  Also try some of the examples from  the
manual. 

If  you  find  problems, remember to compare the doubtful behavior against the
behavior of the executable versions included in the Use-a-ToolKit. 


                           HOW TO MODIFY THE TOOLS


GENERAL PRINCIPLES AND WARNINGS

1) Try to stay within  the  existing  procedures  and  framework.   Carousel's
     implementation  of the Software Tools library necessarily takes advantage
     of many ill-documented, subtle properties of the IBM Fortran compiler and
     runtime library.  Many parts of Carousel's runtime  library  assume  that
     they  are running in a certain setting and then they make changes to that
     setting.  This means that there are certain things you just can't do in a
     Tool, and not all of them are known. 





                                      8




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


2) Beware  of  too  much  expansion,  especially  when  combining  Tools  into
     Toolboxes.   The  existing Toolboxes were carefully tuned to run in about
     100K bytes of  memory  (about  200K  bytes  for  BigFiles  version),  not
     counting  DOS.   If  you  add  much  code or many variables or expand the
     arrays much, they will no longer run in such small environments. 

     (If a .EXE file cannot be loaded, that may be a symptom that it  requires
     too much memory.  If the message

          insufficient memory for dynamic store

     appears when starting a Tool, that may reflect either insufficient memory
     or  too  many  variables  and  constants.  The latter problem can only be
     solved by redesigning the program.) 

     (Memory requirements can be  reduced  by  re-using  common  blocks.   For
     instance,  the  DIFF  and SORTMRG Tools in CMTBOX08.EXE both use the same
     common blocks.  Since only one of them can run at a  time,  there  is  no
     conflict.) 

3) The   global   symbols   listed  in  the  file  called  HANDSOFF  represent
     subroutines, functions, and variables used by the Carousel  library.   Do
     not  define subroutines, functions, or public symbols having any of these
     names unless you thoroughly understand their function and are willing  to
     handle the risk. 

     (It is a fairly straightforward process to modify or replace the routines
     in  PORT.AR and PUBPRIM.AR using the procedures outlined above.  However,
     the  Tools'  high-level  code  assumes  that  these  routines  meet   the
     specifications in the manual, so if you change them, make sure they still
     meet  those specifications.  In fact, the specifications do not perfectly
     describe all of the assumptions placed on the library  routines,  so  you
     should  test  any  modified library routine by watching its effects in an
     existing Tool.) 

4) In addition to the hands-off  symbols  listed  in  HANDSOFF,  each  of  the
     existing  Tools  also  defines  several  functions  and  subroutines.  Of
     course,  these  usually  occur  in  explicit  FUNCTION   and   SUBROUTINE
     statements  visible  in  the Ratfor source code.  However, when the macro
     DRIVER is used in a statement like

          DRIVER(cat)

     this has the effect of declaring CAT as a  subroutine.   Also,  DIFF  and
     other  Tools  use  the  Ratfor  "define"  macro  to establish aliases for
     function and subroutine names.  Beware of duplicating any of the function
     or subroutine names used in modules linked with your code, for  instance,
     in Tools sharing a Toolbox. 

5) Beware  of  duplicating  names  of  common blocks used by the library or by
     individual Tools linked with your code.  The following common blocks  are
     used by the library: 

                              args
                              cdsmem
                              config


                                      9




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


                              dio
                              dirs
                              drvdirs
                              dsflgz
                              firstc

     Again,  some  of  the Tools use the Ratfor "define" macro to make aliases
     for the common blocks they define. 

6) Carousel's library makes extensive assumptions about  the  order  in  which
     segments  are  linked.   Follow the instructions below to avoid violating
     these assumptions. 

     If you vary the link order, add a library, or add a module  generated  by
     something other than the IBM Fortran compiler, check that the segments of
     your program get linked in the following order: 

                         Segment      Class
                         
                         UTIL6        CODE
                         (various)    CODE
                         (various)    (unnamed)
                         HEAP         MEMORY
                         MEMORY       MEMORY
                         STACK        STACK
                         DATA         DATA
                         COMADS       COMADS
                         CONST        CONST
                         (various)    COMMON
                         HIMEM        HIMEM

     Be  sure  that  UTIL6  is  the  first segment and that HIMEM is the last.
     Don't add to or change the sequence of segments from HEAP to HIMEM except
     to add common blocks.   Don't  define  anything  having  class  "MEMORY".
     Don't mess with COMADS. 

7) Remember  that  the  first  four  object  modules  linked must be CMT1.OBJ,
     CMT2.OBJ, the module with the main Fortran routine, and CMT3.OBJ, in that
     order.  Any other object modules (such as individual Tools in a  Toolbox)
     must  come  after  these.   The  last  three  libraries  searched must be
     PORT.LIB, PRIM.LIB, and STUB.LIB, in that order. 

HOW TO BUILD A STAND-ALONE TOOL (NOT IN A TOOLBOX)

          Files to study as examples:
               cat.ar (perhaps packaged inside another archive file)
               rc2.bat
               ratdef

Write the Tool's Ratfor code as usual.  Build the code into a single .RAT file
(perhaps augmented by the Ratfor  "include"  statement).   Following  standard
Ratfor  practice,  begin the Tool's main routine with a call to DRIVER and end
it with

     DRETURN
     end


                                      10




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


(Or use the .AR source archive belonging to a Carousel Tool -- the  code  need
not be changed.  Just extract all of the source files listed in LIST.) 

Run  RC2.BAT to compile and link the Tool.  Be sure that the copy of RATDEF in
the current directory leaves the symbol INBOX undefined.  This will cause  the
proper version of DRIVER to be invoked. 

HOW TO ADD AN ASSEMBLY-LANGUAGE ROUTINE

          Files to study as examples:
               mcall.asm
               pkunpk.asm (inside port.ar)
               the IBM Fortran manual, Appendix D:  Linking Object Modules

Attempt  this  only if you have experience in assembly-language programming on
MS-DOS. 

Define your code segment(s) to belong to class CODE. 

Define your data segment(s) in any of these ways: 

     1) As part of class CODE.   To  address  the  data,  construct  your  own
          segment values, probably by using the SEG operator. 

     2) As  part  of  the  no-name  class,  i.e.,  with class unspecified.  To
          address the data, construct your own  segment  values,  probably  by
          using the SEG operator. 

     3) As  part  of  segment  DATA  (align-type WORD, combine-type PUBLIC) in
          class DATA, in group DGROUP.  Your data will  be  relocated  as  the
          Tool  starts  up.   You  can  assume  that the DS register points at
          DGROUP when your routine is called. 

Be sure your code obeys the protocol for calling an assembly-language  routine
from IBM Fortran. 

Link the object module(s) after CMT3.OBJ and before the libraries. 

HOW TO ADD YOUR OWN LIBRARIES

          Files to study as examples:
               ldbox.bat
               cmtbox01.lrf (inside boxlrfs.ar)

Be  sure  that  each  module  in  the  library obeys all of the rules in these
instructions. 

Link the library before PORT.LIB. 

If any of the routines in the library declares a common block, be sure that at
least one of the .OBJ files linked declares the same common block. 

Generate a map when you link the program.  Check that  segment  HIMEM  is  the
last one. 




                                      11




                   HOW TO USE THE CAROUSEL BUILDER TOOLBOOK


HOW TO ADD MODULES WRITTEN IN ANOTHER LANGUAGE

          Files to study as examples:
               the IBM Fortran manual, Appendix D:  Linking Object Modules

This  may  be  a  very  delicate  operation because the Carousel library is so
sensitive to the order in which segments are linked.  It  might  work  if  the
object   modules   conform   to   all   of   the   restrictions   placed  upon
assembly-language routines, as listed above. 

Please contact Carousel MicroTools, Inc., to discuss your results. 















































                                      12


