Passing Parameters Between Maintain Procedures: FROM...INTO

In this section:

When you CALL a Maintain procedure, you can pass parameters to the called procedure, and receive variables and stacks back from the called procedure using the FROM and INTO keywords in the CALL command. The FROM keyword identifies the parameters being passed, and the INTO keyword identifies the parameters being received.

You can pass and receive both stacks and variables to and from the called procedure. The called procedure will have corresponding FROM and INTO phrases in its MAINTAIN command (the command that begins all Maintain procedures).

When you specify input and output variables for a procedure, WebFOCUS Maintain adds a Parameters folder to the list of options under the procedure and lists the input and output parameters in it.

Note: All user variables (both stacks and simple, or scalar, variables) are global to a function or procedure, but not global to the project. In other words, to protect them from unintended changes in other parts of a project, you cannot directly refer to a variable outside of the procedure in which it is found (with the exception of the FocError transaction variable). However, you can access the data of a variable in other procedures, simply by passing it as a parameter from one procedure to another.


Top of page

x
Specifying FROM and INTO Parameters in the Calling Procedure

You can specify FROM and INTO parameters in the calling procedure in two ways:


Top of page

x
Specifying FROM and INTO Parameters in the Called Procedure

How to:

You can specify FROM and INTO parameters in the called procedure in two ways:



x
Syntax: How to Call a Maintain Procedure With FROM and INTO Parameters

The syntax for the calling procedure is:

CALL Maintain_procedure [AT server] [KEEP|DROP] [FROM var_list1] [INTO  
var_list2] [;]

The syntax for the corresponding called procedure is:

MAINTAIN [FILE[S] filelist] [FROM var_list1] [INTO var_list2]

The following rules apply:


Top of page

x
Defining FROM and INTO Parameters in Calling and Called Maintain Procedures

After you pass a variable to a called Maintain procedure, you must define it in that procedure. The definition depends upon the type of variable:

After a variable is defined in the called procedure, its data becomes available. If you refer to stack cells that were not assigned values in the calling procedure, they are assigned default values (such as spaces or zeros) in the called procedure, and a message warns you that they have not been explicitly assigned any values.

When the called procedure returns control back to the calling procedure, the values of stacks and simple variables specified as output arguments are passed back to the calling procedure. The values of stacks and simple variables specified only as input arguments are not passed back.


Top of page

x
Specifying FROM and INTO Parameters for a Called Procedure Using the Procedure Parameters Dialog Box

How to:

When you right-click a procedure and click Add Parameters in the shortcut menu, WebFOCUS Maintain opens the Procedure Parameters dialog box, shown in the following image. Use this dialog box to specify variables and data source stacks whose values the procedure is receiving from and passing to a calling procedure.

Procedure parameter dialog box



x
Procedure: How to Specify Parameters for a Called Procedure Using the Procedure Parameters Dialog Box
  1. Define the variables and data source stacks whose values will be passed to and from the procedure.
  2. Right-click the procedure, and in the shortcut menu, click Add Parameters.
  3. Select the variables and stacks that will be passed to the procedure from the calling procedure.
  4. Click the right arrow button right arrow button to move them into the Input parameters list.
  5. If necessary, reorder the parameters. They must be in the same order here as they are in the CALL statement in the calling procedure. However, they do not need the same name.
  6. Select the variables and stacks that will be passed back to the calling procedure.
  7. Click the right arrow button right arrow button to move them into the Output parameters list.
  8. If necessary, reorder the parameters. They must be in the same order here as they are in the CALL statement in the calling procedure. However, they do not need the same name.
  9. Click OK.

You will see a Parameters folder under your procedure with the input and output parameters.

Note: If you edit your procedure as text, your parameters are listed in the MAINTAIN line of code. The input parameters follow the FROM keyword. The output parameters follow the INTO keyword.


Top of page

x
Using the Language Wizard to Specify Parameters When Calling a Maintain Procedure

How to:

If you have defined parameters for a called Maintain procedure, you can use the Language Wizard to call that Maintain procedure and specify corresponding parameters in the calling procedure.



x
Procedure: How to Use the Language Wizard to Specify Parameters When Calling a Maintain Procedure
  1. Before you open the Language Wizard, you must define the variables and stacks you will be using as input and output parameters.

    You must also define the corresponding variables and stacks you will use.

  2. Open your calling procedure in the Procedure Editor, and right-click in a function (between a CASE statement and an ENDCASE statement).
  3. Click Language Wizard.
  4. Select Run another procedure and click Next.
  5. Select Call and click Next.
  6. Select the procedure you want to call from the list (or click Find other procedures to look on your local drive or any WebFOCUS Server), and click Next.
  7. Double-click on each parameter listed in the window and specify a corresponding variable or stack from this procedure, using the Parameter Value dialog box.

    Input parameters (which you pass to the called procedure) are represented by the following icon:

    input parameters button

    Output parameters (the values the called procedure will return) are represented by the following icon:

    output parameters button

  8. Click Next.
  9. Specify whether to keep or drop the server connection when the called procedure finishes executing, and click Finish.


Example: Passing Parameters Between Two Procedures

This example demonstrates how to pass a stack from a called procedure to a calling procedure, and the steps you must go through for both procedures to work properly.

Suppose you are designing a project that enables clerks at a video store to sell or rent videos to customers. The clerks access a WebFOCUS Server on a UNIX machine through the web, but the actual project data resides on an MVS machine. The project may have procedures running on both the UNIX machine and the MVS machine; the machines must call each other and pass data back and forth (this is a common occurrence in WebFOCUS Maintain).

Suppose that the project (called VideoApp) must display customer information to the clerk.

  1. On the UNIX machine, the WebFOCUS server will run a procedure (called ShowCust) that calls a procedure (called GetCust) on the MVS machine.
  2. GetCust extracts data from the Videotrk data source and places it in a data source stack called CustInfo.
  3. GetCust passes CustInfo back to ShowCust.

    ShowCust then displays a form with the information in CustInfo, as shown in the following image.

    Image display of ShowCust

Here is the Maintain code for ShowCust:

MAINTAIN FILE Videotrk 
$$Declarations
Case Top
Infer Videotrk.CUST.CUSTID into CustInfo;
Call GetCust Into CustInfo ;
EndCase
END

Here is the Maintain code for GetCust:

MAINTAIN FILE Videotrk INTO CustInfo 
$$Declarations
Case Top
For all next Videotrk.CUST.CUSTID into CustInfo ;
EndCase
END

Before you begin...

  1. Create a project named VideoApp, with the data source Videotrk (one of the sample data sources distributed with WebFOCUS).
  2. Create two Maintain procedures: GetCust and ShowCust.

Specify that GetCust and ShowCust should use the Videotrk data source:

  1. Right-click GetCust.
  2. In the shortcut menu, click Use data sources.
  3. In the Use these Data Sources in Procedure GetCust dialog box, shown in the image below, select Videotrk in the Available data sources list.
  4. Click the right arrow button .

    Use these Data Sources in Procedure GetCust dialog box

  5. Click OK.
  6. Repeat the process for ShowCust.

Create the data source stack CustInfo in GetCust and load the data into it:

  1. Double-click GetCust.
  2. Between the Case Top and EndCase keywords, type the following Maintain language code:
    For all next CUST.CUSTID into CustInfo ;

    Tip: You can also create this code using the Language Wizard. Place your insertion point between the Case Top and EndCase keywords, right-click in the Procedure Editor window, and in the shortcut menu, click Language Wizard.

  3. Close GetCust.

Note: You created the stack CustInfo implicitly when you loaded data into the stack.

Make CustInfo an output parameter of GetCust:

  1. Right-click GetCust.
  2. In the shortcut menu, click Add Parameters.
  3. In the Procedure Parameters dialog box, shown in the image below, select CustInfo in the Available variables and stacks list.
  4. Click the right arrow button right arrow button to copy CustInfo into the Output parameters list.

    Procedure Parameters dialog box

  5. Click OK.
  6. WebFOCUS Maintain creates a Parameters folder under GetCust and adds CustInfo there. The red arrow pointing down indicates that CustInfo is an output parameter.

Define CustInfo in ShowCust:

Since CustInfo is a data source stack in GetCust, ShowCust has no information on the structure of CustInfo. Therefore, you must define a stack to receive its value. However, since you are not loading data into the stack here (rather, you are receiving the data from GetCust), all you have to do is define the columns.

  1. Right-click ShowCust.
  2. In the shortcut menu, click New.
  3. In the submenu, click Data source stack.
  4. In the Stack Editor dialog box, type CustInfo in the Stack Name box.

    Note: In this example, you are giving the stack being passed between the two procedures the same name: CustInfo. However, you do not have to give the stacks the same name as long as they have compatible types.

  5. Expand the fannames data source in the Available fields list.
  6. Expand the CUST segment.
  7. Select the CUSTID field.
  8. Click the right arrow button . WebFOCUS Maintain copies all of the fields in the CUST segment into your stack definition along with CUSTID, as shown in the following image.

    Stack Editor dialog box

  9. Click OK.

Call GetCust from ShowCust:

  1. Double-click ShowCust.
  2. In the Procedure Editor, type the following Maintain language code in front of the keyword EndCase:
    Call GetCust into CustInfo

Note: You can also create this code using the Language Wizard. Place your insertion point in front of the EndCase keyword, right-click in the Procedure Editor window, and in the shortcut menu, click Language Wizard.

The data from the Videotrk data source is now available to you in ShowCust to display for the end user.


Top of page

x
Accessing Data Sources in the Called Procedure

If a called Maintain procedure accesses a data source, whether retrieving or writing records, you must specify the data source in the MAINTAIN command. This is done the same way as a stand-alone procedure. For example, the procedure below specifies the Employee and EducFile data sources:

MAINTAIN FILES Employee AND EducFile FROM StuStk INTO CoursStk
.
.
.
END

Top of page

x
Data Source Position in Child Procedures

Each Maintain procedure tracks its own position in the data source. When you first call a procedure, Maintain positions you at the beginning of each segment in each data source accessed within that procedure. After navigating through a data source, you can reposition to the beginning of a segment by issuing the REPOSITION command. Each data source position of a procedure is independent of the positions established in other procedures.

When a called procedure returns control to its calling procedure, it clears its data source positions by default. You can specify that it retain its positions for future calls by using the KEEP option, as described in Optimizing Performance: Data Continuity and Memory Management.


WebFOCUS