Tracing and debugging a C++ client and C++ business object on OS/390

Objective
The following information applies to OS/390.The objective of this sample is to trace and debug a distributed application in step by step mode. Both server and client code are written in C++ and installed on OS/390.

For this exercise, the OLT server, viewer, client controller, and debugger user interface are running on a Windows NT/2000 workstation. Your client and server applications together with the debugger engine are running on an OS/390 system.

npoolt4a.gif (4444 bytes)

The OS/390 client and server applications can be generated on an AIX or Windows NT/2000 system. For this scenario, we will assume that the code is generated on the Windows NT/2000 system that is running the OLT server.

Preparing to run the OLT sample
Follow these step to set up your system to run the OS/390 OLT sample:

  1. Generate code on Windows NT/2000.
    Generate code for debugging and tracing on a Windows NT/2000 system, as follows:

    The following information applies to Windows.From a command prompt on a Windows NT/2000 system, change to your working directory and generate code for debugging, as follows:

    cd x:\CBroker\samples\InstallVerification\ProgrammingModel
    obgen -pBusinessObjects\Policy -aAll -t390 -OIVB_TRACE_DEBUG

    The code will be generated into a 390 subdirectory. The source code on this system will be used for debugging.

  2. Copy generated code to the OS/390 system.
    Copy the generated code from the following directories on the Windows NT/2000 system:

    to the OS/390 system, for example, $IVB_DRIVER_PATH/samples/Policy/Working/390 and $IVB_DRIVER_PATH/samples/Policy/Working/390/TRACE_DEBUG, respectively.

  3. Build C++ business objects.
    Build the C++ server application, as follows:
    1. On the OS/390 system, set the following environment variables:
      export IVB_TRACE_DEBUG=1
      export STEPLIB=none # no compiler override
      export _CEE_PREFIX=SYS1.CEE # default LE
      export _CEE_CBC=SYS1.CBC #default compiler
      export CB390_ROOT=
      <path_to_CB>
      # where <path_to_CB> is the full path to where Component Broker is installed.
      export IVB_DRIVER_PATH=
      $CB390_ROOT/usr/lpp/CB390
      export CB390_ENVFILE=
      $IVB_DRIVER_PATH/samples/CB390make.env
      # this file is needed by the Object Builder-generated makefile
      export NOHFSLNKOUT=1
    2. Edit the prjdefs.mk makefile and change the following setting:
      IVB_TRACE_DEBUG=1
    3. Compile the C++ business object. cd into the the directory where the generated files are located and enter:
      make -f all.mak cpp

      Where all.mak is the Object Builder generated makefile.

  4. Build C++ client application.
    To build the C++ client application, follow the instructions in policyc++.html. Note that you will need to compile with the -g debug option to create debug information.
  5. Prepare OS/390 server environment for OLT.
    Prepare for an OS/390 server environment for OLT by adding the following environment variable to the server JCL:

    IVB_DEBUG_ENABLED=1

  6. Prepare OS/390 client environment for OLT.
    Prepare for an OS/390 C++ client environment for OLT by adding the following environment variables to the client JCL (ensure that your environment file contains "end of string characters" at the end of each line):

    Ensure that the OLT load modules are accessible from your OS/390 server and client. That is, IVBTR30I and IVBTRMSG must be authorized.

    Use the OS/390 component Broker Administration tool to update the application server properties, as follows:

    npcbadmn.gif (16573 bytes)

    1. Set Object Level Trace hostname to the hostname you plan to run OLT server.
    2. Set Object Level Trace port to 2102 (or the same port as the one in the OLT client controller setting).
  7. Set up prog for Component Broker to load application.
    Set up a prog, such as PROGY3, and add statements to load the application DLLs, as follows:
    APF FORMAT(DYNAMIC)
    LPA DELETE MODNAME(JPOLICYS) FORCE(YES) CURRENT
    LPA DELETE MODNAME(JPOLSQMO) FORCE(YES) CURRENT
    LPA DELETE MODNAME(JPOLTRIR) FORCE(YES) CURRENT
    LPA DELETE MODNAME(POLICYC) FORCE(YES) CURRENT
    LPA DELETE MODNAME(POLICYS) FORCE(YES) CURRENT
    LPA DELETE MODNAME(POLSQIR) FORCE(YES) CURRENT
    LPA DELETE MODNAME(POLTRIR) FORCE(YES) CURRENT
    LPA DELETE MODNAME(POLHMIR) FORCE(YES) CURRENT
    LNKLST ADD MODNAME(JPOLICYS) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(JPOLSQMO) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(JPOLTRIR) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(POLICYC) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(POLICYS) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(POLSQIR) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(POLTRIR) DSNAME(BOSSBET.TESTING.SBBOLOAD)
    LNKLST ADD MODNAME(POLHMIR) DSNAME(BOSSBET.TESTING.SBBOLOAD)
  8. Add the Debug Tool to the linklist by appending the following statements to your prog:
    LNKLST UNDEFINE NAME(DTOLT)
    LNKLST DEFINE NAME(DTOLT) COPYFROM(CURRENT)
    LNKLST ADD NAME(DTOLT) DSNAME(BOSSLAP.DT1R20.SEQAMOD) ATTOP
    LNKLST ACTIVATE NAME(DTOLT)

    where BOSSLAP.DT1R20.SEQAMOD is the name of the Debug Tool dataset. The Debug Tool is installed and shipped with OS/390 C++.

  9. Modify your BBOSYMxx file, as follows:
    IVB_DEBUG_ENABLED=1

Description
In this exercise, you will complete these steps:

  1. Set up the OS/390 environment.
  2. Start OLT client controller.
  3. Start Object Level Trace server and viewer.
  4. Run the client application and step into server code.
  5. Deselect step-by-step debugging and run to application completion.

Sample instructions
Follow these steps to perform the tracing and debugging for this scenario:

  1. Set up the OS/390 environment.
    From the console on OS/390, set your prog, as follows:
    set prog=y3

    where y3 is the prog that you have defined to load the OLT Debug enabled application DLLs.

    Then start the Component Broker daemons and activate the application, as follows:

    s bbodmn
    s bboctl
  2. Start Object Level Trace server and viewer on the Windows NT/2000 system.
    In a command window, enter olt to start the OLT server and viewer.
    1. In the OLT viewer window, select Options > Online mode.
    2. In the OLT Viewer, from the Options menu, make sure that Step-by-step Debugging Mode is selected.

    Note: Do not use the Client Controller page in the OLT Viewer window.

  3. Run the client application on the OS/390 system and step into server code.
    1. From a console on the OS/390 system, type the following to run the JCL to start the client application:
      s bboivpj 

      The OLT Viewer soon displays trace lines and event symbols:

      npnocp1a.gif (10563 bytes)

    2. Debug the server code.
      1. The first debuggable event that OLT encounters is a call to the getamount method. At this point, the application halts and a dialog box opens:

        npnocp2a.gif (3961 bytes)

      2. Click OK.
      3. The debugger opens on the server code and a message appears because the source file cannot be located. Specify the source file with the correct path and click OK.
      4. The debugger opens and steps into the getamount method.

        npnocp3a.gif (16724 bytes)

        Now you can perform source level debugging tasks, such as setting breakpoints and monitoring variables, in the server code.

  4. Deselect step-by-step debugging and run to application completion.
    On the debugger toolbar, click Run. The application runs until it encounters the next debuggable server event, the setamount method.
    1. In the OLT Method Breakpoint dialog box, deselect the Step-by-step debugging mode checkbox:

      npnocp5a.gif (3870 bytes)

    2. Click OK. The application runs through to completion.The OLT Viewer now contains a complete trace:

      npnocp7a.gif (13412 bytes)

      At this point, you can set breakpoints on any of the debuggable server events (shown as filled circles on the Policy trace). If you rerun the application client, the debugger opens only on your breakpoints.

ngrelr.gif (548 bytes)
Component Broker Object Level Trace examples
OLT Overview