Control Commands › RETURN

RETURN

Purpose

Passes control to a higher level dialog or function in the application thread.

Syntax

►►─── RETurn ─┬──────────────────┬─┬────────────┬─┬────────────┬─ . ──────────►◄
              ├─ TO dialog-name ─┤ └┬─ CLEAR ─┬─┘ └─ CONTinue ─┘
              └─ to ─┬─ TOP-─┬───┘  └─ CLR ───┘
                     └─ ALL ─┘

Parameters

TO dialog-name

Introduces the name of a higher level dialog to which control passes.

Dialog-name can be the name of a variable data field that contains the dialog name or the dialog name itself, enclosed in single quotation marks.

to TOP

Specifies the highest level to which control can pass.

ALL can be used in place of to TOP.

CLEAR

Specifies that record buffers are reinitialized and currencies are released for the dialog receiving control.

CLEAR is ignored if the receiving dialog is at the top of a nested application structure.

CLR can be used in place of CLEAR.

CONTinue

Specifies that control returns to the first command in the premap process of the dialog receiving control.

If CONTINUE is not specified, control returns to the mapout operation of the dialog that receives control. If the receiving dialog is at the top of a nested application structure, CONTINUE is ignored.

Usage

Considerations

• The dialog or function receiving control must be operative.
• The dialog that issues the RETURN command becomes nonoperative as do any operative dialogs or functions on a level between the issuing and receiving dialogs or functions.
• All database currencies established by the dialog issuing the RETURN command are released.
• A RETURN command cannot pass control higher than the top of the lowest level nested application structure created by a LINK command.
• The named dialog must not be higher than the top of the nested application structure in which the issuing dialog participates.
• If the named dialog is operative at more than one higher level, control passes to the lowest level operative dialog with the specified name.
• If the issuing dialog participates in a nested application structure, control returns to the top of the nested structure.
• If the issuing dialog does not participate in a nested structure, control returns to the mainline dialog at the top of the application thread.
• If a RETURN statement does not specify a receiving dialog, control passes to the next higher level dialog or function.
• If the mainline dialog at the top of an application thread issues a RETURN command, the RETURN command is treated as a LEAVE APPLICATION command.
• A dialog that receives control at the top of a nested structure resumes execution at the command that follows the LINK command.
• RETURN can pass control within a nested application structure to any operative dialog that passed control with an INVOKE command.
• If the issuing dialog is not in a nested structure, RETURN can pass control to any higher level operative dialog or function, or directly to the top of the application structure.
• The application developer can specify whether the dialog receiving control resumes execution with its premap process or with its mapout operation.
• The application developer can also request reinitialized record buffers for the dialog that receives control.

Examples

The examples below show the use of the RETURN command in response processes from dialogs used in the two sample applications shown in Application Thread:

Example 1: Using RETURN with the LINK command

In Example 1 of Application Thread, dialog UPDATEC passes control to the dialog UPDATEO by means of a LINK command. The following response process from dialog UPDATEO returns control to the command following the LINK command in dialog UPDATEC:

READY USAGE-MODE IS UPDATE.
MODIFY ORDOR.
RETURN.

Example 2: Using RETURN with the INVOKE command

In Example 2 of Application Thread, dialog UPDATEC passes control to the dialog UPDATEO by means of an INVOKE command. The following response process from dialog UPDATEO returns control to the mainline dialog RDCUST# and reinitializes the record buffers associated with RDCUST#:

READY USAGE-MODE IS UPDATE.
MODIFY ORDOR.
RETURN TOP CLEAR.

Example 3: Transferring control within the same level

In Example 2 of Application Thread, dialog UPDATEO provides the ability to transfer to dialog ADDORDR. ADDORDR prompts the user for new order information. The following response process from dialog ADDORDR adds a new ORDOR record to the database and returns control to the mapout operation of dialog UPDATEC:

READY USAGE-MODE IS UPDATE.
STORE ORDOR.
RETURN.