Web 3 Local Context

You have learned about static XHTML pages and how Web pages can pass data back and forth to servers and to themselves or other Web pages using HTML forms. There will be times when you need more data than your form can hold or additional data that is not available in your form. You may need access to records that are stored on a database, or data that has been processed according to complex business logic. We do this data retrieval and processing on the mainframe via Natural subprograms and then send the data out to a Web page to be displayed. But how does it all work?

Through the use of EntireX Broker (referred to as Broker) and webAgent (the primary scripting language we use for administrative applications), our development community has been able to allow the tools in our toolset to do what each does best: webAgent receives and displays data on the Web; Broker transmits the data to and from the mainframe; and Natural subprograms on the mainframe receive data as input, perform the necessary business processing and database access, and then return the results. Because we work in these two distinct environments, it is necessary for our application developers to hone their skills writing code for both Web and mainframe applications. In addition, they must be able to understand and handle data transactions between Web and mainframe applications. In this challenge, you will learn how data moves between the two environments (connectivity) and how to use our scripting language, webAgent.

Introduction to Connectivity

In most administrative Web applications in our environment, webAgent scripts that live on a Unix server use Natural subprograms that live on the mainframe. In the simplest terms, a webAgent script sends a request via Broker that transmits the data to a Natural subprogram. The subprogram processes the request and sends data back through Broker to the webAgent script. That script displays the data on a Web page for the user. The diagram below illustrates this process.

The steps detailing how a user accesses a database record from the Internet
1) User
a person uses a computer and a browser to access the Internet, enters data including a URL pointing to the page to be accessed
2) Internet
the great mysterious collection of routers, wires and URLs that directs us to the pages we want to see
3) Web server
the machine where our Web scripts live in directories; the machine name along with the path to the particular file (directory, subdirectories and document names) comprise the URL.
4) webAgent2 .WBX script
a compiled, executable script that generates the Web page; makes a call to Broker to get data from MVS; passes input data from the user to Broker
5) Broker (Web)
the communication piece between the unix server and MVS; allows data to flow between the Web script and the Natural program
6) Broker (MVS)
receives information from the Unix server; passes data back; the MVS side of the conversation
7) Natural library
where the Natural objects live; where the business logic processing occurs
8) DPP$SERV
the server Natural program that connects the name of the Web script to the name of the Natural object; points to the correct Natural object
9) Program
the Natural object (subprogram) that performs the business logic layer, request data from Adabas
10) Adabas file
where the data is stored in an organized fashion in order to be retrieved by a Natural object

Introduction to webAgent

webAgent is a scripting language developed at the University of Texas at Austin to provide access to administrative applications from the Web. webAgent provides the intermediary services of a CGI scripting language by passing data and requests for service between the user's Web browser and the mainframe. webAgent allows developers to insert programming logic into HTML code so that Web pages can be generated dynamically using data from the mainframe.

Compiled wA2 scripts (indicated by the extension .WBX) consist of a combination of the following component pieces. Not all of the pieces listed below are required; you only need a .wbs or .wbh in order to compile a webAgent script.

.wbs
A script that generates a webAgent object; contains webAgent code and includes the data definition and dispatch functions, establishing what data will be available and what other components will be compiled into the webAgent object. A .wbs script may contain HTML; however, it must be within a write statement. A .wbs or .wbh is the only component required to compile your script.
.wbh
A script that generates a webAgent object; contains webAgent code and includes the data definition and dispatch functions, establishing what data will be available and what other components will be compiled into the webAgent object. Unlike a .wbs script, this script is HTML-centric; all webAgent code must be within <% and %> tags. A .wbs or .wbh is the only component required to compile your script.
.wbt
template that contains the HTML to be generated, along with directives to insert values for webAgent variables
.wbd
data area that may be used for more extensive data definitions than would easily fit into a .wbs or .wbh.
.wbc
webAgent code to be included in one or more scripts

From the Introduction to Programming tutorials you went through in your first days of training here, you are familiar with the fact that programs must define the data to be used in the program and that the flow of the logic in the program can be controlled with conditionals (like if or decide) and loops (such as for or repeat). webAgent scripts are set up in a similar fashion; they have sections for data definition and they make use of conditionals to control the flow of the logic in the script. Variables can be defined in the .wbs or .wbh. In the case that there are many variables, a .wbd may be used. Along with controlling the flow of the logic, (mostly found in the .wbs), you may need to manipulate some of the data. This is accomplished by using data manipulation statements such as compute or examine.

Review some sample .wbs and .wbt scripts. There is also a sample Natural server program on the page with the sample .wbs and .wbt scripts. (At this point, you do not need to know about Natural server programs.)

Introduction to Broker Calls

So now you have the basics for the syntax of webAgent. But how does the mainframe data come into the picture? As mentioned earlier, Broker takes care of transmitting data from the Web browser to the mainframe and back. A Broker call is made when a perform 'SEND' command in your script passes a pre-defined Broker data area to a Natural subprogram on the mainframe. You are able to pass data to the mainframe from your Web script in the send fields of the Broker data area. This send data can be processed. (If the fields are search criteria, data can be retrieved from our mainframe database.) The resultant data is returned to the Web script in the recv fields of the Broker data area.

In order to make a Broker call, you must provide certain pieces of information to tell Broker how to find the specific subprogram you want to use. These fields are called Broker Parameters, which is shortened frequently to Broker parms.

Other features of webAgent

As a scripting language, webAgent offers many features of standard programming languages. Among these is the ability to reuse pieces of code and make code more maintainable through encapsulating routines into modular pieces. These pieces can then be inserted at compile time (with include) or may be called at runtime (with invoke). You can also invoke or include scripts in other programming libraries by linking to them through a file called a steplib. Writing modular Web scripts will save you time by allowing you to reuse code that you (or others) have written.