BDT and Runtime Program Arguments

Program Arguments Overview

BBj Runtime Environments (BREs) and Eclipse Run Configurations both play a role in configuring the bbj.exe command line invocation that BDT makes when a user invokes “Run as a BBj program.” In both cases, the goal is to define any unique program arguments that BDT/BBj should pass to a BBj program when it is run (using the ARGC and ARGV argument variables).

For a discussion on BBj Runtime Environments (BREs), see the BRE Management in BDT online help document.

For an explanation of how bbj.exe passes program arguments once they are on its command line, see the BBj Command Line online help document.

Both objects (BREs and Run Configurations) offer a field where a user can enter program arguments, but the purpose and usage of those two fields vary slightly. The purpose of this document is to explain the relationship between those two fields and to offer suggestions on when a user might want to use one instead of the other.

The BRE’s "Default Program Arguments" Field

This field would perhaps be easier to understand if it was named "Run Configuration Creation Program Arguments" instead of "Default Program Arguments." In other words, the text you put in this field is only used to populate the “Program Arguments” field in a new Eclipse Run Configuration at creation time and only when BDT automatically creates that Run Configuration for you. It is ignored in all other situations. See below for details of how Run Configurations control the program arguments that are passed to bbj.exe.

The Run Configuration’s "Program Arguments" Field

An Eclipse Run Configuration is a collection of values passed to bbj.exe when the user asks to run a program. A Run Configuration defines the values that BDT will pass on the bbj.exe command line. A Run Configuration is a type of Eclipse Launch Configuration used to run a BBj GUI program.

  • The BDT automatically creates a Run Configuration for you whenever you ask it to run a BBj program file for the first time. Specifically, if you ask to run your BBj program and a Run Configuration already exists for it, BDT/Eclipse will use it. Otherwise, BDT will create a new Run Configuration. When it creates that new Run Configuration, BDT populates the "Program Arguments" field with whatever text is present at that moment in the relevant BRE’s "Default Program Arguments" field.

  • Once a Run Configuration exists for your program, running that program uses the “Program Arguments” field value there (at that time, BDT ignores the BRE's "Default Program Arguments" field). The argument(s) text in the Run Configuration's "Program Arguments" field is what gets passed to bbj.exe on its command line and, thus, what is available to your BBj program.

  • You can edit the “Program Arguments” field in any Run Configuration, and that information will be remembered and used from then on.

  • You may delete any Run Configuration at any time. This will permit you to start over and create a new Run Configuration for your program. Remember that any and all edits to the Run Configuration are lost when you delete it.

Editing a Run Configuration

To see and edit a Run Configuration for the execution of a BBj GUI program, follow these steps:

  • In Eclipse's main menu, click on the downward-pointing black triangle next to the "Run Configurations" toolbar button, and click "Run Configurations…" as shown in Figure 1:

Figure 1. The Run Configurations Menu Item

  • In the "Run Configurations" window, select the run configuration (in the left-side navigation tree) for the BBj program you want to configure. When BDT creates the Run Configuration for you, the Name will be the same as the BBj Program, as shown in Figure 2:

Figure 2. Editing the Run Configuration for BBjUtilitiesSource.bbj

  • In the "Run Configurations" window, put your argument(s) as text in the "Program Arguments" field, as shown in Figure 2.

  • Save your "Run Configuration" by clicking the [Apply] button.

  • You may then run your program by clicking the [Run] button; this will also close the Run Configurations window. If you do not want to run it, simply click the [Close] button.

Rationale

Exactly why do we have this odd relationship between the BRE and the Run Configuration? It is easier to understand that if we start by asking a question or two:

  • Where does it make the most sense to define "program arguments"?

  • At the BBj project level (in the BRE) or at the program level (in the Run Configuration)?

The BRE was originally created to capture "all of the command line arguments that bbj.exe offers, letting the user define all of them in one place." Given that, it made sense to have a way to set the "program arguments" in a BRE. But, since "program arguments" may also need to be different for every BBj program (thus the name), it also made sense to be able to override them at the program level (in other words, to configure BDT to send different arguments along to each BBj program). That overriding is only possible in Eclipse via Eclipse's Run Configuration.

And so, we end up with the ability to configure program arguments in two places, with each place providing a slightly different effect.

Understanding and Choosing the Right Option

When and why might you configure the program arguments in one of these locations instead of the other?

Default Program Arguments in the BRE

Enter your argument(s) in the BRE’s “Default Program Arguments” field if:

  • Every BBj program that uses this BRE needs the same arguments to be passed to it at run time.

  • You have not yet run your BBj programs (so that when you run them for the first time, this field’s text will be set in each new Run Configuration as a “creation default”).

Program Arguments in the Run Configuration

Enter your argument(s) in the Run Configuration’s “Program Arguments” field if:

  • A BBj program needs to have unique program arguments passed to it at run time. By setting the Program Arguments field in each Run Configuration differently, you can provide a different set of runtime arguments to each BBj program.

The Bottom Line

  • If you only have one set of "Program Arguments" that will work for every BBj program in your BBj project, then set those arguments in the corresponding BRE before you create any Run Configurations (before you run your BBj programs for the first time).

  • If you want to configure different program arguments for each BBj program in your BBj project, then you will need to configure the arguments in each program's Run Configuration.

Run Time Verification

Regardless of how you choose to configure your BBj GUI program arguments, when you run it, you can tell whether or not it is working by looking at the BDT Console. To do this, perform the following steps:

  • Open Eclipse's Console View (using Window > Show View in the main Eclipse menu)

  • Select the BDT Console, as shown in Figure 3.

Figure 3. The Console View

  • See the arguments you entered in the Run Configuration appended to the end of the bbj.exe command line. If not, let me know.

  • You should also get feedback from your program that indicates that it did receive the ARGC and ARGV values (see Figure 4 for an example).

Figure 4. The SysConsole Output

Here is sample code to “see” the ARGC and ARGV values that appear in your BBj code, as shown in Figure 4:

PRINT "Num Arguments: ", str(ARGC)
PRINT "Program: ", ARGV(0)
IF ARGC > 1
  PRINT "Program Args:"
  FOR I = 1 to ARGC - 1
    PRINT " * ", ARGV(I)
  NEXT I
FI