Control Commands › INVOKE

INVOKE

Purpose

Passes control to a specified dialog in the current application and implicitly establishes the next lower level in the application thread.

Syntax

►►───── INVoke ──┬──────────┬── dialog-name ─── . ────────────────────────────►◄
                 └─ NOSAVE ─┘

Parameters

NOSAVE

Specifies that database currencies are not saved for the dialog issuing the INVOKE command.

dialog-name

Specifies either the name of a variable data field containing the dialog name to which control passes or the dialog name itself, enclosed in single quotation marks.

Usage

Considerations

• The load module for the named dialog must be available at run time.
• The dialog that issues the INVOKE command remains operative.
• A lower level dialog can return control to the dialog by issuing a RETURN command.
• The issuing dialog's database currencies are saved and available to the dialog receiving control, unless the NOSAVE option is specified.

  When a dialog that issued an INVOKE NOSAVE command regains control from a lower level dialog or program, database currencies are dependent upon whether or not the run unit was extended. The following diagram shows how currencies are affected when the NOSAVE option is used in extended and nonextended run units.

Currency Settings of Extended and Nonextended Run Units

      1. DIALOG 1, which uses subschema SS1,
         obtains values for records A and B:

                  DIALOG 1
              ┌───────────────┐    Currencies:
              │   OBTAIN A    │    A: Jones
              │   OBTAIN B    │    B: Accounting
              └───────────────┘
      2. DIALOG 1 invokes DIALOG 2 using
         the NOSAVE option:
                  DIALOG 1                       ──┐ The run unit is
              ┌───────────────┐    Currencies:     │ extended only if
              │               │    A: Jones        │ DIALOG 2 uses the
           ┌──┤ INVOKE NOSAVE │    B: Accounting ──┘ same subschema as
           │  └───────────────┘                      DIALOG 1.
           │
           │      DIALOG 2
           │  ┌───────────────┐
           │  │               │
           └──►               │
              └───────────────┘
      3. DIALOG 2, which can use DIALOG 1's
         record buffers and currencies, obtains
         a new occurrence of record A:
                  DIALOG 1
              ┌───────────────┐    Currencies:
              │               │    A: Jones
              │ INVOKE NOSAVE │    B: Accounting
              └───────────────┘
                  DIALOG 2
              ┌───────────────┐    A: Smith
              │   OBTAIN A    │
              │               │
              └───────────────┘
      4. DIALOG 2 issues a RETURN to DIALOG 1:
                  DIALOG 1
              ┌───────────────┐    Currencies:
              │               │    If the run unit
              │ INVOKE NOSAVE ◄──┐ was extended:
              └───────────────┘  │ A: Smith
                                 │ B: Accounting
                  DIALOG 2       │
              ┌───────────────┐  │ If the run unit
              │               │  │ was not extended:
              │    RETURN     │──┘ A: _________
              └───────────────┘    B: _________
                                   (Currencies in DIALOG 1
                                   have been initialized)

Considerations for Using NOSAVE

• When the dialog that issues the command regains control from a lower level dialog and the run unit is extended by the INVOKE command, currencies are set to those of the most recent dialog returning control.
• When the dialog that issues the command regains control from a lower level dialog and the run unit is not extended by the INVOKE command, currencies are set to the original currencies available to the dialog when it became operative in the application thread.

Example

In the sample applications shown in Application Thread, dialog RDCUST# prompts the user for the CALC key of a CUSTOMER record to be retrieved. RDCUST# passes control to dialog UPDATEC, which retrieves and displays the record, and then modifies or erases it as instructed by the user. RDCUST# uses the following response process to pass control to UPDATEC:

INVOKE 'UPDATEC'.

Because RDCUST# uses the INVOKE command to pass control, processing can return to the RDCUST# mapout operation following completion of UPDATEC processing. This allows the user to update multiple CUSTOMER records in one CA ADS runtime session.

More information:

CA ADS Runtime System