ENTER statement

ENTER operates like a RUN statement except that the specified program is an MTB subprogram.

When an ENTER statement is executed, the partition environment of the current program is saved and the specified program is loaded and executed in the same partition.

The partition environment is passed in full to the called subprogram. This includes the data division (COMMON and LOCAL fields) and the open logical unit numbers. If the data division of the subprogram is structured exactly the same as the calling program, data values are preserved when the subprogram is executed. (Data values are not preserved, however, when the subprogram is concluded information.)

In addition, when the ENTER statement is executed, Comet increments the "open count" for all open logical unit numbers in the original program. This protects the files associated with these logical unit numbers (for example, it makes it impossible for another user to erase a file which was opened in the original program and subsequently closed in the subprogram).

The called subprogram must conclude with an EXIT, EXITALL, or EXITTO statement. When an EXIT statement is executed by the subprogram, the partition environment is restored to its previous state and the calling program continues executing at the next instruction following the ENTER statement. In this regard, the ENTER and EXIT statements are very similar to the GOSUB and RETURN statements, respectively.

When Comet restores the partition environment, all data values, formats, and instructions are restored to their original (pre-subprogram) values. Thus, data is not automatically passed back to the calling program from the subprogram.

However, a subprogram can pass data back to the calling program via the user record buffer (#). The subprogram can write a record to the user record buffer and execute an EXIT instruction. Then, the calling program can read the contents of the user record buffer to retrieve the data passed back from the subprogram.

Upon executing an EXIT, EXITALL, or EXITTO instruction, Comet decrements the "open count" for the program's logical unit numbers. This returns the logical unit numbers to their original status.

The partition environment files are erased when Comet is terminated.

Subprograms may be nested up to 99 levels. Each ENTER statement calls another level of subprogram, and each EXIT statement returns to the previous level. The EXITALL statement returns to the original calling program (i.e., the top level). The EXITTO statement returns to a specified subprogram level.

A system variable, ENTERLEVEL (numeric, 2.0), contains a value equal to the relative subprogram level of the program currently executing. If ENTERLEVEL equals zero, the current program is not a subprogram (i.e., it was RUN, not ENTERed). Values greater than zero equal the number of ENTER operations used to execute the current program (i.e., the nesting depth).

  Calling program 
  ===========================
  .
  .
  .
  ENTER "SUBPROG",DIR="DSK"
  .
  .
  .
  .
  

  Subprogram ("SUBPROG" on "DSK")
  ===============================
  .
  .
  .
  .
  .
  .
  .
  .
  EXIT
  

This example shows the relationship between a calling program and a subprogram. In this example, the calling program executes (via the ENTER statement) the subprogram named "SUBPROG" from the Comet directory named "DSK". The final statement in the subprogram (EXIT) returns control to the calling program at the statement immediately following the ENTER statement.