Knowledge Base

How do I deliver an application on CD?

Article: P1972

The information in this article applies to:

Product: ToolBook
Component: CD ROM Delivery via Setup Manager
Product version(s): ToolBook 3, 4 and 5

There are three ways to deliver an application on a CD:

1. The application can be completely installed to the hard drive. In this case, the CD is just used to deliver the application to the target computer. The application can be packaged with Setup Manager and the CD root directory will contain SETUP.EXE, the .ASU setup script, and a .001 compressed file containing the application and runtime files. No scripts need to be added to the application since the CD plays no part in the execution of your program.
    
2. The application can be partially installed to the hard drive. In this case, some files are left on the CD and are used by the application while it runs. For example, some multimedia files can be so large in size that it is best to leave them on the CD. The application itself is packaged with Setup Manager (not the files to be left on the CD) and you have the files mentioned in step one above.
    
3. The application can be completely run off the CD with nothing installed to the hard drive. In this case, Setup Manager is not used at all. All the files exist on the CD uncompressed. The main application will be saved as an .EXE and put in the root directory of the CD with the runtime ToolBook files.
   
   To develop an application that will use a CD for distribution, follow the appropriate steps below. There are three steps required to develop any application:
   
   A. Set the directory structure for the program.
   B. Develop and test the application.
   C. Package the media.
   
   If the application is not going to access files on the CD when it runs, use Setup Manager to prepare an installation and put the files in the root directory of the CD.
   
   If the CD is going to be used when the application runs some more steps are required.
    
4. Use script to find the CD when the program runs. See details below.

Setting up the application to run completely off the CD requires additional steps.

Save the book as EXE and put the ToolBook runtime files in the same directory as the executable file. Create a special SETUP.EXE file if necessary.

Details for each of these five steps follow.

1. In the first stages of development you can eliminate some future problems by setting up the anticipated directory structure for the application. Once you decide on the directory structure, develop your application with that same directory structure off the hard drive's root directory.
    
2. Develop and finish your application. During this process, be sure to keep backup copies of your book(s). Test the application thoroughly.
    
3. Package the media. From the Tools menu choose Package Media and in the resulting dialog box choose Media Paths. Set the Media Paths to for both the HARD DISK and CD-ROM by using the Remove Path button. Click OK. This will return you to the Media Packager dialog box. Choose Start.
   
   At this point either the Choose Package Option dialog box or the Find Media File dialog box will be displayed. The Find Media File will be displayed when the system cant find the file specified in the clip manager. In this case, use the Find Media File dialog box to find the file and select OK. The Choose Package Option dialog box will tell you that the file is in neither the CD nor HD media paths. Always click the Add button. When asked which media path to add the path of the file to, select CD-ROM check box and clear the hard drive check box.
   
   At this point the media is packaged. Save the book and test it. If testing fails use a backup copy of the book file and repeat step 2.
   
   Now you can use Setup Manager to create an installation for your application. If your application doesn't use files residing on the CD, the installation will put all the files on the hard drive. If your application accesses files on the CD when it runs, the installation should install every file that won't be left on the CD. If your application runs completely from the CD, don't use Setup Manager at all (since no files need to be installed).
   
   If your application does not access files on the CD, you don't need to apply the following steps.
    
4. When your application runs it will need to know where the CD files are located. When the book first opens, have it create a CDMediaPath with the correct drive letter. After that use the CDMediaPath in any script that refers to files on the CD.
    
   Here is a sample enterApplication handler that triggers your handler that creates the CDMediaPath. The handler that creates the CDMediaPath for an application using files on the CD will be different than the handler for an application running completely off the CD. This handler should go into the book script.
   
   to handle enterApplication
   -- your other code can go here.
   -- pass the message on so that other scripts can be triggered
   forward
   -- create the CDMediaPath using the correct drive letter
   send createCDMediaPath
   -- your other code can go here.
   end
    
5. In the case where the application will be installed to the hard drive and it accesses files on the CD, you need to find the CD and check that it is in the drive. Add these handlers to the book script:
    
   to handle createCDMediaPath
      -- the fileName variable should be assigned a file specific to your
      -- application. It should be a file that would only
      -- exist on your CD and not on any other CD.
      -- Don't put a drive letter before the file name.
      fileName = "files\myFile.tbk"
     
      -- look for the CD with your file until
      -- the file is found or the user quits
      cdDriveLetter = NULL
      while cdDriveLetter is NULL
         -- this returns just a letter with no ":" or "\"
         cdDriveLetter = cdDriveWithFile(fileName)
        
         -- if the CD was not found, alert user
         if cdDriveLetter is NULL      
            -- add a message for the user if CD is missing
            cdMissingMessage = "This program requires a CD. " \ 
               & "Place the CD in the CD-ROM drive and press OK."
           
            -- give user a choice to look again or give up
            request cdMissingMessage with "OK" or "Quit"
           
            -- what did the user choose?
            if it is "OK" 
               -- pause to give the drive a chance to read CD
               -- then look again for CD (continue the loop).
               pause 5 seconds
            else
               -- user chose "Quit"
               -- shutdown the program     
               send exit
               break to system
            end if
         end if
      end while
      
      -- after the while loop, if the script is still running
      -- then we have a drive letter (if the user quit looking,
      -- the program exited)  
      -- construct a CDMediaPath using the correct drive letter
      -- The following lines should be edited to reflect the
      -- directory structure on your CD-ROM.
      -- what do you want your application's CDMediaPath to be?
      -- substitute the names of your directories for the example
      -- directories below
   
      CDMediaPath of this book = \
         cdDriveLetter & ":\mtb40\samples;" & \
         cdDriveLetter & ":\Video"
   end
   
   to get cdDriveWithFile pFileName
      fileName = pFileName
     
      -- if the file isn't found the driveWithFile
      -- variable will remain NULL
      driveWithFile = NULL
   
      -- link the necessary functions to get the drive information.
      -- use TB30DOS.DLL if your version of ToolBook is 3.0
      linkDLL sysToolBookDirectory & "TB40DOS.DLL"
         STRING getCDDriveList()
         STRING getFileOnlyList(STRING,STRING,STRING)
      end
   
      -- link to the Windows API error enabling/disabling function
      linkDLL "Kernel"
         INT SetErrorMode(INT)
      end
     
      -- the CD drive may not have a disk in it.
      -- to avoid the error message that windows generates,
      -- turn off windows error reporting
      get setErrorMode(1)
     
      -- get CRLF delimited list of all CD drives on the system
      allCDDrives = getCDDriveList()
     
      -- step through each drive and check to see if the file is there
      step i from 1 to textLineCount (allCDDrives)   
         -- each drive is a separate textline
         cdDrive = textLine i of allCDDrives
        
         -- construct a version of name with the drive letter
         fileNameWithDrive = cdDrive & ":\" & fileName
    
         -- get a list of all files with that name
         -- it should get a list of one file
         fileList = getFileOnlyList ( fileNameWithDrive , "" , "" )
      
         -- if the file list is not null, we just looked at the CD
         -- with the file so we have the correct drive letter
         if fileList is not NULL
            driveWithFile = cdDrive
            break step -- no reason to keep looking at drives
         end if
      end
   
      -- turn on windows error reporting again
      get setErrorMode(0)
     
      -- if the file wasn't found, the return value will be NULL
      return driveWithFile
   end
   
6. In the case where all the files are on the CD, the correct drive letter will be the drive the main book is on. Add these handlers to the book script:
    
   to handle createCDMediaPath
      -- this returns just a letter with no ":" or "\"
      cdDriveLetter = driveWithThisBook()
     
      -- construct a CDMediaPath using the correct drive letter
     
      -- The following lines should be edited to reflect the
      -- directory structure on your CD-ROM.
     
      -- what do you want your application's CDMediaPath to be?
      -- substitute the names of your directories for the
      -- example directories below
      CDMediaPath of this book = \
         cdDriveLetter & ":\mtb30\samples;" & \
         cdDriveLetter & ":\Video"
   end
   
   to get driveWithThisBook
      -- the name of a book is the full drive, path, and filename
      -- the book.
      return first character of name of this book
   end
    
7. In the case where the application will be completely installed on the hard drive including the media files, create and use a CDMediaPath anyway.
   
   Why use CDMediaPath when the files are on the hard drive? CDMediaPath and HDMediaPath are exactly the same thing: a list of directories to search. Neither care whether the directory is on the CD or the hard drive. So there is no need to consider using both. Let's just use the CDMediaPath. Step 3 packaged all the clips to use it and it is the more intuitive to use since sometime you may want to move the multimedia clips to a CD. If you are using the CDMediaPath now, you just have to change the createCDMediaPath handler so that it builds the correct path.
   
   Add these handlers to the book script:
   
   to handle createCDMediaPath
      -- this returns a path without the "\" on the end
      bookPath = pathOfThisBook()
     
      -- construct a CDMediaPath using the path of the book
    
      -- The following lines should be edited to reflect the
      -- media file subdirectory structure of your
      -- application's book dir.
   
      -- what do you want your application's CDMediaPath to be?
      CDMediaPath of this book = \
         bookPath & "\Sound," & \
         bookPath & "\Video\AVI"
   end
   
   to get pathOfThisBook
      -- the name of a book is the full drive, path, and filename
      -- the book.
   
      bookName = name of this book
     
      -- strip off the filename on the end of the path.
      -- remove characters from the end up to and includign
      -- a "\".
      bookPath = bookName
      while last char of bookPath is not "\"
         clear last char of bookPath
      end while
     
      -- clear the "\"
      clear last char of bookPath
     
      -- return the path without "\" on the end
      return bookPath
   end
   
   If your application runs completely off the CD with no files installed to the hard drive, you need to follow the step below.
     
8. Save the book as an EXE file and put all the runtime files in the same directory as the executable file. To save a book as an EXE file, choose Save As EXE from the File menu. All the necessary runtime files are documented in FILELIST.WRI in your ToolBook directory.
   
   In the steps so far, a user will need to look on the CD for the correct file to run. If you want to create a program group and icons, you should add a SETUP.EXE to the root directory of the CD. Make a SETUP.EXE file specifically for your program. It can be a book saved as an .EXE that does DDE with Program Manager to create a program group and icons. If you use icon files that are on the CD and the CD is removed, the Program Manager icon will turn into a blank icon, so you should also install the necessary .ICO files to the target computer.

OPENSCRIPT NOTICE The OpenScript programming examples found in many articles may need modification in order to work in ToolBook 9.0 or higher, particularly if the article was written for an older version of ToolBook. To learn more, click here.

Provide Anonymous Feedback About This Article

Are you interested in providing feedback to SumTotal about this article? Yes