Program Template for Online Applications

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

By entering a single AMB keyword, NTRY, you can generate a program template, or shell, that fully defines all parts of your online program except for the procedural code that you supply.

Default Template Definitions

The online template defines the following:

  • The Identification Division
  • The Environment Division
  • The Data Division, including the following Working-Storage and Linkage Section structures:
    • Your database record or file definitions
    • Your IMS PCB mask for IMS programs
    • An AMB data structure for passing data between programs, known as a Commarea, which appears in either Working-Storage or the Linkage Section, depending on your user interface target
    • Function key definitions, based on your specified user interface target
    • Flags required by AMB
  • Portions of the Procedure Division, including:
    • A housekeeping routine to initialize Working-Storage fields, flags, and counters
    • Program invocation logic to initialize your program
    • Logic to send the program screen

By default, the NTRY keyword tailors the generated program template depending on the DC target you use. The template tests the field TP-INVOCATION-MODE to determine the mode that invoked it (ie. via a transaction ID, another program, or a screen). Once the mode has been determined, the program performs one of the following paragraphs.

Displays the first input screen associated with the program in the Application Painter or the screen coded with NTRY. This paragraph is performed if a transaction ID has been entered and no screen information or data is passed to the program; not applicable for IPSF Dialog programs.
Displays the first input screen associated with the program in the Application Painter or the screen coded with NTRY. This paragraph is performed if the program is called from another program and data is available in the Commarea; not applicable for IMS/DC programs.
Performed if the program is screen-invoked. The program checks field edits to see if input paragraphs must be performed before it starts. This paragraph also performs APS-USER-CODE-PARA, which contains the statement(s) you coded with the NTRY keyword.

Customizing the Program Template

You can customize the template generated by the NTRY keyword by substituting your own logic in place of any generated invocation paragraph, or even substituting your own logic for the entire Procedure Division. You can also add your own logic at entry and exit points in the template using predefined paragraph names that are invoked automatically.

To substitute template logic, you can do either or both of the following:

  • Substitute your own paragraph logic in place of the logic supplied with any of the default invocation paragraphs: APS-PROGRAM-INVOKED-PARA, APS-TRANSID-INVOKED-PARA, and APS-SCREEN-INVOKED-PARA

    You must use these paragraph names, replacing the logic only. For example, you might want to modify APS-PROGRAM-INVOKED-PARA to move information from the Commarea to the screen before it is displayed, or you might want to modify the APS-TRANSID-INVOKED-PARA to perform more initialization.

  • Substitute the entire Procedure Division portion of the generated template with your own logic. To do so:
    • Add the OPT PROG statement on a line above NTRY.
    • Add your custom Procedure Division code beneath NTRY.

    When using OPT PROG, any invocation paragraphs that you have overridden are not automatically performed from the generated Procedure Division. Therefore, if you specify OPT PROG and also substitute your own logic for one or more invocation paragraphs, you must also include the code that performs those paragraphs. Other, non-Procedure Division portions of the template are still generated, however.

To add logic at entry or exit points in your program, supply either or both of the following two paragraphs, which are automatically invoked from the mainline code if they exist in the program:

Performed immediately after the program receives control from a screen and all field edits have been performed, regardless of the invocation mode. You can use this paragraph, for example, to check security.
Performed before a send of the default screen if control was not transferred by a previously executed program. It is performed regardless of the specified invocation mode. You can use this paragraph, for example, to blank out a password field.