The Basics of Dialogue Managerfor Application Development

Walter F. Blood

June, 2008

Dialogue ManagerAgenda

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 ManagerWhat is Dialogue Manager?

Process Controller Prepare FOCUS commands for execution Get values for variables (indicated by leading '&')

User suppliedProcess supplied (statistical variables)Calculated

Control Execution FlowBranchingConditional 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 –<osname>

Naming Conventions VM: focexecname FOCEXEC filemode MVS

Member of PDS allocated to FOCEXECSequential 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 SFEXFIN/*

Dialogue ManagerProcessing

Parse FOCEXECSubstitute variables

Prompt for variables not previously setExecute Dialogue Manager commands (- in column 1Place 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

ProcessingEnding 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 EMPLOYEEHEADING CENTER"REPORT OF SALARIES"

TABLE FILE EMPLOYEEHEADING CENTER"REPORT OF SALARIES"SUM SALARY BY DEPARTMENTBY EMP_ID

TABLE FILE EMPLOYEEHEADING CENTER"REPORT OF SALARIES"SUM SALARY BY DEPARTMENTBY EMP_IDWHERE LAST_NAME CONTAINS 'SMITH'

TABLE FILE EMPLOYEEHEADING CENTER"REPORT OF SALARIES"SUM SALARY BY DEPARTMENTBY EMP_IDWHERE LAST_NAME CONTAINS 'SMITH'END

WHO = USNAME = SMITH

EX PROC1 WHO=US, NAME=SMITH

-STEP1

ProcessingExample

HEADING CENTER"REPORT OF SALARIES"

EX PROC1 WHO=US,NAME=SMITH

WHO = USNAME = SMITH NAM1 = 'SMITH'

-SET &NAM1=IF &WHO EQ 'GB'- THEN '''SMYTH'''- ELSE ''''| &NAME ||'''';TABLE FILE EMPLOYEE-INCLUDE HEADINGSUM SALARY BY DEPARTMENTBY EMP_IDWHERE LAST_NAME CONTAINS &NAM1END-RUN-STEP2

Variables

10

VariablesUser 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

VariablesNames 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

VariablesVariable 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

VariablesVariable 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=>qwerIN QWER OUT qwerT

-PROMPT &STRING-SET &LSTR = &STRING.LENGTH;-SET &LSTRING = LOCASE(&LSTR, &STRING,'A&LSTR');-TYPE IN &STRING OUT &LSTRING

VariablesVariable 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=>qwerIN QWER OUT qwer

VariablesVariable 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 debugREST OF PROCESS

>>ex debug debug=onVALUE OF DEBUG IS ONREST OF PROCESS

VariablesSystem Variables

&DATE ------- MM/DD/YY &DATEYYMD --------YYYY/MM/DD&YMD ------- YYMMDD&DMY ------- DDMMYY&MDY ------- MMDDYY&TOD ------- HH.MM.SS&FOCFOCEXEC ------- <focexecname>&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=ENGLANDTABLE FILE CARSUM RCOST BY COUNTRYIF 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 REQUESTEDCOUNTRY=

PLEASE SUPPLY VALUES REQUESTEDCOUNTRY=

Please enter a value for country

-PROMPTExamples

-PROMPT &COUNTRY.A10.Please enter a value for country.

-PROMPT &COUNTRY.(ENGLAND,FRANCE).Please enter a value for country.

Please enter a value for countryWEST GERMANY(FOC291) THE VALUE IN THE PROMPT REPLY EXCEEDS THE MAXIMUM LENGTH: 10 CHARS:WEST GERMANYPlease enter a value for country

Please enter a value for countryWEST GERMANYPLEASE CHOOSE ONE OF THE FOLLOWING: ENGLAND,FRANCEPlease enter a value for country

Supplying Values for User Variables -SET

Alphanumeric or numeric constantsString concatenationMathematical 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;

-SETExamples

-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 <T.&variable2> "-" text <D.&variable3> "

-CRTFORMExample

-CRTFORM-"ENTER COUNTRY <&COUNTRY/10"TABLE FILE CAR SUM RCOST BY COUNTRYIF COUNTRY EQ '&COUNTRY'END-RUN

-SET &COUNTRY=' ';-CRTFORM“ COUNTRY - <T.&COUNTRY>“ ...

Supplying Values for User Variables -READ

Use format for fixed length filesUse commas for comma delimited files ddname closed with -RUN ddname closed when a statistical variable is referencedNOCLOSE 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 = &EXTSORTTABLE FILE BIGFILEPRINT * BY KEYFLDEND-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 ManagerNavigating 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 ProcedureBranching 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 ProcedureAlternative 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 FINANCESUM AMOUNT BY ACCOUNT BY CUSIPBY YEAR&SORTEND-RUN

Navigating the ProcedureLoops

TABLE FILE CARSUM COUNTRY BY COUNTRYON TABLE SAVEEND-RUN-LP-READ SAVE &COUNTRY.A10.-IF &IORETURN NE 0 GOTO NOMORE;

TABLE FILE CARSUM RETAIL_COST BY COUNTRYIF COUNTRY EQ '&COUNTRY'END

-GOTO LP-NOMORE-EXIT

Navigating the Procedure-REPEAT

TABLE FILE FINANCESUM AMOUNT BY ACCOUNTACROSS 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

FOCEXECsEX focexecname

Starts a new Dialogue Manager session Variables are not shared with calling FOCEXEC Must be 'complete' (self-contained)

Debugging Dialogue Manager

39

Dialogue ManagerDebugging

-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 FINANCESUM AMOUNT BY ACCOUNT BY CUSIPBY YEAR-SET &ECHO=ALL;-IF &PERIOD EQ 'ANNUAL' GOTO NOMORE ELSE-IF &PERIOD EQ 'QUARTER' GOTO QTRLY;BY MONTH-GOTO NOMORE-QTRLYBY QUARTER-NOMORE-SET &ECHO=OFF;END

Basics of Dialogue Managerfor Application Development