IB Statements/enter

From CometWiki

ENTER statement

Syntax: ENTER program [,DIR=directory] [,EXCP=statement-label | NOEXCP]

Discussion: The ENTER statement executes a subprogram.

ENTER operates like a RUN statement except that the specified program is an Internet Basic 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.

DOS Version of Comet Comet saves the partition environment as a disk file. Initially, Comet searches for a local RAM disk among the accessed Comet directories, and if one is found, saves the partition environment there. If no local RAM drive is found, Comet saves the partition environment on the current DOS directory. Since a RAM drive is faster than a hard drive, we recommend configuring one in your Comet system if you plan to use the ENTER statement. (Note: The Comet Help System makes extensive use of the ENTER statement, so we recommend a RAM drive if you plan to use the help system.)

Windows Version of Comet * Each ENTER operation writes the partition environment to RAM using the virtual memory system capability of Windows. Each EXIT thus restores the data from RAM. The result is much faster performance for ENTER/EXIT operations.

In Comet16 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 exits.) In Comet32 LOCAL data is not passed.

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).

When a program is ENTER'd the system variable RUNSTATE is set to 6.

History: * Starting in Comet version 504.213, the ENTER/EXIT logic in Comet for Windows uses RAM instead of disk storage. The result is much faster performance for ENTER/EXIT operations.

Example: 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.