CONNECT Directives

The CONNECT directive can be used:

• From a menu
• From a data element name pre-process
• From a data element name post-process
• From within any script method

The general form of the CONNECT directive is:

CONNECT [(function-key-number)] CLASS class-name [message]

Example

CONNECT(2) METHOD OEZSTST START

This example connects to the OEZSTRT method when F2 is pressed. The START message string is passed to the method.

Note: Where a graphical user interface is employed, the option is displayed in a pop-up menu when you click the right mouse button, as well as being associated with the function key.

The following rules apply to CONNECT directives:

• The optional function-key-number is only valid when the CONNECT directive is called from a data element name pre-process. It defines the function key that the user must press to cause the activation of this CONNECT directive.
• The optional message is not valid for CONNECT HELP, CONNECT MENU, CONNECT SCREEN, and CONNECT VIEW. It is only available for CONNECT METHOD, CONNECT REPORT, and CONNECT QUERY.
• Only methods have the ability to pass string arrays to connected classes. These arrays can be used to control the behavior of the connected class. If it is important to exercise this level of control you should first connect to a method, then use the method to set the required parameters in an array before calling the required class.

Data Element Name Pre-process CONNECT Directives

The data element name pre-process CONNECT directives are evaluated when the cursor is placed in a view or screen on the data element name, before the user has entered any data. Typically, the pre-process facility is used to allow the user to decide the next action. Screen prompts and view prompts, displayed on the first line of the screen, provide the user with information on options.

In a data element name pre-process a CONNECT statement specifies the actions to be taken. If the CONNECT statement includes a function-key-number, the directive is executed when that function key is pressed. If no function key number is supplied, or if 0 is specified, the directive is executed automatically when the view or screen field enters data entry mode.

The following CONNECT directives may be used in a data element name pre-process.

CONNECT[(function-key-number)] HELP help-name

Connects to the help subsystem, which will display the named help message. When the connected help is closed control will be returned to this pre-process.

CONNECT[(function-key-number)] MENU menu-name

Connects to the menu subsystem and displays the named menu. When the connected menu is closed control will be returned to this pre-process.

CONNECT[(function-key-number)] METHOD method-name
   [message]

Passes control to the named method. When the method exits then control will be returned to this pre-process. Methods may pass back method return directives, to be honored by the pre-process. See the information on pre-process in the Data element names subsection earlier in this section.

CONNECT[(function-key-number)] METHOD method-name
   [PP=xx]

xx is a two-character value which will be received by the system data element name #IDSV.PASSED-PARMS and by the Script system variable MENU-PARMS. This data element name can be used to control the behavior of the method.

CONNECT[(function-key-number)] QUERY query-name
   [,parameter[,parameter]...]

Passes control to Query-IV to execute the named query. When the query terminates, control will be returned to this pre-process. Parameters may be supplied to Query-IV in a comma-separated string. For more information on parameters, refer to information on the QUERY$ string array in the QUERY$ section of this manual.

CONNECT[(function-key-number)] REPORT report-name
   [,parameter[,parameter]...]

Passes control to Report-IV to execute the named report. When the report terminates, control will be returned to this pre-process. Parameters may be supplied to Report-IV in a comma-separated string. For more information on parameters, refer to information on the REPORT$ string array in the REPORT$ section of this manual.

CONNECT[(function-key-number)] SCREEN screen-name

Connects to the named screen. When the connected screen is closed, control returns to this pre-process.

CONNECT[(function-key-number)] VIEW view-name
[USING data element name or expression; |
USING RANGE FROM data element name or expression; TO data element name or
expression;]
[SELECT WHEN expression;]
[SORT [BY] n]

Connects to the named view. When the connected view is closed, control is returned to this pre-process.

The USING and USING RANGE clauses specify one or more data element name values or expressions that, when evaluated, restrict the key range in the connected view to select records to be displayed.

The SELECT WHEN clause is used when the required selection criterion is to be based on non-key field(s).

The optional SORT BY clause specifies which sort definition will be used in the connected view.

If an expression has embedded blanks, then it must be terminated by a semicolon.

Script Method CONNECT Directives

The script method CONNECT directives are evaluated when invoked. Methods may pass parameters and messages through the CONNECT directive using string arrays. For a description of the relevant array see the section on String Arrays. The script method must dimension these arrays before they are used.

The following CONNECT directives can be used in a script method.

CONNECT HELP help-name

Connects to the help subsystem, which will display the named help message. When the connected help is closed control will be returned to the original method.

The method may supply parameters and messages to control the behavior of the help subsystem by building string array HELP$. See the HELP$ section of this manual.

CONNECT MENU menu-name

Connects to the menu subsystem and displays the named menu. When the menu is closed, control will be returned.

The method may supply parameters and messages to control the behavior of the Menu subsystem by building string array MENU$. See the MENU$ section of this manual.

CONNECT METHOD "method-name" ["message"]

Passes control to the named method. When the method exits, control will be returned to the original method.

The method may supply parameters and messages to control the behavior of the called method by building the MSG1$ string array. OPENworkshop will place the optional message in MSG1$[1]. See the information on application methods in the OPENworkshop Methods section of this manual.

CONNECT QUERY query-name[,parameter[,parameter]...]

Passes control to Query-IV to execute the named query. When the query terminates, control will be returned. Parameters may be supplied to Query-IV in a comma-separated string. For more information on parameters, see the information on the QUERY$ string array in the QUERY$ section of this manual.

Alternately, the method may supply parameters and messages to control the behavior of the Query-IV subsystem by directly building the QUERY$ string array.

CONNECT REPORT report-name[,parameter[,parameter]...]

Passes control to Report-IV to execute the named report. When the report terminates, control will be returned. Parameters may be supplied to Report-IV in a comma-separated string. For more information on parameters, refer to the REPORT$ string array section of this manual.

Alternately, the method may supply parameters and messages to control the behavior of the Report-IV subsystem by directly building the REPORT$ string array.

CONNECT SCREEN screen-name

Connects to the named screen. When the screen is closed, control returns to the method.

The method may supply parameters and messages to control the behavior of the called screen by building the SCREEN$ string array. For more information on parameters, refer to the SCREEN$ string array section of this manual.

CONNECT VIEW view-name

Connects to the named view. When the view is closed, control is returned to the method.

Optional USING, USING RANGE and SELECT WHEN clauses may be used to specify one or more data element name values or expressions that, when evaluated, should be used as the key in the connected view to select records to be displayed.

The optional SORT clause specifies the sort index that should be used when record selection is carried out in the connected view.

Unlike a pre-process CONNECT, when these optional functions are invoked from a script method, they must be placed in a string within string array VIEW$. For more information on parameters, see the VIEW$ string array section of this manual.

If an expression has embedded blanks, then it must be terminated by a semicolon.

Other CONNECT Directives

The CONNECT directive may also be initiated from a data element name post-process or menu. In these cases, the directive behaves as described for data element name pre-process CONNECT directives, except that the function key number option is not available and the following exceptions apply:

CONNECT	From Data Element Name Post-Process	From Menu
HELP	As data element name pre-process	As data element name pre-process
MENU	As data element name pre-process	As data element name pre-process
METHOD	Method return directives will not be evaluated	Method return directives will not be evaluated. If the menu is a selection type menu, then selection parameters will be passed to the called method in the MSG$[2] string array.
QUERY	As data element name pre-process	As data element name pre-process
REPORT	As data element name pre-process	As data element name pre-process
SCREEN	As data element name pre-process	As data element name pre-process
VIEW	As data element name pre-process	As data element name pre-process

From the OPENworkshop Reference, version 8.9.1. Open this page in the PDF