5.10 CallForm Method

Description:	Opens (Shows) a form in "Modal" mode. "Modal" means that the parent form is inactive until the child form is closed. The child form looks like a dialog box. It is different from the OpenForm method in that control is returned after all the child form's procedures have completed. The child form cannot be re-opened if the child form is already open.
Used in controls:	None.
Used in objects:	Form
Parameters:	VT_BSTR - FormNameX(8192) [VT_BSTR - DllNameX(8192)] [VT_I4 - CookieS9(9) COMP-5]
Description of Parameters:	FormName: The name of the form to be opened. DllName: When the form is in a DLL file, defines the name of the DLL file containing the form. It should be omitted when you specify a form in the same Module, as specifying the same DLL name that contains the invoking form degrades performance. Cookie: An integer to distinguish the opened form. It is set in a parameter of the CloseChild event when the opened form is closed. If omitted, the parameter value is zero.
Return value:	VT_I4 - ReturnValueS9(9) COMP-5 This is the value set in the Result parameter when the CloseForm method is invoked. When you omit the parameter, or the form is closed in some way other than by invoking methods, the value is zero. Otherwise, if the form was not closed for any reason, the value is -1.
DLL Search Path:	When the DllName parameter does not contain the full path, PowerCOBOL searches for the DLL folders in the following order: 1. The folder containing the execution file. 2. The current folder 3. The system folder of 32 bit Windows 4. The system folder of 16 bit Windows 5. The folder in which Windows is installed. 6. The folders of the PATH environment variable.
Example:	To invoke another form called "DialogBox1", contained within the same module, you would code: WORKING-STORAGE SECTION. 01 ReturnValue PIC S9(9) COMP-5. PROCEDURE DIVISION. INVOKE POW-SELF "CallForm" USING "DialogBox1" RETURNING ReturnValue IF ReturnValue = ID-OK * Code to handle a good return : END-IF Where ID-OK is a global variable set in a top-level section of each form, such as the forms' CONSTANT sections: 01 ID-OK PIC S9(9) COMP-5 VALUE 1 IS GLOBAL. To return from "DialogBox1", with an "OK" value you would code, in a closing event such as the user clicking on DialogBox1's "OK" button: INVOKE POW-SELF "CloseForm" USING ID-OK
Backward compatibility method name:	None.