1. The Basics of Dialogue Manager for Application Development Walter F. Blood June, 2008

2. Dialogue Manager Agenda 1. What is Dialogue Manager? 2. How does Dialogue Manager process? 3. What are Dialogue Manager variables?  Types - user, system, statistical  Assigning values to variables 4. How can I navigating the procedure? 5. How can I debug Dialogue Manager procedures?

3. Dialogue Manager What is Dialogue Manager?  Process Controller  Prepare FOCUS commands for execution  Get values for variables (indicated by leading '&')  User supplied  Process supplied (statistical variables)  Calculated  Control Execution Flow  Branching  Conditional Branching  Dialogue Manager commands - leading dash in column 1

4. What is Dialogue Manager? FOCEXECs  Applications are built using FOCEXECs as building blocks  Dialogue Manager Commands – preceded by dash  FOCUS Commands – not preceded by dash  System Commands – preceded by –  Naming Conventions  VM: focexecname FOCEXEC filemode  MVS  Member of PDS allocated to FOCEXEC  Sequential file allocated to focexecname  Focexecname.fex NOT terminal input or SYSIN (no &YMD in HEADING)

5. What is Dialogue Manager? FOCEXECs  Application profiles automatically executed by system  EDASPROF.PRF ‘EDASPROF PROF’  ERRORS(FOCPARM)‘FOCPARM ERRORS’  ERRORS(FOCPROF)‘FOCPROF ERRORS’  FOCEXEC(PROFILE)PROFILE FOCEXEC  All others  EX focexecname [variable=value,variable=value]  MVS Batch //SFEX DD * focexec /* //SYSIN DD * EX SFEX FIN /*

6. Dialogue Manager Processing  Parse FOCEXEC  Substitute variables  Prompt for variables not previously set  Execute Dialogue Manager commands (- in column 1  Place non-Dialogue Manager commands on a stack for further processing EX focexecname [variable=value,variable=value]

7. Processing Parsing the FOCEXEC  Line begins with - (dash) in column 1  Evaluate and process immediately  -* Comment lines ignored  Line does NOT begin with - (dash)  TABLE, DEFINE, MODIFY, SET, etc.  Evaluate &variables (may PROMPT or AUTOPROMPT)  Write to execution stack with substitution  Stack is executed with –RUN or –EXIT  Stacked commands executed by command processor

8. Processing Ending the Process  -RUN  Execute the current stack  Return to procedure at the next line  -EXIT  Execute the current stack  Return to FOCUS command level (SYSIN)  -QUIT  Return to FOCUS command level (SYSIN)  Clear the current stack  -QUIT FOCUS n  Return to system command level  Return code set to n

9. TABLE FILE EMPLOYEE TABLE FILE EMPLOYEE HEADING CENTER "REPORT OF SALARIES" TABLE FILE EMPLOYEE HEADING CENTER "REPORT OF SALARIES" SUM SALARY BY DEPARTMENT BY EMP_ID TABLE FILE EMPLOYEE HEADING CENTER "REPORT OF SALARIES" SUM SALARY BY DEPARTMENT BY EMP_ID WHERE LAST_NAME CONTAINS 'SMITH' TABLE FILE EMPLOYEE HEADING CENTER "REPORT OF SALARIES" SUM SALARY BY DEPARTMENT BY EMP_ID WHERE LAST_NAME CONTAINS 'SMITH' END WHO = US NAME = SMITH EX PROC1 WHO=US, NAME=SMITH -STEP1 Processing Example HEADING CENTER "REPORT OF SALARIES" EX PROC1 WHO=US, NAME=SMITH WHO = US NAME = SMITH NAM1 = 'SMITH' -SET &NAM1=IF &WHO EQ 'GB' - THEN '''SMYTH''' - ELSE ''''| &NAME ||''''; TABLE FILE EMPLOYEE -INCLUDE HEADING SUM SALARY BY DEPARTMENT BY EMP_ID WHERE LAST_NAME CONTAINS &NAM1 END -RUN -STEP2

10. Variables 10

11. Variables User Variables  &variable  Single ampersand (&) precedes variable name  In effect throughout a single procedure  &&variable  Remain in effect throughout the FOCUS session  Change with -SET &&variable  Cleared by the LET CLEAR command  In a non-persistent connection, set in edasprof, or controlled by IBIF_persistentamp setting  &variable.&index  Indexed variables  Multiple selections for the same variable name

12. Variables Names and Values  &variable names  Each name from 1-100 characters  Case sensitive  Variable values  Variables may be from 1 - 32K in length  Stored as alphanumeric values  Interpreted as integer or alphanumeric based on usage  SET DMPRECISION introduces decimal values

13. Variables Variable Attributes  &variable.EXIST  Test to see if variable exists  0 - value not set  non-zero - value has been set  &variable.LENGTH  Length of the variable value  &variable.TYPE  Type of value  A - alphanumeric  N - numeric  U - undefined

14. Variables Variable Evaluation  &variable.EVAL  Normal D.M. evaluation of variables only occurs ONCE  Amper variables replaced by their value  Problem for User Written Subroutines. Last arg must be format: Gives: STRING= >qwer IN QWER OUT qwerT -PROMPT &STRING -SET &LSTR = &STRING.LENGTH; -SET &LSTRING = LOCASE(&LSTR, &STRING,'A&LSTR'); -TYPE IN &STRING OUT &LSTRING

15. Variables Variable Evaluation .EVAL replaces D.M. variable and RE-EVALUATES: Gives: -PROMPT &STRING -SET &LSTR = &STRING.LENGTH; -SET &LSTRING = LOCASE(&LSTR, &STRING,'A&LSTR.EVAL'); -TYPE IN &STRING OUT &LSTRING STRING= >qwer IN QWER OUT qwer

16. Variables Variable Evaluation .EVAL can be used to control D.M. execution Gives: -DEFAULT &DEBUG=OFF -SET &C = IF &DEBUG EQ 'ON' THEN '-TYPE' ELSE '-*'; &C.EVAL VALUE OF DEBUG IS &DEBUG -TYPE REST OF PROCESS >>ex debug REST OF PROCESS >>ex debug debug=on VALUE OF DEBUG IS ON REST OF PROCESS

17. Variables System Variables  &DATE ------- MM/DD/YY  &DATEYYMD --------YYYY/MM/DD  &YMD ------- YYMMDD  &DMY ------- DDMMYY  &MDY ------- MMDDYY  &TOD ------- HH.MM.SS  &FOCFOCEXEC -------  &FOCREL ------- FOCUS release number  &FOCCPU ------- OS CPU time  …and many more, check the manual.

18. Variables Statistical Variables  TABLE Command  &LINES, &RECORDS, &BASEIO, &FOCERRNUM  Operating System Command  &RETCODE  -READ  &IORETURN  -? TSO DDNAME ddname  &FOCUSPAGES, &DSNAME  Referencing a statistical variable implies –RUN  Needs execution to get a value

19. Variables Supplying Values for User Variables  EX focexec variable1=value1,variable2=value2  -DEFAULT  -PROMPT  Implicit PROMPT  -CRTFORM  -SET  -READ

20. Supplying Values for User Variables -DEFAULT  -DEFAULT variable=value -DEFAULT &COUNTRY=ENGLAND TABLE FILE CAR SUM RCOST BY COUNTRY IF COUNTRY EQ '&COUNTRY' END  EX PRC1  Use default value  EX PRC1 COUNTRY = FRANCE  Override default value WebFOCUS, with AUTOPROMPT, will use the DEFAULT value within the prompt as the 'default' value

21. Supplying Values for User Variables -PROMPT  -PROMPT &variable  -PROMPT &variable.message.  -PROMPT &variable.format.  Alphanumeric format: An  Numeric format: In (enforces numeric only)  -PROMPT &variable.format.message.  -PROMPT &variable.(value1,value2,...).message.  Implicit PROMPT  IF COUNTRY EQ '&variable'  IF COUNTRY EQ '&variable.message.'  IF COUNTRY EQ '&variable.format.message.'  IF COUNTRY EQ '&variable.(value1, value2).message.'

22. -PROMPT Examples  Implicit PROMPT: IF COUNTRY EQ '&COUNTRY'  Can be overridden at run time  -PROMPT &COUNTRY  Always prompted  -PROMPT &COUNTRY.Please enter a value for country. PLEASE SUPPLY VALUES REQUESTED COUNTRY= Please enter a value for country

23. -PROMPT Examples  -PROMPT &COUNTRY.A10.Please enter a value for country.  -PROMPT &COUNTRY.(ENGLAND,FRANCE).Please enter a value for country. Please enter a value for country WEST GERMANY (FOC291) THE VALUE IN THE PROMPT REPLY EXCEEDS THE MAXIMUM LENGTH: 10 CHARS:WEST GERMANY Please enter a value for country Please enter a value for country WEST GERMANY PLEASE CHOOSE ONE OF THE FOLLOWING: ENGLAND,FRANCE Please enter a value for country

24. Supplying Values for User Variables -SET Alphanumeric or numeric constants  String concatenation  Mathematical expressions  SET DMPRECISION= n (number of decimal places)  Functions  Typically require format as last or output parameter  Logical expressions (IF...THEN...ELSE) -SET &variable=expression;

25. -SET Examples  -SET &COUNTRY='ENGLAND';  -SET &COUNT=1001;  -SET &NAME = &LN || (', ' | &FN);  -SET &WITHQUO = '''' | &LN || '''';  -SET &INCREASE = &PCT1 + 3;  -SET &COUNTRY=UPCASE(12,&COUNTRY,'A12');  -SET &COUNTRY= IF &COUNTRY EQ 'GERMANY' - THEN 'W GERMANY' ELSE &COUNTRY;

26. Supplying Values for User Variables -CRTFORM  <T.&variable – display current value for change  <D.&variable – display current value. Cannot be changed. -SET &variable1=... ; -SET &variable2=... ; -SET &variable3=... ; -CRTFORM -" text <&variable0/length " -" text <&variable1" -" text "

27. -CRTFORM Example -CRTFORM -"ENTER COUNTRY <&COUNTRY/10" TABLE FILE CAR SUM RCOST BY COUNTRY IF COUNTRY EQ '&COUNTRY' END -RUN -SET &COUNTRY=' '; -CRTFORM “ COUNTRY - “...

28. Supplying Values for User Variables -READ  Use format for fixed length files  Use commas for comma delimited files  ddname closed with -RUN  ddname closed when a statistical variable is referenced  NOCLOSE option keeps file open until explicitly closed with -CLOSE -READ ddname [NOCLOSE] &var1.format &var2.format -READ ddname [NOCLOSE] &var1, &var2

29. Supplying Values for User Variables -TYPE  -TYPE prints messages to the screen -DEFAULT &START=STEP1 -DEFAULT &END=STEP99 -GOTO &START -STEP1 -TYPE NOW ENTERING &START TABLE FILE... -RUN -TYPE THE VALUE OF &|LINES IS &LINES

30. Dialogue Manager -WRITE  -WRITE prints messages to a file -PROMPT &EXTSORT.(ON,OFF).EXTERNAL SORT?. SET EXTSORT = &EXTSORT TABLE FILE BIGFILE PRINT * BY KEYFLD END -RUN -WRITE OUTFI WHEN EXTERNAL SORT IS &EXTSORT -WRITE OUTFI THE NUMBER OF LINES IS &LINES -WRITE OUTFI THE BASEIO IS &BASEIO

31. Navigating the Procedure 31

32. Dialogue Manager Navigating the Procedure  Labels (-name)  -GOTO label  -IF expression THEN GOTO label1 ELSE... ;  -REPEAT  -REPEAT label n TIMES  -REPEAT label WHILE expression;  -REPEAT label FOR &variable [FROM m TO n STEP s]  -INCLUDE focexec

33. Navigating the Procedure -GOTO and Labels -DEFAULT START=STEP1,END=STEP99 -GOTO &START -STEP1 TABLE FILE... -RUN -IF &END EQ 'STEP1' THEN GOTO STEP99; -STEP2 TABLE FILE... -RUN -IF &END EQ 'STEP2' THEN GOTO STEP99;... -STEP99 -EXIT

34. Navigating the Procedure Branching to Control Execution -DEFAULT &PERIOD = 'MONTH' TABLE FILE FINANCE SUM AMOUNT BY ACCOUNT BY CUSIP BY YEAR -IF &PERIOD EQ 'ANNUAL' GOTO NOMORE - ELSE IF &PERIOD EQ 'QUARTER' GOTO QTRLY; BY MONTH -GOTO NOMORE -QTRLY BY QUARTER -NOMORE END -RUN

35. Navigating the Procedure Alternative to Branching -DEFAULT &PERIOD = 'MONTH' -SET &SORT=IF &PERIOD EQ 'MONTH' - THEN 'BY MONTH' - ELSE IF &PERIOD EQ ‘QUARTER' - THEN 'BY QUARTER' - ELSE ' '; TABLE FILE FINANCE SUM AMOUNT BY ACCOUNT BY CUSIP BY YEAR &SORT END -RUN

36. Navigating the Procedure Loops TABLE FILE CAR SUM COUNTRY BY COUNTRY ON TABLE SAVE END -RUN -LP -READ SAVE &COUNTRY.A10. -IF &IORETURN NE 0 GOTO NOMORE; TABLE FILE CAR SUM RETAIL_COST BY COUNTRY IF COUNTRY EQ '&COUNTRY' END -GOTO LP -NOMORE -EXIT

37. Navigating the Procedure -REPEAT TABLE FILE FINANCE SUM AMOUNT BY ACCOUNT ACROSS MONTH COLUMNS ‑ REPEAT NOMORE FOR &CTR1 FROM 1 TO 12 STEP 1 -SET &XYZ=IF &CTR1 EQ 1 THEN &CTR1 - ELSE 'AND ' | &CTR1; &XYZ -NOMORE END -EXIT

38. Navigating the Procedure -INCLUDE  -INCLUDE focexecname  Reads another FOCEXEC into the same session  Inserted lines treated as if they were in the calling FOCEXEC (may be 'partial' FOCEXEC)  Variables are shared within session  Use -INCLUDE to insert common code in several FOCEXECs  EX focexecname  Starts a new Dialogue Manager session  Variables are not shared with calling FOCEXEC  Must be 'complete' (self-contained)

39. Debugging Dialogue Manager 39

40. Dialogue Manager Debugging  -SET &ECHO=  OFF – do not echo any code  ON – echo only stacked commands after substitution  ALL – echo all commands after substitution  Applies only focexec in which it is called  SET DEFECHO=  ON – Forces ECHO for all commands across focexecs  OFF – Turns off forced echo of all commands  Requires –RUN to engage this setting.  SET XRETRIEVAL=OFF  Parses the non-Dialogue Manager commands  Does not retrieve data from databases

41. Debugging &ECHO Examples  EX procedure  Only output from procedure seen  EX procedure ECHO=ON  Output from procedure seen  Stack (after substitution) displayed  EX procedure ECHO=ALL  Output from procedure seen  Dialogue Manager commands echoed  Stack (after substitution) displayed

42. Debugging &ECHO Examples -DEFAULT &PERIOD = 'MONTH' TABLE FILE FINANCE SUM AMOUNT BY ACCOUNT BY CUSIP BY YEAR -SET &ECHO=ALL; -IF &PERIOD EQ 'ANNUAL' GOTO NOMORE ELSE -IF &PERIOD EQ 'QUARTER' GOTO QTRLY; BY MONTH -GOTO NOMORE -QTRLY BY QUARTER -NOMORE -SET &ECHO=OFF; END

43. Basics of Dialogue Manager for Application Development