Creating Dialogs

The Process Mode of the EDITOR panel allows you to make a query into a dialog that prompts for variable selections at execution time. 
datacom151
The Process Mode of the EDITOR panel allows you to make a query into a dialog that prompts for variable selections at execution time. A 
dialog
 is a query that, when executed, prompts the user for specific entries where portions of the query have been designated as variable. The dialog can provide a default selection, a list of valid entries for character variables and a range of valid entries for numeric variables.
Any part of a query can be a 
variable
 for which the person executing the query can substitute another value. Each variable must have a unique variable ID.
For information about how dialogs work when the user sees them, see Responding to Extra Panels During Execution.
The following topics are discussed on this page:
 
 
Reviewing the Process
When the dialog is executed, panels appear to prompt the user to take appropriate actions. First, a panel appears that describes the dialog. Next panels appear for each variable that prompt the user to use the variable default or to enter a new variable. When you define the dialog, you define these panels.
The panels for defining the prompts appear automatically after you define the type, insert variables, and press <PF5> DIALOG DEF.
The remainder of this section describes the process of setting dialog specifications.
 
Rules
 
Dialogs must:
  • Follow the rules for query creation
  • Contain the word 
    dialog
     in the TYPE field
  • Contain variables that you define and save
Any item that is to be a variable must have a one or two digit number and a variable symbol preceding it. You can use any number between 1 and 99, but you can only use 25 variables.
The default variable symbol is a question mark (?). Your site may use a different character as a dialog variable symbol. View the SYSTEM PROFILE HELP from the General Help panel of the Main Menu to determine what character your site uses.
To create a dialog, you must create or edit an existing query. Create variables of any query part by substituting that part with a variable.
 
Sample
 
Following is a sample format for a dialog variable. See the online HELP SYSTEM PROFILE topic for symbols.
25?CUST_ID_________
The following explains each part of the preceding sample variable.
 
Sample
 
 
Name
 
 
Explanation
 
25
Variable
ID
Enter a number from 1 to 25 that is unique in this dialog.
?
Dialog symbol
The installation default symbol is a question mark. Your site may use a different character.
CUST_ID
Default
The default item to be used in processing the dialog if no replacement is entered or selected. Any query item may be made into a variable.
_______
 
Dialog fill character
Enter enough site-specific dialog fill characters to allow room for the longest variable replacement you will allow. Your site may use a different character.
Planning the Dialog
The following query produces a typical report. It also contains an ORDER BY clause that permits control breaks to be specified. For more information on control breaks and ORDER BY, see Step 1: Plan a Report in SQL Mode.
=> --------------------------------------------------------------------------DQD10 DATAQUERY: EDITOR ------------------------------------------------------------------------------- NAME: SALARY_INFO TYPE: QUERY STATUS: PRIVATE DESCRIPTION: ____________________________________________________________ ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+. .. ================================ T O P ===================================== 01 SELECT SALARY, 02 DEPT, 03 NAME, 04 ID 05 FROM STAFF 06 ORDER BY DEPT
The plan for this query is to make it into a dialog so that users who execute it can change the sorted order of the output.
 
Action
 
To make the preceding query into a dialog, the object of the ORDER BY clause (DEPT) should be a variable and the TYPE should be 
dialog
, as in the following example:
=> --------------------------------------------------------------------------DQD10 DATAQUERY: EDITOR ------------------------------------------------------------------------------- NAME: SALARY_INFO TYPE: DIALOG STATUS: PRIVATE DESCRIPTION: ____________________________________________________________ ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+. .. ================================ T O P ===================================== 01 SELECT SALARY, 02 DEPT, 03 NAME, 04 ID 05 FROM STAFF 06 ORDER BY 1?DEPT_____________
Defining the Dialog
When 
dialog
 is the TYPE, you have access to <PF5> DIALOG DEF. This PF key accesses the panels you use to define the panels that appear during execution, along with your definitions of each variable you created on the EDITOR.
The following steps show the sequence of panels that appear when you choose <PF5> DIALOG DEF during EDITOR panel Process Mode.
This particular set of panels defines the preceding sample dialog.
  •  
    Step 1
    Create or select a query to be made into a dialog.
  •  
    Step 2
    Enter dialog as the Type.
  •  
    Step 3
    Move the cursor to DEPT in the ORDER BY clause, press the insert key, and type 1?.
  •  
    Step 4
    Save the dialog.
  •  
    Step 5
    Press <PF5> DIALOG DEF.
  •  
    Step 6
    Complete DEFINE DESCRIPTIVE TEXT (DQDP0) as shown following:
--------------------------------------------------------------------------DQDP0 DATAQUERY: DEFINE DESCRIPTIVE TEXT NAME: SALARY_INFO ------------------------------------------------------------------------------- DESCRIPTION: STATUS: INCOMPLETE ------------------------------------------------------------------------------- ENTER THE DESCRIPTIVE TEXT TO BE USED AS A TITLE AND SAVE IT The report created by this dialog gives you salary, department, name and ID ___ data. You can sort the data by any one of these items.________________________ _______________________________________________________________________________ _______________________________________________________________________________ ------------------------------------------------------------------------------- <PF1> HELP <PF2> RETURN <PF3> CONTINUE <PF4> SAVE <PF5> NOT USED <PF6> NOT USED <PF7> LAST VARIABLE <PF8> FIRST VARIABLE
  •  
    Step 7
    Press <PF4> SAVE to save this part of the dialog definition. Then, press <PF8> FIRST VARIABLE to define the 1? variable.
  •  
    Step 8
    Complete the DEFINE VARIABLE (DQDV0) panel as shown following:
--------------------------------------------------------------------------DQDV0 DATAQUERY: DEFINE VARIABLE NAME: SALARY_INFO ------------------------------------------------------------------------------- DESCRIPTION: STATUS: INCOMPLETE NAME, FROM STAFF ORDER BY 1?DEPT____________ VARIABLE ID: 1 ? ENTER THE PROMPT TO BE DISPLAYED FOR THIS VARIABLE: SELECT A COLUMN NAME FROM THE ALLOWED NAMES OR LEAVE DEPT AS THE DEFAULT.______ VARIABLE TYPE: c C - CHARACTER N - NUMERIC A - ALPHABETIC VARIABLE LENGTH: 16 VARIABLE DEFAULT VALUE: DEPT____________ ------------------------------------------------------------------------------- <PF1> HELP <PF2> RETURN <PF3> CONTINUE <PF4> SAVE <PF5> RANGE/LIST <PF6> DELETE <PF7> PREV VARIABLE <PF8> NEXT VARIABLE
The prompt text indicates the information that identifies the variable being defined.
  •  
    Step 9
    Press <PF4> SAVE and then press <PF5> RANGE/LIST. Defining a range or list is optional.
  •  
    Step 10
    Complete the DEFINE VARIABLE LIST panel (DQDL0) as shown following:
=> ENTER THE VALID VALUES FOR THE VARIABLE BELOW --------------------------------------------------------------------------DQDL0 DATAQUERY: DEFINE VARIABLE LIST ------------------------------------------------------------------------------- NAME SALARY_INFO VARIABLE ID: 1 ? PROMPT FOR VARIABLE: SELECT A COLUMN NAME FROM THE ALLOWED NAMES OR LEAVE DEPT AS THE DEFAULT. DEPT____________ SALARY NAME ID ________________ ________________ ________________ ________________ ________________ ________________ ________________ ------------------------------------------------------------------------------- <PF1> HELP <PF2> RETURN <PF3> DELETE <PF4> SAVE <PF5> NOT USED <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
You can define a list or a range (if the data is numeric) for each variable in the dialog or you can allow users to enter any valid names.
Press <PF4> SAVE to save the list and press <PF2> RETURN to go back to the DEFINE VARIABLE panel. Note that the status of the dialog is now 
complete
.
  •  
    Step 11
    Press <PF4> CONTINUE. When the last dialog panel is saved, 
    CA Dataquery™ for CA Datacom®
     redisplays the EDITOR panel and a message telling you to validate.
  •  
    Step 12
    Validate the dialog. Follow these steps:
    1. Complete the dialog definition.
    2. Return to the EDITOR.
    3. Press <PF10> VALIDATE.
    4. View dialog prompt panel and check it for accuracy.
    5. Display any range or list definitions and check them for accuracy.
    6. Make selections from the range and list panels.
    7. Change values on the prompt panels you designed.
    8. Press <PF4> CONTINUE to complete the validation.
    9. If you are satisfied with the results of validation, your dialog is complete and ready to execute <PF3>. If you are not satisfied, you can return to the dialog definition, delete saved panels that you do not like, and change all or part of the definition.
Other Things You Could Do
The preceding sample query could also be changed so that users could add any valid column name to the SELECT clause. To do that, a variable with a blank default must be defined and added to the SELECT clause, as follows:
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+. .. ================================ T O P ===================================== 01 SELECT SALARY, 02 DEPT, 03 NAME, 04 ID, 05 1?__________________ 06 FROM STAFF 07 ORDER BY 2?DEPT_____________ .. =========================== B O T T O M ==================================
Note that a comma was added to the preceding column name and that the dialog fill character defines the whole variable. Read more about dialog fill characters on Reviewing the Process.
With the ORDER BY clause, three things are possible:
  • Reuse the 1? variable so that any column named as a SELECT clause variable would also be the sort column for the report.
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+. .. ================================ T O P ===================================== 01 SELECT SALARY, 02 DEPT, 03 NAME, 04 ID, 05 1?__________________ 06 FROM STAFF 07 ORDER BY 1?DEPT_____________ .. =========================== B O T T O M ==================================
Make the entire ORDER BY clause into a variable by providing variables before and after the clause that are comment symbols. Substitutions for these symbols may be any two-letter word that is ignored by 
CA Dataquery™ for CA Datacom®
.
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+. .. ================================ T O P ===================================== 01 SELECT SALARY, 02 DEPT, 03 NAME, 04 ID, 05 FROM STAFF 06 1?*/ 07 ORDER BY 2?DEPT___________ 08 3?/* .. =========================== B O T T O M ==================================