This section covers the following topics:
The following software must be installed:
On the web client | Browser software, such as Mozilla Firefox or Microsoft Internet Explorer. |
On the web server | HTTP server software, such as Apache Server or Microsoft Internet Information Server. |
Different prerequisites must be met if communication is to be used by RPC:
RPC | The broker of the Software AG product EntireX Communicator must be installed (for installation information, see the EntireX Communicator documentation). |
The Natural Web Server Extensions part is needed for communication between a web browser and a Natural RPC server.
For Natural Web Interface SYSWEB the following prerequisites must be met:
Current Natural Version must be installed.
The library SYSWEB.
Either Natural steplibs must be available or the contents of
the library SYSWEB must be copied to the library SYSTEM or to the user library
that will be called by the RPC.
The parameter data Area W3PARM.
The Natural RPC stub or NaturalX.
The following diagram illustrates how you can build a subprogram:
Using an HTML editor
You use an HTML editor to enter HTML and Natural code.
Then convert it to Natural source.
Finally move the generated program to Natural. (You code directly in Natural.)
Each stage of the process is identified by a number; what happens at these stages is explained below.
1a. Natural Code is written and stored in User Library.
You write Natural code on the server side either by including HTML tags in the code or by calling pre-fabricated subprograms that generate HTML tags. Then you store it as a server program or use the subprogram WEB-WIZ to generate a default program.
1b. Natural Code is entered as HTML. Continue with 2.
You use an HTML editor to create HTML pages.
Program HTML2NAT generates Natural Sources out of HTML.
You start the program HTML2NAT out of the library SYSWEB and let it convert your HTML pages created in step 1b.
Generated Natural Source is moved to the User Library.
The returning HTML page is limited to the maximum data that can be transmitted. This maximum is determined by the return page variable.
You must initialize and end the access to the Natural server subroutines by calling the subroutines W3INIT and W3END in the library SYSWEB.
Always use the parameter data areas W3PARM and W3CONST.
Use the subprogram WEB-WIZ to generate a frame (default program) for your own program.
There are two basic alternatives. You can either start coding directly in Natural or use an HTML editor.
When coding directly in Natural again there are two alternatives:
Entering calls to SYSWEB subroutines (such as W3HTML or W3TEXT) for your return page in the program editor. See the programs in the library SYSWEB, which help you perform only basic system functions; this approach requires a good knowledge of the data type you are creating, for example HTML or XML; or
calling subprograms that generate HTML tags. See the library SYSWEB; the programs in the library SYSWEB enable you to perform basic system functions and in addition, the programs in the library SYSWEB generate HTML tags; this approach requires less explicit HTML knowledge and you can still modify the programs you are calling.
* * Example E3END * DEFINE DATA PARAMETER USING W3PARM LOCAL USING W3CONST LOCAL 1 W3VALUE (A250) END-DEFINE * --- ERROR HANDLING --- ON ERROR PERFORM W3ERROR ##W3ERROR PERFORM W3END ##RPC ESCAPE ROUTINE END-ERROR * * --- INITIALIZE W3 PROCESSING --- PERFORM W3INIT ##RPC * * --- SET TYPE OF RETURN-PAGE --- PERFORM W3CONTENT-TYPE 'text/html' * --- WRITE THE DOCUMENT --- PERFORM W3TEXT '<HTML><BODY><H2>Initialize</H2>' * * --- END THE HTML PAGE --- COMPRESS '<HR>generated:' *DATE *TIME ##HTTP_NEWLINE '</BODY></HTML>' ##HTTP_END INTO W3VALUE PERFORM W3TEXT W3VALUE * * --- END W3 PROCESSING --- PERFORM W3END ##RPC * END
Example: Calling Subprograms that Generate HTML Tags
* * Example E3IMAGE * DEFINE DATA PARAMETER USING W3PARM LOCAL USING W3CONST LOCAL 1 H3VALUE (A250) 1 H3VALUE-MAX (I004) 1 H3URL (A250) * 1 II (I001) 1 GIF (A064) END-DEFINE * --- ERROR HANDLING --- ON ERROR PERFORM W3ERROR ##W3ERROR PERFORM W3END ##RPC ESCAPE ROUTINE END-ERROR * * --- INITIALIZE W3 PROCESSING --- PERFORM W3INIT ##RPC * * --- Pathname of picture --- PERFORM W3READ-ENVIRONMENT "PICTURES" ' ' H3VALUE H3VALUE-MAX IF H3VALUE-MAX EQ 0 THEN GIF := "/pictures" ELSE GIF := H3VALUE END-IF * * --- START HTML API --- PERFORM H3-OPEN-HTML 'HTML Api -Image' " " " " * --- THE LEVEL 2 HEADER --- PERFORM H3-HEADER 2 'Image' * PERFORM H3-RULE 0 * PERFORM H3-HEADER 4 'left:' * COMPRESS GIF '/natw_sam.gif' INTO H3URL LEAVING NO PERFORM H3-IMAGE H3URL 'NATweb left' 219 229 "L" * FOR II 1 TO 10 PERFORM H3-LINE-BREAK END-FOR PERFORM H3-RULE 80 * PERFORM H3-HEADER 4 'small right:' * COMPRESS GIF '/natw_sam.gif' INTO H3URL LEAVING NO PERFORM H3-IMAGE H3URL 'NATweb small right' 100 100 'R' * FOR II 1 TO 5 PERFORM H3-LINE-BREAK END-FOR * PERFORM H3-RULE 0 * PERFORM H3-TIME_DATE * * --- END HTML API --- PERFORM H3-CLOSE-HTML * --- END W3 PROCESSING --- PERFORM W3END ##RPC * END
There are two alternatives:
Creating static pages (you only enter HTML, which will be converted to a Natural subprogram)
Creating dynamic pages (you enter HTML plus Natural program code).
You can, of course, also create pages that are partly dynamic, partly static.
<HTML> <TITLE>NATweb - Test</TITLE> <BODY bgColor=d3d3d3 > <BR> <center> <h2> This Natural subprogram was generated by a HTML page. </h2> </CENTER> </BODY></HTML>
This Natural subprogram will be generated from the above HTML page:
* ----- SUBPROGRAM generated out of file: * ----- C:\static.htm DEFINE DATA PARAMETER USING W3PARM LOCAL USING W3CONST LOCAL * ----- PRIVATE VARIABLES ----- 1 W3VALUE (A250) END-DEFINE * * ----- ERROR HANDLER ----- ON ERROR PERFORM W3ERROR ##W3ERROR PERFORM W3END ##RPC ESCAPE ROUTINE END-ERROR * ----- INITIALISE HTTP API ----- PERFORM W3INIT ##RPC * ----- HEADER FOR SERVER ----- PERFORM W3CONTENT-TYPE 'text/html' * PERFORM W3TEXTLINE '<HTML>' PERFORM W3TEXTLINE '<TITLE>NATweb - Test</TITLE>' PERFORM W3TEXTLINE '<BODY bgColor=d3d3d3 >' PERFORM W3TEXTLINE '<BR>' PERFORM W3TEXTLINE '<center>' PERFORM W3TEXTLINE '<h2>' PERFORM W3TEXTLINE 'This Natural subprogram was generated by a HTML page.' PERFORM W3TEXTLINE '</h2>' PERFORM W3TEXTLINE '</CENTER>' PERFORM W3TEXTLINE '</BODY></HTML>' * ----- END HTTP API ----- PERFORM W3END ##RPC * ----- END MAIN PROGRAM ----- * * ----- SUBROUTINES ----- * END
Example: Creating Dynamic Pages
<Natural><!-- * * Read form Pers-View starting with value given by the * Parameter START * * Use HTML2NAT to generate a Natural Program * * 22.09.03 * --></Natural> <! --- Variables to read the environment ---> <Natural data><!-- * ----- DATA ----- 1 H3VALUE (A250) 1 H3MAX (I4) --></Natural> <! --- Head of the HTML page ---> <HTML> <TITLE>Natural - Environment Test</TITLE> <BODY bgColor=d3d3d3 > <BR> <center> <h2> This Natural subprogram was generated by a HTML page. The program had been precompiled out of a HTML page. <br><br> </h2> </center> <br> <hr> <! --- Subprogram to write the output to work file, from where the server will read it --- > <Natural DATA><!-- 1 #CONTENT (A1/1:48) 1 REDEFINE #CONTENT 2 #PERSONNEL-NUMBER (N8) 2 FILLER 1X 2 #NAME (A20) 2 FILLER 1X 2 #FIRST-NAME (A15) 2 FILLER 1X 2 #AGE (N2) --></Natural> <Natural SUB><!-- * ----- Do the OUTPUT ----- DEFINE SUBROUTINE WRITELINE PERFORM W3TEXT "<LI>" * #PERSONNEL-NUMBER:=PERSONNEL-NUMBER #NAME:=NAME #FIRST-NAME:=FIRST-NAME #AGE:=AGE PERFORM W3HTMLARRAY #CONTENT(*) 48 * PERFORM H3-LINE-BREAK END-SUBROUTINE --></Natural> <UL><PRE> <! --- Parameter used for reading data from the DATABASE ---> <Natural DATA><!-- * ----- DATA ----- 1 #VALUE (A20) 1 PERS-VIEW VIEW OF PERSONNEL 2 PERSONNEL-NUMBER 2 NAME 2 FIRST-NAME 2 AGE --></Natural> <! --- Main program to read the data ---> <Natural NOT> <LI>Value1 <LI>Value2 <LI>... </Natural> <Natural><!-- * --- READ ENVIRONMENT --- PERFORM W3READ-ENVIRONMENT 'START' 'P' H3VALUE H3MAX IF H3MAX GT 0 THEN #VALUE := H3VALUE ELSE #VALUE := "A" END-IF * * ----- MAIN ----- F. FIND (100) PERS-VIEW NAME > #VALUE IF NO COMPRESS 'Sorry nothing found for:' #value '!' INTO H3VALUE PERFORM W3HTMLLINE H3VALUE END-NOREC IF *NUMBER > 0 PERFORM WRITELINE END-IF END-FIND * IF *NUMBER(F.) > 0 PERFORM H3-RULE 0 * COMPRESS 'well done for: ' #value '!' ##HTTP_END INTO H3VALUE PERFORM W3HTMLLINE H3VALUE END-IF --></Natural> </PRE></UL> <! --- The footer of the HTML page --- > <hr> <BR> <center> <A HREF="index.htm">back to Index</A> This program has been generated. <Natural><!-- PERFORM H3-TIME_DATE --></Natural> </P> </CENTER> </BODY></HTML>
This Natural subprogram will be generated from the above HTML page:
* ----- SUBPROGRAM generated out of file: * ----- C:\doit.htm DEFINE DATA PARAMETER USING W3PARM LOCAL USING W3CONST LOCAL * ----- DATA ----- 1 H3VALUE (A250) 1 H3MAX (I4) 1 #CONTENT (A1/1:48) 1 REDEFINE #CONTENT 2 #PERSONNEL-NUMBER (N8) 2 FILLER 1X 2 #NAME (A20) 2 FILLER 1X 2 #FIRST-NAME (A15) 2 FILLER 1X 2 #AGE (N2) * ----- DATA ----- 1 #VALUE (A20) 1 PERS-VIEW VIEW OF PERSONNEL 2 PERSONNEL-NUMBER 2 NAME 2 FIRST-NAME 2 AGE * ----- PRIVATE VARIABLES ----- 1 W3VALUE (A250) END-DEFINE * * ----- ERROR HANDLER ----- ON ERROR PERFORM W3ERROR ##W3ERROR PERFORM W3END ##RPC ESCAPE ROUTINE END-ERROR * ----- INITIALISE HTTP API ----- PERFORM W3INIT ##RPC * ----- HEADER FOR SERVER ----- PERFORM W3CONTENT-TYPE 'text/html' * * ----- MAIN PROGRAM ----- * * Read form Pers-View starting with value given by the * Parameter START * * Use HTML2NAT to generate a Natural Program * * 22.09.2003 * PERFORM W3TEXTLINE '<! --- Variables to read the environment --->' PERFORM W3TEXTLINE '<! --- Head of the HTML page --->' PERFORM W3TEXTLINE '<HTML>' PERFORM W3TEXTLINE '<TITLE>Natural - Environment Test</TITLE>' PERFORM W3TEXTLINE '<BODY bgColor=d3d3d3 >' PERFORM W3TEXTLINE '<BR>' PERFORM W3TEXTLINE '<center>' PERFORM W3TEXTLINE '<h2>' PERFORM W3TEXTLINE 'This Natural subprogram was generated by a HTML page. Th' -'e program had been' PERFORM W3TEXTLINE 'precompiled out of a HTML page.' PERFORM W3TEXTLINE '<br><br>' PERFORM W3TEXTLINE '</h2>' PERFORM W3TEXTLINE '</center>' PERFORM W3TEXTLINE '<br>' PERFORM W3TEXTLINE '<hr>' PERFORM W3TEXTLINE '<! --- Subprogram to write the output to work file' PERFORM W3TEXTLINE ' from where the server will read it --- >' PERFORM W3TEXTLINE '<PRE>' PERFORM W3TEXTLINE '<! --- Parameter used for reading data from the' -' DATABASE --->' PERFORM W3TEXTLINE '<! --- Main Program to read the data --->' * --- READ ENVIRONMENT --- PERFORM W3READ-ENVIRONMENT 'START' 'P' H3VALUE H3MAX IF H3MAX GT 0 THEN #VALUE := H3VALUE ELSE #VALUE := "A" END-IF * * ----- MAIN ----- F. FIND (100) PERS-VIEW NAME > #VALUE IF NO COMPRESS 'Sorry nothing found for:' #value '!' INTO H3VALUE PERFORM W3HTMLLINE H3VALUE END-NOREC IF *NUMBER > 0 PERFORM WRITELINE END-IF END-FIND * IF *NUMBER(F.) > 0 PERFORM H3-RULE 0 * COMPRESS 'well done for: ' #value '!' ##HTTP_END INTO H3VALUE PERFORM W3HTMLLINE H3VALUE END-IF PERFORM W3TEXTLINE '</PRE>' PERFORM W3TEXTLINE '<! --- The footer of the HTML page --- >' PERFORM W3TEXTLINE '<hr>' PERFORM W3TEXTLINE '<BR>' PERFORM W3TEXTLINE '<center>' PERFORM W3TEXTLINE '<A HREF="index.htm">back to Index</A>' PERFORM W3HTMLLINE 'This program has been generated.' PERFORM H3-TIME_DATE PERFORM W3TEXTLINE '</P>' PERFORM W3TEXTLINE '</CENTER>' PERFORM W3TEXTLINE '</BODY></HTML>' * ----- END HTTP API ----- PERFORM W3END ##RPC * ----- END MAIN PROGRAM ----- * * * ----- SUBROUTINES ----- * ----- Do the OUTPUT ----- DEFINE SUBROUTINE WRITELINE PERFORM W3TEXT "<LI>" * #PERSONNEL-NUMBER:=PERSONNEL-NUMBER #NAME:=NAME #FIRST-NAME:=FIRST-NAME #AGE:=AGE PERFORM W3HTMLARRAY #CONTENT(*) 48 * PERFORM H3-LINE-BREAK END-SUBROUTINE END
The local data area W3CONST contains a number of constant values which you might find useful:
##HTTP_NEWLINE, ##HTTP_NEWLINE_LENGTH
If you enter the
##HTTP_NEWLINE
string into your HTML, you can use all the subroutines beginning withW3TEXT
in the library SYSWEB to create a physical new line by compressing#HTTP_NEWLINE
into the string by usingW3TextDynamic
.##W3ERROR
Parameter used for calling W3ERROR.
##HTML_LT
Constant HTML value for "less than" sign (<).
##HTML_GT
Constant HTML value for "greater than" sign (>).
##HTML_AMP
Constant HTML value for "ampersand" sign (&).
##HTML_QUOT
Constant HTML value for "double quote" sign (").
##HTML_REG
Constant HTML value for "Registered Trademark" sign.
##HTML_COPY
Constant HTML value for "copyright" sign.
##HTML_NBSP
Constant HTML value for "no page breaking" space (' ').
All input variables are defined BY VALUE, that is, every value which is MOVE compatible can be used, especially strings.
If your output possibly exceeds the limits of your return page, use the subroutine W3COUNTER in the library SYSWEB to evaluate how many bytes are free in the return page.
There are three ways to test your subprograms:
Call the subprogram from your web browser.
Call the subprogram NAT-DIR in the library SYSWEB to see the contents of a Natural library. You can also specify the name of the library in the parameters, for example http://.../sysweb/NAT-DIR?LIB=SYSEXT. Click on your program to start it.
If you do not want to call your subprogram from the web, you can use the Natural program WEB-ONL to simulate a remote call. The output of this program will be saved as a Natural text object. This "online execution" allows you to use the Natural Debugger.
The Natural Web Server Extension is called from a HTTP server. The program repackages the parameters it receives from the HTTP server and performs an Entire Broker RPC or a DCOM call to the specified Natural subprogram or method.
Data sent by the HTTP server is recognized and preprocessed. The URL, which was transmitted to the HTTP server in a URL-decoded (modified) form, is reset to its original state. All non-binary data can be transmitted as data and will be converted from ASCII to EBCDIC and vice versa, if necessary.
Only variables specified in your HTML page will automatically be
transferred to the subprogram called. All other variables to be transferred
must be specified in an ENV= entry of the .ini file. In this way, it is
possible to add variables which will be treated as system environment
variables. To add a system environment variable, specify a SETENV= entry in the
.ini
file.
ENV=HTTP_REFERRER ENV=HTTP_HOST ; SETENV=VERSION:=alpha SETENV=BROKER:=local
To save the last HTML page that was transmitted from the server to a file, specify the TRACE_FILE parameter in your configuration file.
To return an error log, specify the ERROR_LOG_FILE parameter as log-file name in your configuration file.
To get your own error screen, specify the ERROR_TEMPLATE parameter in your configuration file with your desired HTML error page's name. Environment variables can be specified in the HTML error page by using the prefix "$". With the environment variable $NWW_ENVIRONMENT, all environment variables transmitted to the subroutine called will be written as comment lines to the error page.
- Subroutines W3*
W3*
subroutines access the interface to your HTTP server in the Natural Web Server Extension. Such an interface consists (basically) of a parameter data area and of a log of the data transmitted. TheW3*
subroutines used by the subprogram are called by the HTTP server using the Natural RPC.- Subroutines H3*
If you call one the
H3*
subroutines from one of your subroutines, it creates a basic HTML tag.- Subprograms NAT*
The
NAT*
subprograms are utilities that can be called from the Internet.You can use the
NAT-DOCU
subprogram to access the Natural Web Online Documentation SYSWEB.- Text Objects T3*
The
T3*
text objects describe the contents of the library SYSWEB, what the subroutine names are and which parameters can be passed. They also provide a code sample of how to invoke them.- Subprograms E3*
Sample code of the online documentation.
- Objects D3* and D4*
The
D3*
andD4*
objects are demonstration applications.- Programs Web*
The
Web*
programs are utilities that run from the Natural NEXT prompt.