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

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?

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

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)

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 /*

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]

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

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

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

Variables 10

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

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

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

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

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

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

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.

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

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

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

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.'

-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

-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

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;

-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;

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 "

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

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

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

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

Navigating the Procedure 31

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

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

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

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

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

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

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)

Debugging Dialogue Manager 39

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

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

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

Basics of Dialogue Manager for Application Development