unloadOnExit

The unloadOnExit property specifies whether to unload a called program after it ends. The valid values are YES or NO.

The following restrictions apply to the unloadOnExit property:
  • Use the property only in the following places:
    • With exit program statements inside a program that has the BasicProgram or TextUIProgram stereotype
    • At the program level for programs that have the BasicProgram or TextUIProgram stereotype

    If you specify the property at both the program and statement levels, the statement level takes precedence; see "Example" in this topic.

  • The property affects only called programs. EGL ignores the property unless you are making a local call. To be considered local, a call must meet all the following conditions:
    • You generate both programs to the same language.
    • You run both programs on the same system.
    • Either you do not specify a linkage options part, or the type property of the callLink element is set to localCall.

    For Java™ generation, the unloadOnExit property has no effect if the linkType property of the callLink element is set to LIBRARY.

When you set the unloadOnExit property to NO, you get the following results:
  • The called program remains in memory.
  • All SQL result sets and prepared statements that the program created remain open.
  • If you call the program again, the initNonIODataOnCall and initIORecordsOnCall build descriptor options control whether global data in the program is reinitialized.
When you set the unloadOnExit property to YES:
  • All memory allocated for the program is released.
  • All SQL result sets and prepared statements that the program created are closed, unless the program is running in Java™ or in the debugger and has the localSqlScope property set to NO.
  • If you call the program again, you get a new copy.

Unloading a program does not automatically unload other programs called by that program. Each program is unloaded or retained individually.

Retained programs are kept until they are unloaded after a subsequent call, or until the run unit ends. A transfer to transaction statement ends the run unit, and therefore overrides the value of the unloadOnExit property. Retained programs are kept after a transfer to program statement.

The following elements are shared by all programs in a run unit and are therefore not affected when a called program is unloaded:
  • Files
  • Message queues
  • Database connections
  • DataTables
  • Libraries

DL/I programs have one scheduled PSB active at a time. This PSB is shared by any number of programs. Unloading a called program does not affect the PSB. It is still scheduled.

The forms that a program uses are considered to be global data. They are retained when a called program is retained and discarded when it is unloaded.

Unloading does not imply a commit or rollback.

Recursive program calls

COBOL does not support recursive program calls.

Java™ supports recursive local calls except in situations like the one in the following example:
  1. ProgramA calls ProgramB, directly or indirectly.
  2. ProgramB returns and is retained.
  3. ProgramA calls ProgramB again.
  4. ProgramB calls itself, directly or indirectly.

In this example, the final call statement causes an InvocationException to be thrown. Therefore, after a locally called Java™ program returns and is retained, only one copy of the program can be active at a time, although it can be unloaded later.

Values

The unloadOnExit property has the following values:
YES
Release all memory for the program, including SQL result sets. This value is the default for Java™ generation. For debugging, set the Called programs release resources by default upon return preference; see Setting preferences for the EGL debugger.
NO
Keep the called program in memory, along with SQL result sets and all other variables. This value is the default for COBOL generation.

Example

In the following example, the program will be retained in memory after it returns control to the program that called it, unless it encounters an unrecoverable error: 

Program custProcess1 type basicProgram (custNum INT) {unloadOnExit = NO}

  ...

  if(myErrorCode == TERM_ERROR)
    exit program {unloadOnExit = YES};
  end
end