|Forms and HTML||Data Access 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.
Creating an Internet or intranet application is very easy with Net Express. Use it to paint the forms you need and then it automatically creates 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:
A simple running example illustrates each part of the process. The instructions in this chapter are not at the detailed level of "now click OK". They explain the overall process; detailed step-by-step instructions for Form Designer and Net Express are available in the on-line help. If you want to get a feel for Form Designer and Net Express before you start, run the sample sessions in your Getting Started.
This section introduces Form Designer. Net Express starts Form Designer whenever you create a new HTML page or edit an existing one. The following three subsections explain:
The screenshot below shows Net Express with an HTML page open inside Form Designer:
Figure 4-1: Form Designer
The main parts of Form Designer are:
Enables you to edit the page and forms you are currently working on.
Displays all the properties for the element currently selected in the Page Tree View. Generally selecting a element in either the Page Design Area or the Page Tree View selects it in both views. The exceptions are those elements which are not rendered in the Page Design Area - for example <BODY>.
Properties are grouped onto different panes, selected by clicking the tabs at the bottom. The Attributes pane displays the HTML attributes and the Styles pane displays its CSS style settings. If a form or form element is selected, the COBOL pane enables you to set properties for linked data items (see Properties and Linked Data Items). If you select a Java applet or ActiveX control, a Properties pane enables you set any exposed properties.
Shows the hierarchy of all the elements on the page. You can also select elements in the Page Design Area by clicking on their equivalent representation on the Page Tree View. You can filter out different types of element from the Page Tree View, by right-clicking and clicking Element Filtering on the popup menu.
Enables you to add elements to your page or form. Elements are grouped onto different tabs. The Page Elements tab contains HTML elements which can be placed anywhere on a page. The Form Elements tab contains HTML elements which can only be placed inside an HTML form.
Enables you to change the format of selected text. You can change a paragraph into a heading, change the font and color, use bold, italics or underline, and change the alignment of text. You can also add hyperlinks.
We recommend you to set Small Fonts on the Windows Display Settings dialog box, accessible from the Control Panel. Form Designer calculates text sizes based on the size of font you are using. Consequently, any positional form designed on a PC with one font size displays differently on a PC set with a different font size. Most users use Small Fonts, so forms display correctly on more machines if you design them with Small Fonts set on the Display Settings. Alternatively you can make positional forms appear the same on all machines, by explicitly setting the font size of all the text in your positional forms. You can do this with the Form Designer format toolbar
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:
Enables you to drop a control or text label anywhere inside a positional form. You can drag the elements of your form around with a mouse.
Enables you to type, insert, overtype and delete text as you would inside any text editor.
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.
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.
Figure 4-2: How controls map to linked data items
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 Net Express 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.
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.
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 Net Express. 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:
Figure 4-3: 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 and click on the item you want to see help for. Alternatively, put the cursor into a field and press F1.
You can find a completed version of this application in \netexpress\base\demo\bevord_h.
To paint the drinks example form:
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.
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.
Use Spans to add labels to positional forms.
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".
If this radio button is selected when the form is submitted, data item beveragetype is set to "COFFEESELECTED".
If this Check Box is selected when the form is submitted, data item milkrequest is set to 1.
If this Check Box is selected when the form is submitted, data item sugarrequest is set to 1.
This declares COBOL data item submit in bev_h.cbl, which is be set to 1 when the button is clicked.
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 Net Express to start Form Designer.
You can now generate a simple CGI (server-side program) to accompany the form.
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 in Windows Explorer), you see the following in the field:
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.
Note: When you're choosing filenames and folder names for Internet applications, avoid using the hash character (#), as it is significant to Web browsers.
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.
The Internet Application Wizard always uses quoted identifiers when referencing table and column names in generated SQL. This is to avoid problems if the name contains spaces or special characters which would make it illegal as an unquoted identifier.
If the name generated from the column name (including any prefixes and suffixes) would be illegal in COBOL because it is longer than 31 characters or contains illegal characters, a host variable is generated using the column number (for example, COL005) rather than the column name.
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.
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 Net Express applications as explained in the chapter Deploying Your Application. You can also find quick instructions for using other Web servers in the Net Express online help. Select Help Topics on the Help menu. 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:
You can step through your program using the Net Express Animator. If you haven't used the Animator before, there is a Sample Session on using the Net Express Animator in your Getting Started, in the chapter Net Express Integrated Development Environment.
To animate your Internet Application:
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:
If you want to use a different Web server, select Help Topics on the Net Express 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.
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 Start Animating At is set to the input page for the application. In this case you only see your COBOL code inside the debugger when you click Submit on the input page.
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 Net Express IDE or Solo Web server before, try the sample sessions in your Getting Started.
To build and run the example:
To see the code execute in the debugger:
This starts your Web browser, gives it the URL for the program, and starts executing the program inside the Net Express Animator. If the form appears immediately in your Web browser, and you don't see the code start inside the Net Express Animator, try clicking Reload or Refresh on your browser.
For more information about using Animator, select Help Topics on the Net Express Help menu. Then from the Contents tab, select Development Environment, Debugging and Animating Programs.
In the Overview of Internet Programming chapter, we characterized server-side programs as symmetric or asymmetric, as shown in the diagram below:
Figure 4-4: 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:
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 that accepts input from the input form and returns the output form.
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-5: 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:
When you regenerate the server-side program, data items CUSTOMEROUT, BEVERAGEOUT and OPTIONSOUT are automatically declared.
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.
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:
A COBOL source file with the skeleton code for your server-side program. This is the only one of the generated files you should edit.
A COBOL copyfile containing variables with the picture strings you have specified in the COBOL Picture property of an HTML control. These data items have the same names you set up in Form Designer.
If the program is generated for an asymmetric application, the data items declared in this copyfile are the union of all the linked data items for the input and output forms. That is, all the data items used on all of the output forms, but only one shared data item is created for those controls which share duplicate names.
A COBOL copyfile which declares data items to transfer data between the form and the program. These data items are all of type PIC X(n), and are all named from the name property of the controls on the form.
If the program is generated for an asymmetric application, the data items declared in this copyfile are the union of the all the data items for the input and output forms.
A COBOL copyfile containing code to convert data between the format sent by the form (the data items in the .cpf file) and the format specified by you in the COBOL Picture property of each control (the .cpy file).
If the program is generated from a form which specifies an input form, the input conversion is for the data from the input form and the output conversion is for the data for the output form.
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.
So far in this chapter, you have created an input form, an output form and generated a server-side program. In this section, you 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:
*> Add application business logic here
*> 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
When you input the data and click the button to submit the form, the output form appears, summarizing your input choices.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Forms and HTML||Data Access Applications|