Callframe
Transfers control from the current frame to another ABF frame.
Syntax
[returnfield :=] callframe calledframe
[([parameterlist])] [with style = fullscreen
[(screenwidth = value)] | popup [(optionlist)]]
returnfield
Specifies the field in the calling frame or procedure that receives the return value from the called frame. The data type of the return field must agree with the return type of the called frame as declared in ABF.
calledframe
Specifies the ABF name of the frame you are calling (a 4GL name)
parameterlist
A series of assignment statements separated by a semicolon (;) or comma (,). Do not use a comma where it results in ambiguity, such as following a parameter that is a query with a name list as its last component (such as from or order by clauses). Use (;) to separate query parameters from other parameters in the list.
Each assignment statement links a field or a variable in the initialize section in the called frame with an expression, as shown below.
Simple assignments:
simpleobjectname := expression
or
simpleobjectname := byref (simpleobjectname)
On the left hand side of the assignment: simpleobjectname is the name of a field in the called form or a simple variable in the initialize section of the called frame.
On the right hand side of the assignment: simpleobjectname is the name of a field in the calling form or a simple variable in the calling frame.
Expression is any legal 4GL expression. Usually it contains values from the calling frame or from a database table. The data types of the expression and the simpleobjectname must be compatible.
For a simple object, byref() indicates that the object is passed by reference; this is discussed below. A complex object is always passed by reference; do not include the byref() statement.
Complex assignments:
arrayname := arrayname
recordname := recordname
tablefieldname := database query
calledformname := database query
calledformname := callingformname.all
calledformname := tablefieldname[[integerexpr]].all
On the left hand side of the assignment: arrayname and recordname are the names of objects in the initialize section of the called frame. Tablefieldname is the name of a table field in the called frame.
On the right hand side of the assignment: arrayname and recordname are the names of objects in the calling frame. Tablefieldname is the name of a table field in the calling frame.
The parameter list can include assignment statements for any mix of form object types. However, 4GL allows only one database query within the parameter list.
screenwidth = value
Specifies the screen width for a fullscreen frame. The value is a keyword, integer constant, or integer variable as shown:
0 | default
Specifies VIFRED definition
1 | current
Specifies current screen width
2 | narrow
Specifies narrow width for screen, typically 80
3 | wide
Specifies wide width for screen, typically 132
intvar
Specifies a 4GL expression evaluating to 0, 1, 2, or 3
optionlist
Specifies a list of style options for pop‑up position and border style. Syntax:
option = value [,option = value]
Options: startcolumn, startrow, border.
startcolumn and startrow specify the coordinates for the upper left corner of the pop-up form. The value is a keyword, integer constant, or integer variable as follows:
default | 0
Specifies VIFRED definition or default
floating | -1
Specifies current cursor position
int
Specifies a positive integer indicating the number of rows or columns from the origin. The origin (1,1) is the upper left corner of the screen.
intvar
Specifies a 4GL expression evaluating to -1, 0 or a positive integer
border
Specifies the form's border type. The value is a keyword, integer constant, or integer variable as follows:
default | 0
Specifies VIFRED definition or default
none | 1
Specifies no border
single | 2
Specifies single-line box border
intvar
Specifies a 4GL expression evaluating to 0, 1, or 2
Description
The 4GL callframe statement is the only means by which an operation, such as a menu operation, can transfer control to, or call, a new frame. The calling operation appears in the calling frame, and the frame to which it transfers control is known as the called frame.
You can include an optional with style clause to override the called frame's original style definition (as specified through the Application-By-Form's FormEdit operation). The two available styles are popup or fullscreen. You can specify options to modify pop‑up or full‑screen behavior.
Popup
You can use variables in the optionlist to specify the pop‑up form's exact location dynamically at run time. If there is not enough room in the window to start the pop‑up form at the user-specified location, the forms system displays the form in fullscreen width.
Fullscreen
This option forces the FRS to use the entire window to display the form. You have four choices for the screenwidth option: current, default, narrow, and wide. Use VIFRED to specify a width for a form. You can override these settings at run time.
You can nest called frames so that the called frame calls another frame, and so on. A frame cannot call any frame whose form is associated with a frame at an outer level of nesting.
You can pass the value in derived fields or columns to another frame in a callframe statement, but you cannot pass a value to a derived field with any statement.
You can use a return statement in either of two ways: to exit a called frame or to pass a value back to the calling frame, as follows:
• To exit a called frame, you normally use a return statement to transfer control back to the calling frame.
• To pass a value back to the calling frame, specify an expression on the return statement in the called frame. In the calling frame, place a returnfield on the left side of an assignment statement, with the entire callframe statement on the right side.
The value returned must meet the following requirements:
• The value can be of any data type, as long as you have previously declared it in the ABF User‑Specified Frame Definition frame for the called frame.
• The value must be compatible in data type and nullability with the return field.
Under certain circumstances, you can return additional values to a calling frame by means of the byref option.
For information on returning a value to the top frame, see
Returning to the Top Frame.
The callframe statement can pass values to the called frame by means of an optional parameter list. These values are supplied either by fields in the calling frame or by a query against the database.
Using different versions of the parameterlist, you can pass values to a form, a table field, simple fields, a record, or an array in the called frame.
The with style options in optionlist or screenwidth override the definition of the form made through the ABF FormEdit operation. If startcolumn and startrow specify a numeric location for the pop‑up form, the called form appears at that specified location, regardless of how the form is declared (that is, fullscreen, popup/floating, or popup/fixed).
For example, when your application calls a form declared as a fixed‑location pop‑up with the startcolumn and startrow set to "floating" or "-1," the form appears at the "floating" location (the current cursor position) rather than at the fixed location.
The forms system attempts to display floating pop‑up forms without obscuring the field that the cursor occupies. If there is not enough room on the frame to display it at the specified location, an error message appears and the forms system displays the form as close as possible. If the window is too small to display the pop‑up form and its border, the form appears in fullscreen mode.