Server Guide

Packaging a base or reusable module

The procedure below describes how to package: a base module that will be used by a dependent module to run under CICS/ESA, IMS/ESA, or OS/390; or a reusable IC that will be used by a leaf IC 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 application. If your packaged image does not include the correct prerequisite application, it will not run on the target platform.

If you want your own applications included in the base module, ensure that the prerequisite applications are established.

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

Tip icon
Before continuing further with the packaging, ensure that your development image holds configuration maps needed for producing ICs. You will likely need to load the configuration maps ENVY/Packager IC Instructions and VisualAge IC Instructions. If your application uses SST classes, you will also need to load the map Server Smalltalk IC Instructions.

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. This selection is important because it loads the correct configuration map into your passive image.
    2. For Image Name, enter the name of this passive image. This example uses the name Native MVS Target.
    3. 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, select 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 are hidden while all passive image windows are displayed.
    4. 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.
    5. 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. 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:

  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. Press OK.
  3. Close the XD Application Manager.

Step 5: Producing the packaged base or reusable 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 base image, select Create New Instructions and then select a Base Image Component radio button. If you will have only one dependent IC, select the option for a single-dependent base IC. If you will have two or more dependent ICs, select the option for a multiple-dependent base IC. For OS/390, you must select the single-dependent base IC option and have only one dependent IC.

    To package the application as a reusable image, select Create New Instructions and then select a Reusable Image Component radio button.

    Further, you can change the name of the packaged instruction by entering a new name in the input area to the right.

  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 base image begins with only the Kernel included.

    To move applications from the left pane to the center pane, select the application in the left pane and press the >> key. Be careful about what applications you put into a base image. Only stable code should be included in the base, as any change to the base requires that all packaged dependent images using that base be re-packaged. In the example below, the OS/390 Native application has been included; note that its prerequisites were also moved into the center pane to be included in the base image.
    Pressing arrow key(s) to move applications

  4. Select the Startup Code tab from the top of the window. Select a startup class from the Image Startup Class drop-down list. There is no launch code to specify for a base image, so you cannot enter a value in 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 when 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.
  5. Select the Reduce procedure step at the bottom of the window. This minimizes the components in the packaged image. Note that when 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. Yes, you need to reduce the base image!
  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 Image Contents from the Browse menu 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 problem is fixed, save the base image's packaging instructions to make it available to dependent images. This must be done before you output the image. 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 SampleBasePackagerClass as the class name and SampleBasePackagerApp 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.

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 base image is to save the instructions and to not 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 ]