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.
You can specify FROM and INTO parameters in the calling procedure in two ways:
How to: |
You can specify FROM and INTO parameters in the called procedure in two ways:
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:
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:
DECLARE Counter/A20; EmpStack.FullName/A15;
INFER Emp_ID Pay_Date INTO EmpStack;
The INFER command declares data source fields and the stack with which they are associated. You can specify one field for each segment you want in the stack, or simply one field each from the anchor and target segments of a path you want in the stack.
While INFER re-establishes the definition of a stack, it does not retrieve any records from the data source.
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.
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.
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.
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.
You must also define the corresponding variables and stacks you will use.
Input parameters (which you pass to the called procedure) are represented by the following icon:
Output parameters (the values the called procedure will return) are represented by the following icon:
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.
ShowCust then displays a form with the information in CustInfo, as shown in the following image.
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...
Specify that GetCust and ShowCust should use the Videotrk data source:
Create the data source stack CustInfo in GetCust and load the data into it:
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.
Note: You created the stack CustInfo implicitly when you loaded data into the stack.
Make CustInfo an output parameter of GetCust:
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.
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.
Call GetCust from ShowCust:
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.
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
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 |