How Does RPG Talk to a Browser? Paul Tuohy. Copyright ComCon, ComCon. 5, Oakton Court Ballybrack Co. Dublin Ireland

Transcription

1 How Does RPG Talk to a Browser? ComCon 5, Oakton Court Ballybrack Co. Dublin Ireland Phone: tuohyp@comconadvisor.com Web: Paul Tuohy Copyright ComCon,

2 Paul Tuohy Paul Tuohy has worked in the development of IBM Midrange applications since the 70s. He has been IT manager for Kodak Ireland Ltd. and Technical Director of Precision Software Ltd. and is currently CEO of ComCon, a midrange consultancy company based in Dublin, Ireland. He has been teaching and lecturing since the mid- 80s. Paul is the author of "Re-engineering RPG Legacy Applications, The Programmers Guide to iseries Navigator and the self teach course iseries Navigator for Programmers. He writes regular articles for iseries 400 Experts Journal and Search400 and is one of the quoted industry experts in the IBM Redbook "Who knew you could do that with RPG IV?". He is also an award winning speaker who speaks regularly at US Common conferences and the renowned RPG World conferences. Copyright ComCon,

3 Agenda The HTTP Server Configuring the HTTP Server Common Gateway Interface (CGI) RPG writes to a browser RPG reads from a browser Copyright ComCon,

4 What is a HTTP Server? Web Browser Any Client, Any Browser HTML TCP /IP HTTP server HTML Documents etc. CGI Programs Data base RPG, Cobol, etc. A browser sends a HTTP request to a port on a server. The HTTP server determines if the request is for a static document; in which case the document is returned to the browser the request is for a CGI script; in which case the script is called and it uses APIs to sent data to the HTTP server which sends it to the browser. Copyright ComCon,

5 The URL A. request is made to a HTTP server through the URL (Uniform Resource Locator) in a browser window. The first portion indicates the server. On the internet, these are administered. On an intranet, these are assigned through a Domain Name Server You can also use an IP address identifies that this is a request to a HTTP server. The next portion identifies the server (and, optionally, the port on the server). This is followed by the required directory and document. Copyright ComCon,

6 The Big Difference Sessions are not conversational sessions are. The conversation is "question and answer" The browser sends a request to the HTTP server. The server processes the request The server sends back a web page The conversation ends The next request could go to a different server. Web Browser Any Client, Any Browser HTML TCP /IP HTTP server HTML Documents etc. CGI Programs Data base RPG, Cobol, etc. Copyright ComCon,

7 What about the iseries? iseries has the HTTP Server powered by Apache The traditional HTTP server was available up to V5R2. The HTTP server (powered by Apache) is based on the popular Apache web server implementation. The HTTP server (original) was available from V3R2 to V5R2 and was based on a CERN web server implementation. Copyright ComCon,

8 How do you configure a HTTP Server? Start the HTTP Admin Server. From iseries Navigator use Network->Servers and start HTTP Administration From a command line use STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN) Open the IBM Administration for iseries web page. From iseries Navigator use Network->Internet->IBM HTTP Server for iseries Open your browser and enter a URL of You cannot configure a HTTP server unless the *ADMIN server has been started. Since the configuration is through a browser, it can be done by any web administrator. Copyright ComCon,

9 Use the Create HTTP Server wizard For the uninitiated, there are wizards to ensure easy progress. Copyright ComCon,

10 Name the Server The server name will also be the name given to the server jobs running in the QHTTPSVR subsystem. Copyright ComCon,

11 Where is server information stored? This is where configuration information and logs are stored. Configuration information will be in a sub directory called conf. Logs will be in a sub directory called logs. Use the command WRKLNK /www/servername/ to get to the directories. Logs are invaluable for debugging. It is recommended that you take the defaults for this parameter. Copyright ComCon,

12 What is the root directory for the server? Identify what you consider to be the root directory. This will really be dictated by referencing within your HTML and also by security considerations. In this case it will be the root directory in the IFS. Copyright ComCon,

13 Which IP address and port? The port indicates which port the server should "listen" to. If not specified, the port number defaults to 80. The use of a port makes it a lot easier to test new web applications. The port number should be and must not conflict with another program using the port. To see port usage in iseries Navigator use Network->TCP/IP Configuration- >Connections and sort on Port column. You can view the server jobs by right clicking on remote address entry and selecting Jobs. Copyright ComCon,

14 What about logging? An access log gives details of who did what with the server. Again, this is invaluable for debugging purposes. Logs are kept in the www/servername/logs directory (unless you changed it!). Copyright ComCon,

15 Don t keep too many logs. Copyright ComCon,

16 Confirm your choices Copyright ComCon,

17 A basic server is created Copyright ComCon,

18 Add a Directory to the Web wizard You need to add details of every main directory that will be accessed for this server; so use the Add a Directory to the Web wizard. Copyright ComCon,

19 Identify it for CGI programs Indicate if the directory is to serve static web pages or CGI programs. Copyright ComCon,

20 Identify the library for the programs Identify the directory. If the directory is for RPG CGI programs, you identify the library where the CGI programs are kept. Note, the library is identified using the root file system naming convention. Ensure there is a / at the end of the name. Copyright ComCon,

21 Identify the corresponding directory in the URL Identify the corresponding directory that is entered in the URL. This defaults to cgi-bin for CGI programs. In other words, any requests from a browser for the directory cgi-bin will be redirected to the directory (library) identified on the previous page (QSYS.LIB/CGISEMINAR.LIB). Copyright ComCon,

22 Confirm your choices Copyright ComCon,

23 URL Mapping for less Keying You can change the URL mapping to save the amount of information that has to be entered in the URL. In this example, any request to /cgi-bin/name will be aliased to /cgi.bin/name.pgm. Copyright ComCon,

24 Security - Authentication To define security for a directory select the required directory from the Server Area list; select the Security link and then the Authentication tab. These directives control security access to the directory from a browser. They indicate that a user must log on before they can access the directory. Normal iseries security still applies. This example indicates that normal system user profiles apply. You can also use a validation list, but this is of more use for internet style access. Copyright ComCon,

25 Security at Work Copyright ComCon,

26 This is the configuration file Click on Preview to see details of the configuration file. The configuration file is in www/servername/conf/httpd.conf. Copyright ComCon,

27 Full Help Available Click on the Related Links tab for links to any information you need about configuring the Apace server. Copyright ComCon,

28 Starting and Stopping the server To start a HTTP server, Click the Start button in IBM Web Administration for iseries. Select the server from the Start option on the context menu for HTTP Administration in iseries Navigator Network->Servers. Enter the following command on a command line STRTCPSVR SERVER(*HTTP) HTTPSVR(RPGBROWSE) To end a HTTP server Click the Stop button in IBM Web Administration for iseries. Select the server from the Stop option on the context menu for HTTP Administration in iseries Navigator Network->Servers. Enter the following command on a command line ENDTCPSVR SERVER(*HTTP) HTTPSVR(RPGBROWSE) Starting and ending servers is something you will be doing a lot as you get to grips with CGI programs :-) Copyright ComCon,

29 Where do we see it running? The HTTP Server runs in it's own subsystem QHTTPSVR. Each server is a number of jobs in QHTTPSVR. The server name and the job name are the same. Copyright ComCon,

30 The Basics - What is CGI? CGI stands for 'Common Gateway Interface' It supports the ability to dynamically build web pages - It dictates format of the data stream for requests and responses A standard for communicating between a browser and an HTTP Server. Server is configured to pass specific URLs to CGI scripts Not simply to respond with a pre-built web page In our case the "script" will be an RPG IV program The program generates HTML and passes it to the server Which then sends it out for display as it would any other page CGI programming on the AS/400 is supported by: RPG IV (ILE RPG) Java - Plus ILE COBOL, ILE C, ILE C++, Rexx and Perl When the server receives a request for a specific URL it uses rules to determine if this is a simple page request or if the request should be passed to a program for processing. The nominated CGI program is activated on the iseries. The program can be written in any language, but an ILE language is the best candidates and must be used at some stage as they are the only ones that can interface to the necessary APIs. The response by the CGI program is in the form of HTML, which would normally incorporate data read from iseries files. This is passed back to the server by calling an API. The server then transmits the HTML to the browser. Copyright ComCon,

31 The CGI APIs The CGI APIs are stored in the service program QHTTPSVR/ QZHBCGI (put it in a binding directory). The main APIs are:- QtmhWrStout QtmhGetEnv QtmhRdStin QtmhCvtDb Write Standard Output Get Environment Variables Read Standard Input Convert to DB You can find them (and a couple of other APIs) documented in the Information Center for V5R3 by following the link Networking->HTTP Server->Programming->API Copyright ComCon,

32 A (very) simple CGI program To "call" the program Enter the URL associated with the CGI program in the browser - For program HELLOTHERE on the iseries known as iseries.comcon.com the entry could look like this: The program then writes HTML to "standard out" This is done through the use of the API QtmhWrStout This is the result of running the program We will look at the details behind this program in the next few charts. The program should be compiled and placed in a library referenced by a ScriptAliasmatch statement in your HTTP configuration file. The statement will be something like this: ScriptAliasMatch ^/cgi-bin/(.*) /QSYS.LIB/libname.LIB/$1.PGM This will cause all (indicated by the ^") URL requests to cgi-bin to be directed to programs in the library libname. This should be the name of the library in which your CGI program resides. Once you have made this change to your HTTP configuration file, you will need to stop and restart the appropriate HTTP server configuration. You can then run the program by entering the URL: For example. If we assume that the program is called HELLO and it resides in a library named CGISEMINAR on the iseries known as AS400.MIDCS.COM, then if the entry ScriptAliasMatch ^/cgi-bin/(.*) /QSYS.LIB/CGISEMINAR.LIB/$1.PGM has been added to the HTTP configuration file, the URL to be used to "call" the program would be: Copyright ComCon,

33 The CGI program source D Specs These are the H and D spec in the "HelloThere " program These would normally be placed in standard copy members H Option(*SrcStmt : *NoDebugIO) H DftActGrp(*No) BndDir('*LIBL/CGIBNDDIR') D WriteWebData Pr ExtProc('QtmhWrStout') D Data Like(WebData) D Length 10I 0 Const D Error Like(APIError) D APIError DS Qualified D BytesP 10I 0 INZ(%Len(APIError)) D BytesA 10I 0 D MsgID 7 D Reserverd 1 D Data 40 D WebData S 2048 D NewLine C X'15' The service program QHTTPSVR/ QZHBCGI has been included in the binding directory. All of the CGI APIs have to have prototypes since they are procedure calls. The APIError data structure is the standard error data structure that is used with most APIs. The NewLine constant has a hex value of 15 which is a carriage return/linefeed. You need it at the very start of a web page and if you want the HTML source to be legible if you view it in a browser. Copyright ComCon,

34 The CGI program source This is the mainline of the "HelloThere " program The Content-type: text/html followed by two carriage return/line feed must be the first string written to the HTTP server. /Free WebData = 'Content-type: text/html' + NewLine + NewLine + '<html><head><title>' + NewLine + 'Test RPG CGI' + NewLine + '</title></head><body>' + NewLine + 'Hello There! Well Done!! You have managed to ' + 'connect to a working RPG CGI Program' + NewLine + '</body></html>' + NewLine; WriteWebData(WebData : %Len(%Trim(WebData)) : APIError); *INLR = *On; /End-Free The first thing we write is the HTTP header ('Content-type: text/html'+ NewLine + NewLine) the two carriage return/line feed are very important. This informs the browser that the data that follows is to be treated as HTML. The HTML for the web page is added and the data is then written to the standard output (i.e. the web page) using the QtmhWrStout API. The QtmhWrStout API may be called multiple times to build the web page. Copyright ComCon,

35 A Simple Report How about a standard listing? The easiest way to achieve a listing is to use a table. This is where you start to see some of the benefits of HTML since you do not have to provide starting positions or offsets. Copyright ComCon,

36 The List Program 1 of 4 D Specs are as in HelloThere + program work fields Start by writing page and table headings WebData = 'Content-type: text/html' + NewLine + NewLine + '<html><head><title>sample of CGI List></title>' + '</head><body><center>' + '<B> Product list as at ' + %editc(udate:'y') + ' - Days Since Last Order</b>' + '</center><br><center>' + '<table border=1 CellSpacing=2 ' + 'CellPadding=2 Width="80%">' + NewLine + '<b><th>' + 'Product<br>Code' + '<b><th>' + 'Description' + '<th>' + 'Category<br>Code' + '<th>' + 'Landed<br>Cost' + '<th>' + 'Selling<br>Price' + '<th>' + 'Date Last<br>Ordered' + '<th>' + 'Days Since<br>Last Ord' + '</b>' + NewLine; WriteWebData(WebData : %Len(%Trim(WebData)) : APIError); The equivalent of writing page headings at the start of the program is to write the start of the web page along with the table headings. Again, the first thing we write is the HTTP header ('Content-type: text/html'+ NewLine + NewLine) the two carriage return/line feed are very important. Copyright ComCon,

37 The List Program 2 of 4 Loop through the Product File Perform any business logic for record. // Loop through Product File; Read PRODUCT1; DoW Not %EOF(PRODUCT1); If DtlOrd <> 0; LastSold = %Date(DtlOrd:*YMD); PrLOrdA = %Char(LastSold); NoDaysA = %Char(%Diff(%Date():LastSold:*D)); Else; PrLOrdA = 'No sales to date'; NoDaysA = 'No sales to date'; EndIf; The processing of the database file is as it would be in any print program. Copyright ComCon,

38 The List Program 3 of 4 Print a line by adding a row to the table. Get the next record. WebData = NewLine + '<tr align=right>' + '<td>' + ProdCd +'</td>' + '<td align=left>' + ProdDs +'</td>' + '<td>' + CatCod + '</td>' + '<td>' + %Char(LndCst) + '</td>' + '<td>' + %Char(SellPr) + '</td>' + '<td>' + PrLOrdA + '</td>' + '<td>' + NoDaysA +'</td></tr>'; WriteWebData(WebData : %Len(%Trim(WebData)) : APIError); Read PRODUCT1; EndDo; Instead of writing a record to a print file, construct a row of the table and write it. Remember, you cannot concatenate numeric fields so you must use one of the conversion BIFs (%CHAR, %EDITC etc.). Copyright ComCon,

39 The List Program 4 of 4 Write the closing tags at program end. WebData = '</center></table></body></html>'; WriteWebData(WebData : %Len(%Trim(WebData)) : APIError); *InLR = *On; Copyright ComCon,

40 A Simple Report with a Face Lift This is the same report as the previous example but the background has changed and there is now a picture of each product. Copyright ComCon,

41 Coding Changes for a Face Lift Change the HTML for Inclusion of a Cascading Style Sheet. + '<html><head><title>sample of CGI List></title>' + '<link rel="stylesheet" type = "text/css" ' + 'href="/stylesheet.css">' + '</head><body><center>' A blank column heading + '<b><th>' + 'Description' + '<th>' + '<th>' + 'Category<br>Code' A link to an image whose name is based on the product code. + '<td align=left>' + ProdDs +'</td>' + '<td><img border=0 width=40' + ' height=30 src="/images/p' + ProdCd + '.JPG"></td>' + '<td>' + CatCod + '</td>' The background is provided by a cascading style sheet. A blank column heading is included where the picture will be. Am image link is included for the picture. All pictures are stored as JPG images and the name is P with the product code (e.g. P JPG is the picture of product ). All entries are relative to the Document Root configured for the server. i.e. StyleSheet.css and the directory Images are in the directory www/rpgbrowse/htdocs Copyright ComCon,

42 The next step Reports will rarely fit on a single page So we need to have a way to page through the data But basic CGI sessions are not conversational i.e. there is no direct program/user relationship So you can't rely on program variables or the file's position to tell you what record to read next The programmer must maintain state information One way of doing this is to include additional data in the output HTML - This can be done through the use of "invisible" fields Or by including the relevant key value in the "Next Page" link - The data is appended to the URL This is known as a Query String - This is the way that our example works Other methods involve using Javascript, Cookies, or persistent CGI A CGI program can be called from a link! Because many (most?) reports will go beyond a single page, we need to accommodate the ability to "Page" through the report. The operational sequence is as follows: User requests initial page by entering URL The program retrieves the Query String by calling the QtmhGetEnv API. On the initial call the API will return a length of zero (i.e. there was no Query String). The program formats and sends the first page, Including the key of the next record on the "Next Page" link. The User presses the "Next Page" link. This time when the program calls the API it will receive the query string (i.e. the data that the program included in the page link). The program extracts the key from the query string, positions the file, formats the page and... We could also have included a "Previous Page" link - It is just a "simple matter of programming"!! Copyright ComCon,

43 The program will expect a parameter Since CGI sessions are not conversational, we need to pass parameters when we call the CGI program. Do not confuse these parameters with the parameter lists that we are used to in RPG IV! Parameters are passed as a string, directly after the program name, in the format //server/directory/programname?parm1=value&parm2=value&parm3=... the first parameter follows the?. each parameter is followed by a parameter name. each parameter is assigned a value (=). following parameters are delineated by an &. there is no predefined sequence to parameters and they are optional it is possible to have the same parameter name multiple times. Copyright ComCon,

44 Paging a Report Copyright ComCon,

45 Add the QtmhGetEnv API Add a prototype for QtmhGetEnv Add required work fields. D GetEnvData Pr ExtProc('QtmhGetEnv') D EnvData Like(InputData) D AvailLen 10I 0 Const D ReturnedLen 10I 0 D EnvName 30A Const D EnvNameLen 10I 0 Const D Error Like(APIError) D InputData S 1000A D Inputlen S 10I 0 D QUERYSTRING C 'QUERY_STRING' Copyright ComCon,

46 Check for parameters Use QtmhGetEnv to get any passed parameters If so, use it to set lower limits on the product file. Otherwise, get the first record off the product file. Use ReadE to read records for the required category. GetEnvData(InputData : %Len(InputData) : InputLen : QUERYSTRING : %Len(QUERYSTRING) : APIError ); If InputLen = 0; Setll *Loval Product2; Read Product2; Else; CatCod = %Subst(InputData:6:2); EndIf; SetLL CatCod Product2; ReadE CatCod Product2; Chain CatCod Categor1; Copyright ComCon,

47 Ready the Next link Before ending, check if there are any more records on file If so, add a link for the program with a parameter for the next category code (cgilist03?code=xx). Otherwise, just ignore the link. WebData = '</table></center>' + NewLine; SetGT CatCod Product2; Read Product2; If Not %EOF(Product2); WebData = %Trim(WebData) + '<A HREF="/cgi-bin/cgilist03?Code=' + CatCod + '"> Next Page </A>' + NewLine; EndIf; WebData = %Trim(WebData) + '</body></html>'; WriteWebData(WebData : %Len(%Trim(WebData)) : APIError); *InLR = *On; Copyright ComCon,

48 But now it gets ugly The real difficulty comes with multiple parameters (regardless of whether they are sent using GET or POST) Parameter strings have special characters and blanks replaced. Consider the following parameter string - Spaces are replaced by a + - Special characters are replaced with a hex code e.g. / is replaced with %2F And do you really want to have all that HTML in your RPG program? So why waste time mastering the APIs use CGIDEV2! www-922.ibm.com cgiprodcd= &cgiprodds=philips+screwdrivers&cgicatcod=27 &cgistoh=21&cgilndcst=120.00&cgisellpr=130.00&cgidatea=05%2f01%2f99 &cgioption=change This really is as far as you should go with the CGI APIs. You should now have the basic principle of what is going on. But won t it be a lot nicer to have your HTML externally defined, not have to convert parameter strings, not have to determine if the page was sent using GET or POST and a myriad of other issues that have not been mentioned. Copyright ComCon,

49 Ready to go To get RPG talking to the web. Configure the server Start the server Write the programs Copyright ComCon,