Server Guide

Packaging a dependent or leaf module

The procedure below describes how to package: a dependent module that uses a base module to run in a native server environment or under CICS/ESA, IMS/ESA, or OS/390; or a leaf module that uses a reusable module to run in a native server environment.

Step 1: Establishing prerequisite applications

Before you create a passive image for packaging, ensure that your application has the correct prerequisite applications. If your packaged image does not include the correct prerequisite applications, it will not run on the target platform.

Step 2: Releasing all classes to your application

You must release all classes to your application; otherwise, when you load your application into the passive image, the classes will not be loaded or will not contain the latest updates. To version and release all classes to your application in the development image, select Manage Applications from the Tools menu; then--

  1. In the Application Manager, select your application from the selection list.
  2. From the Classes menu, select Version/Release All > Use Defaults and press OK.
  3. You can also version the application by selecting Version > Use Defaults from the Applications menu and pressing OK.
  4. Close the Application Manager.

Step 3: Making the passive image the current image

If you do not already have a passive image, add one by following these steps:

  1. From the XD menu of the System Transcript, select New Image.
  2. In the Image Properties window, change the following values:
    1. For Image Type, select the correct type of image for this passive image.
    2. For Image Name, enter the name of this passive image. This example uses the name Native MVS Target.
    3. From the Installed Features list, select which features of VisualAge Smalltalk Server you want pre-loaded into this passive image. Note that if you choose not to load certain features at this time, you can load the features into the image later.
    4. When you have a development image and a passive image running at the same time, your screen can be filled with many windows. If you want the windows of only the current image to be displayed, click the box next to Hide Windows. For example, if you change from the development image to the passive image, all windows of the development image will be hidden while all passive image windows will be displayed.
    5. For more information about setting the locale, see Appendix D, National Language Support for CICS/ESA, IMS/ESA, OS/390, or OS/400 or the IBM Smalltalk Programmer's Reference.
    6. Press OK to create the passive image.

Image Properties window

When you switch to the passive image -- whether you have just created it or it has been previously created--the XD Transcript window opens. The XD Transcript is to this passive image what the System Transcript is to the development image. Each passive image has its own XD Transcript. The XD Transcript looks like this:
XD Transcript window

Step 4: Loading your application into the passive image

To load your application into the passive image, select Manage Applications from the Tools menu of the XD Transcript window; then--

  1. In the XD Application Manager, select Load > Available from the Applications menu.
  2. Select your application or applications, indicating the edition you want loaded, and press the >> button to move the applications to the Selected Editions pane. Select OK.
  3. Close the XD Application Manager.
Tip icon
If you are packaging a CICS application that accesses IMS databases, ensure that the prerequisite IMS applications are loaded into the passive image.

Step 5: Producing the packaged dependent or leaf image

To produce the packaged image, select Browse Packaged Images from the Tools menu of the XD Transcript window:

  1. The first time you package an application in this passive image, the XD Packager Control Panel window will open with the Create New Instructions tab in the foreground. Subsequent packaging commands will open the XD Packager Control Panel with the Instructions In Memory tab in the foreground. If you are packaging a previously packaged application image again, choose one of the previously packaged application's instructions.

    To package an application as a single image for the first time, select Create New Instructions and then select a Dependent Image Component radio button. If you have a single dependent base IC, select the single dependent IC option. If you have a multiple dependent base IC, select the reusable IC or the leaf IC option. If you have a reusable IC for your core classes (and no base IC), select the leaf IC option.

    You can change the name of the packaged instruction by entering a new name in the input area to the right. In the example provided below, the dependent image will be packaged as Sample Dependent Image.
    Naming a packaging instruction

  2. Select the Modify Instructions tab from the procedure bar at the bottom of the screen. The active procedure step will have a white background.
  3. In the XD Packager Control Panel window, select the Applications and ICs tab at the top of the window. There are three panes displayed in this window. The left pane contains those applications that are available in this passive image but that are not currently included in the packaged image. The center pane contains those applications which are to be included in the packaged image. The right pane contains the name of the base images available to this dependent image.

    To move applications from the left pane to the center pane, select the application in the left pane and press the >> key. If you want to specifically exclude applications from the packaged image before reducing the non-referenced methods, select the applications you do not want in the packaged image in the center pane and move them to the left pane. Ensure that the application you are packaging and its prerequisite applications are in the center pane. You must also select the base image you want to be associated to this dependent image in the right pane and move it into the center pane.
    Pressing arrow key(s) to move applications

  4. Select the Startup Code tab from the top of the window. To specify the startup class, select one from the Image Startup Class drop-down list. To specify the launch code for the application, enter it into the Application Entry Point input area. To specify the file name for the packaged image, enter it into the Output File input area. You can also select Choose to open a file selection window. Note that after you complete the Modify Instructions step, the yellow flag is removed from the upper right corner of the procedure step at the bottom of the window.
    Specifying launch code
  5. Select the Reduce procedure step at the bottom of the window. This minimizes the components in the packaged image. Note that after you complete the Reduce step, the yellow flag is removed from the upper right corner of the procedure step at the bottom of the window.
  6. Select the Examine & Fix Problems procedure step at the bottom of the window. From this window you can browse any errors that the packager has found. Also from this window you can choose Browse Image Contents to display the applications, classes, and methods that have been included in the packaged image. You can modify the included objects from the image content browser.
  7. Once the problems have been fixed, save the packaging instructions. This must be done before you output the image. You do not need to save the instructions, but once the XD Packager Control Panel window closes, any packaged image instructions that were not saved are unrecoverable. To save the packaged image's instructions, select the Save Instructions procedure step at the bottom of the window:
    1. Select the Save these instructions radio button.
    2. Select the Keep these instructions in memory radio button.
    3. In the Save Instructions box, supply a class name in the as class input area and an application name in the in application input area. The example below displays SampleDependentPackagerClass as the class name and SampleDependentPackagerApp as the application name. You can also choose an application from the available list of applications by selecting Choose Application.
      Tip icon
      For cross-platform debugging in XD, use options available from the Snapshot menu to store a snapshot of your image and packaging instructions. You can store the snapshot to a file (.snp file) or to the library.

      Snapshot
    4. Press the Save Now button. Once the packaging instructions are saved, you can re-package the same application when you open the packaged images browser by selecting Instructions In Memory from the Choose Instructions procedure step at the bottom of the window.
  8. Select the Output Image procedure step at the bottom of the window. The applications will be packaged into the file name you supplied on the Startup Code panel under Modify Instructions.
  9. If you are packaging with the interactive debugger, you are prompted to specify the destination identifier associated with the development workstation to be notified if a Smalltalk error occurs. This is the destination name you supplied in the side information of the target image. See Using the interactive debugger for more information. The specification you supply is saved globally throughout the images. If you do not make this specification, a Smalltalk error in your application will produce a stack dump. To change the workstation address at any time, select Set Workstation Address from the XD menu of the XD Transcript window.

When closing the XD Packager Control Panel, the options on the Save Instructions window determine the action taken for each packaging instruction, if the instructions were not saved during the packaging process. If you saved the packaging instructions during the packaging process, you can close the Packager Control Panel without concerning yourself about whether the instructions will or will not be saved. The Save or Don't Save radio buttons options are as follows:

The Keep or Don't keep in memory radio buttons options are as follows:

The default setting for a dependent image is to save the instructions and to keep the instructions in memory.

If you are packaging for CICS/ESA, go to Step 2: Building the CICS load module. If you are packaging for IMS/ESA, go to Step 2: Building the IMS load module. If you are packaging for OS/390, go to Step 2: Building the OS/390 Native load module.

To test your packaged image, see Running a packaged image.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]