ENTER Verb - BBj

For this topic's original documentation, see the ENTER Verb.

BBj-Specific Information

Syntax

ENTER {varname{,varname...}{,ERR=lineref}}

Description

In BBj, varname can refer to an object variable or an object array.

A simple object variable, like X!, must correspond to either a simple object variable in the CALL argument list, or to any expression.

An object array, like X![ALL], must correspond to an object array reference in the CALL argument list.

The original BBx ENTER Verb documentation says, "The same simple variable cannot appear more than once in an ENTER statement." Prior to BBj 16, BBj inadvertently did not enforce this rule. This oversight was corrected in BBj 16, but some applications may include code that violates this rule. If updating the application is impractical, the ALLOW_DUPLICATE_ENTER_VARS !COMPATsetting can be set to TRUE in BBj 17 and higher to allow the original more lenient BBj behavior.

See CALL Verb for additional information.

Example 1

An object variable must be passed to an object variable:

CALL "subprog",X!
...
ENTER Y!

Example 2

An object array must be passed to an object array:

CALL "subprog",X![ALL]
...
ENTER Y![ALL]

Example 3

Any expression involving objects can be passed to any variable type for which a corresponding assignment would be legal:

X!=23
CALL "subprog",(X!); REM ' parentheses make it an expression
...
ENTER Y!; REM ' OK - object variable can accept any expression
ENTER N; REM ' OK – LET N=X! is legal for X!=23
ENTER I%; REM ' OK - LET I%=X! is legal for X!=23
ENTER S$; REM ' !ERROR=36 because S$=23 isn't allowed.

Example 4

An object expression that does not evaluate to a number or string must be passed to an object variable.

CALL "subprog",new java.lang.ArrayList()
...
ENTER myList!

Example 5

This larger sample demonstrates some subtleties with object variables and declare, and object variables passed by reference versus passed by value.

rem ' callprog
declare Integer i!
rem ' declared variables in the call must also be declared in the other program:
i! = new Integer(0)
call "enterprog::declared",i!
print "Declared and passed by reference to declared returns: ",i!
rem ' this is an error:
i! = new Integer(0)
call "enterprog::undeclared",err=oops,i!
print "Declared and passed by reference to undeclared returns: ",i!
goto ok
oops:
print "Declared and passed by reference to undeclared throws error: "
print errmes(-1),err
ok:
rem ' if passed by value, the variable does not have to be declared:
i! = new Integer(0)
call "enterprog::declared",(i!)
print "Declared and passed by value to declared returns: ",i!
rem ' undeclared variables in the call can be declared or undeclared in the other program.
x! = new Integer(0)
call "enterprog::declared",x!
print "Undeclared and passed by reference to declared returns: ",x!
x! = new Integer(0)
call "enterprog::undeclared",x!
print "Undeclared and passed by reference to undeclared returns: ",x!
s! = new StringBuffer()
call "enterprog::stringbuffer",s!
print "Mutable variable passed by reference returns: ",s!
s! = new StringBuffer()
call "enterprog::stringbuffer",(s!)
print "Mutable variable passed by value returns: ",s!
end

rem ' enterprog
declared:
declare Integer declaredInteger!
seterr oops
enter declaredInteger!
declaredInteger! = new Integer(42)
exit
undeclared:
seterr oops
enter undeclaredVariable!
undeclaredVariable! = new Integer(42)
exit
stringbuffer:
seterr oops
enter stringbuffer!
stringbuffer!.append("modified in enterprog")
exit
oops:
throw errmes(-1),err
exit

This sample highlights two important details:

A declared variable passed by reference in the CALL must also be declared before the ENTER.
A mutable object passed by value can be modified in the called program. If it's important that the variable be protected against possible changes, the value must be explicitly copied to a temporary throwaway variable.

READY
>run "callprog"
Declared and passed by reference to declared returns: 42
Declared and passed by reference to undeclared throws error:
undeclaredVariable! of type <undeclared> must be of type java.lang.Integer 36
Declared and passed by value to declared returns: 0
Undeclared and passed by reference to declared returns: 42
Undeclared and passed by reference to undeclared returns: 42
Mutable variable passed by reference returns: modified in enterprog
Mutable variable passed by value returns: modified in enterprog

READY
>