PreviousForms and HTML Data Access ApplicationsNext

Chapter 4: Creating New Applications

This chapter explains how you create a new Internet application using Form Designer to paint the interface, and the Internet Application Wizard to generate a skeleton server-side program.

4.1 Overview

Creating an Internet or intranet application is very easy with NetExpress. Use it to paint the forms you need, then let it automatically create one or more server-side programs for you. The skeleton code generated by the Internet Application Wizard accepts data from the form, and puts it into COBOL data items. It also outputs the information in those data items to a form. You add the code which processes the data between input and output.

The Wizard can create two styles of program:

This chapter takes you through the steps to create an application:

  1. Painting a form.
  2. Running a skeleton application.
  3. Creating an asymmetric server-side program (not all applications use an asymmetric server-side program).
  4. Adding functionality to a server-side program.

A simple running example illustrates each part of the process. The instructions in this chapter are not at the detailed level of "now click the OK button". They explain the overall process; detailed step-by-step instructions for Form Designer and NetExpress are available in the on-line help. If you want to get a feel for Form Designer and NetExpress before you start, run the sample sessions in your Getting Started.

4.2 Form Designer

This section introduces Form Designer. NetExpress starts Form Designer whenever you create a new HTML page or edit an existing one. The following three subsections explain:

4.2.1 The Form Designer Window

The screenshot below shows NetExpress with an HTML page open inside Form Designer:

Form Designer with empty form
Fig 4-1: Form Designer

The main parts of Form Designer are:

4.2.2 Positional and Flow Editing

Form Designer can be used either as an HTML editor, or as an HTML form painter. To cope with these different demands, it has two editing modes:

Flow is the default editing mode. Form Designer changes to positional editing only when you have a positional form selected on the page. If you select the Positional Form template when you create a new page with the HTML Page Wizard, Form Designer creates an empty page containing a single positional form.

You can also insert a positional form anywhere on an HTML page by clicking the Positional Form button on the Form Elements component palette. Form Designer inserts the form at the current text cursor position. If you click above or below a positional form, you can add text or images to the page before or after the form.

You can also add form elements to a page while editing in flow mode, by clicking any form element on the Form Elements palette. When you do this, Form Designer asks you if you want an HTML form inserted into your page at the current cursor position. The form is not enabled for positional editing, but you can place elements inside the form by using paragraphs, spaces or tables.

4.2.3 Properties and Linked Data Items

Form Designer enables you to link the controls on a form to data items in a COBOL server-side program. When you use the Internet Application Wizard to generate a server-side program from forms created in Form Designer, the generated program is created with a data item for each named control on each form.

The Internet Application Wizard looks at the Name attribute (or ID attribute if the control does not have a Name attribute) and generates a COBOL data item with the same name to represent that control in the server-side program. The Name and ID attributes are both set on the Attributes pane of the Property Editor. The picture of the data item is taken from the COBOLPicture property (set on the COBOL pane of the Property Editor). If the COBOLPicture property is blank, no linked data item is created.

When a form is submitted and used as input to the server-side program, the linked data item is set to the value of the control; when a form is output by the server-side program, controls on the form are set to the value of the linked data items in the server-side program.

The diagram below shows an input form with an entry field, two radio buttons and two submit buttons, and an output form with three entry fields. In between is the server-side program, with linked data items generated by the Internet Application Wizard in a server-side program.

When the end-user of the application clicks either of the Submit buttons, the values of the controls are passed through to the server-side program. The radio buttons share a common name, and are represented by a single data item in the server-side program. The submit buttons also share a single name and data item. When the server-side program sends back the output form, the entry-fields are set from the values of the linked controls.

Input form, server-program and output fo

Fig 4-2: How controls map to linked data items

4.3 Creating a Form and Server-side Program

This section describes the basic process for creating a form and a server-side program, and illustrates it with a worked example. Although Form Designer's primary focus is creating forms and their use with COBOL server-side programs, any HTML page can be loaded into Form Designer and edited with it. When you create a new page with the Page Wizard, you can use any HTML page as the template. You can also copy HTML pages into your NetExpress project directory, add them to the project and edit them directly with Form Designer.

This gives you a great deal of flexibility in how the pages for your applications are designed and created. You can take pages made by professional layout designers, and just add the forms using Form Designer. For simplicity, this chapter uses blank HTML pages which contain a single positional form, as forms are the only part of a page that interact with a server-side program.

Before you can generate the server-side program for your form, you need to decide:

With an asymmetric application, two pages share the same server-side program. When you generate the server-side program, you specify an HTML page, and an input form on it as input to the program, and a separate output page. There is some extra information on asymmetric applications in the section Creating an Asymmetric Server-side Program. When you generate the server-side program for a symmetric application, you specify the same form and page for both input and output.

The instructions below are at a high-level. If you need detailed step-by-step instructions, consult the on-line help. If you haven't used Form Designer and Net Express before, Getting Started has sample sessions to help you.

  1. Set up a NetExpress project to hold your application files.

  2. Click New on the File menu and select HTML page from the New dialog box to start the Page Wizard.

  3. Fill in the Page Wizard prompts.

    You can base your page on one of the supplied template files on the General and Frames tabs of the New HTML Page, or on any HTML file by clicking the From Existing tab.

  4. Edit the page and the form (or forms) on it.

  5. Save the page.

  6. Once you have created pages with the input and output forms for your application, click New on the File menu, and select Internet Application to start the Internet Application Wizard.

  7. Select Server Program on the Internet Application Wizard and click Next.

  8. On the Server Program Generation page, select a single input page and input form for the server program (a page can have more than one form). Select one or more output pages. For a symmetric application, select the same Input and Output page.

4.3.1 Painting an Example Form

This form is part of a running example used throughout the rest of this chapter to illustrate the principles of building an Internet application with NetExpress. The form enables you to enter details to order a hot drink - looking forward to the time when office coffee machines are connected over your corporate intranet. Your finished form should look like this:

Form with a single entry field, tea& cof
Figure 4-1: The drinks example form

The instructions below are not detailed step-by-step instructions for painting the form. If you haven't used Form Designer before, try the Sample Session for it in your Getting Started. Detailed How To instructions for most Form Designer tasks are available in Form Designer help. Click Help Topics on the Help menu to display help, then click Programming, Internet Application Programming, Form Designer on the Contents tab. Context sensitive help is also available on many Form Designer dialog boxes and entry fields. Click the question mark icon on a dialog box, then click on the item you want to see help for. Alternatively, put the cursor into a field and press the F1 key.

You can find a completed version of this application in \netexpress\base\demo\bevord_h.

To paint the drinks example form:

  1. Start NetExpress, and create a new empty project called bevord.app.

  2. Click New on the File menu and select HTML Page from the New dialog box to start the Page Wizard.

    Fill in the details on the Page Wizard as follows:

    When you click Finish, the wizard generates bevord_h.htm and opens it in Form Designer.

  3. Add a Text Input to the form (from the Form Elements palette). Use the Property Editor to set the following:

    When you later create the server-side program, bev.cbl, the Internet Application Wizard generates data item customername. When the form is submitted, data item customername is set to the contents of this Text Input.

  4. Use the Text button on the Form Elements palette to add a Span element to the left of the Text Input, and click inside it. Type in "Name".

    Use Spans to add labels to positional forms.

  5. Add a Radio Button to the form. Change the caption to "Tea".

    The default caption text is already selected when you drop the control on the form, so you can overtype it. To change the caption subsequently, you need to click inside the caption text to display a text cursor. You can then select the text and overtype it with something new.

    Click the radio button itself (or select it using the Page Tree View) and set the following properties:

    If this radio button is selected when the form is submitted, data item beveragetype is set to "TEASELECTED".

  6. Add a second Radio Button to the form. Change the caption to "Coffee".Set the following properties:

    If this radio button is selected when the form is submitted, data item beveragetype is set to "COFFEESELECTED".

  7. Add a Check Box to the form. Change the caption to "Milk". Set the following properties:

    If this Check Box is selected when the form is submitted, data item milkrequest is set to 1.

  8. Add a Check Box to the form. Change the caption to "Sugar". Set the following properties:

    If this Check Box is selected when the form is submitted, data item sugarrequest is set to 1.

  9. Add a Submit button. Set the button caption to "Brew It!". Set the following properties:

    This declares COBOL data item submit in bev_h.cbl, which will be set to 1 when the button is clicked.

  10. Click the Save button on the toolbar to save your form.

    All the details of your page are saved in bevord_h.htm. The information needed to generate the linked data items in the server-side program is stored in bevord_h.mff.

    These files are added to your project. The .mff is only added to the source pool (the right-hand side of the project window). The .htm is added to both panes of the project window. You can open either file inside NetExpress to start Form Designer.

    You can now generate a simple CGI (server-side program) to accompany the form.

  11. Start the Internet Application Wizard by clicking New on the File menu and selecting Internet Application.

  12. Fill in the details on the wizard as follows:

    When you click Finish on the wizard, these files are generated for the server-side program:

    The .cbl file is the program itself, and the others are copyfiles for the form data. They are explained in more detail later in this chapter.

You can only preview the form as it will look to the end-user by running its associated CGI application. If you load the form directly into your Web browser (for example by double-clicking on it Windows Explorer), you will see the following in the field: 

:f-customername

This is a substitution parameter for data sent from the CGI program to the form. When the form is displayed by the CGI program, the entry field is shown as spaces, or with information returned by the program. Running the program is covered in the next section.

4.4 Running the Skeleton Application

At this point you have the skeleton of a working Internet application:

You can test that everything is working by building the server-side program and running it.

4.4.1 Building the Server-Side Program

This chapter documents building the server-side program as a CGI program, as this is the simplest to run and animate. You can change your program to ISAPI or NSAPI when you have it working - this is documented in the chapter CGI, ISAPI and NSAPI Programs.

To build the server-side program:

You can now run the application.

4.4.2 Running the Application

You need to start a Web server on your local machine to run the application. If you are not using Solo as your Web server, configure your Web server to debug NetExpress applications as explained in the chapter Deploying Your Application. You can also find quick instructions for using other Web servers in the NetExpress online help. Click Help Topics on the Help menu, then on the Contents tab click Programming, Internet Application Programming, Debugging Internet Applications, How to, Animate internet applications.

If you haven't run an Internet application on your machine before, try the sample session for the Solo Web Server, in Getting Started.

To run the application using Solo:

4.4.3 Debugging the Application

You can step through your program using the NetExpress Animator. If you haven't used the Animator before, there is a Sample Session on using the NetExpress Animator in your Getting Started, under the chapter NetExpress Integrated Development Environment.

To animate your Internet Application:

  1. Form Designer has already set the Animate Settings to enable you to animate your application using the Solo Web server. If you click Settings on the Animate menu, you can see that it has set the Start Animating At field to the URL of your server-side program: 
    http://127.0.0.1/cgi-bin/program.exe

    where program.exe is the name of your server-side program. If you want to use a different Web server, you must change the URL to:

    http://machine.domainname/cgi-bin/program.exe

    If you want to use a different Web server,click Help Topics on the NetExpress Help menu, and on the Help Contents tab click Programming, Internet Application Programming, Debugging Internet Applications, How to, Animate Internet Applications, and follow the instructions.

  2. Start your Web server if it isn't already running - if you are using Solo you can skip this step as NetExpress starts it automatically.

  3. Click Start Animating on the Animate menu.

    This starts your Web browser, with the URL for your server-side program. The browser requests the Web server run the program. Starting the program invokes Animator. You can now step through your server-side program.

    Whenever you step an EXEC HTML statement, your program outputs a page to the browser.

Note: This applies to symmetric applications - for asymmetric applications the Start Animating At field is set to the input page for the application. In this case you only see your COBOL code inside the debugger when the Submit button on the input page is clicked.

4.4.4 Example

You can run the skeleton server-side application for the drinks example to demonstrate that everything is working. As before, when you painted the form, the instructions below are not detailed step-by-step instructions. If you haven't used the NetExpress IDE or Solo Web server before, try the sample sessions in your Getting Started.

To build and run the example:

  1. Rebuild the project from NetExpress.

  2. Click Run on the Animate menu.

To see the code execute in the debugger:

  1. Click Start Animating on the Animate menu.

    This starts your Web browser, gives it the URL for the program, and starts executing the program inside the NetExpress Animator. If the form appears immediately in your Web browser, and you don't see the code start inside the NetExpress Animator, try clicking the Reload or Refresh button on your browser.

  2. You can now step through the code in your program, using Animator's powerful debugging features.

    For more information about using Animator, click Help Topics on the NetExpress Help menu, then from the Contents tab, select Development Environment, Debugging and Animating Programs.

4.5 Creating an Asymmetric Server-side Program

In the Overview of Internet Programming chapter, we characterized server-side programs as symmetric or asymmetric, as shown in the diagram below:


Figure 4-2: Symmetric and Asymmetric application

So far, you have seen how to develop a symmetric program. Now we shall look at creating an asymmetric program using Form Designer. When you develop an asymmetric program, you have to create an input form and an output form, and the server-side program which joins them together.

To develop an asymmetric application:

  1. Create the input form using the Page Wizard.
  2. Create the output form using the Page Wizard.
  3. Run the Internet Application Wizard, and select Server Program. Select your input and output forms in the wizard.

When you click Finish in the Page Wizard, a skeleton server-side program is generated for you and added to the project. The program contains code to accept input from the input form, and to return the output form.

4.5.1 Example

To demonstrate the difference between symmetric and asymmetric applications, we'll create a second form for the beverage application. This is an output form which summarizes the choices you made on the input form. In this section we'll paint the output form, and in the last part of this chapter, we'll add the code to the generated application which processes the input and summarizes it for the output form.

The output form looks like this:


Figure 4-3: Example output form for the drinks application

There is no pushbutton on this form because we are not going to connect it to another server-side program.

To paint the output form:

  1. Start NetExpress, and load the project bevord.app you created earlier.

  2. Click New on the File menu and select HTML Page from the New dialog box to start the Page Wizard. Create a Positional form, with filename bevsum_h.

  3. Add "Name", "Beverage" and "Options" labels to the form (use Text on the Form Elements menu to add a span to a form for inserting text).

  4. Add three Input Text controls to the form, and set their properties as follows:
    1. Name to customerout, COBOLPicture to X(60)
    2. Name to beverageout, COBOLPicture to X(60)
    3. Name to optionsout, COBOLPicture to X(60)

    When you regenerate the server-side program, data items CUSTOMEROUT, BEVERAGEOUT and OPTIONSOUT are automatically declared.

  5. Save the form.

  6. Start the Internet Application Wizard.

  7. Fill in the details on the wizard as follows:

When you click Finish on the wizard, a new skeleton server-side program is generated. You are asked whether you want to overwrite the existing server-side program, just in case you have started to add business logic to it. If you want to keep the existing program, you can create the new one with a different name.

4.6 Adding Functionality to the Skeleton Server-Side Program

This section describes the construction of the skeleton server-side program generated by the Internet Application Wizard. For a symmetric application, the skeleton server-side program simply echoes back the form with the data the end-user entered. You need to add functionality to turn it into a working application.

When you run the Internet Application Wizard, it creates the following files for you:

You add functionality by modifying the generated program.cbl. Whenever you save any of the forms associated with a server-side program, all the copyfiles listed above are regenerated. This ensures that your server-side program always contains all the data items needed to communicate with the forms it uses.

The main .cbl file is not updated, so any changes you make to the program itself are preserved. Do not change the copyfiles listed above; any edits you make in these are lost the next time you edit and save a form associated with the server-side program.

4.6.1 Example

So far in this chapter, you have created an input form, an output form, and generated a server-side program. In this section, you will add some code to the generated server-side program so that it takes and summarizes whatever was entered on the input form, and sends the summary to an output form. Although this is very simple, it shows you where and how you can edit your server-side program. The same principles would apply to a more complex application.

To add functionality to your program:

  1. Double-click on the file bev.cbl in the Project Window of the NetExpress IDE, to start editing it.

  2. Find the PROCESS-BUSINESS-LOGIC Section, and put the text cursor on the line below the comment: 
    *> Add application business logic here
  3. Add the following statements: 
     *> Output the customer's name                                
    move CustomerName to CustomerOut                          
 *> Output type of beverage                                   
    if BeverageType = "TEASELECTED"                           
        move "Tea" & x"0" to BeverageOut                      
    end-if                                                    
    if BeverageType = "COFFEESELECTED"                        
        move "Coffee" & x"0" to BeverageOut                   
    end-if  *> Summarize the choices for milk and sugar       
    if MilkRequest = 1                                        
        if SugarRequest = 1                                   
            move "Milk and sugar" to OptionsOut               
                 else                                         
            move "Milk" to OptionsOut                         
        end-if                                                
    else                                                      
        if SugarRequest = 1                                   
            move "Sugar" to OptionsOut                        
        end-if                                                
    end-if
  4. Save your changes and rebuild the application.

  5. Rerun the application, starting it with the URL for your input form.

    When you input the data and click the button to submit the form, the output form appears, summarizing your input choices.

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousForms and HTML Data Access ApplicationsNext