Rational Business Developer

Rational Business Developer
Rational Business Developer - Text User Interface Rational Business Developer Text User Interface Programming

IBM Trademarks and Copyrights
Rational Business Developer - Text User Interface IBM Trademarks and Copyrights © Copyright IBM Corporation 2003, All rights reserved. The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM Rational products and services are trademarks or registered trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others. 2003, 2008

Course Contributing Authors
Rational Business Developer - Text User Interface Course Contributing Authors Thanks to the following individuals, for assisting with this course: Mike Virga, Mark Evans, Jon Sayles, Reginaldo Barosa Disclaimer – This course does not cover all the nuances of using text and print forms. For example, it does not emphasize the compatibility considerations for the various target runtime environments. There is an EGL “Best Practices” seminar you can attend that delivers clear guidelines and advice on how to develop and deliver your first project with EGL. Contact: Jon Sayles: for information on scheduling and availability.

Rational Business Developer - Text User Interface
Course Details Audience This course is designed for application developers who have programmed in a 3rd or 4th generation language – and who need to build leading-edge Text User Interface applications using Rational Business Developer. Prerequisites You must have the following software installed: RBD or later This course assumes that you have the following skills: Basic knowledge of information systems technologies, data processing, software and have programmed for at least two or more years in a language such as: COBOL, RPG, PL/1, Pascal, or some 4th Generation Language or tool. Basic PC and mouse-driven development skills is also assumed. Eclipse development – Terms, tools, and navigation EGL language Some understanding of User Interface and basic screen development Knowledge of SQL (Structured Query Language) for database access Finally, it is assumed that you have taken the EGL “Foundation Language” Programming course. This current course builds on the “Foundation Language” focusing on the Text User Interface capabilities. Downloads EGLDerbyR7.zip – the course database EGL_TUIBasics_v751_PIF_StartCourse_version.zip – the project interchange file to start the course EGL_TUIBasics_v751_PIF_EndCourse_version.zip – the project interchange file at the end of the course Your course setup will direct you as to where to get these resources

Course Objectives At the end of this course, you will be able to: Define the nature and purpose of the following : FormGroup TextForm PrintForm Form Components – variable and constant fields TextUIProgram converse, display, and print statements Understand some basics of the EGL text user interface FormGroup and Form Floating area How a program references a FormGroup What happens during generation Use the EGL Text Form Editor to create 3270 or 5250 screens Form Group Text Form Popup Menu or Popup Form Text Form from an existing record Code EGL programs that use a text user interface Typical Development Issues Typical Organization for Text UI Source Code Techniques for dealing with “end user think time” Debug EGL programs that use a text user interface

Course Introduction – Unit Descriptions
Rational Business Developer - Text User Interface Course Introduction – Unit Descriptions Course Setup – configure the workbench for the Text User Interface (Text UI) course and run an installation verification program to confirm your setup. Text UI QuickStart – learn Text UI basics by creating and testing a Hello World Text UI application. EGL Text Form Editor – learn how to use the Text Form Editor, all the features and functions, and how to test Text Forms in the debugger. Text UI Programming – develop a Text UI application system that includes: the Logon Screen, a Main Menu, a List Screen, a Detail Screen, and a Report program. This unit also includes information about development issues, source code organization, and dealing with “end user think time”. Appendices: Installing Rational Business Developer Optional Lab – Generate and Run helloProgram as JavaTM Text UI Compatibility Considerations

RBD/EGL Text UI Programming
Rational Business Developer - Text User Interface Course RBD/EGL Text UI Programming Units: Course Setup Text UI QuickStart EGL Text Form Editor Text UI Programming Course Summary Appendices

UNIT Course Setup Topics: How to take this course Installing and configuring the course project and database

How to Use this Book This course has two different modes of educational delivery – each based on both content matter, and on effective knowledge transfer: Read and Learn:  Do and Acquire: 

Read and Learn  Read and learn is the most prevalent form of education presented in this course. From the slides you are viewing, you can read and understand concepts about RBD and EGL. This is static information presented as traditional text and graphics. Occasionally a slide will have a double-right-pointed triangle in the header:  This means you should do or try something on your computer. The Notes (at the bottom of most slides) present additional information on each concept. The Notes also present (wherever relevant) System z and System i programmer analogies or information for migrating VisualAge Generator Customers.

Do and Acquire  Do and Acquire To make all of the pieces of information covered in this course yours – and to convince you that you’ve got the skills to match the knowledge you accumulate, you need to use RBD and EGL to create software functionality. There are lots of workshops and labs throughout this course that allow you to discover, practice and master the RBD functionality and development techniques used to create no-compromise, production-worthy applications. All of the “do this” steps have a consistent icon to the left of them, the:  When you see this  symbol either at the top of a page, or at the beginning of a step, it signifies that you are to “do” something with the product or language.

 View the Slide Notes  Using your mouse expand the Notes at the bottom of this slide and read them. Adjust the size of the slides or notes to suit your viewing Instructor Notes: This section of the slides is the Notes – but you can read them too! They contain additional information and explanations (like the fact that you can print everything off all at once!) System z – You’ve taken plenty of classes on the mainframe! System i – And you’ve taken classes on the AS/400 too. Figure 1 – PowerPoint Notes View

 Learn More! There are a large number of excellent sources for background information freely available online. Here are a few we use a lot: Product Help Help Contents Search Tutorials and examples – from the Sample Gallery EGL Language Reference EGL Generation Guide EGL Programmer’s Guide Migration Guides Runtime and Server Guides EGL Café Announcements Resource Libraries Forums Blogs IBM Systems Information Center From the home page, click: General Searches GOOGLE: Wikipedia: Search on any topic Answers for virtually any topic Depending on your experience, gaining knowledge in leading-edge development subjects and topics can be crucial to the success of your projects. Do not spin your wheels wondering about a given concept, term, new vocabulary, and so on. Look it up or ask a question on an EGL Café Forum!!

 Product Help – Help Contents and EGL
Rational Business Developer - Text User Interface  Product Help – Help Contents and EGL

 EGL Café – Central Place to Connect with Other EGL Folks

UNIT Course Setup Topics: How to take this course. Installing and configuring the course project and database

 Lab – Start Rational Business Developer
Rational Business Developer - Text User Interface  Lab – Start Rational Business Developer This course uses a pre-configured Project and an open source (Derby) database, which you will need to install and configure. Someone may already have installed and configured theses artifacts for you. If so, you can skip ahead to the next section. If not, please follow the steps below to install and configure the course project and database: Download the following files (your course setup will direct you where to get these files and the version for the project interchange files): EGLDerbyR7.zip – the course database EGL_TUIBasics_v751_PIF_StartCourse_version.zip –project interchange file to start the course EGL_TUIBasics_v751_PIF_EndCourse_version.zip – (optional) project interchange file at end of course From the Windows start menu, launch RBD. At the Workspace Launcher window, specify the directory into which you want to organize all of your RBD Education resources. Usually something like: c:\RBDev751\ …or… d:\RBDev751\ Close the Welcome window This will open to the Workbench (next slide) If you do not have Rational Business Developer installed, see the Appendix for information on how to install it.

 Lab – Initial Workbench Window
Rational Business Developer - Text User Interface  Lab – Initial Workbench Window If you have not applied the license, you might see a Manage Licenses button on the tool bar. You can ignore it.

 Lab – Set EGL Capabilities
Rational Business Developer - Text User Interface  Lab – Set EGL Capabilities Enable the EGL Text UI support as follows: Click Window -> Preferences Expand General Select Capabilities Click Advanced Expand EGL Developer Select EGL Text UI Clear EGL JSF and EGL Rich UI Click OK to close the Advanced Capabilities Settings window Click OK again to close the Preferences window You might have other EGL capabilities selected, but as a minimum, for this course, you need to select EGL Core Language and EGL Text UI. The screen shots for this course were done with only the EGL Core Language and the EGL Text UI capabilities selected. You might see some minor differences for some screen shots depending on which capabilities you have selected.

 Lab – Set EGL Perspective
Rational Business Developer - Text User Interface  Lab – Set EGL Perspective Open the EGL Perspective using the following steps: Click Window -> Open Perspective -> Other Double-click EGL If you already have projects in your workspace you might want to close them so they do not conflict with the projects for the Text UI course. Select the projects, right-click and then select Close Project from the pop-up menu. Optionally, close the Web perspective.

 Lab – Install and Configure the Course Database (Step 1 of 5)
Rational Business Developer - Text User Interface  Lab – Install and Configure the Course Database (Step 1 of 5) This course uses an open-source (Derby) database, which you will need to install and configure. Someone may already have installed and configured the database (for example, if you took the EGL Foundation Language course). If so, you can skip the steps to install the database. If not, please follow the steps below to install and configure the Derby database. Unzip the EGLDerbyR7.zip **** file into: C:\databases\ Your files should look like this after you have unzipped them  Note that the folder appears after you begin using the database during the labs in this course. **** This is one of the files you downloaded in a previous step

Rational Business Developer - Text User Interface  Lab – Install and Configure the Course Database (Step 2 of 5) Add the database connection to your workstation preferences using the following steps: Open the Workstation preferences using the following steps: Click Windows -> Preferences Expand EGL Select SQL Database Connections Click New You might have additional connection details listed (for example, DB2 databases that are defined on your workstation).

Rational Business Developer - Text User Interface  Lab – Install and Configure the Course Database (Step 3 of 5) Complete the New Connection window using the following steps: Select Derby Use the drop down to set the JDBC driver to Derby Embedded JDBC Driver 10.1 Default (near bottom of the list) Click Browse to point to the location where you placed the course database (C:\databases\EGLDerbyR7) Set User name and Password to your Windows logon user ID and password Click Test Connection Click OK for the message that the Connection succeeded Click Finish

The new connection is listed in the EGL SQL Database Connections Click OK to close the Preferences window

Rational Business Developer - Text User Interface  Lab – Install and Configure the Course Database (Step 5 of 5) Derby can only have one database connection at a time Follow these steps to disconnect the database (so we can use Debug in a few minutes): Click Window -> Open Perspective -> Other Double-click Data In the Data Source Explorer view Right-click EGLDerbyR7 and click Disconnect from the popup menu EGLDerbyR7 icon should change to show that it is disconnected Close the Data perspective

 Lab – Configure EGL Preferences (Step 1 of 4)
Rational Business Developer - Text User Interface  Lab – Configure EGL Preferences (Step 1 of 4) You need to configure your EGL preferences in order to complete the labs in this course. From the Workbench Click Window -> Preferences Expand the EGL folder and from within the EGL folder… Select Generation Check  Library Check  Program Check  FormGroup Click APPLY Do not leave Preferences yet 

Rational Business Developer - Text User Interface  Lab – Configure EGL Preferences (Step 2 of 4) Still from within the Preferences window Expand EGL Select Debug Select Stop at first line of program Do not leave Preferences yet 

Rational Business Developer - Text User Interface  Lab – Configure EGL Preferences (Step 3 of 4) Still from within the Preferences window Expand EGL Select Editor Select Show line numbers Do not leave Preferences yet 

Rational Business Developer - Text User Interface  Lab – Configure EGL Preferences (Step 4 of 4) Still from within the Preferences window Select Validation Click Disable All Click OK to close the Preferences window If you are prompted for changing the validation settings, respond Yes

 Lab – Import the Tutorial Project
Rational Business Developer - Text User Interface  Lab – Import the Tutorial Project From the Workbench Click File -> Import Expand the Other folder (at the bottom of the list) Select Project Interchange Click Next From Import Project Interchange Contents Click the top Browse… button (next to From zip file) and browse to select: EGL_TUIBasics_v751_PIF_StartCourse_version.zip **** Selecting the zip file opens its contents in the window, and a resource folder appears Click Select All Click Finish If a popup window appears during the import that asks if you want to “Update resources?” answer: Yes This imports the Tutorial Project into your Workspace **** This is one of the files you downloaded in a previous step You might have some warning messages in the Problems view. You can ignore these messages.

 Lab – Confirm / Set the Build Descriptor Options
Rational Business Developer - Text User Interface  Lab – Confirm / Set the Build Descriptor Options From the Project Explorer Expand EGLTUIProject Expand EGLSource Open the EGLTUIProject.eglbld file with the EGL Build Parts Editor (Hint: Right-click the file and then click Open With -> EGL Build Parts Editor) In the Build Parts Editor Use the drop down list for Load DB options using Connection to point to the connection you previously defined (EGLDerbyR7) This automatically updates the SQL-related build descriptor options and sets your sqlID and sqlPassword based on the connection you defined Hint: If you have shut down the workspace between the time you created the EGLDerbyR7 database connection and the time you update the .eglbld file, you might need to set the sqlPassword manually.

 Lab – Clean the Tutorial Project
Rational Business Developer - Text User Interface  Lab – Clean the Tutorial Project From the Workbench window Click Project -> Clean Click Clean all projects Click OK You might have some warning messages in the Problems view. You can ignore these messages.

 Lab – Run the Installation Verification Program
Rational Business Developer - Text User Interface  Lab – Run the Installation Verification Program From the Project Explorer view Expand the EGLTUIProject Expand the EGLSource folder Expand the egltui.allcustomers package Right-click allCustomersProgram.egl and click Debug EGL Program on the pop-up menu When prompted to switch to the Debug perspective, respond YES Click the Resume button until the List of Customers screen appears

 Lab – Your First Text UI Screen
Rational Business Developer - Text User Interface  Lab – Your First Text UI Screen Press F3 to Exit Other things to try: Enter the first few characters of the last name (such as Sp) and press Enter. Note that the SQL search is case sensitive. The characters that you enter for the last name remain in the case in which you enter them, so SP and Sp retrieve different sets of data. Press F3 to end the program.

Unit Summary Now that you have completed this topic, you should be able to: Launch RBD – and Select/Create a workspace View the EGLTUIProject in Eclipse Connect to the Derby database View data rendered in a simple EGL Text UI Note this verifies that all of the software components necessary for this course are: Installed Configured Operational

Unit Objectives At the end of this unit, you will be able to: Define the nature and purpose of the following : FormGroup TextForm PrintForm Form Components – variable and constant fields TextUIProgram converse, display, and print statements Use the EGL Text Form Editor to create 2 simple Text UI screens Create an EGL TextUIProgram to show the screens and move data from one screen to another Debug the TextUIProgram

Web versus Text UI: Two User Interfaces – Different Technologies
Rational Business Developer - Text User Interface Web versus Text UI: Two User Interfaces – Different Technologies Web Browser interface using JSF Tool: Page Designer Logic: JSFHandler Deploy: Web Application Server (WebSphere Application Server, Tomcat, …) For the Web, the user interface is called a page or window. For Text UI, the user interface is usually called a screen or sometimes a “green screen” (dating back to the original hardware that used green text on a black background).

Web versus Text UI: Two User Interfaces – Different Technologies
3270/5250 interface using FormGroup and Forms Tool: EGL Text Form Editor Logic: Program of type TextUIProgram Deploy: CICS, IMS, iSeries (COBOL only), or Java

Text UI Terminology FormGroup Collection of one or more forms that describe screens or print output TextForm Describes the layout and other properties for a 3270 or 5250 screen PrintForm Describes the layout and other properties for printed output constant field Field on form for which value does not vary – title, column headings, instructions, and so on variable field Field on form for which the value can vary – customer name, order number, part number, part description, shipping address, and so on TextUIProgram Program that uses textForms converse Statement used to show a text form to a user and wait for input display Statement used to show a text form to a user, without the possibility of the user responding to the form (see floating and partial forms later in this course) print Statement used to show a print form CICS customers: A form is similar to a BMS map. For the CICS environment, EGL uses 3270 data streams rather than generating a BMS map. IMS customers: A form is similar to an MFS map. For the IMS environment, EGL generates MFS maps from the FormGroup and form definitions VAGen customers: VAGen map group becomes an EGL FormGroup VAGen display map becomes an EGL textForm VAGen print map becomes an EGL printForm VAGen main transaction program or single segment program becomes and EGL TextUIProgram VAGen DISPLAY statement becomes display for a text form or print for a print form

The EGL Text Form Editor
When you create a Text Form, you start by creating a FormGroup part. Contains one or more forms that the user of your EGL TextUIProgram can interact with Generatable part, so requires a source file to itself and generates into one or more compiled modules EGL Text Form Editor - Similar to the Page Designer for Web pages Enables you to edit a FormGroup part graphically, including its form parts and the fields on those forms Click the Source tab at the bottom of the Content Area to see the EGL source code that the graphical editor is creating Areas of the EGL Text Form Editor Content Area Palette Both Design and Source tabs Properties view 1 2 3 4

Hello World: The User View – The Screens To Create
Rational Business Developer - Text User Interface Hello World: The User View – The Screens To Create Follow the detailed steps in the lab to build these two simple Text UI screens with EGL The screens are very similar to make development for Hello World easier.

Hello World: The EGL Source View – The Generatable Parts
Rational Business Developer - Text User Interface Hello World: The EGL Source View – The Generatable Parts Objective: Create two forms in the same form group Create helloGroup FormGroup Create HelloWorld1 Text Form using the EGL Text Form Editor Add a few fields to the form Try a few things in the Text Form Editor Create HelloWorld2 Text Form by copying the source code from the notes section of the slides (keeps the lab simple) Objective: Create a simple program that converses the two forms Create the HelloProgram TextUIProgram by copying the source code from the notes section of the slides (keeps the lab simple) Converse HelloWorld1 When user presses F5 on HelloWorld1, move data to HelloWorld2 converse HelloWorld2 When user presses Enter on HelloWorld2, converse HelloWorld1 Debug HelloProgram TextUIProgram TextUIProgram HelloProgram.egl Use helloGroup; Function Main() converse helloWorld1; converse helloWorld2; FormGroup helloGroup.egl … Form HelloWorld1 Form HelloWorld2

Hello World: The Development Process – From 10,000 Feet
Rational Business Developer - Text User Interface Hello World: The Development Process – From 10,000 Feet Follow these steps to create the Hello World screens and program Launch RBD and select your workspace Create a new package to contain the Hello World FormGroup and program Create a new Text UI screen Customize the default screen layout Create variable fields on the screen Copy the first screen to create the second screen Create a program to “converse” these Text UI screens Run (test) the Text UI in the debugger Now begin the lab from the detailed instructions starting on the next slide…

 Lab – Launch RBD and Select your Workspace
Rational Business Developer - Text User Interface  Lab – Launch RBD and Select your Workspace (If RBD is not already up and running) From the Windows Start menu, launch RBD From the initial prompt, specify or browse to select your Workspace Your EGLTUIProject should open Open the EGL perspective (see notes for a hint) Hint: To change to the EGL perspective, click Window -> Open Perspective -> Other -> EGL.

 Lab – Create the Package and FormGroup
Rational Business Developer - Text User Interface  Lab – Create the Package and FormGroup In EGLTUIProject, create a new package named egltui.helloworld Hint: Right-click EGLSource and click New -> Package on the pop-up menu Right-click the new package Click New -> Other from the pop-up menu Expand EGL Select FormGroup Click Next Name the EGL part: helloGroup Click Finish The EGL Text Form Editor appears Generally it is easier to create the FormGroup part directly because EGL automatically creates the skeleton of the FormGroup for you. Alternatively, you can create a plain EGL source file and then enter the following code with the EGL Editor: formGroup helloGroup end After you copy in the code, do the following: Save and close the file. In the Project Explorer view, right-click the source file name and click Open With -> EGL Text Form Editor from the pop-up menu.

 Lab – Set Edit Options: Color versus Black and White
The EGL Text Form Editor has many options For now, the option that might matter to you is the ability to toggle between Color mode and Black and White mode Color – gives a more realistic appearance to the screen Black and White – can be easier on the eyes Use whichever mode you prefer Screen shots for the labs are done with Black and White mode

 Lab – Add a Text Form to the FormGroup (Slide 1 of 2)
Create a Text Form within the FormGroup using the following steps: In the Palette area, click on Text Form Drag the cursor to any point in the Content Area Click the left mouse button Name the form: HelloWorld1 Click OK

 Lab – Add a Text Form to the FormGroup (Slide 2 of 2)
 Now: The Content Area indicates you are editing HelloWorld1 The Outline view lists the text form The Properties view shows the text form properties

 Lab – Add EGL Fields to the HelloWorld1 Text Form (Step 1 of 4)
Rational Business Developer - Text User Interface  Lab – Add EGL Fields to the HelloWorld1 Text Form (Step 1 of 4) Add an output field to the form using the following steps: From the EGL Text Form Editor Palette, click on Output field Put the cursor on the Content Area and click again You are prompted for a name: For this lab exercise, the specific locations (row/column) of the fields do not matter. Field name: OutputField Data type: char Dimensions: 20 Click Finish

In the Outline view Expand HelloWorld1 Select OutputField In the Properties view, on the Form Field tab Set the Value to: Hello World !!!! The Content Area is updated to show the value

Add an input field to the form using the following steps: From the EGL Text Form Editor Palette, click on Input field Put the cursor on the Content Area and click again You are prompted for a name: Field name: InputField Data type: char Dimensions: 20 Click Finish

 Lab -- Add EGL Fields to the HelloWorld1 Text Form (Step 4 of 4)
Rational Business Developer - Text User Interface  Lab -- Add EGL Fields to the HelloWorld1 Text Form (Step 4 of 4) Add the Function Key Label using the following steps: From the Palette, click on Output field Put the cursor on the Content Area near the bottom and click again You are prompted for a name: Field name: FKeyLabel Data type: char Dimensions: 25 Click Finish In the Properties view Change the Value to: Press F5 for next screen

 Lab – EGL Text Form Editor – HelloWorld1 Text Form
Rational Business Developer - Text User Interface  Lab – EGL Text Form Editor – HelloWorld1 Text Form You should now have the following when you look at the Design tab: You might want to toggle Black and White mode to see the screen in color.

 Lab – EGL Text Form Editor – HelloWorld1 Text Form
Rational Business Developer - Text User Interface  Lab – EGL Text Form Editor – HelloWorld1 Text Form To view the EGL source that was created, click the Source tab TextForm FormGroup The helloGroup FormGroup contains the HelloWorld1 form. For now, do not worry about the ScreenFloatingAreas property.

 Lab – Create HelloWorld2 Text Form
Rational Business Developer - Text User Interface  Lab – Create HelloWorld2 Text Form Create the HelloWorld2 Text Form using the following steps: Expand the project ZZZTUIProject_CopyPaste and the folder quickStart Double-click the file HelloWorld2_TextForm.txt Copy the HelloWorld2 text form and paste it into the helloGroup.egl file just before the last end statement Hint: use Source tab in the EGL Text Form Editor Click on File -> Save or Ctrl+S to save your work Close both files Code for HelloWorld2 text form: form HelloWorld2 type textForm { FormSize = [24, 80], Position = [1, 1]} OutputField char(35) {Value = "Hello World !!!! THIS IS SCREEN 2", Position = [1, 9], color = green, protect = skipProtect}; OutputField2 char(20) {Position = [6, 19], highlight = underline, color = green, protect = noProtect}; FKeyLabel char(34) {Value = "Press Enter to return to screen 1", Position = [20, 20], color = green, protect = skipProtect}; end If you look at the Design tab, notice that the forms are super-imposed on one another. Later, we will look at how to filter the EGL Text Form Editor to only look at one form at a time.

 Lab – Create EGL TextUIProgram to Use the Text Forms (Step 1 of 3)
Right-click the egltui.helloworld package Click New -> Program from the pop-up menu Set the EGL source file name to: helloProgram Click Text – Create a Text UI-based program Click Finish

Rational Business Developer - Text User Interface  Lab – Create EGL TextUIProgram to Use the Text Forms (Step 2 of 3) Create the source for the helloProgram using the following steps: Method 1 – type the code from the Notes section below into the program Method 2 – copy/paste the code from the ZZZTUIProject_CopyPaste project using the following steps: Expand the project ZZZTUIProject_CopyPaste and the folder quickStart Double-click the file helloProgram.txt Copy the entire contents of the file and paste it into the helloProgram.egl file, so that you replace all of the default EGL source code Click on File -> Save or Ctrl+S to save your work Close both files Source code for the TextUIProgram: package egltui.helloworld; program helloProgram type TextUIProgram use helloGroup; function main() while (converseVar.eventKey not pf3) converse HelloWorld1; if (converseVar.eventKey is pf5) move HelloWorld1.InputField to HelloWorld2.OutputField2; set HelloWorld2.OutputField2 protect; converse HelloWorld2; end

Take a few minutes to look at the program: Line 3 – program type is TextUIProgram Line 5 – use statement enables the program to reference forms in the FormGroup Line 8 – converseVar.eventKey system variable to determine which key the user pressed Line 9 – converse statement to send/receive data from the user Lines 11 and 12 – move statement is just like move or assignment statements between records Line 13 – set statement to set certain properties (hardware attributes) More about the various statements later in the course

 Lab – Debug the EGL TextUIProgram (Step 1 of 2)
Debug the program by following these steps Right-click on helloProgram.egl Click Debug EGL Program from the pop-up menu When prompted to change to the Debug perspective, respond: YES In the Debug perspective, click the Resume button to continue debugging until the first screen appears

 Lab – Debug the EGL TextUIProgram (Step 2 of 2)
Rational Business Developer - Text User Interface  Lab – Debug the EGL TextUIProgram (Step 2 of 2) The first screen should look like this Enter something in the Input field (for example: EGL Rocks !!!) Press F5 The second screen appears and echoes what you entered Try pressing Tab Nothing happens because all the fields on the second screen are protected Press Enter to return to the first screen Notice that the Input field still has whatever you typed in it EGL preserved the information on the form for you What happens if you press any other function key for the first screen? Function key F3 ends the program Any other function key just loops and redisplays the first screen without clearing the input field What happens if you press any other function key for the second screen? Any other function key or Enter always returns to the first screen, without clearing the input field There are various alternatives for coding an application such as this. We chose to code helloGroup as two separate forms to illustrate the capability to have multiple forms in one FormGroup used by one program. Another alternative is to use one form and set properties at runtime to hide, show, protect, or unprotect the input and output fields. We will do this in another lab. Also, it is a simple exercise to generate this application to Java and deploy it to Windows on the workstation. If you want to do this, see the course appendix for an optional lab.

Hello World: Checkpoint – Let’s Review
Rational Business Developer - Text User Interface Hello World: Checkpoint – Let’s Review Objective: Create two forms in the same form group Created helloGroup FormGroup Created HelloWorld1 Text Form using the EGL Text Form Editor Added a few fields to the form Tried a few things in the Text Form Editor Created HelloWorld2 Text Form by copying the source code from the notes section of the slides (keeps the lab simple) Objective: Create a simple program that converses the two forms Created the HelloProgram TextUIProgram by copying the source code from the notes section of the slides (keeps the lab simple) Converse HelloWorld1 When user presses F5 on HelloWorld1, move data to HelloWorld2 converse HelloWorld2 When user presses Enter on HelloWorld2, converse HelloWorld1 Debug HelloProgram TextUIProgram The text forms are essentially just data – information about the fields, the position of the fields, and the validation and formatting of the fields. EGL generation and runtime deal with this information about the fields on the forms – including handling a lot of logic under the covers for you. The TextUIProgram contains all your the business logic. We will talk later and have labs to show the things EGL does for you automatically, but it includes things like: Automatically reconversing the screen if there is a validation error Moving a message to the screen if there is a validation error Automatically displaying help if the user requests help (you still have to provide the help screen and tell EGL which help screen goes with your form!!!) TextUIProgram HelloProgram.egl Use helloGroup; Function Main() converse helloWorld1; converse helloWorld2; FormGroup helloGroup.egl … Form HelloWorld1 Form HelloWorld2

Unit Summary Now that you have completed this topic, you should be able to: Define the nature and purpose of the following : FormGroup TextForm PrintForm Form Components – variable and constant fields TextUIProgram converse, display, and print statements Use the EGL Text Form Editor to create 2 simple Text UI screens Create an EGL TextUIProgram to show the screens and move data from one screen to another Debug the TextUIProgram

Unit Objectives At the end of this unit, you will be able to:
Understand some basics FormGroup and Form Floating area How a program references a FormGroup What happens during generation Set the preferences for the Text Form Editor General Palette Entries Know and understand the parts of the Text Form Editor Content Area Palette Display Options Filters Work with the Text Form Editor Create a Form Group Create and edit a Text Form Create a Text Form from a Record Create a Popup Menu Create a Popup Form Test your forms in the Debugger

What Is a FormGroup? FormGroup Collection of text and print forms Text forms can be used in a TextUIProgram Print forms can be used in a TextUIProgram or BasicProgram Forms can be Nested within the FormGroup part Included by specifying the appropriate import statement and a use formName statement (good for common forms that are needed in several form groups) FormGroup also defines properties that apply to the entire collection of forms Floating area Help function key … and so on formGroup DemoGrp {ScreenFloatingAreas = [ @ScreenFloatingArea{screenSize=[24, 80], bottomMargin=0, topMargin=0, leftMargin=0, rightMargin=0} ], helpKey = pf1} form DemoForm1 type textForm … end form DemoForm2 type printForm use CommonForm2 type textForm; end // end FormGroup Forms VAGen customers: A VAGen map group converts to an EGL FormGroup. In VAGen, the only properties for a map group were the floating areas. EGL has additional properties, which are not used in migrated code. However, you can use the FormGroup level properties in EGL code that you write or modify. In VAGen, all maps used by the map group had to be named with the map group name. In EGL, the use form statement includes a form that is outside the current FormGroup. You can use this technique to include common forms in multiple FormGroups.

What Is a Form? Form Representation of a Single 3270 / 5250 screen (or what can be displayed with a terminal emulator) Single page of printer output Portion of a screen or printer page (called a partial form) Multiple representations Design EGL source What you see in the Debugger Final screen or printer page Contains information about Properties Help key Help form Constant fields Variable fields that the program or user can change at runtime Help forms can only contain constants There are two types of forms: Text form – representation of a 3270 or 5250 screen that can be displayed on an actual terminal, monitor, or a terminal emulator. Print form – representation of printer output that can be printed on an actual printer or sent to a file for later printing. There are two types of fields on both text and print forms: Constant fields contain fixed text; cannot be changed by the user at runtime; cannot be referenced in an EGL program. Variable fields contain data that can be changed by the user or the program at runtime. VAGen customers: A VAGen map converts to an EGL form. CICS customers: A form is similar to a BMS map. For the CICS environment, EGL uses 3270 data streams rather than generating a BMS map. IMS customers: A form is similar to an MFS map. For the IMS environment, EGL generates MFS maps from the FormGroup and form definitions.

What Is a Floating Area? Floating area is the space on a form reserved for displaying repeating forms Techniques typically used for print forms Can be used for text forms Method 1 – single form using arrays Method 2 – Header form, trailer form, and a floating area with single line map that is displayed or printed repeatedly (with different data for each line) Body – Floating Area Header Trailer ScreenFloatingAreas defines an area on a screen that is reserved for displaying repeating forms; a different floating area can be defined for each screen size. PrintFloatingAreas defines the same type of information for printer output. A fixed form has a specific starting row and column in relation to the output surface of the device. You could assign a fixed form such as the Header form to start at line 1, column 1 and another fixed form such as the Trailer form to start at line 21, column 1. A floating form has no specific starting row or column; instead, the placement of a floating form is at the next unoccupied line in the floating area. You might declare a floating area to be a rectangle that starts at line 10, extends through line 20, and is the maximum width of the output device. If you have a one-line floating form of the same width, you can construct a loop that acts as follows for each of 11 times (once for each row in the floating area): Places data in the floating form Writes the floating form to the next line in the floating area A partial form is smaller than the standard size of the output surface for a particular device. You can declare and position partial forms so that multiple forms are displayed at different horizontal positions. Although you can specify the starting and ending columns for a partial form, you cannot display forms that are next to one another. Both the Header and Trailer forms in the slide are partial forms – they do not completely cover the screen. A typical scenario for a text forms is: Display partial Header form Loop to display the partial Body forms in the floating area of the screen, until the floating area is full Converse the partial Trailer form which causes EGL to build the entire screen of Header form, multiple Body forms, and the Trailer for to be sent to the user. EGL automatically waits for user input to the TRAILER form. The user cannot enter data in the Header or Body forms because they were displayed. VAGen customers: The technique for floating areas, fixed, and partial forms is the same as in VisualAge Generator.

How Does a Program Reference a Form? (Part 1 of 3)
Rational Business Developer - Text User Interface How Does a Program Reference a Form? (Part 1 of 3) To reference a form, a program must specify use declaration statement Method 1: use FormGroup1; All forms in the FormGroup are available to the program All variable fields on all forms are in the name space for the program Method 2: use FormGroup2.formA, FormGroup2.formB; Only formA and formB are available to the program – regardless of the number of forms in the FormGroup Only the variable fields on these two forms are in the name space for the program The FormGroup must be in the name space for the program If the FormGroup is in a different project, the EGL Build Path for the project that contains the program must include the project that contains the FormGroup If the FormGroup is in a different package, the program file must specify an import statement for the package that contains the FormGroup VAGen customers: Method 2 is used by the VAGen to EGL Migration Tool. This provides the same access to forms as in VAGen – only the forms you actually use within the program are listed in the use statement.

Rational Business Developer - Text User Interface How Does a Program Reference a Form? (Part 2 of 3) Program can reference a maximum of two FormGroups use FormGroup1; // contains FormA use FormGroup2 {helpGroup = yes}; // contains FormH Within the program: Reference a variable field on a form as: FormA.FieldX (the FormGroup name is not specified in any statements other than the use statement) Program converse FormA User presses Help key FormA specifies helpForm = “FormH” EGL automatically shows FormH User done with Help EGL shows FormA again Help forms can only contain constant (fixed text) fields. Help forms are for reference information only – not for entering or displaying dynamic data, so statements in your program never reference a help form directly. If a form specifies the helpForm property, then when the user requests help by pressing the help function key, EGL automatically displays the specified help form. A help form can specify its own helpForm property so that you can build a chain of help forms. When the user eventually stops requesting help, then EGL automatically displays the original form again (FormA in this example). Handling help forms is an example of the power of EGL. You do not have to code program logic to display help information; you just need to code the helpForm property and the helpKey property. If a program specifies two FormGroups, one of the FormGroups must include the helpGroup=yes property and is called the help FormGroup. EGL looks for any help forms in the help FormGroup. If a program only specifies one FormGroup, EGL looks for any help forms that FormGroup.

Rational Business Developer - Text User Interface How Does a Program Reference a Form? (Part 3 of 3) Certain properties can be specified for the Form FormGroup Program Which specification wins? Form – enables you to have special treatment for a form Others: FormGroup – general way to set all forms in the FormGroup, if not explicitly set in the individual form Program – general way to set both FormGroups for the program, if not explicitly set in the FormGroups FormGroup DemoGrp {helpKey = pf1} form DemoForm1 type textForm {helpKey = pf2, helpForm=“DemoFormH”} … end Form DemoFormH type textForm end // end FormGroup Program DemoPgm use DemoGrp {helpKey = pf3}; VAGen customers: VAGen only supported these properties at the map and program level. EGL adds the capability to also specify these properties at the FormGroup level.

What Happens When You Generate?
Rational Business Developer - Text User Interface What Happens When You Generate? Just like programs, FormGroups must be generated Usually automatic when you generate the program because the genFormGroup and genHelpFormGroup build descriptor options default to YES For Java A class for each FormGroup A class for each Form For COBOL Beyond the scope of this course Become one or more load modules Varies by Target runtime environment Text or print forms Build descriptor options VAGen customers: For COBOL generation, EGL creates the same modules for a FormGroup as in VAGen Version 4.5. EGL Java generation replaces VAGen C++ generation for Text UI programs that run in distributed environments such as Windows, AIX, and so on. The modules created for Java generation are a bit different than what is created for C++ generation.

Setting Preferences for the Text Form Editor – General
Rational Business Developer - Text User Interface Setting Preferences for the Text Form Editor – General To set overall preferences Click Window -> Preferences Expand EGL Select Text Form Editor You can change the overall appearance of the Text Form Editor Some of the screen shots in this section of the course use Background color changed to grey Font size changed to 14 To change any of the colors, click the corresponding color box and select the new color. You can still toggle Black and White mode in the Text Form Editor. If you change the Font, be sure to select a monospaced font (one whose characters are all the same width)!!! Other preferences: Highlight fields causes a border to be placed around the fields defined for a form. Show rulers causes rulers to be displayed at the left and top of the Content Area. You can also toggle the rulers on and off in the Text Form Editor. Show 4 Color Mode is useful if you define a TextForm with all the constant and variable fields using defaultColor. You can also toggle 4 Color Mode in the Text Form Editor. In 4 Color Mode, the actual color of each field is determined by other properties of the field: Protect Intensity Color protect normal blue protect bold white noProtect normal green noProtect bold red Visually demonstrate blinking fields causes fields with the blink option to be displayed as italics in the Content Area. It has no effect on the field at runtime.

Setting Preferences for the Text Form Editor – Palette Entries
Rational Business Developer - Text User Interface Setting Preferences for the Text Form Editor – Palette Entries From the Preferences window Expand EGL -> Text Form Editor Select Palette Entries Palette Entries lets you set default properties for various types of fields For example, when you drop an Input field on a Text Form, the Text Form Editor automatically sets the presentation properties specified as defaults in the Palette Entries preferences Other Palette Entries preferences let you control Default size for text and print forms Default appearance of popup screens If you have standard presentation properties for certain types of fields on your text forms, setting the Palette Entries to match those standards reduces the tedium of setting the presentation properties when you create a new text form or drop a new field onto an existing text form. So, for example if a constant title for your screens is always supposed to be blue, you can set that default color and whenever you drop a Title field on a form, the EGL Text Form Editor automatically sets the color property to blue. To restore the default settings, simply click Restore Defaults. VAGen customers: The ability to set preferences for the Palette Entries is new in EGL.

Text Form Editor – Content Area and Palette
The Palette view displays the types of forms and fields that can be created in the visual editor. The Content Area displays the graphical representation of the FormGroup and the source code for the FormGroup. You can switch between the graphical representation and the source code by clicking the Design and Source tabs at the bottom of the editor. Changes to the Source view or Design view are reflected immediately in the other view.

Text Form Editor – Properties and Outline Views
The Properties view displays the EGL properties of the FormGroup, form, or field that is currently selected in the editor. The Outline view displays a hierarchical view of the FormGroup that is open in the editor.

Text Form Editor – Display Options (Part 1 of 2)
Rational Business Developer - Text User Interface Text Form Editor – Display Options (Part 1 of 2) Display options enable you to control how FormGroups are displayed in the editor at design time. Size – drop-down list to select a new size for the form Toggle 4 color mode – switch between monochromatic and 4 color modes Toggle Rulers – shows or hides the rulers at the top and left sides of Content Area Toggle Gridlines – shows or hides a grid over the form to help in sizing and arranging fields You can set defaults for using 4 color mode and displaying the rulers in the Window -> Preferences -> EGL -> Text Form Editor preferences. Note that 4 color mode only has an effect if all variable and constant fields for the form are defined with defaultColor. If any variable or constant field on the form has a color other than defaultColor, the actual colors specified for all variable and constant fields are based on the color property. You can set the color of the gridlines in the Window -> Preferences -> EGL -> Text Form Editor preferences. Except for Size, the display options have no effect on the form at runtime.

Text Form Editor – Display Options (Part 2 of 2)
Rational Business Developer - Text User Interface Text Form Editor – Display Options (Part 2 of 2) Display options enable you to control how FormGroups are displayed in the editor at design time. Toggle Sample Values – shows or hides sample values in variable fields, which are otherwise invisible unless they have the value property specified Toggle Black and White Mode – switches the editor between black and white mode and full color mode using the default background color Zoom level – sets the magnification level of the editor Filters (see next slide) Sample values provides a quick way to see how “busy” the form is when the fields are completely filled. When you are developing a new form, using Black and White Mode (white background with black fields) can be easier on the eyes. When you need to have a better idea of how the form will appear at runtime, toggle Black and White Mode off to see the default background color with the fields in full color based on the color property. VAGen customers: Toggle Sample Values is a new capability in EGL.

Text Form Editor – Filters (Part 1 of 2)
Rational Business Developer - Text User Interface Text Form Editor – Filters (Part 1 of 2) Filters enable you to Focus on just one form Review the appearance of a popup form and its underlying form The first time you use the Text Form Editor for a FormGroup, you are prompted to set a default filter Click on the form name to see a preview of the form Select or deselect to filter the forms you want to include in the default filter The prompt for an initial setting of a default filter might occur if you create a FormGroup using the EGL Text Editor – for example, if you copy several forms from other FormGroups into a new FormGroup part. VAGen customers: You will see this Filters prompt the first time you use the EGL Text Form Editor to open an EGL FormGroup that contains multiple EGL forms.

Text Form Editor – Filters (Part 2 of 2)
Rational Business Developer - Text User Interface Text Form Editor – Filters (Part 2 of 2) If you select all the forms, they all appear in the Content Area, one on top of the other Pretty messy!!! The Filters drop down in the Display Options area enables you to Change what is included in the default filter Define new filters that are then included on the Filters list – and are available whenever you edit this FormGroup You can modify existing filters, add new filters, or remove filters that you no longer need. You can define any number of filters, but only one filter can be active at a time. Like the other Display Options, Filters only affect the presentation of the forms in the Text Form Editor; they have no effect at runtime and no effect on the EGL code that you write for a TextUIProgram.

Text Form Editor – Palette View
Rational Business Developer - Text User Interface Text Form Editor – Palette View Select – Allows you to select a field and sets focus on that field Marquee – Allows you to select multiple fields at once Text Form – Select this option to create a form that will be “conversed” on a screen Print Form – Select this option to create a form that will be sent to a printer Constant Fields – display a string of text that does not change in a form. Unlike variable fields, constant fields cannot be accessed by your EGL program logic Marquee is the same as having the Select option set and holding the Ctrl button down as you right-click the fields you want to select. The purpose of this is usually to move groups of fields around on the screen. The Window -> Preferences -> EGL -> Text Form Editor -> Palette Entries preferences enable you to set the following information: Text and print forms – default size for the form Constant fields – default color, intensity, highlight, and protect for various types of constant fields that you might use. Variable fields – default length color, intensity, highlight, and protect for various types of variable fields that you might use. Popup Form – vertical and horizontal characters to surround the form, as well as default color, intensity, highlight, and protect for the border. Variable Fields – serve as input or output data in a form. Each variable field is based on an EGL primitive or a DataItem part. Variable fields can be accessed by EGL code Templates – assist you in creating standard text form parts such as popups, records, and common forms. (More on this in the upcoming lab)

Text Form Editor – Properties
Field Level Rational Business Developer - Text User Interface Text Form Editor – Properties What about all these properties? FormGroup Level  Form Level

Text Form Editor – FormGroup Properties
Rational Business Developer - Text User Interface Text Form Editor – FormGroup Properties Explanation of properties is in the notes Alias – specifies a runtime name for the part that differs from the part name. This is useful for COBOL environments where generatable part names are limited to 8 characters. In the case of a FormGroup part, the name is limited to 6 characters. If you do not specify an alias, EGL uses the first 6 characters of the FormGroup name – which might conflict with other names in your system. HelpKey – specifies a function key that causes the helpForm that corresponds to the current form to be displayed. The helpKey for a FormGroup specifies a default for all forms in the FormGroup, but the default can be overridden on a specific form. PfKeyEquate – specifies whether the keystroke that is registered when the user presses a high-numbered function key (PF13 through PF24) is the same as the keystroke that is registered when the user presses a function key that is lower by 12. ValidationBypassKeys – specifies one or more user keystrokes that causes the EGL runtime to skip input-field validations. Validation bypass keys are typically used for function keys that indicate that the user wants to cancel or exit the program – situations in which you do not want to force the user to enter valid input. The ValidationBypassKeys property for a FormGroup specifies a default for all forms in the FormGroup, but the default can be overridden on a specific form. Floating area information: ScreenFloatingAreas – Defines the floating area used for output to a screen; each screen size can have one set of margin specifications PrintFloatingAreas – Defines the floating area used for printer output; each page size can have one set of margin specifications; deviceType indicates whether the printer is a single-byte or double-byte device Margins specify the area OUTSIDE the floating area Bidi Related Properties: BidiInput – logical or visual Orientation – specifies screen orientation; ltr or rtl – Left to Right or Right to Left NumericSwapping – yes or no; SymmetricSwapping – yes or no; related to keyboard mapping

Text Form Editor – Form Properties
Rational Business Developer - Text User Interface Text Form Editor – Form Properties Explanation of properties is in the notes Alias – specifies a runtime name for the part that differs from the part name. This is useful for COBOL environments where the form name is limited to 8 characters. If you do not specify an alias, EGL COBOL generation uses the first 8 characters of the form name. Properties for automatic EGL processing: MsgField – specifies a field on the form in which EGL can display error messages. At runtime, if EGL detects an error, it moves the EGL message to this field. If you write validation code, detect an error, and set converseLib.validationFailed(messageNumber), EGL looks up the messageNumber in the program’s message DataTable (specified by the msgTablePrefix property) and moves the message text to this field. HelpForm – (optionally) specifies the name of a corresponding help form. The help form can be in the same FormGroup or in a different FormGroup that the program specifies as the help FormGroup for the program. The advantage of a separate help FormGroup is that the help forms do not have to be loaded unless the user actually requests help. HelpKey – specifies a function key that causes the helpForm that corresponds to the current form to be displayed. The help key for a form overrides the helpKey specified at the FormGroup or program level. ValidationBypassKeys – specifies one or more user keystrokes that causes the EGL runtime to skip input-field validations. Validation bypass keys are typically used for function keys that indicate that the user wants to cancel or exit the program – situations in which you do not want to force the user to enter valid input. The validation bypass keys specified for a form override the keys specified at the FormGroup or program level. Properties controlling the position of the form on the physical device: ScreenSizes – the size of the physical devices that can display this form; you can specify multiple screen sizes. FormSize – the number of rows and columns for the form. If the form size does not completely fill the screen, this is a partial form. Position – the row and column of the upper left corner of this form. If no position is specified, this is a floating form and will be displayed in the next available row of the floating area for the physical device that is being used at runtime. IMS customers: Floating forms and partial forms are only supported for print forms – not for text forms. So do not set a ScreenFloatingAreas for the FormGroup and be sure to set Position for the text form.

Text Form Editor – Variable Field Properties (Page 1 of 6)
Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 1 of 6) Form Field Properties Specify basic information about the field Explanation of properties is in the notes FieldLen – specifies the number of single-byte characters that can be displayed in a form field. This value does not include the preceding attribute byte. For numeric fields, the value of FieldLen must be large enough to display the largest number that can be held in the field, plus (if appropriate) a decimal point, a sign, and any additional formatting characters (numeric separator, currency symbol, and so on). The default FieldLen is the number of bytes needed to display the largest number possible for the primitive type, including all formatting characters. For character fields (CHAR, DBCHAR, MBCHAR, or UNICODE), the value FieldLen for a field of type DBCHAR, MBCHAR, or UNICODE must be large enough to account for the double-byte characters and any shift-in or shift-out characters. Position – specifies the row and column of the starting position for the field on the form. Value – specifies a string literal that is used as the initial field content. VAGen customers: If you use VAGen Compatibility mode, the value is only used when displaying the form if the field has not been previously initialized; the value has no effect on the initial value of the field in storage. This matches the way VAGen treated the value for a variable field.

Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 2 of 6) Text Field Properties Only affect fields on text forms – not on print forms Explanation of properties is in the notes Cursor – specifies that the cursor is positioned in this field by default when the form is displayed or conversed. At runtime, you can change the cursor position by using the set formField cursor statement Modified – specifies that when the form is initially displayed, this field is to be treated as though the user actually entered data in the field. At runtime, you can force a field to be treated as modified by using the set formField modified statement before conversing the form. ValidationOrder – specifies the order in which the field’s validatorFunction runs in relation to the validatorFunction for any other field. The property is important if the validation of one field depends on the previous validation of another. The value is a literal integer. Validation occurs first for any fields for which you specified a value for the validationOrder property, and the items with the lowest-numbered values are validated first. Validation then occurs for any fields for which you did not specify a value for validationOrder, and the order of validation in this case is the order in which the fields are defined in the form. VAGen customers: ValidationOrder was required for every form field. This order is preserved when migrating to EGL. If you add a new field to the form and do not specify the ValidationOrder property, that field is edited last. Detectable – indicates whether a light pen can be used to cause an interrupt for the field. Protect – specifies whether the field is protected to prevent users from changing the value of the field. There are three possible values: noProtect – the user can enter data in the field. protect – the user cannot enter data in the field. When the user completely fills the field that is physically prior to this field on the form, the cursor moves to this field, but the user cannot type data into it. protect is useful if you want the user to be aware that there is no more space in the prior field. skipProtect – the user cannot enter data in the field. When the user completely fills the field that is physically prior to this field on the form, the cursor skips over this field and moves to the next field that is defined as noProtect or protect. skipProtect is useful if the prior field is always filled completely and you want the user to be able to power-type to enter data. Note: The Tab key skips both protect and skipProtect fields, but stops in noProtect fields.

Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 3 of 6) Common Field Properties Used for arrays on the form Explanation of properties is in the notes When you drop a field on the form and indicate that it is an array, you specify this group of properties to quickly place the elements of the array in a uniform pattern on the form: Columns – specifies the number of columns of array elements IndexOrientation – specifies whether the array elements are numbered across (elements 1 – 5 on row 1 of the array, elements 6 – 10 on row 2 of the array, and so on) or down (elements 1 – 5 in column 1 of the array, elements 6 – 10 in column 2 of the array, and so on) LinesBetweenRows – if the array occupies multiple rows on the form, specifies how many blank lines to leave between the rows. The default is 0. SpacesBetweenColumns – if the array occupies multiple columns on the form, specifies how many spaces to leave between the end of one column and the beginning of the next. The default is 1. VAGen customers: The properties Columns, LinesBetweenRows, IndexOrientation, and SpacesBetweenColumns are all new in EGL. For arrays that follow a uniform pattern (horizontal rows or vertical columns), the properties provide a quick way of specifying the placement of the array elements. Some forms developed in VisualAge Generator had “nonstandard” or “irregular” arrays that do not follow a uniform pattern. The elements of these arrays are specifically placed on the EGL form using notation similar to the following: WIERDARRAY char(2) [3] { position = [15,66], this [2] { position = [13,70] }, this [3] { position = [15,69] } }; You can still edit these forms with the EGL Text Form Editor.

Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 4 of 6) Formatting Properties Context sensitive based on the field type (numeric or character) Output – cause extra characters to be included in the field (sign, currency symbol) Input – cause extra characters to be stripped from the field and folding to upper or lower case Explanation of properties is in the notes General formatting properties: Align – specifies that you want a field left or right justified, centered, or just as the user entered the data. For COBOL-generated forms, center is not supported. FillCharacter – specifies what character fills unused positions in the field. The property also changes the effect of the set field full statement. The effect of this property is only at output. The default is a space for numbers, a 0 for hex items, and an empty string for character types. Masked – if set to YES, displays asterisks on the screen instead of user-entered input. For COBOL-generated forms, blanks are used instead of the asterisk. Character field formatting properties: LowerCase – if set to YES, EGL converts alphabetic, single-byte characters in user input to lower case. This property is not supported for COBOL-generated forms. UpperCase – if set to YES, EGL converts alphabetic, single-byte characters in user input to upper case. Numeric field formatting properties: Currency – if set to YES, a locale-dependent currency symbol is automatically added to the beginning of the field on output. CurrencySymbol – specifies the currency symbol that is to be used. NumericSeparator – if set to YES, indicates that a separator character is to be included in a number that has an integer component of more than 3 digits. For example, using a comma as the separator symbol, one million is shown as 1,000,000. Sign – indicates whether to display a sign and if so, in what format. The values are none, leading (in which case a sign is displayed only when the value is negative), trailing, or parens (in which case the value is displayed as a positive number and enclosed in parentheses). For COBOL-generated forms, the parens value is not supported. For a leading sign, the exact position is affected by the ZeroFormat property (except in MONEY fields). ZeroFormat – specifies how zero values are displayed in numeric fields (except in MONEY fields). This property is affected by the NumericSeparator, Currency, and FillCharacter properties. See the EGL Language Reference for details. Date and Time formatting properties: DateFormat – provides the format that EGL uses to parse or display dates. Can be used with CHAR or DATE fields. TimeFormat – provides the format that EGL uses to parse or format a TIME variable. This property is not supported for COBOL-generated forms (The TIME primitive type is not supported for COBOL-generated forms.) TimestampFormat – provides the format that EGL uses to parse or format a TIMESTAMP variable. This property is not supported for COBOL-generated forms. (The TIMESTAMP primitive type is not supported for COBOL-generated forms.) Other Formatting properties supported only for Java-generation (not COBOL generation): isBoolean – indicates that the field represents a Boolean value. For a numeric field, the value is represented as 0 (for false) or 1 (for true). For a character field, the value is represented by a word or subset of a word that is national-language dependent. In English, for example, a boolean field of three or more characters has the value YES (for true) or NO (for false), and a one-character boolean field value has the truncated value of Y or N. The specific character values are determined by the locale. Formatting properties not supported for Forms: Pattern – matches the user entered text against a specified pattern, for validation

Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 5 of 6) Presentation Properties Affect the appearance of the field on the form at runtime Explanation of properties is in the notes Color – specifies the color of a field in a text form. The following values are valid: black, blue, cyan, defaultColor (the default), green, magenta, red, white, yellow. For COBOL-generated forms, black is not supported. Intensity – specifies the strength of the displayed font. The following values are valid in forms: bold, dim, invisible, and normalIntensity (the default). For COBOL-generated forms, dim is not supported. There is another value defaultIntensity that is not supported for forms. Highlight – specifies the special effect (if any) with which to display the field. The following values are valid: blink causes the text to blink repeatedly reverse reverses the text and background colors. For example, if the display has a dark background with light letters, the background becomes light and the text becomes dark. For Java-generated forms, this value is not supported. underline places an underline at the bottom of the field. normalIntensity (the default) indicates that no special effect is to occur; specifically, no blink, reverse, or underline. There are compatibility considerations for various target environments, print forms, and text forms. Refer to the EGL Language Reference manual for details. Outline – for DBCS devices, specifies that lines are to be drawn at the edges of the field. Value values are box or any combination of left, right, over, under.

Rational Business Developer - Text User Interface Text Form Editor – Variable Field Properties (Page 6 of 6) Validation Properties Context sensitive based on the field type (numeric or character) Specify how input from the user is to be validated BEFORE being used in the program If there is an error, EGL automatically converses the form again The message you specified in the corresponding *MsgKey property or the message you specify with the converseLib.validationFailed() function in the function you coded as the validatorFunction EGL message in other situations Explanation of properties is in the notes Elementary checks occur first: InputRequired, IsDecimalDigit, IsHexDigit, MinimumInput, needsSOSI, validValues. Then validatorDataTable, followed by validatorFunction. This enables the validatorFunction to do cross-field validation. Error messages specified by the *MsgKey properties or by converseLib.validationFailed(messageNumber) must be in the DataTable with stereotype msgTable that is specified by the program’s msgTablePrefix property. If you do not specify the *MsgKey properties, EGL provides a default message. Amount of data the user must enter: Fill – indicates whether the user must enter data in each position of the field. InputRequired – indicates whether the user must enter at least some data in the field. InputRequiredMsgKey is the corresponding error message. MinimumInput – indicates the minimum number of characters that the user must enter in the field. MinimumInputMsgKey is the corresponding error message. Other validation properties: IsDecimalDigit – indicates whether to check that the input data includes only decimal digits, which are as follows: This property applies only to character fields. IsHexDigit – indicates whether to check that the input data includes only hexadecimal digits, which are as follows: abcdefABCDEF. This property applies only to character fields. TypeChkMsgKey – provides a user-defined message if the data the user enters is not of the proper type. ValidValues – indicates a single value, a single range of values, or a list of single values and ranges that must match the data entered by the user. ValidValuesMsgKey is the corresponding error message. ValidatorDataTable – specifies the name of a DataTable with the stereotype of matchValidTable, matchInvalidTable, or rangeChkTable. ValidatorTableMsgKey is the corresponding error message. ValidatorFunction – specifies the name of a function with no parameters that provides the validation for the field. The validatorFunction can perform cross-field validation. If the field is an element of an array, the validatorFunction is only called once for the entire array, so you must code the function to validate all the elements. If the function detects an error, it must request a re-converse of the form by invoking converseLib.validationFailed(messageNumber). See the EGL Language Reference for details. You can also specify either of two system functions: sysLib.verifyChkDigitMod10 or sysLib.verifyChkDigitMod11. If validation fails for one of the system functions, ValidatorFunctionMsgKey specifies the corresponding error message. Validation properties that only apply to MBCHAR fields: NeedsSOSI – if set to YES, indicates that EGL does a special check when the user enters MBCHAR data on an ASCII device. The check determines whether the input can be converted properly to the host SO/SI (Shift Out/Shift In escape codes) format. The property is useful because trailing blanks are deleted from the end of a MBCHAR string during conversion to allow the insertion of SO/SI delimiters around each substring of double-byte characters. For details, see the EGL Language Reference. Formatting properties not supported for Forms: ValidationPropertiesLibrary (this property is only used for Rich UI). VAGen customers: The VisualAge Generator edit routine converts to either a validatorDataTable or validatorFunction, based on the type of part that was specified as the edit routine. You can now have both types of validation for the same field. converseLib.validationFailed() is the EGL replacement for EZEMNO. IsDecimalDigit only applies to character fields.

Text Form Editor – Constant Field Properties
Rational Business Developer - Text User Interface Text Form Editor – Constant Field Properties Constant Field Properties Just a subset of the properties for variable fields See the explanations in the notes for the corresponding variable field properties

One File – Two Editors A FormGroup can be edited with two different editors EGL Text Form Editor Design tab Shows visual representation of the FormGroup and its forms Drag and drop development for the forms Source tab EGL source code for the FormGroup and its forms EGL Editor Useful if cloning a FormGroup or copy/pasting in a single form Which editor gets used when you double-click a FormGroup file? Default – the LAST editor you used for THAT FILE If you copied the entire file, this is the EGL Editor The one that you specifically request when opening the file: Right-click the FormGroup file, then click Open With -> EGL Editor Open With -> EGL Text Form Editor VAGen customers: After migration, the default editor for each FormGroup file is the EGL Editor. You must open each FormGroup file with the EGL Text Form Editor to switch the default editor.

Lab Overview – Work with the EGL Text Form Editor
This lab gives you a chance to work with the EGL Text Form Editor Set your preferences for the EGL Text Form Editor Create a new package Create a new FormGroup Set display options Create a new form Add constant and variable fields Set constant and variable field properties Move fields Test this form in the Debugger Drag an existing record onto a new form (Optional) More practice adding and moving fields (Optional) Create a partial form (Optional) Create and test a popup Menu (Optional) Create and test a popup Form

 Lab – Set Your Preferences for the Text Form Editor
Rational Business Developer - Text User Interface  Lab – Set Your Preferences for the Text Form Editor Click Window -> Preferences Expand EGL Expand Text Form Editor Select Palette Entries Change the Constant Field properties as follows: Title – yellow, skipProtect Column Heading – green Label – green Help – yellow Change the Variable Field properties as follows: Input – green, underline, noProtect Output – green, skipProtect Password – green, underline, noProtect Click Apply and then click OK Best practice for a development environment is to set a standard look and feel for the applications you create. Typically, a project leader sets all the preferences for EGL, exports the preferences, and then makes this file available to the rest of the team.

 Lab – Create New Package and FormGroup in a Single Step
Rational Business Developer - Text User Interface  Lab – Create New Package and FormGroup in a Single Step In Project Explorer view Right-click EGLSource Click New -> Other Expand EGL Select FormGroup Click Next In New EGL FormGroup window Set Package to egltui.demogrp Set EGL source file name to DemoGroup Click Finish The package gets created and the EGL Text Form Editor opens 1 2 3 This technique shows how to create both the FormGroup and the package that contains it at the same time. Alternatively, you could create the package first by right-clicking EGLSource and then clicking New -> Package from the pop-up menu. To open an existing FormGroup, right-click the FormGroup name in the Project Explorer, then select Open With -> EGL Text Form Editor.

 Lab – Set Content Area Size
Rational Business Developer - Text User Interface  Lab – Set Content Area Size With the Text Form Editor open, maximize the window and the editor pane. Optionally, click Zoom to change the size of the data in the Content Area. 

 Lab – Create a New Form Method 1 – Standard Size Set Size to 24 x 80
From the Palette, select Text Form Move the cursor anywhere in the Content Area Click the left mouse button Set the part name to Form1 and click OK Form1 is created with the specified size

 Lab – Some Tricks for Using the EGL Text For Editor
Rational Business Developer - Text User Interface  Lab – Some Tricks for Using the EGL Text For Editor  How you move the mouse matters!!! Drop a field On the Palette, using the left mouse button, click the type of field you want and release the button Move the mouse to where you want to drop the field (watch the position box change) Click again with the left mouse button to drop the field (position box indicates where the left-most character of the data will be placed; there must be room for an attribute byte immediately preceding the field) Sizing a constant field Immediately after clicking to drop the constant, just start typing the text The field is automatically sized for you Changing a single field With the left mouse button, click once inside the field Selection handles appear around the field The Properties view changes to show this field Position the cursor over one of the selection handles until the double-headed arrow appears; press and hold down the left mouse button; drag to shorten or lengthen the field; release the left mouse button when the field is the correct size For a constant field, click a total of 3 times with the left mouse button inside the field A vertical bar appears Start typing to change the text You’ll get a chance to practice on the next several slides The attribute byte is where the 3270/5250 hardware keeps track of the presentation properties that you set (color, highlighting, intensity, protection, and for DBCS devices, the outline property).

 Lab – Put Fields on the Form (Step 1 of 4)
 Follow the steps on the next few slides to create this screen  Things to consider: Save (Ctrl+S) periodically Edit -> Undo (Ctrl+Z) works backward to undo previous steps Edit -> Redo (Ctrl+Y) works forward to put back in what you previously undid Tailor preferences and display options to meet your needs. Hint: Click Window -> Preferences Expand EGL Select Text Form Editor Background color Font and font size … Workbench size Content Area size

Rational Business Developer - Text User Interface  Lab – Put Fields on the Form (Step 2 of 4) Drop the fields listed in the table onto Form1 What to Drop – what to select from the Palette area in the EGL Text Form Editor Field Name – an asterisk (*) indicates that this is a constant field. Position – the row and column when you drop the field. This is where the data goes. Notice that the Position in the Properties view, shows the column as 1 less than where you dropped the field. This is why you cannot drop a field at row 1, column 1. This extra byte is where the attribute byte goes at runtime. The attribute byte controls color, highlighting, intensity, and protection for both constant and variable fields. Note: The specific positions are not critical for this lab. Type & Size – For constant fields, you can automatically size the field by just typing in the constant text. The type is determined by the actual characters you type in the field (single-byte, double-byte, or mixed bytes). For both constant and variable fields, you can also size the field when you drop it with the following steps: Move the mouse to the starting position for the field Click and hold down the left mouse button Drag the mouse to the lower, right end of the field Release the left mouse button Array Information and Value Text – you need to Toggle Sample Values off to see the value that you enter. For the purposes of this lab, the specific positions of the fields do not matter. Just practice dropping fields onto the form. Tricks: If you drop a variable field and it does not appear on the screen, check the Source tab. If there is an error, with the variable positioned in row=1, column=1, delete the field in the source. Then try closing the editor and then Open With -> EGL Text Form Editor. What to Drop Field Name Position Type & Size Array information and Value Text Constant – Title * 1,15 n/a Value = “This is the screen Title Line. It is a Constant” Variable – Input Input1 10.8 char(24) Value = “Input Field” Variable – Output Output1 10,33 char(32) Value = “Output Field” (Array) See Next Slide for Info on Dropping an Array Array1 12,8 char(57) Array Size = 2, Index Orientation = Down, Fields Down = 2; Fields Across = 1 [1] Value = “Column Array, Element 1” [2] Value = “Column Array, Element 2” Variable – Message Message1 21,8 char(68) Value = “This is the Message Line”

Rational Business Developer - Text User Interface  Lab – Put Fields on the Form (Step 3 of 4) To Drop an Array Click the left mouse button to drop the upper left corner of array element 1 Fill out the New Variable Field like normal, BUT… Select Array and click Next Fill out the Array Properties window and click Finish The EGL Text Form Editor automatically places the elements of the array based on your specifications. Arrays are only single-dimension arrays, but can be placed in row/column format, with the indexes numbered across or down.

Rational Business Developer - Text User Interface  Lab – Put Fields on the Form (Step 4 of 4) Now that you have created all the fields, let’s take a look: Toggle Black and White Mode so that fields are displayed in color Toggle Sample Values so that values are displayed in all the variable fields Notice Defaults for various types of constants and variables match the defaults you set in the Window -> Preferences -> EGL -> Text Form Editor -> Palette Entries preferences Title is yellow Input field is green, with underline and noProtect Output field is green, with skipProtect Message field is red and bold Array elements are numbered based on the index orientation In the Content area click one element of the array and then look at the Properties view to see the element number

 Lab – More Tricks for Using the EGL Text For Editor (Slide 1 of 4)
Rational Business Developer - Text User Interface  Lab – More Tricks for Using the EGL Text For Editor (Slide 1 of 4)  Several techniques to select ONE field Select one constant or variable field In the Palette view, click on Select Technique 1 – use the Outline view Select the field name Technique 2 – use the Content Area Then click on the field With either technique: The Content Area is updated to show the selection handles around the field The Outline view is updated to show the field that is selected The Properties view changes to show the information for the selected field

Rational Business Developer - Text User Interface  Lab – More Tricks for Using the EGL Text For Editor (Slide 2 of 4)  Several techniques to select MULTIPLE fields Select multiple constant or variable fields Technique 1 – use the Outline view Click on Select and then select the first field Hold down the Ctrl key and select the remaining fields Technique 2 – use the Content Area Click on Select and then click on the first field Hold down the Ctrl key and then click on the remaining fields Technique 3 – use the Content Area Click on Marquee Move the mouse into the Content Area until the cross hairs appear; then continue moving the cross hairs to the upper left corner of the group of fields you want to select and press and hold down the left mouse button Drag the cross hairs to the lower right corner of the group of fields you want to select and release the mouse With any of the techniques: The Content Area is updated to show the selection handles around the fields The Outline view is updated to show the fields that are selected The Properties view changes to show the information for one of the selected fields

Rational Business Developer - Text User Interface  Lab – More Tricks for Using the EGL Text For Editor (Slide 3 of 4)  Combining techniques Make the first selection in one of the following ways: From the Outline, select the first field From Content Area, select the first field From the Content Area, select Marquee and then draw the first bounding box Hold down the Ctrl key If necessary, switch selection mode If previously used Marquee and want to release, select Select on the Palette If previously used single selection and want to use Marquee, select Marquee on the Palette Make additional selections in any of the following ways From the Outline, select the next field From Content Area, select the next field From the Content Area, draw the next bounding box for Marquee selection You’ll get a chance to practice in a few minutes Which selection mode? Where to select from? Answer: It depends on what you want to do; Use whichever method is easiest

Rational Business Developer - Text User Interface  Lab – More Tricks for Using the EGL Text For Editor (Slide 4 of 4)  How you select an array matters!!! Select entire array In the Outline view, select the array variable All elements of the array are selected The Properties view shows all of the properties Select an element of an array In the Content Area, click with the left mouse button inside the element of the array The element of the array is selected The Properties view shows the properties that can be unique for a particular element of an array (a very limited subset) Validation and Formatting properties must be the same for all elements of the array. Presentation properties, the value property, and the modified property can be different for each element of the array.

 Lab – Change Some Properties for the Fields
Now that you have created all the form fields, let’s change some properties: Toggle Black and White Mode so that the screen shows in color “Title Line” constant Set Color = green, Intensity = bold, and Highlight = reverse As you change each property, notice how the appearance on the screen changes Input1 field (an input field) On the Validation tab, set InputRequired = yes and MinimumInput = 3 In the Outline view, select Array1 Both elements of the array are selected and you can set any of the properties On the Text Field tab, change to Protect = noProtect (essentially changing this to an input array) In the Content Area, select element 2 of the Array1 Only a limited set of properties can be set for the individual elements Change to Value = Vertical Array, Element 2 Hint: You need to Toggle Sample Values off to see the initial values for variable fields in the Content Area

 Lab – Move Some Fields Around
Rational Business Developer - Text User Interface  Lab – Move Some Fields Around Now let’s move some fields around: Single field – move the “Title Line” constant to row 2, column 14 Select the field using the left mouse button and hold the button down Drag the field to position row 2, column 14 and release the left mouse button Note: The position shows the position of the attribute byte Block of fields – move Input1 and Output1 fields so that Input1 is in row 7, column 7 Select both fields Technique 1 – select Input1, hold down the Ctrl key, select Output1, release the Ctrl key Technique 2 – select Marquee on the Palette, use the cross-hairs to draw a box around Input1 and Output1 (click the left mouse button down and hold it down to start the box and release the left mouse button when the box is complete), select Select on the Palette to end Marquee selection With the mouse positioned inside Input1, press and hold down the left mouse button Drag the fields until the Input1 field is positioned starting in row 7, column 7 and release the left mouse button Entire array – move Array1 so that element 1 is in row 9, column 7 Use the Marquee technique described above to select the entire array With the mouse positioned inside element 1, press and hold down the left mouse button Drag the fields until they are positioned one row below their original location When you are done, save and close the DemoGroup file For the purposes of this lab, the specific positions for the fields do not matter. Just practice moving the fields.

 Lab – Test Your Form in the Debugger (Step 1 of 3)
Rational Business Developer - Text User Interface  Lab – Test Your Form in the Debugger (Step 1 of 3) Create an EGL Program using the following steps Right-click the egltui.demogrp package and click New -> Program Set the program name to DemoProgram Click Text – Create a Text UI-based program Click Finish

Rational Business Developer - Text User Interface  Lab – Test Your Form in the Debugger (Step 2 of 3) Create the source for DemoProgram using the following steps: Method 1 – type the code from the Notes section below into the program Method 2 – copy/paste the code from the ZZZTUIProject_CopyPaste project using the following steps: Expand the project ZZZTUIProject_CopyPaste and the folder textFormEditor Double-click the file DemoProgram.txt Copy the entire contents of the file and paste it into the DemoProgram.egl file, so that you replace all of the default EGL source code Click on File -> Save or Ctrl+S to save your work Close both files Source code for the TextUIProgram: package egltui.demogrp; program DemoProgram type TextUIProgram {} use DemoGroup; Function main() While (converseVar.eventKey not PF3) //optionally, set Form1 empty; converse Form1; end end // end main function end // end program ** This is a good program to file away as a quick test program for other forms. Just change: FormGroup name Form name Then test.

Rational Business Developer - Text User Interface  Lab – Test Your Form in the Debugger (Step 3 of 3) Test the program in the Debugger Notice the cursor is positioned in the Input1 field Default cursor position is in the physically first variable field on the screen Try clicking F3 to end the program Message that input is required In the Input field – try entering just x and clearing the rest of the field Message that minimum input is 3 In the Input field – try entering xxx in the field This time the data is accepted Now you can click F3 to end the program Hint: To test the program, right-click the program and then click Debug EGL Program from the pop-up menu.

 Lab – Create a Form from an Existing Record (Step 1 of 7)
Rational Business Developer - Text User Interface  Lab – Create a Form from an Existing Record (Step 1 of 7) Another productive way to build a text form is to drag and drop an existing record onto a new form To keep it simple, follow these steps Create a new package: egltui.zzz.common See the notes for hints if you need help creating a new package Expand the project ZZZTUIProject_CopyPaste and the folder textFormEditor Copy the file commonRecords.txt to package egltui.zzz.common Right-click the new file in package egltui.zzz.common and click Rename on the pop-up menu Change the file type from .txt to .egl Hint: To create a new EGL package, right-click the EGLSource folder and then click New -> Package. VAGen customers: The ability to drag a record onto a form is new in EGL.

Rational Business Developer - Text User Interface  Lab – Create a Form from an Existing Record (Step 2 of 7) Again, to keep it simple, follow these steps to create a new form in DemoGroup Open DemoGroup with the EGL Text Form Editor Hint: Right-click the file and then click Open With -> EGL Text Form Editor Click on the Source tab Scroll to the bottom of the editor Expand project ZZZTUIProject_CopyPaste and the folder textFormEditor Double-click on file FormFromRecord.txt Copy the code from FormFromRecord.txt and paste it into DemoGroup.egl just before the end statement for the FormGroup Close the FormFromRecord.txt file Save your changes (Ctrl+S), but do not close the DemoGroup file end for the FormGroup Copying the initial FormFromRecord gives you a starting point for the new form. If you have a standard layout for forms, you can use this technique to copy/paste an existing form into a FormGroup and then use that form as the starting point for a new form.

Set the Filters using the following steps: Click on the Design tab Change the Filters to select just FormFromRecord Click OK to see FormFromRecord in the Content Area In the Outline view, notice that there is currently no import statement

Follow these steps to drag and drop the record From the Palette, select Record and release the left mouse button Move the cursor to upper left corner of where you want the fields to drop (row 6, column 5) Press and hold down the left mouse button and drag the cursor to the lower right corner of the area where you want the fields to drop (around row 18, column 65) When you release the mouse button the EGL Record Placement window opens (see the next slide) 1 2 3

Rational Business Developer - Text User Interface  Lab – Create a Form from an Existing Record (Step 5 of 7) From EGL Record Placement Click Browse From Select a Record Part Select CustomerRec in egltui.zzz.common/CommonRecords.egl Click OK

Rational Business Developer - Text User Interface  Lab – Create a Form from an Existing Record (Step 6 of 7) The EGL Record Placement window appears The fields from the record are shown with their type definitions (because that is what the record used) You can edit a field to change the label or length You can toggle whether the field is input or output You can add or remove fields or reorder the fields using the Up and Down buttons Select Break links with DataItems The fields in the EGL Record Placement window now show their primitive types Click Finish The advantage of breaking the links with the Data Item definitions is that this automatically sizes the variable fields and also “locks” the definitions and properties for this form. If the DisplayName property or the length or type of a field changes in the record definition, the form is not affected – so there is no chance that something that used to fit on the form no longer fits. You can make any changes you want/need to the fields on the form without affecting the record or DataItem parts. VAGen customers: Breaking the links with the DataItems provides the equivalent function as in VAGen.

Rational Business Developer - Text User Interface  Lab – Create a Form from an Existing Record (Step 7 of 7) The updated form appears All the selected fields have been included in the bounding box that you drew Specified labels are also included Save and close the DemoGroup (Optionally) Test FormFromRecord using the Debugger. Just modify DemoProgram to converse FormFromRecord.

 (Optional) Lab – More Practice with the EGL Text Form Editor (1 of 3) This optional lab provides more practice with dropping fields onto a form Hint: If you need help, see the previous slides for more detailed instructions Open DemoGroup with the EGL Text Form Editor Set the Filters to display just Form1 Add the fields listed in the table below to Form1 What to Drop Field Name Position Type & Size Array information and Value text Constant – Title * 1,2 n/a Value = “This is Another Title Line.” Constant – Label 4.8 Value = “Label Field” Constant – Instructions 5,8 Value = “Instructions Field” Constant – Help 6,8 Value = “Help Field. Note the properties for these fields” Variable – Output (Array) Array2 12,8 char(20) Array Size = 3, Index Orientation = Across, Fields Down = 1, Fields Across = 3, Spaces between columns = 5 [1] Value = “Row Array, Element 1” [2] Value = “Row Array, Element 2” [3] Value = “Row Array, Element 3” Variable –Output (Array) Array3 15,8 Array Size = 9, Index Orientation = Down, Fields Down = 3, Fields Across = 3, Spaces between columns = 5 Variable – Password PasswordField 18,8 char(15) Value = “Password Field” FKeyLine1 23,2 char(69) Value = “Function Key Line 1 – This is a Variable Field” How to read the table: Field Name – an asterisk (*) indicates that this is a constant field. Position – the row and column when you drop the field. This is where the data goes. Notice that the Position in the Properties view, shows the column as 1 less than where you dropped the field. This is why you cannot drop a field at row 1, column 1. This extra byte is where the attribute byte goes at runtime. The attribute byte controls color, highlighting, intensity, and protection for both constant and variable fields. Type & Size – For constant fields, you can automatically size the field by just typing in the constant text. The type is determined by the actual characters you type in the field (single-byte, double-byte, or mixed bytes). For both constant and variable fields, you can also size the field with the following steps: (1) move the mouse to the starting position for the field, (2) click and hold down the left mouse button, (3) drag the mouse to the lower, right end of the field, and (4) release the left mouse button. Value text – you need to Toggle Sample Values off to see the value that you enter. Note that the PasswordField has the intensity property set to invisible, so the value that you enter for the field and the sample values are not visible in the EGL Text Form Editor – just as any values the user enters will not be visible at runtime.

 (Optional) Lab – More Practice with the EGL Text Form Editor (2 of 3)
Things to try: Toggle Black and White Mode to see the colors for the various types of constants Toggle Sample Values Save the FormGroup Try the alignment tool Right-click the Title constant in row 1, column 2 Click Align -> Align to Parent -> Center The Title constant is centered on row 1 WARNING: Use the Align function with caution because it sometimes has unexpected side effects Save the form frequently (Ctrl+S) Use Edit -> Undo (Ctrl+Z) if necessary

 (Optional) Lab – More Practice with the EGL Text Form Editor (3 of 3)
Other things to try: Practice Moving fields Single field Group of fields All elements of an array Setting properties All elements of an array (for example, the validation or formatting properties) Single element of an array (for example, the color or value property) Increase the length of fields Optionally, debug Form1 using DemoProgram

 (Optional) Lab – Create a Partial Form (Step 1 of 2)
Rational Business Developer - Text User Interface  (Optional) Lab – Create a Partial Form (Step 1 of 2) Change the Filters to not show any forms using the following steps: From the drop-down list, click Filters Change the default filter so NO forms are selected Click OK Depending on which labs you did, you might see different forms in the Filters window.

 (Optional) Lab – Create a Partial Form (Step 2 of 2)
Create a partial form using the following steps: From the Palette, select Text Form Move the cursor to the upper, left row/column position for the partial form Press and hold down the left mouse button and drag to the lower, right row/column position for the partial form Release the mouse Set the part name to PartialForm and click OK PartialForm is created with the specified size and position 1 - Move 2 - Drag

 (Optional) Lab – Create and Test a Popup Menu (Step 1 of 10)
Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 1 of 10)  A popup menu is a special kind of form that you can add to a FormGroup Similar to an ordinary text form, BUT Designed to “pop up” over an underlying form so only has fields in a small area of the form Created with pre-defined features like a title, help text, and a specified number of menu options Follow the steps on the next few slides to create this popup screen VAGen customers: You could develop popup menus and popup forms in VAGen. But, they were tedious to create (especially to create the box around the borders of the popup if you wanted the popup to look pretty). The Popup Menu and Popup Form entries on the Palette view provide an easy way of creating these types of forms. IMS customers: Floating forms and partial forms are only supported for print forms – not for text forms. So, you might want to skip the optional labs on popups.

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 2 of 10) Create the Popup Menu Open the DemoGroup with the EGL Text Form Editor See the notes for hints if you need help Set your filters so that just Form1 shows On the Palette view, select Popup Menu Move the mouse to the upper left corner for the popup area Press and hold down the left mouse button and drag a rectangle that indicates the position, size, and shape of the popup menu (the lighter grey area) When you release the mouse, the Create Form Part window appears Set the form name to: PopupMenu1 Click OK Hints: To open the FormGroup, right-click DemoGroup and then click Open With -> EGL Text Form Editor. To change the filters, click on the down arrow beside defaults and then click Filters. The advantage of setting the filter to show Form1 is that you can see how the Popup Menu will overlay the data on Form1. This can help you determine where to place the Popup Menu.

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 3 of 10) In the New Popup Menu Template Enter the size (Width and Height) for the popup menu. Default is the size you created by dragging the cursor Set Menu Title to: Title of PopUp Menu Set the other fields as shown Click Finish The outline and fields for the popup menu appear over Form1 Pretty messy! Change your Filters so only PopupMenu1 shows VAGen customers: In the VAGen Map Editor you could only look at one map at a time. The EGL Text Form Editor provides the ability to see the popup menu and popup form over the top of the underlying map – so it is easier to position the popup.

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 4 of 10) Finish the popup menu Edit the existing fields Change Help text so it fits Enter a Value for the elements of VariableFormField2 (the array of option text) Add an additional Help constant field below the options Be careful not to add too much text. Use Ctrl+Z to undo your change if necessary The editor works just the same as for a bigger screen, except now you need to stay within the area of the popup menu Save and close the FormGroup file Notice that the popup menu comes pre-formatted: An outside bounding box that includes the attribute byte at the beginning of each row of the popup menu. The bounding box does not appear at runtime – it is just there for your reference during development. A constant field of dashes at the top and bottom of the popup menu and constant fields of vertical bars at the left and right of the popup menu. The dashes and vertical bars appear at runtime to make it easy for the user to see what is included in the popup window. You set (or defaulted) the Vertical Character and Horizontal Character when you set the Window -> Preferences -> EGL -> Text Form Editor -> Palette Entries preferences. The VariableFormField1 array is an array of single byte characters where the users can select the option they need. The VariableFormField2 array is an array that contains the option text. Because this is a variable array, you can set the text for the options at runtime. A bit of space at the bottom for you to add additional variable or constant fields. The size of this space varies depending on the size of the popup menu and the number of options you requested.

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 5 of 10) Create the source for DemoProgram2 using the following steps: Expand the ZZZTUIProject_CopyPaste project and folder textFormEditor Copy the file DemoProgram2.txt to package egltui.demogrp Right-click the new file in package egltui.demogrp and click Rename on the pop-up menu Change the file type from .txt to .egl Notice converseLib.clearScreen() When you use pop-ups, converseLib.clearScreen() gets rid of residual data from the pop-up before conversing any other forms package egltui.demogrp; program DemoProgram2 type TextUIProgram {} use DemoGroup; Function main() While (converseVar.eventKey not PF3) //optionally, set Form1 empty; converse Form1; if (converseVar.eventKey is PF4) PopupMenu1.VariableFormField2[1] = "Option 1"; PopupMenu1.VariableFormField2[2] = "Option 2"; converse PopupMenu1; if (PopupMenu1.VariableFormField1[1] is cursor) Form1.Output1 = PopupMenu1.VariableFormField2[1]; end if (PopupMenu1.VariableFormField1[2] is cursor) Form1.Output1 = PopupMenu1.VariableFormField2[2]; converseLib.clearScreen(); end // end if for eventKey is PF4 end // end while for eventKey not PF3 end // end main function end // end program

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 6 of 10) Debug DemoProgram2 On Form1 Tab to the Input field Type xxxxx in the Input field (VariableField1) to meet the minimum input requirement Press F4 to see PopupMenu1 On PopupMenu1 Position the cursor by Option 2 Press Enter Form1 should show “Option 2” in the Output Field (VariableField2) Press F3 to end the program BUT the underlying Form1 is not shown beneath the PopupMenu1! A BUG!!!

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 7 of 10) There are a couple of tricks necessary to show the underlying form Change PopupMenu1 to a floating form Open DemoGroup with the EGL Editor See the notes for hints if you need help Find PopupMenu1 Change the form properties as shown on the slide Save and close the FormGroup file Open DemoGroup with the EGL Text Form Editor Set the filters to show just PopupMenu1 Notice that PopupMenu1 is now in the upper, left corner Not exactly what we had in mind, but let’s see what happens when we debug New PopupMenu1 form properties: { FormSize = [24,80], screenSizes = [[24,80]] } Notice that there is no position property – this makes the PopupMenu1 a floating form. Hints: To open the DemoGroup with the EGL Editor, right-click the file and click Open With -> EGL Editor. To open the DemoGroup with the EGL Text Form Editor, right-click the file and click Open With -> EGL Text Form Editor.

Debug DemoProgram2 again On Form1 Tab to the Input field Type xxxxx in the Input field (VariableField1) to meet the minimum input requirement Press F4 to see PopupMenu1 On PopupMenu1 Position the cursor by Option 2 Press Enter Form1 should show “Option 2” in the Output Field (VariableField2) Press F3 to end the program Now we see the underlying Form1, but PopupMenu1 is in the wrong position Still a BUG!!!

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 9 of 10) Change the position of PopupMenu1 Open DemoGroup with the EGL Text Form Editor See the notes if you need help Set the Filters to just show PopupMenu1 From the Palette, select Marquee Create a box around the entire PopupMenu1 From the Palette, select Select With the cursor positioned INSIDE the first row of the popup box, press and hold down the left mouse button and drag the entire PopupMenu1 box to the new location (around row 4, column 19 for the upper left corner) Hint: This only works if the cursor is positioned on a field with selection handles within the box; positioning the cursor near the upper left corner of the popup box works best Release the mouse Save and close the DemoGroup file Hints: To open the DemoGroup with the EGL Text Form Editor, right-click the file and click Open With -> EGL Text Form Editor.

Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Menu (Step 10 of 10) Debug DemoProgram2 again On Form1 Tab to the Input field Type xxxxx in the Input field (VariableField1) to meet the minimum input requirement Press F4 to see PopupMenu1 On PopupMenu1 Position the cursor by Option 2 Press Enter Form1 should show “Option 2” in the Output Field (VariableField2) Press F3 to end the program Now we see the underlying Form1, and PopupMenu1 is in the right position!!! See Notes for one more “trick” Actually there is one additional “trick” that is required…. After returning from PopupMenu1 and before conversing Form1 again, the converseLib.clearScreen() function is required to clear out any residual data from PopupMenu1. VAGen customers: The VAGen SET map PAGE statement for a display map converts to the EGL converseLib.clearScreen() system function.

 (Optional) Lab – Create and Test a Popup Form (Slide 1 of 2)
Rational Business Developer - Text User Interface  (Optional) Lab – Create and Test a Popup Form (Slide 1 of 2) A popup form is similar in concept to a popup menu. However, the body of the menu has a 1-byte selection field for each row, followed by the data. In a popup form, you can control the number and size of each section, as well as the constants and variable fields in the sections. To create a popup form, follow these steps: Open the DemoGroup with the EGL Text Form Editor Set the Filters so no forms are currently shown From the Palette view, select Popup Form Click and drag a rectangle that indicates the size and shape of the popup form. The Create Form Part window opens In the Create Form Part window: Specify the name for the form: PopupForm1 Click OK. The New Popup Form Template window opens In the New Popup Form Template window (see next slide): Specify the characters to use for the form’s borders in the Vertical Character and Horizontal Character fields Specify other properties for the border by selecting the Color, Intensity, and Highlight properties In the Popup Sections, repeat the following steps for each section that you want to include in the Popup Form Click Add. The Create Popup Form Section window appears. In the Create Popup Form Section window, enter a Section Name and the Number of Rows for the section. Do not specify a number greater than the Remaining Effective Rows, which is displayed at the bottom of the New Popup Form Template window. Click OK. Use the Up and Down buttons to change the order of the sections When you have finished adding the sections to the popup form, click Finish. The new popup form is created in the editor. Add any fields you need to the popup form The rest of the processing and programming is similar to that for a Popup Menu Be sure to save and close the FormGroup and program files before trying to debug Popup Forms can be useful for displaying field-level help, instructions, and so on. Save time by using the following technique: Use the Text Form Editor to drop the Popup Form at row 1, column 1. Use the EGL Editor to change the Popup Form properties (which would move any form to row 1, column 1). Use the Text Form Editor to set the Filters to show both the Popup Form and Form1; be sure to have the Popup Form on top. Use Marquee selection to surround the Popup Form then select and drag the Popup Form to the final location. Set the filters to show just the Popup Form and complete the form layout with constant fields, variable fields and their properties.

 (Optional) Lab – Create and Test a Popup Form (Slide 2 of 2)
New Popup Form Template Corresponding Popup Form

Unit Summary Now that you have completed this topic, you should be able to: Understand some basics FormGroup and Form Floating area How a program references a FormGroup What happens during generation Set the preferences for the Text Form Editor General Palette Entries Know and understand the parts of the Text Form Editor Content Area Palette Display Options Filters Work with the Text Form Editor Create a Form Group Create and edit a Text Form Create a Text Form from a Record Create a Popup Menu Create a Popup Form Test your forms in the Debugger

Unit Objectives The purpose of this unit is to bring together the material from the EGL Foundations course and the material from the earlier sections of this Text User Interface course At the end of this unit, you will be able to: Understand Use of Data Access Libraries Typical Development Issues Naming Conventions Typical Organization for Text UI Source Code Create and debug a Text UI application system Create a Logon Screen Create a Menu Screen Create a Customer Detail Screen Create a Customer List Screen Create a Customer Orders Report Understand techniques for dealing with “end user think time”

UNIT RBD/EGL Text UI Programming Topics: Overview of Text UI systems Create a Logon screen Create a Main Menu Create a Customer List screen Create a Customer Detail screen Create a Customer Orders report

Text UI Application Programming – The Screen Flow
Rational Business Developer - Text User Interface Text UI Application Programming – The Screen Flow Your Next Text UI Application: XYZ Company – what the user wants to see 1 - List 2 - Detail Cursor Position and F5 F4 Starting Position + Enter Insert, Select, Update, Delete This is a small online system with a logon screen, a menu, a customer list, and a customer detail screen. There is also a batch report. The red arrows show the transfer from one program to another. For example, Option 2 on the menu takes you directly to the customer detail screen. The customer detail screen can loop to handle insert, select, update, and delete processing. Valid logon: UserID = a; Password = a Other function keys to test: F2 – return to Menu (or in the case of the menu, return to the Logon screen) F3 – exit

Text UI Application Programming – The Architectural View
Rational Business Developer - Text User Interface Text UI Application Programming – The Architectural View Your Next Text UI Application: XYZ Company – what programs you need Logon Main Menu Customer List Customer Detail Screens the User Sees Customer Orders Report Customer Library Siteuser Behind the Scenes: Data Access Libraries Similar to Data Access Libraries in the Foundations Course – just a few more functions Orders Just like for any programming language, what the user wants to see needs to be translated into an architecture of how various programs interact. In this case, just like with the Foundations course, the database access is in libraries that can be easily used by any program in the system. We’ve just added a few extra functions for this Text UI course.

Text UI Application Programming – Typical Program Architecture
Rational Business Developer - Text User Interface Text UI Application Programming – Typical Program Architecture Similar to EGL\JSF programs in the Foundations course, EGL Text UI programs typically have A Display part (the Form Group) A Controller part (the Text UI Program) One or more Data Access parts for database I/O (the Data Access Libraries) For example: for the Logon program xyzLogonProgram.egl xyzLogFormGroup.egl SiteuserLib.egl (TextUIProgram – Logic) (FormGroup – User Interface) (Data Access Library) For COBOL generation, the names used for Programs are limited to 8 characters and the names used for FormGroups are limited to 6. If the name is longer, EGL automatically truncates the name to the required length during generation. For example, for the xyzLogonProgram and xyzLogFormGroup, the COBOL names are XYZLOGON and XYZLOGxx respectively, where xx varies based on the type of module that COBOL generation produces for the FormGroup when generating for a particular target runtime environment. You can specify runtime names by setting the alias property for the program and/or the FormGroup part. The advantage of using short names for the parts is that the name of the source code file matches the runtime name in the COBOL environments. There is an additional (small) runtime performance improvement in the COBOL environments if you use short names. The obvious disadvantage of using short names for the parts is that the source code is less readable. Because we are using data access libraries similar those from the foundations course, we use longer names for the libraries. VAGen customers: In VAGen the program name and the load module name had to match – there was no alias property (or default of truncating the name to just 8 characters). Similarly for map group and table names. The alias property is new for EGL. In the migrated EGL source code, the original VAGen names are used for the program and FormGroup parts.

XYZ Company Application System
Rational Business Developer - Text User Interface XYZ Company Application System The XYZ Company Application System is a realistic example of an application that uses many of the functions and capabilities of EGL in a Text User Environment. The application consists of: Online portion: a logon screen, a main menu, a list, and a detail screen Batch portion: a printed report At the beginning of each section we will discuss the details of the program and how to create it. There are however, other aspects of Text UI development to keep in mind as you do the labs for this unit. Naming Standards Reusability Source Code Management Development Methodology Transfer of Control and Session Management There are some aspects of Text UI Development that you need to consider prior to and during the creation of an application system Naming Standards. If you can create an application system with a meaningful naming standard, you have won half the battle in terms of productivity. In Text UI programming you should name the programs, form groups, and data access programs in such a way that you can copy a program easily without having to do major structural changes. This helps you get a new program up and running in minutes instead of hours. For example, if a program and its parts are named in such a way that you can change the first 5 characters of the program and form group and then make minor changes needed for the specific use of the new program, imagine how quickly you could implement the whole application. Reusability. This is not a new concept. As you build a new application, you should move common modules into a common package or even a whole different project. In the case of the XYZ Company, we have already structured the Data Access into Libraries – just like you did in the Foundations course. Source Code Management. How would you manage this code in a Team environment? This is an advanced topic that we do not cover in this course. We do provide some suggestions for typical organization of Text UI source code. Development Methodology. How effectively you use Rational Business Developer and EGL helps determine how successful you will be in your project. Transfer of Control and Session Management. Do you call a program or transfer to another program and not keep the previous program in memory? What about the data you are collecting from the user? Do you store it in the database immediately or navigate through several screens and then if all is good store and commit it to the database at one time?

Naming Conventions – Part name versus the Runtime Name
Different runtime environments have different restrictions on the runtime name Java – No restriction If alias property is specified, it is used to generate the runtime name COBOL – varies by part type and runtime environment If alias property is not specified, part name is truncated to the required length Program – zSeries – maximum of 8 iSeries – maximum of 7 for a main program and 8 for a called program Library – maximum of 8 Service – maximum of 7 DataTable – maximum of 7 FormGroup – maximum of 6 Multiple programs are generated, characters 7 and 8 indicate which of the programs related to the FormGroup; for IMS environments, characters 7 and 8 are used by IMS Form – maximum of 8 DL/I records and PSBRecords – can use long names and then use properties like segmentName, dliFieldName, defaultPSBName, pcbName, and secondaryIndex to give the name that corresponds to the information in the IMS PSB that is used at runtime

TradeOff – Long Name versus Short Name
Rational Business Developer - Text User Interface TradeOff – Long Name versus Short Name No one solution is right for everyone Generally site standards dictate the naming conventions Long Name More meaningful Easier to train a new person Minimize / avoid duplicate truncated names by explicitly coding the alias property Might require linkage options part to provide alias if called or transferred to programs are not in the workspace during generation (or during debug if calling a program on the host) Short Name Easier to match to the runtime environment Name of program itself Name of program called or transferred to No concern about two long names being truncated to the same short name Easier to find the program if called in in the middle of the night

XYZ Company Application System – Naming Conventions
Rational Business Developer - Text User Interface XYZ Company Application System – Naming Conventions Requirements Must generate both Java and COBOL Include FormGroup and Program as part of the name as an education aid Goals Want long names for Java (so cannot use the alias property) Must have short names for COBOL Easy to copy and modify an existing program to create a new program Compromise Use carefully chosen long names so that the names are valid in COBOL without having any duplicates, but allow room for expansion if extend the course Examples: xyzLogFormGroup – COBOL name is XYZLOG xyzLogonProgram – COBOL name is XYZLOGON xyzCL1FormGroup – COBOL name is XYZCL1 (number used in case add more list programs to the course) xyzCustListProgram – COBOL name is XYZCUSTL (yes, will have to do something different here if add more list programs – so not every goal was achieved) The “copy” goal might not be achieved as well as it could be if a different naming convention was used Consider the following example for the “copy” goal. The xyzLogonProgram uses Logon both as part of the program name and also as the name of the form. So just changing logon, can result in unintended and unfortunate side effects. Therefore, before you finalize your naming conventions, it is important to try out your proposed naming conventions with a few standard tasks that you might need to do such as copying a program and its associated FormGroup.

XYZ Company Application System – Organizing the Source Code
For Web (JSF) development, it is typical to have: Web pages (the JSPs) in the WebContent folder JSFHandler in a different package Reasons: You need the WebContent structure when you deploy The person doing the logic is not always the person who “beautifies” the page For Text UI development, it is more typical to have: Program and FormGroup in the same package More likely to generate COBOL – and the project/package structure does not matter (nor even exist) for the COBOL environments More likely that the same person does both the logic and the screen design – because much less room and no graphics to permit “artistic expression”. Usability is still very important because there is so little space available on a screen. So, with this in mind, let’s build the package structure for the XYZ Company application system

 Lab – Create the Package Structure for the XYZ Company System
There are 5 programs, so create 5 packages In EGLTUIProject, create the following packages: egltui.logon egltui.menu egltui.opt1.custlist egltui.opt2.custdetail egltui.opt3.report Hint: Right-click EGLSource and then click New -> Package We already have a package egltui.zzz.common for anything new we develop that needs to be shared by the programs

 Lab – Create a Common Record
Rational Business Developer - Text User Interface  Lab – Create a Common Record Just from looking at the screen flow, there is already some common data that needs to be passed from one program to the next The user name needs to be passed from the Logon screen to the Menu Notice the Welcome, userName on the Menu The selected customer name needs to be passed from the List to the Detail So the Detail program can pre-fill the screen before conversing it the first time Follow these steps to create the xyzTransferData record: Expand the egltui.zzz.common package Double-click on commonRecords.egl Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Double-click on xyzCommonData.txt Copy the code from xyzCommonData.txt and paste the code into commonRecords.egl, immediately after the package statement Save and close the commonRecords.egl file and the xyzCommonData.txt file We might need more fields later, but at least this gives us a start!

What Does the Logon Program Look Like? (Slide 1 of 4)
Typical EGL program: Import statements Record declarations Declarations for other variables Use declaration statements FormGroup and the form within it Library used for data access Main function Initialization – both of fields in the program and fields on the form xyzLogonProgram.egl

Typical Text UI while loop Loop forever, conversing the form Check the function keys to see what the user wants Exit at user request Validate the data Basic validation Coded here in the program Could use validation properties for InputRequired or MinimumInput More extensive validation in ValidateLogon Database access for final validation If everything is good, transfer to next program (currently commented out because the Menu program does not exist yet)

More extensive validation in the ValidateLogon function Counts invalid attempts and blocks further access if more than 3 Uses SiteuserLib to verify that the user ID is valid Also uses SiteuserLib to verify that the password is valid Could check both in a single SQL call, but then could not distinguish between invalid user ID and invalid password

Rational Business Developer - Text User Interface What Does the Logon Program Look Like? (Slide 4 of 4) Looks like lots of EGL programs, but some special Text UI statements: converse login; // converse the form name Sends the form to the user and waits until the user responds Formats any data (removes currency symbol and so on) Does EGL validation based on validation properties you specify Simple validation – InputRequired, MinimumInput, and so on validatorDataTable validatorFunction If validation fails – EGL automatically converses the form again and displays the message in the field identified on the form by the msgField property If validation passes – EGL gives control to the statement after the converse if (converseVar.eventKey is PF3) // what key did the user press? converseVar.eventKey enables you to determine which PA key, function key, or Enter that the user pressed to send a response for the converse set login.userName cursor; // where to place the cursor? Enables you to specify at runtime which field on the form to position the cursor in

Text Forms – I/O Statements
Rational Business Developer - Text User Interface Text Forms – I/O Statements display formName; Adds the form to the group of forms that will be sent at the next converse Can have multiple display statements followed by one converse statement Use can only enter data on forms that are conversed – not on displayed forms Use for partial or floating maps (for example, display a 2-line header form, display several 1-line body forms in the floating area, and then converse the trailer form) converse formName; Adds the form to the group of forms that will be sent Sends the accumulated forms to the user and waits until the user responds Processes user input for the conversed form as described on previous slide show formName returning to targetName passing basicRecordVariable; Sends the form to the terminal When user responds, start the program named by targetName Data from formName goes to the form specified by the target program’s inputForm property Data from basicRecordVariable goes to the record variable specified by the target program’s inputRecord property VAGen customers: The VAGen XFER with map converts to the EGL show form statement. The VAGen First Map property for a program converts to the EGL inputForm property. The VAGen primary working storage record converts to the EGL inputRecord property.

Text Forms – SET Statement
Rational Business Developer - Text User Interface Text Forms – SET Statement set formName alarm – sound an alarm when sending to the screen empty – resets fields to their initial values based on data type or value property; does not affect the attribute bytes initial – like empty, but also resets attributes of fields (color, highlight, intensity, and protect) to their defined value set textFormField – group 1 (any combination of the following) cursor – places the cursor in the field; most recent set cursor statement “wins” full – causes asterisks or the fillCharacter to completely fill a blank or empty field on output to the screen normal – sets the field normalIntensity, unmodified, unprotect initialAttributes -- resets attributes of fields (color, highlight, intensity, and protect) to their defined value Note: normal and initialAttributes are mutually exclusive set textFormField – group 2 (any combination of the following) color – defaultColor, blue, green, magenta, red, cyan, yellow, white extendedHighlight – noHighLight, blink, reverse, underline modified – flag the field as though the user typed data in the field, regardless of whether the user actually did intensity – bright, invisible protection – protect, skip VAGen customers: The VAGen statement SET form CLEAR converts to the EGL statement set form initial. The VAGen statement SET textformField DEFINED converts to the EGL statement set textformField initialAttributes. The VAGen colors PINK and TURQuoise convert to the EGL colors magenta and cyan respectively. The VAGen intensities BOLD and DARK convert to the EGL intensities bright and invisible respectively. In VAGen compatibility mode, the EGL value property does NOT set the initial value of the field in storage. The value property is only used if the form is displayed or conversed without first moving data to the form field. This is consistent with VAGen behavior. The VAGen SET map PAGE statement does not convert to an EGL set statement. Instead SET map PAGE converts to converseLib.clearScreen() for a text form or to converseLib.pageEject() for a print form.

Text Forms – Conditional Expressions
Rational Business Developer - Text User Interface Text Forms – Conditional Expressions (converseVar.eventKey is … ) or (converseVar.eventKey not … ) enter bypass – any of the keys specified by the validationBypassKeys property or any of the PA keys pa1 through pa3 pf1 through pf24 pakey – one of the pa keys was pressed pfkey – one of the pf keys was pressed (formName is … ) or (formName not … ) modified – was any field on the conversed form modified by the user (or set modified before the converse) (textFormField is … ) or (textFormField not … ) blanks – does a character field contain only blanks cursor – was cursor positioned in the field when user pressed a key to send data to program data – does the field contain any non-blank or non-null characters modified – was the field modified by the user (or set modified before the converse) numeric – does a character field contain only numeric digits Also for a text form field: converseLib.fieldInputLength(textFormField) – contains the length of the data entered by the user PA keys are always considered to be validationBypassKeys. VAGen customers: The VAGen statement TEST mapField nnn converts to the following in EGL: customer_PrefixEZE_ITEMLEN = converseLib.fieldInputLength(formField); if (customer_PrefixEZE_ITEMLEN is nnn) Where: customer_Prefix is the renaming prefix that you specified during migration. The VAGen to EGL Migration Tool adds the definition of customer_PrefixEZE_ITEMLEN to every program that you migrate.

Lab Overview – Create the Logon Screen and Program
The steps to complete the Logon Screen are as follows: The Data Access parts are already created for you The Logon Program uses the Siteuser table Create the Logon FormGroup Copy and paste the FormGroup from the ZZZTUIProject_CopyPaste project Create the Logon program Copy and paste the program from the ZZZTUIProject_CopyPaste project Test the Logon program in the Debugger Enter user a, password a, expect success Enter user a, password b, expect fail and redisplay with message Enter user b, password a, expect fail and redisplay with message Enter user b, password f, expect fail and redisplay with message Try other Function keys Press F3

 Lab – Create the Logon Screen
Rational Business Developer - Text User Interface  Lab – Create the Logon Screen Follow these steps to create the xyzLogFormGroup: Expand the project ZZZTUIProject_CopyPaste and the folder xyzSystem Copy the file xyzLogFormGroup.txt to package egltui.logon Right-click the new file in package egltui.logon and click Rename on the pop-up menu Change the file type from .txt to .egl Open xyzLogFormGroup.egl with the EGL Text Form Editor to get a better picture of what the screen looks like Close the EGL Text Form Editor Hints: To open the xyzLogFormGroup.egl file with the EGL Text Form Editor, right-click the file and then click Open With -> EGL Text Form Editor. Toggle sample values to fill in all the fields on the screen.

 Lab – Create the Logon Program
Rational Business Developer - Text User Interface  Lab – Create the Logon Program Follow these steps to create the xyzLogonProgram: Expand the project ZZZTUIProject_CopyPaste and the folder xyzSystem Copy the file xyzLogonProgram.txt to package egltui.logon Right-click the new file in package egltui.logon and click Rename on the pop-up menu Change the file type from .txt to .egl Edit the xyzLogonProgram.egl file Comment out the transfer to program statement that is in error (because the Menu program does not exist yet) Save and close the xyzLogonProgram.egl file …. ….

 Lab – Debug the Logon Program
Rational Business Developer - Text User Interface  Lab – Debug the Logon Program Test the Logon program in the Debugger Enter user “a”, password “a” Expect success Screen just converses again because we commented out the transfer statement Enter user “a”, password “b” Expect fail and redisplay with “Invalid password” Enter user “x”, password “b” Expect fail and redisplay with “Invalid user ID” Enter user “c”, password “b” Enter user “b”, password “f” Expect fail and redisplay with message Try other function keys Press F3 to exit What if you get an error? Set a breakpoint at the beginning of the xyzLogonProgram.egl and test again, stepping through the program.

What Does the Menu FormGroup Look Like? (Slide 1 of 2)
Rational Business Developer - Text User Interface What Does the Menu FormGroup Look Like? (Slide 1 of 2) Multiple forms Chaining of Help screens Menu helpForm points to Help1 form Help1 helpForm points to Help2 form When the user is on the Menu and presses F1 (the helpKey for the Menu form), EGL automatically displays Help1 If the user then presses F1 again (the helpKey for the Help1 form), EGL automatically displays Help2 When the user presses any key at this point, there are no more help forms in the chain, so EGL automatically converses the Menu again The help forms can be in the same FormGroup as the corresponding form as shown in the Menu FormGroup. However, Best practice generally places the help forms in a different FormGroup, which the program specifies by including the helpGroup=yes property on the use declaration for the help FormGroup. The advantage of using a separate help FormGroup is that the module size for the main FormGroup is smaller and the help forms are only loaded when the user actually requests help – which typically becomes less frequent as the user becomes familiar with the application.

What Does the Menu FormGroup Look Like? (Slide 2 of 2)
Rational Business Developer - Text User Interface What Does the Menu FormGroup Look Like? (Slide 2 of 2) Multiple forms ValidationBypassKeys The MenuOption field specifies ValidValues for the input data and also specifies InputRequired=yes BUT, what if the user wants to exit or cancel the program? ValidationBypassKeys to the rescue! If the user presses either F2 or F3, EGL skips all the validation for the form, your program gets control at the statement after the converse, and you can code the logic to exit or cancel the program

What Does the Menu Program Look Like?
Transferring data into a program inputRecord property defines a record that this program expects to receive as input on startup If record is not passed from the transferring program, EGL initializes the fields in the record based on the data types Transferring data to a program transfer to program statement does exactly what it sounds like – transfers to the next program without expecting to return Specify the program name Maximum of one record that can be passed Depending on the runtime environment, there might be size restrictions on the record (normally around 32K) In this case if the user presses F2, the program transfers back to the Logon program From the Logon Program Back to the Logon Program

Transferring Data into the Menu Program
Rational Business Developer - Text User Interface Transferring Data into the Menu Program Typical initialization EGL automatically puts the transferred record into the record variable specified by the program’s inputRecord property Then the data can be used to set values for the form before conversing the form In this case, the Logon program saved the user name in the transferData record so that the Menu program can show: Welcome, userName … The word “Welcome” is hard-coded on the Menu form.

Transfer of Control between Programs
Rational Business Developer - Text User Interface Transfer of Control between Programs call – wait for called program to return (like a call in other languages) Control passes to the called program; current program waits for called program to return and then resumes processing at the statement after the call Multiple parameters are permitted; called program receives parameters in its parameters list Some environments restrict to maximum of 30 parameters Can be record variables, variable data items, or forms Can call a program on the local system or, for runtime environments like Java or CICS, can call a program on a remote system Can call an EGL or non-EGL program transfer – transfer control with no expectation of return Transfer-to program can transfer back to the original program, but control goes to the top of the original program, not to the statement after the transfer One record can be passed; record is sent to the transfer-to program and placed in the record specified by that program’s InputRecord property Can only transfer to a program on the local system Can transfer to an EGL program; ability to transfer to non-EGL program varies with environment Two types of transfer: transfer to program – target of the transfer is always a program name; generally a commit point does not occur transfer to transaction – target of the transfer generally is a program name, but for CICS and IMS/VS, the target is the CICS or IMS transaction ID; for CICS and IMS/VS a commit point always occurs; for other environments, setting the build descriptor option syncOnTrxTransfer=“YES” causes a commit point show – combination of converse and transfer to transaction; no expectation of return Transferring program sends the form to the terminal; when user responds, the form is sent to the transfer-to program and placed in the form specified by that program’s InputForm property Transfer-to program starts at the top of the program vgLib.startTransaction() – starts an asynchronous program Current program continues processing Asynchronous program might start immediately or wait until some other event occurs depending on the runtime environment To indicate that a program is non-EGL, use one of the following techniques: call "XXX" (parameterList) {isExternal = yes}; isExternal=yes on the call, transfer, or show statement indicates that the program is non-EGL. The advantage of this technique is that the information is always there, right in the program. Linkage table entry specifying that the called or transferred to program is non-EGL VAGen customers: VAGen DXFR statement migrates to EGL transfer to program statement VAGen XFER without a map migrates to EGL transfer to transaction statement VAGen XFER with a map migrates to EGL show statement

Lab Overview – Create the Menu Screen and Program
The steps to complete the Menu Screen are as follows: No data access required Create the Menu FormGroup Copy and paste the FormGroup from the ZZZTUIProject_CopyPaste project Create the Menu program Copy and paste the program from the ZZZTUIProject_CopyPaste project Change the Logon program – remove the comment on the transfer statement Test the Menu program in the Debugger Logon – user a, password a is valid Menu – check the appearance Press F1 to get the Help1 screen Press F1 again to get the Help2 screen Press any function key or Enter to return to the Menu Enter c as a selection – fails with error message that it cannot be converted to numeric Enter 9 as a selection – fails with error message that is not a valid value Press F3 to exit the program – uses validationBypassKey to avoid having to enter valid data

 Lab – Create the Menu Screen
Rational Business Developer - Text User Interface  Lab – Create the Menu Screen Follow these steps to create the xyzMnuFormGroup: Expand the project ZZZTUIProject_CopyPaste and the folder xyzSystem Copy the file xyzMnuFormGroup.txt to package egltui.menu Right-click the new file in package egltui.menu and click Rename on the pop-up menu Change the file type from .txt to .egl Open xyzMnuFormGroup.egl with the EGL Text Form Editor to get a better picture of what the screen looks like Hint: Set the Filters to show just one form at a time Close the EGL Text Form Editor Hints: To open the xyzMnuFormGroup.egl file with the EGL Text Form Editor, right-click the file and then click Open With -> EGL Text Form Editor. To change the filters, click on the down arrow next to defaults and then click Filters. Toggle sample values to fill in all the fields on the screen.

 Lab – Create the Menu Program
Rational Business Developer - Text User Interface  Lab – Create the Menu Program Follow these steps to create the xyzMenuProgram: Expand the project ZZZTUIProject_CopyPaste and the folder xyzSystem Copy the file xyzMenuProgram.txt to package egltui.menu Right-click the new file in package egltui.menu and click Rename on the pop-up menu Change the file type from .txt to .egl Edit the xyzMenuProgram.egl file Comment out the transfer to program statements that are in error We’ll create the List and Detail programs shortly Save and close the xyzMenuProgram.egl file Edit the Logon program Uncomment the line that transfers to the Menu program

 Lab – Debug the Menu Program
Rational Business Developer - Text User Interface  Lab – Debug the Menu Program Test the Menu program in the Debugger by starting with the xyzLogonProgram.egl file Logon user a, password a is valid Menu Check the appearance Make sure “Welcome, William” is there (name passed from Logon program) Check the help form chaining Press F1 to get the Help1 screen Press F1 again to get the Help2 screen Press any function key or Enter to return to the Menu Press Enter Enter c for the Selection field Enter 9 for the Selection field Press F3 to end the program What if you get an error? If the logon program just loops, check that you uncommented the transfer statement. For any other error, set a breakpoint at the beginning of the xyzLogonProgram.egl or the xyzMenuProgram.egl and test again, stepping through the program. What happens and WHY when you do the following: Press Enter without entering any data? Answer, because the field is defined as inputRequired=yes, EGL issues a message indicating that data is required. Enter c for the Selection field? Answer, because the field is defined as num(1), EGL issues a message indicating that the type of data is not valid (cannot be converted to integer). Enter 9 for the Selection field? Answer, because the field is defined as with validValues=[[1,5]], EGL issues a message indicating that the value is not valid. Press F3 with 9 still in the Selection field? Answer, because F3 is a validationBypassKey, EGL skips all validation for the input and gives control to the next statement in your program. The validationBypassKeys are useful so that the user can exit or cancel from the program without having to first correct the data.

What Does the Customer List Screen Look Like?
Rational Business Developer - Text User Interface What Does the Customer List Screen Look Like? Four arrays Default IndexOrientation=down Default LinesBetweenRows=0 So, these properties do not have to be included in the EGL source

What Does the Customer List Program Look Like? (Slide 1 of 3)
Rational Business Developer - Text User Interface What Does the Customer List Program Look Like? (Slide 1 of 3) Pretty standard initialization, but a few differences Dynamic array of customers Constant to remember number of lines on screen (maintainability) Retrieves customer data before first converse Moves the data to the form converse is moved to separate function

Rational Business Developer - Text User Interface What Does the Customer List Program Look Like? (Slide 2 of 3) Moving data to the screen Loop to move up to a maximum of 15 rows from the dynamic array to the form Loop to blank out remaining rows on form if the dynamic array retrieved fewer than 15 rows Clear the StartName on the form for the user Other things you might do with lists: Provide scrolling back and forth within the rows retrieved for the dynamic array Specify a maximum size for the dynamic array (for example, 100). Best practice is to do this, especially if the data is on one platform (for example, the mainframe), and the control or business logic program is on another platform (for example, Windows). That way you avoid bringing down thousands of rows that the user might not be interested in. You can then either: Scroll within just the 100 rows you retrieved and tell the user to refine the search. Advantage is that the user has control and can choose to change the search criteria to avoid scrolling through lots of data to get to the row they really want. Scroll within the 100 rows and if the user requests to scroll beyond that point, handle it under the covers by retrieving the next group of 100 rows. More complex logic, but might be better if the user frequently needs to look at the entire list.

General processing for the list Loop until the user requests exit For Enter Retrieve customers based on starting last name Move the data to the form Give error message if problem retrieving the data Prompt if no starting last name For F5 (requesting details) Determine which line has the cursor Move the CustomerID to the transferData record Transfer to the Details program For F2, transfer back to Menu For F3, exit the program

Lab Overview – Create the Customer List Screen and Program
The steps to complete the List Screen are as follows: Data access provided by CustomerLib Create the Customer List FormGroup Copy and paste the FormGroup from the ZZZTUIProject_CopyPaste project Create the Customer List program Copy and paste the program from the ZZZTUIProject_CopyPaste project Change the Menu program Remove the comment on the transfer statement to the xyzCustListProgram Test the Customer List program in the Debugger Logon – user a, password a is valid Menu – 1 for the List option List – check appearance; first screen should have list of customers List – leave Starting from Last Name blank and press Enter – message asking for input List – set Starting from Last Name set to SP and press Enter List – set Starting from Last Name set to Sp and press Enter Press F3 to exit the program

 Lab – Create the Customer List Screen
Rational Business Developer - Text User Interface  Lab – Create the Customer List Screen Follow these steps to create the xyzCL1FormGroup: Expand the project ZZZTUIProject_CopyPaste and the folder xyzSystem Copy the file xyzCL1FormGroup.txt to package egltui.opt1.custlist Right-click the new file in package egltui.opt1.custlist and click Rename on the pop-up menu Change the file type from .txt to .egl Open xyzCL1FormGroup.egl with the EGL Text Form Editor to get a better picture of what the screen looks like Close the EGL Text Form Editor Hints: To open the xyzCL1FormGroup.egl file with the EGL Text Form Editor, right-click the file and then click Open With -> EGL Text Form Editor. Toggle sample values to fill in all the fields on the screen.

 Lab – Create the Customer List Program
Follow these steps to create the xyzCustListProgram: Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Copy the file xyzCustListProgram.txt to package egltui.opt1.custlist Right-click the new file in package egltui.opt1.custlist and click Rename on the pop-up menu Change the file type from .txt to .egl Edit the xyzCustListProgram.egl file Comment out the transfer to program statement that is in error We’ll create the Detail program shortly Save and close the xyzCustListProgram.egl file Edit the Menu program Uncomment the line that transfers to the Customer List program

 Lab – Debug the Customer List Program
Rational Business Developer - Text User Interface  Lab – Debug the Customer List Program Test the Customer List program in the Debugger Logon user a, password a is valid Menu Set Selection to 1 and press Enter List Check appearance; first screen should have list of customers Leave Starting from Last Name set to blank and press Enter Set Starting from Last Name to SP and press Enter Set Starting from Last Name to Sp and press Enter Press F2 to return to the Menu Press F3 to exit the program What if you get an error? Be sure that in the xyzMenuProgram, you removed the comments from the import statement for egltui.op1.custlist and the transfer statement for xyzCustListProgram. Otherwise, set a breakpoint at the beginning of the failing program and test again, stepping through the program. Extra credit #1: Why does setting Starting from Last Name to SP and then to Sp produce the same results? The startName field on the form specifies UpperCase=yes, so that both SP and Sp (and sp for that matter) are already all converted to upper case SP before the statement after the converse gets control. Extra credit #2: What happens if you set Starting from Last Name to x and press Enter? Answer, get message about “Problem retrieving data”. Why? Because the program is not making a distinction between sqlCode=100 (for no record found) and other sqlCode values. How could you fix it? One option is to change the xyzCustListProgram to move status.message to the form rather than putting in its own (less meaningful message). Extra credit #3: In the xyzCL1FormGroup, in the CustList form, remove UpperCase=yes, save the FormGroup and then test again. What happens?

What Does the Customer Detail Program Look Like?
Nothing particularly exciting about the Customer Detail screen What about the Customer Detail Program? If the CustomerId is filled in the transferData record, then the program retrieves the customer information before conversing the form the first time The Customer List Program fills in the CustomerId based on the Customer’s Last Name Loops until the user requests to exit If user presses Enter, checks to see what Action is requested and processes it

Lab Overview – Create the Customer Detail Screen and Program
Rational Business Developer - Text User Interface Lab Overview – Create the Customer Detail Screen and Program The steps to complete the Detail Screen are as follows: Data access provided by CustomerLib Create the Customer Detail FormGroup and program Copy and paste the files from the ZZZTUIProject_CopyPaste project Change the Menu and Customer List programs Uncomment the transfer statement for the xyzCustDetailProgram Test the Customer Detail program in the Debugger Logon – user a password a is valid Menu – 1 for the List option List – position the cursor in a customer last name field and press F5 Details – check appearance; initial screen should show customer selected on the List Details – set the Action to S (select), change the customer ID and press Enter Details – press F4 to return to the List Details – press F2 to return to the Menu Press F3 to exit the program

 Lab – Create the Customer Detail Screen
Rational Business Developer - Text User Interface  Lab – Create the Customer Detail Screen Follow these steps to create the xyzCD1FormGroup: Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Copy the file xyzCD1FormGroup.txt to package egltui.opt2.custdetail Right-click the new file in package egltui.opt2.custdetail and click Rename on the pop-up menu Change the file type from .txt to .egl Open xyzCD1FormGroup.egl with the EGL Text Form Editor to get a better picture of what the screen looks like Notice that Directions wraps over several lines Close the EGL Text Form Editor Hints: To open the xyzCD1FormGroup.egl file with the EGL Text Form Editor, right-click the file and then click Open With -> EGL Text Form Editor. Toggle sample values to fill in all the fields on the screen.

 Lab – Create the Customer Detail Program
Follow these steps to create the xyzCustListProgram: Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Copy the file xyzCustDetailProgram.txt to package egltui.opt2.custdetail Right-click the new file in package egltui.opt2.custdetail and click Rename on the pop-up menu Change the file type from .txt to .egl Edit the Menu and Customer List programs Uncomment the lines that transfer to the Customer Detail program

 Lab – Debug the Customer Detail Program
Rational Business Developer - Text User Interface  Lab – Debug the Customer Detail Program Test the Customer Detail program in the Debugger Logon – user a, password a is valid Menu – set Selection to 1 and press Enter List – position the cursor in a customer last name field and press F5 Details – Check appearance; initial screen should show customer selected on the List Set the Action to S (select), change the customer ID and press Enter Press F4 to return to the List Press F2 to return to the Menu Press F3 to exit the program What happens if you go directly from the Menu to the Customer Detail? Answer: See the Customer Detail screen with no customer data filled in. What happens if you set Customer ID to 0 and press Enter? Answer: Get a message that the ID is less than 0. This is from logic coded in the Customer Detail program. What is another way you could get validation? Answer: Set validValues=[[1, ]]. Then EGL provides a message that the data is invalid. What happens when you try action codes I (insert), D (delete), or U (update)? Answer: Get a message that the action is not supported yet. Will discuss the options for completing this program next.

What about the Insert, Delete, and Update Actions? (Slide 1 of 2)
When data gets updated, need to think more about what happens during “end user think time” For insert – someone else might insert the same CustomerID and assuming duplicate keys are not permitted Error on the add Probably retrieve the row from the database, show it to the user, indicate that the key is already there, and ask if the user wants to update the data For delete – someone else might delete the same CustomerID Error trying to get forUpdate Show the row again, with a message that it has already been deleted

What about the Insert, Delete, and Update Actions? (Slide 2 of 2)
Rational Business Developer - Text User Interface What about the Insert, Delete, and Update Actions? (Slide 2 of 2) When data gets updated, need to think more about what happens during “end user think time” For an update – someone else might update the data Option 1 – prevent the problem; keep the row locked during the converse What if current user goes to lunch – row might be locked for a long time Option 2 – detect that the row has changed Technique A – keep a copy of the entire record from before the converse, commit at the converse to release the lock, get the record again after the converse, and compare all fields in the record to see if it has changed. Advantage is that if the record has changed, you have it available for redisplay Technique B – similar to A, but use one field within the record to determine if it has changed Counter TimeStamp Must remember to bump the counter or reset the timestamp for every UPDATE in every program!!! Technique C – similar to A or B, except rather than a separate retrieve, write SQL UPDATE with a complex WHERE clause that checks to see if any of the fields or the critical counter or timestamp field has changed Technique D – do not worry about it – update any way For example, if only subtracting the quantity that was ordered from the quantity that is in stock, might not matter if the inventory has changed during end user think time, BUT need to code for the situation where the inventory goes negative Technique A is good if the record is small in terms of the number of bytes – especially if the record is smaller in terms of the bytes than a timestamp requires. Technique B is better for large records because there is a smaller amount of data to save and compare. Technique C has faster performance because there is no extra get forUpdate in the normal situation, but it does require a get if the record has changed so that the current data can be displayed to the user. The logic and SQL statement are more complex to code, but if performance is critical then this is better than Techniques A or B. Technique D can be acceptable in certain situations such as the inventory example. SQL customers: If these techniques sound familiar, it is because they are the same techniques that you use in non-EGL programs.

What about Releasing Locks during a Converse?
Rational Business Developer - Text User Interface What about Releasing Locks during a Converse? Several techniques textUIProgram is nonsegmented by default Does not commit resources or release resources at a converse Called textUIProgram can only run in nonsegmented mode converseVar.commitOnConverse = 1 Causes nonsegmented program to automatically take a commit point at a converse segmented=yes program property Causes program to run in segmented mode For CICS and IMS/VS, at the converse statement, EGL Automatically saves a copy of all the program variables and forms in the program, plus other information to restore position within the program logic Takes a commit point – so databases and recoverable resources are committed and locks are released Sends the data to the screen and releases all program resources (for CICS and, when appropriate for IMS/VS) When the user responds, restores the copy of all the program variables and forms Repositions within the program logic and completes the standard EGL validation Assuming no validation errors, gives control to the program logic at the statement following the converse For Debug, Java generated programs, and System i generated COBOL programs Simulates the segmented processing (does the commit and other refreshing of system variables that occurs at a segmented converse), but does not release the program resources Reference: Refer to the EGL Language Reference or the online helps for details about everything that occurs if you set converseVar.commitOnConverse = 1 or use segmented processing. CICS customers: EGL nonsegmented processing is CICS conversational processing. EGL segmented processing is CICS pseudoconversational processing. IMS customers: EGL only supports segmented processing for IMS/VS. If you set the spaSize build descriptor option to 0, EGL segmented processing results in IMS nonconversational processing. If you set the spaSize build descriptor option > 0, EGL segmented processing results in conversational processing (and the record passed on a transfer to transaction is passed in the IMS SPA). VAGen customers: The VAGen special function word EZECNVCM converts to the EGL converseVar.commitOnConverse system variable. The VAGen special function word EZESEGM (which enables you to switch the next converse from the program default to either segmented or nonsegmented mode) converts to the EGL converseVar.segmentedMode system variable. converseVar.segmentedMode is supported only in VAGen compatibility mode.

 Lab – Completing the Customer Detail Program
Rational Business Developer - Text User Interface  Lab – Completing the Customer Detail Program Pick your technique for handling possible changes to the data during “end user think time” Insert Delete Update – limited to Technique A, C, or D (do not add fields to the course database) Pick your technique for releasing locks during “end user think time” Finish the program Your organization probably has standards in terms of whether and how to release locks during end user think time and how to deal with potential changes by other users during the current “end user think time”. Those are the standards you should consider adapting for use with EGL.

What Does the Customer Orders FormGroup Look Like? (Slide 1 of 3)
PrintFloatingAreas – defines the margins for each pageSize and deviceType combination (only one in this example) Fixed forms – have position property Header – form to go at top of page Trailer – form to go at bottom of page

Floating forms – do not have the position property; placed in the next available line of the floating area CustomerLine – 4-line form containing customer data OrderLine – 2-line form containing order data for a specific customer NoOrdersForm – 1 line form to print if the customer does not have any orders

Rational Business Developer - Text User Interface What Does the Customer Orders FormGroup Look Like? (Slide 3 of 3) All the forms – positions set for the floating forms so can view all forms at one time Why is the line of column heading for the order information included in the CustomerLine form? Answer: This simplifies the program logic for the purposes of this course. In a real program, you probably should create an OrderHeading form and only display that form when there are orders for a particular customer.

What Does the Customer Orders Program Look Like? (Slide 1 of 3)
Rational Business Developer - Text User Interface What Does the Customer Orders Program Look Like? (Slide 1 of 3) Program type is basicProgram Pretty standard initialization Two dynamic arrays: All customers All Orders for one CustomerID Need to count the lines used in the floating area Constant maxBodyLines for total lines in the floating area Initialize and print the Header form on the first page Print forms and the print statement can be used in either basicPrograms or in textUIPrograms. Text forms and the converse and display statements can only be used in textUIPrograms.

Get all customers Loop to process all customers Move customer data to CustomerLine form If not enough space left in floating area, print Trailer form, then print Header form on next page Print CustomerLine Keep track of used lines

Get all orders for the current customer Process the orders If no orders, print NoOrdersForm Loop through all orders for specific customer Move data If not enough space to print an order Print Trailer Print Header Print “continued” Print CustomerLine again Print OrderLine Keep track of used lines End of report

Print Forms – I/O Statements, System Variables and System Functions
Rational Business Developer - Text User Interface Print Forms – I/O Statements, System Variables and System Functions print formName; Write a print form to the location specified for the printer close formName; Issues a form feed and then either closes the printer file or disconnects the physical printer Implicit close occurs at: Segmentation break for a converse statement in CICS or IMS/VS End of the program converseLib.pageEject() Forces a page eject for a printer Not needed for report example print Trailer places form at bottom of current page print Header requires placement at top of next page (row 1), so EGL automatically issues the page eject converseVar.printerAssociation Dynamically change the resource association for the printer Depending on runtime environment and resource association file types, can have multiple reports open by changing converseVar.printerAssociation VAGen customers: In VAGen Compatibility mode, display printForm is treated like print printForm. converseLib.pageEject() is the replacement for the VAGen SET map PAGE statement when the map is a printer map. converseLib.clearScreen() is the replacement when the map is a display map.

Lab Overview – Create the Customer Orders Report and Program
The steps to complete the Customer Orders Report are as follows: Data access provided by CustomerLib and OrdersLib Copy and paste the GetCustomerOrdersListAll function from the ZZZTUIProject_CopyPaste project into the CustomerLib.egl file Create the Customer Orders FormGroup Copy and paste the FormGroup from the ZZZTUIProject_CopyPaste project Create the Customer Orders program Copy and paste the program from the ZZZTUIProject_CopyPaste project Test the Customer Orders program in the Debugger Run the program Examine the output report

 Lab – Create the GetCustomerOrdersListAll Function
Follow these steps to create the GetCustomerOrdersListAll function Expand the egltui.access package Double-click on OrdersLib.egl Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Double-click on GetCustomerOrdersListAll.txt Copy the code from GetCustomerOrdersListAll.txt and paste the code into CustomerLib.egl, near the bottom of the file just before the comment for: //END custom source definitions Save and close both files

 Lab – Create the Customer Orders FormGroup
Rational Business Developer - Text User Interface  Lab – Create the Customer Orders FormGroup Follow these steps to create the xyzRP1FormGroup Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Copy the file xyzRP1FormGroup.txt to package egltui.opt3.report Right-click the new file in package egltui.opt3.report and click Rename on the pop-up menu Change the file type from .txt to .egl Open xyzRP1FormGroup.egl with the EGL Text Form Editor to get a better picture of what the forms look like Close the EGL Text Form Editor Hints: To open the xyzRP1FormGroup.egl file with the EGL Text Form Editor, right-click the file and then click Open With -> EGL Text Form Editor. To look at one form at a time, change the Filters in the Design tab of the EGL Text Form Editor. (The screen shot on the slide was done with a “trick” by setting the position property for each form to be in a different row so that all the forms are visible at once. But you do not want to do this because it breaks the xyzReportProgram). Toggle sample values to fill in all the fields on the screen.

 Lab – Create the Customer Orders Program
Follow these steps to create the xyzReportProgram Expand project ZZZTUIProject_CopyPaste and folder xyzSystem Copy the file xyzReportProgram.txt to package egltui.opt3.report Right-click the new file in package egltui.opt3.report and click Rename on the pop-up menu Change the file type from .txt to .egl

 Lab – Debug the Customer Orders Program
Rational Business Developer - Text User Interface  Lab – Debug the Customer Orders Program Header CustomerLine OrderLine – repeated once for each order for this customer NoOrdersForm Trailer Test the Customer Orders program in the Debugger Click the Resume button repeatedly until the program finishes There is a slight pause while the report window is created; watch for the Print Preview window to appear (it might be in the background) Use Next and Prev to page back and forth through the report Close the report window The Debugger terminates the session What if you get an error? Set a breakpoint at the beginning of xyzReportProgram.egl and test again, stepping through the program.

Unit Summary Now that you have completed this topic, you should be able to: Understand Use of Data Access Libraries Typical Development Issues Naming Conventions Typical Organization for Text UI Source Code Create and debug a Text UI application system Create a Logon Screen Create a Menu Screen Create a Customer Detail Screen Create a Customer List Screen Create a Customer Orders Report Understand techniques for dealing with “end user think time”

Course Summary Now that you have completed this course, you should be able to: Define the nature and purpose of the following : FormGroup TextForm PrintForm Form Components – variable and constant fields TextUIProgram converse, display, and print statements Understand some basics of the EGL text user interface FormGroup and Form Floating area How a program references a FormGroup What happens during generation Use the EGL Text Form Editor to create 3270 or 5250 screens Form Group Text Form Popup Menu or Popup Form Text Form from an existing record Code EGL programs that use a text user interface Typical Development Issues Typical Organization for Text UI Source Code Techniques for dealing with “end user think time” Debug EGL programs that use a text user interface

Getting Started With EGL – At Your Shop
Rational Business Developer - Text User Interface Getting Started With EGL – At Your Shop General EGL assistance from IBM: Take a tutorial / follow a cheat sheet – in the documentation Other Courses – see the EGL Course Road Map (next slide) On-Site Training Project Planning & Architecture Pilot Project Ongoing Support EGL Links: EGL Café: ibm.com product page: RBD Announcement Letter:

EGL Course Road Map EGL Foundations Course VAGen to EGL Migration EGL JSF - Web Course EGL Text UI Course EGL for the CICS Developer EGL for the IMS Developer (under development) EGL for the iSeries Developer (under development) EGL Best Practices Seminars – send an to: EGL Best Practices JSF - Web EGL Best Practices Text UI EGL Best Practices SQL

Rational Business Developer - Text User Interface Course RBD/EGL Text UI Programming Appendices Installing Rational Business Developer (Trial) Optional Lab – Generate and Run helloProgram as Java Text UI Compatibility Considerations

RBD v7.5.1 Installation Process
Rational Business Developer - Text User Interface RBD v7.5.1 Installation Process RBD v7.5.1 can be installed standalone, or can be installed into (on top of): RDz RDi/SOA The RBD v7.5.1 installation process is as follows: Download and install Installation Manager – a separate piece of IBM software that will guide you through the rest of the installation process Download and install RBD v7.5.1 … The link to get the trial software for RBD v7.5.1 is here: In addition to the RBD v7.5.1 software, you also need to download the following files to your workstation: EGLDerbyR7.zip – the course database EGL_TUIBasics_v751_PIF_StartCourse_version.zip – project interchange file at start of course EGL_TUIBasics_v751_PIF_EndCourse_version.zip – project interchange file at end of course Your course setup will direct you as to where to get these resources and the version to use for the project interchange files

 Install RBD 7.5.1 (Slide 1 of 11)
Rational Business Developer - Text User Interface  Install RBD (Slide 1 of 11) The following slides show the installation snapshots for RBD v Follow these steps carefully. If you already have Installation Manager installed AND downloaded RBD 7.5.1, navigate to IBM Installation Manager and click Install If you install from the Trial site (without downloading), click the install method you want to use (depends on whether you already have Installation Manager or not)

Select Rational Business Developer, Version and then click Next

Accept the terms and conditions (in order to continue) Click Next

**** If you already have a Rational product installed, this page of the wizard does not appear. The Installation Manager uses the existing Shared Resources Directory If this page appears: Optionally, change the Shared Resources Directory Click Next

Create a new package group, and browse to where you want the product installed Click Next

Install (do not extend) Eclipse Click Next

Choose your installation language (the default is English) Click Next

If you plan to generate COBOL for System z or VSE, select the corresponding generation feature (Optional) If you are developing Web applications or plan to take the EGL JSF course, select the version of WebSphere Application Server (WAS) you plan to use Recommendation: Even if you plan to use Tomcat for the EGL JSF course, select the tools for your version of WAS. Screen shots for the course use WAS V6.1 Click Next

Specify personal information Click Next

Review your installation specifications / settings Click Install

The installation should complete successfully Click Finish

(Optional) Lab Overview – Generate and Run helloProgram as Java
Rational Business Developer - Text User Interface (Optional) Lab Overview – Generate and Run helloProgram as Java Would you like to generate the helloProgram as a Java program and run it outside of RBD? It is actually a lot easier than you think. Here are the steps: Set the build descriptor options Generate the program Verify that the rununit.properties file is set correctly Export the application as a JAR file Create a .bat file to run the program Run the .bat file 

 (Optional) Lab – Set the Build Descriptor Options
Double-click on the EGLTUIProject.eglbld file Clear Show only specified options Set sqlID and sqlPassword to your user ID and password Select Show only specified options Verify your settings Save and close the file

 (Optional) Lab – Generate the Program
Rational Business Developer - Text User Interface  (Optional) Lab – Generate the Program Verify that the project has a default build descriptor Right-click the EGLTUIProject and click Properties Select EGL Default Build Descriptors Verify the Target system build descriptor is set as follows: Click OK Expand the egltui.helloworld package Right-click the helloProgram.egl and click Generate Notice that both helloProgram and helloGroup are generated. This is because the genFormGroup build descriptor option defaults to YES.

 (Optional) Lab – Verify that the rununit.properties File is Set Correctly An EGL-generated Java program uses a set of properties that provide information at runtime Most of these Java runtime properties are set using build descriptor options (such as the sqlID and sqlPassword you set in the previous step) By default, the file is the rununit.properties file and is created in the JavaSource folder Double-click the rununit.properties file to open it Verify your settings Close the file For more information on the rununit.properties file and a description of all the different properties that you can set, refer to the online Help in Rational Business Developer or to the EGL Generation Guide. Search on rununit.properties or Java runtime properties. Some of the database settings are from the installation verification steps. The vgj.jdbc.default.database.user.id and vgj.jdbc.default.database.user.password are what you entered into the .eglbld file. Additional, optional settings you can use for debugging

 (Optional) Lab – Export the Program as a JAR File
Create a folder to contain the .jar files For example: C:\EGLJavaGenOut Export the EGLTUIProject as a .jar file using the following steps: Right-click the EGLTUIProject and click Export Expand Java Select JAR file Click Next On the JAR Export window Under Select the resources to export Expand EGLTUIProject Clear EGLbin and EGLSource Specify a directory and name for the JAR file For example: C:\EGLJavaGenOut\TUIProject.jar Click Finish If prompted about warnings, respond OK

 (Optional) Lab – Create .bat File to Run the Program
Rational Business Developer - Text User Interface  (Optional) Lab – Create .bat File to Run the Program Create a .bat file to run the program using the following steps: Expand project ZZZTUIProject_CopyPaste and folder quickStart Copy the file RunHelloProgramAsJava.txt to the folder you created for the .jar file (c:\EGLJavaGenOut) In your folder (c:\EGLJavaGenOut), Edit RunHelloProgramAsJava.txt and set the following values: INSTALL_DIRECTORY – directory where you installed RBD (see notes) SHARED_DIRECTORY – directory for the shared resources when you installed RBD (see notes) JAVA_RUNTIME_PLUGIN - the version for the com.ibm.etools.egl.java.runtime plug-in (see notes) TUI_DIRECTORY – directory where you placed the .jar file for the EGLTUIProject (c:\EGLJavaGenOut) TUI_JARFILE – name you gave the .jar file for the EGLTUIProject (TUIProject.jar) Save your changes and close the file Change the file name as follows: Change the file extension in c:\EGLJavaGenOut from .txt to .bat (Optionally) Shorten the file name (for example: testTUI) If you used the default directories when you installed RBD, the directory names are in the format: INSTALL_DIRECTORY: C:\Program Files\IBM\SDP SHARED_DIRECTORY: C:\Program Files\IBM\SDPShared JAVA_RUNTIME_PLUGIN: To determine the version for com.ibm.etools.egl.java.runtime, locate your sharedInstallationDirectory\plugins directory and find the plug-in directory named com.ibm.etools.egl.java.runtime_version. If there are several plug-ins with the same name, use the highest version number in your plugins directory.

 (Optional) Lab – Run the helloProgram
Rational Business Developer - Text User Interface  (Optional) Lab – Run the helloProgram From Windows Explorer Navigate to the directory where you placed the .bat file (c:\EGLJavaGenOut) Double-click on the .bat file This same technique works for running the XYZ Company application (Logon, Menu, List, and Detail programs) that you develop later in the class. The .bat file already includes the Derby.jar file that is needed for the SQL access in the XYZ Company system. All you need to change to start the Logon program is to change the java command from: java egltui.helloworld.helloProgram to java egltui.logon.xyzLogonProgram.

Compatibility – Text UI Restrictions for COBOL Generation
Rational Business Developer - Text User Interface Compatibility – Text UI Restrictions for COBOL Generation Certain properties or property values related to forms: align – center is not supported color – black is not supported highlight Support varies based on emulator iSeries – blink is only supported if color=red; otherwise blink is ignored intensity – dim is not supported isBoolean – not supported masked – blanks are used instead of * to hide the data sign – parens is not supported dateFormat – only certain masks are supported; lengths of 6, 8, or 10; combinations of MM and dd with yy or yyyy OR systemGregorianDateFormat DDD with yy or yyyy OR systemJulianDateFormat timeFormat – not supported timestampFormat – not supported validValues – only a single pair of numeric values is supported Certain set statement values: full – ignored for fields on print forms unless the setFormItemFull build descriptor option is set to YES Certain primitive types are not supported on forms: BOOLEAN HEX (CHAR with isHexDigit=yes is permitted) FLOAT, SMALLFLOAT STRING TIME, TIMESTAMP, INTERVAL VAGen customers: restrictions on properties, including dateFormat, are no more restrictive than in VAGen; the single pair of values for validValues is the VAGen minimum and maximum edits.

Compatibility – Text UI for Specific Environments: Java, iSeries, CICS
Rational Business Developer - Text User Interface Compatibility – Text UI for Specific Environments: Java, iSeries, CICS Compatibility Consideration Java Generation timeFormat and timestampFormat properties The specified pattern values must exactly match the field length highlight Only noHighlight and underscore are supported Compatibility Consideration iSeries Screen size Only screen sizes 24x80 and 27x132 are supported highlight highlight=blink is only supported if color=red; otherwise blink is ignored Compatibility Consideration z/OS CICS Form field properties: lowerCase upperCase If terminal is defined as UCTRAN, CICS automatically converts the input to uppercase, so the lowercase and uppercase properties have no effect.

Compatibility – Text UI for Specific Environments: IMS/VS
Rational Business Developer - Text User Interface Compatibility – Text UI for Specific Environments: IMS/VS Compatibility Consideration IMS/VS converse statement Not supported in called program display statement Not supported for text forms Segmented=no Not supported, TextUI programs must run in segmented mode converseVar.segmentedMode Ignored, TextUI programs must run in segmented mode Text form related: Function keys PA keys cannot be used as helpKey or validationBypassKeys and never is a value for converseVar.eventKey F12 often reserved for local copy Screen layout Minimum screen size is 24x80. Smaller screens are treated as though they were defined on 24x80. Use the mfsDevice, mfsExtendedAttr, and mfsIgnore build descriptor options to specify device characteristics for various screen sizes. Partial forms are not supported. Floating forms are not supported. If the text form is displayed using the IMS /FORMAT command, all variable fields are set to blanks instead of the initial values defined in the form definition. row 1, column 1 must be blank or contain a constant or variable field attribute byte. Unprotected constant fields are not supported. If a constant field attribute byte is in the last position of the form (last row, last column) it is treated as though it is in row 1, column 1. A zero-length constant field is not supported. Non-blank constant fields longer than 255 bytes are not supported. DBCHAR constant fields longer than 254 bytes are not supported. MBCHAR constant fields longer than 255 bytes are not supported. Be aware of MFS control block size limits. Refer to EGL Programmer’s Guide, section on “Defining forms for IMS programs” IMS/VS is the most restrictive of the environments.

Compatibility – Text UI Restrictions for Specific Technology
Rational Business Developer - Text User Interface Compatibility – Text UI Restrictions for Specific Technology Compatibility Consideration Text User Interface Library Cannot use converse, display, or show statements Cannot access a text form Requires a use FormGroup statement to access print forms The library is reloaded when a segmented text UI program does a converse or show Text Forms *msgKey properties (like inputRequiredMsgKey) should be a string or literal that matches the first column of a msgTable that is specified by the msgTablePrefix property of the program. If the key is numeric and the first column of the table is character or string, the key is converted to character. If the key is character or string and the first column of the table is NUM, the key is converted to NUM

Compatibility – Highly Variable Based on Runtime Environment
Rational Business Developer - Text User Interface Compatibility – Highly Variable Based on Runtime Environment Definition varies by runtime environment Run unit Unit of work Statements: transfer to program, including effect of synchOnPgmTransfer build descriptor option for ZOSCICS programs using DL/I transfer to transaction, including effect of synchOnTrxTransfer build descriptor option for nontransactional environments converse, including effect of segmented=yes/no and converseVar.commitOnConverse show Library functions: sysLib.commit, sysLib.rollback, including implicit commits vgLib.startTransaction System variables: sysVar.sessionID, sysVar.terminalID, sysVar.userID sysVar.transferName sysVar.transactionID sysVar.returnCode sysVar.errorCode also varies by file type, resource association, and sysCodes build descriptor option converseVar.printerAssociation If you are writing programs that must run in several runtime environments, you need to be particularly aware of the compatibility considerations in these areas.

Rational Business Developer

Similar presentations

Presentation on theme: "Rational Business Developer"— Presentation transcript:

Similar presentations

About project

Feedback

Log in

Auth with social network:

Rational Business Developer

Similar presentations

Presentation on theme: "Rational Business Developer"— Presentation transcript:

Similar presentations

About project

Feedback