ELowell at 21:46, 5 January 2016

2016-01-05T21:46:26Z

JAL at 23:56, 10 October 2014

2014-10-10T23:56:28Z

JAL2: Created page with " Using `Janus Web Server` it is possible to create complete web applications using only the `Model 204` editor. With the 2011-10-25T00:30:30Z Created page with " Using <var class="product">Janus Web Server</var> it is possible to create complete web applications using only the <var class="product">Model 204</var> editor. With the <var c..." New page Using <var class="product">Janus Web Server</var> it is possible to create complete web applications using only the <var class="product">Model 204</var> editor. With the <var class="product">Model 204</var> editor, it is possible to create static HTML pages and <var class="product">User Language</var> procedures that dynamically generate HTML and that accept input from HTML forms. There might be a need, however, to include binary data generated outside of <var class="product">Model 204</var> in an application. This data can include graphical images, audio data, java applets and many other workstation generated binary datatypes. Furthermore, it might be desirable to generate static HTML pages using an HTML editor, some other workstation based editor or even a mainframe editor outside of <var class="product">Model 204</var>. All these cases raise the issue of how the data generated outside of <var class="product">Model 204</var> can be loaded into <var class="product">Model 204</var> procedures. Since <var class="product">Model 204</var> procedures are generally expected to contain text data, there is also an issue of how binary, non-text data can be stored in a <var class="product">Model 204</var> procedure. This problem is solved by <var class="product">Janus Web Server</var> with the use of special format procedures that allow the storing of data as either binary or base64 encoded data. To keep these procedures from causing problems in <var class="product">Model 204</var>, the data is "wrapped" with some character data that is stripped by <var class="product">Janus Web Server</var> when the data is downloaded as part of a web request. More information on producing these special format procedures is available in [[#Loading with the SIRPIPE and SIRPUT Utilities|"Loading with the SIRPIPE and SIRPUT Utilities"]], [[#HTTP PUT support|"HTTP PUT support"]], and [[#Form-based uploads|"Form-based uploads"]]. Historically, two mechanisms were mainly used for moving data from outside of <var class="product">Model 204</var> into procedures: <ul> <li>Placing data into a BATCH2 (or BATCH204) stream between a <var>PROCEDURE</var> and <var>END PROCEDURE</var> statement. <li>Using <var>READ IMAGE</var> and <var>$BLDPROC</var> to create <var class="product">Model 204</var> procedures. </ul> The latter mechanism can be quite cumbersome, so it is not discussed further. The former mechanism has some problems uploading binary or text data that has long records (lines), which are often created by HTML-generating packages. The SIRPIPE and SIRPUT utilities were designed for loading binary and text data into <var class="product">Model 204</var>. SIRPIPE uses BATCH2 or BATCH204 to load the data, while SIRPUT uses HTTP PUT. With these utilities, moving data from a workstation to <var class="product">Model 204</var> is a two-step process: <ol> <li>A file upload program moves the data from a workstation to an operating system file. Since any site using <var class="product">Janus Web Server</var> will have a TCP/IP package on the host mainframe, FTP is probably the best of the many ways to transfer files from a workstation to a mainframe (FTP, IND$, 3270 emulator uploads, PCTRANS, Kermit, etc.). <li>SIRPIPE or SIRPUT moves the data from the operating system file into <var class="product">Model 204</var>. For information about using SIRPIPE and SIRPUT, see [[#Loading with the SIRPIPE and SIRPUT utilities|"Loading with the SIRPIPE and SIRPUT utilities"]]. </ol> While an FTP plus SIRPIPE or SIRPUT, batch-based, transfer mechanism is very flexible, it generally requires that any transfer be initiated from the mainframe. This might not be a good solution at sites where it is desirable to allow programmers, web designers, and end-users to upload data directly from their workstations. To service workstation-initiated file transfers, <var class="product">Janus Web Server</var> provides HTTP PUT support and "form-based file upload" support, as described in the following sections. An additional alternative, comparable or superior to these methods, is the [[Janus FTP Server]], which lets you upload and download directly to and from <var class="product">Model 204</var> procedure files. Not a <var class="product">Janus Web Server</var> feature, the Janus FTP Server requires that you be licensed for <var class="product">[[Janus Sockets]]</var> and <var class="product">[[Janus TCP/IP Base]]</var> and be running the <var class="product">[[Sirius Mods]]</var>. ==HTTP PUT support== HTTP PUT support adds Web Server handling of the '''PUT''' method, which calls for an upload to the server of the data in the request. With PUT support, you can use <var>[[JANUS WEB ON]]</var> rules to control the uploading of files to <var class="product">Model 204</var>, as described in [[Defining Web rules|"Defining Web rules"]]. You can programmatically control HTTP PUT file uploads with <var>JANUS WEB ON</var> rules and the <var>[[$Web_Proc_Receive]]</var> and <var>[[$Web_List_Receive]]</var> functions. Since the PUT method is part of the HTTP 1.1 standard, it is expected that most vendors of HTML editors and perhaps browsers will ultimately support this method. As of this writing, HTTP PUT is supported on most web servers and by Perl, PHP, Python and the other popular web development languages. but is not widely accessible on web clients. ==Form-based uploads== An alternative approach to uploading files to a <var class="product">Janus Web Server</var> is form-based uploads. Form-based uploads work in conjunction with HTML forms. An HTML form can have in input field with a type of "file." The content of such a field is the name of a file (including disk and path information), and when the form is submitted, the contents of the named file, as well as the name of the file, are sent to the web server. The following is an example of HTML that generates a form that allows the upload of a single file that defaults to a file called <code>capture.dat</code>: <p class="code"><form method=POST enctype="multipart/form-data"> <input type=FILE name=indata value="C:/upload/capture.dat"> <br> <input type=SUBMIT value="Upload file"> </form> </p> Note especially the <code>enctype</code> attribute in the <code>form</code> tag. This is required because the default form encoding, <code>application/x-www-form-urlencoded</code>, does not allow file uploads. <var class="product">Janus Web Server</var> automatically handles the different encoding mechanisms for form data, so other than specifying the appropriate <code>enctype</code> when form-based file uploads are to be used, an application programmer need not be concerned about the encoding mechanism. An <code>enctype</code> of <code>multipart/form-data</code> can be used even if no <code>type=file</code> input fields are present in the form, but this is a slightly less efficient way of representing a form than the default encoding mechanism of <code>application/x-www-form-urlencoded</code>. The form encoding mechanism can be queried with the <var>[[$Web_Hdr_Parm]]</var> function, as in the following: <p class="code">If $web_hdr_parm('content-type') Ne 'MULTIPART/FORM-DATA' Then %rc = $web_done(400, 'Invalid upload type') Stop End if </p> Since form-based file uploads are part of both the HTTP and HTML standards, it is quite likely that most browsers already support this mechanism. A limitation of this technology is that some implementations of the <code><input type=file></code> tag by ''Internet Explorer'' essentially ignored the default value (file name). This might be viewed as a security feature since it prevents a malicious server from presenting a user with a form with a file upload buried in the middle that uploads a secure file from the browser's machine. If the user doesn't notice that this is being done on the form, the secure file could be blindly uploaded to the malicious server. In theory, this security hole could be dealt with by displaying a pop-up window that warns the user which file is being uploaded and gives the user a chance to cancel the request. It is not currently known if this type of warning system has been or will be implemented in ''Internet Explorer'' or other browsers. A form-based upload might always bear the inconvenience of forcing the end-user to pick out the uploaded file at each invocation. Another weakness of form-based uploads is that each <code><input type=file></code> tag can only be associated with a single file. There is no easy way to upload the entire contents of (or several files in) a directory. While multiple <code><input type=file></code> tags can be present in a form so that multiple files can be uploaded with a single request, each file must be individually selected by the end-user. A final weakness of the form-based file upload approach is that since it is part of a form, it must be processed by <var class="product">User Language</var> and cannot be processed with simple <var>JANUS WEB ON ... RECEIVE</var> rules. <var class="product">User Language</var> can process files being uploaded as part of a form-based upload with some special purpose $functions, which are described in <var>[[$Web_Proc_Receive]]</var> and <var>[[$Web_List_Receive]]</var>. Despite these weaknesses, form-based file uploads present the simpler option for allowing untrained end users to upload files to a web server as part of an integrated web application, especially when the upload consists of only a very few files. For relatively frequent uploads of, say, more than five files, the option of choice is the Janus FTP server. ==Janus FTP Server== Another option for uploading files to <var class="product">Model 204</var>, for use on the web (or for any other use), is the FTP feature of <var class="product">Janus Sockets</var>. The Janus FTP Server lets you use any standard FTP client to upload one or a set of files in a directory to a <var class="product">Model 204</var> file, storing the uploaded files as <var class="product">Model 204</var> procedures. To implement the FTP feature, you use <var class="product">User Language</var> to define the following, the details for which are provided in [[Janus FTP Server|"Janus FTP Server"]]: <ul> <li>A <var class="product">Janus Sockets</var> port with the special type <var>[[JANUS DEFINE#type|FTPSERVER]]</var> <li>Web server rules specific to the upload location </ul> The following sample definition deck creates and starts a Janus FTP Server port called <code>MYFTP</code>: <p class="code">JANUS FORCE MYFTP JANUS DELETE MYFTP * FTP server on port 3205 JANUS DEFINE MYFTP 3205 FTPSERVER 4 CLIENTSOCKET FTPDCLIENT - AUDTERM PASVPORT 3001 BINDADDR 198.242.244.100 * Client port definition for active transfers JANUS DEFINE FTPDCLIENT * CLSOCK 5 REMOTE SOCKPMAX 5 JANUS CLSOCK FTPDCLIENT ALLOW * FTP access to MYPROC JANUS FTP MYFTP ASSIGN /MY TO FILE MYPROC * Permissions JANUS FTP MYFTP ALLOW /MY WRITE TO USER CARTMAN * Set the home folder JANUS FTP MYFTP HOME /MY TO ALL JANUS START MYFTP JANUS START FTPDCLIENT </p> In this example: <ul> <li>The <code>MYFTP</code> port defined above runs on port 3205 on machine 198.242.244.100. The port definition includes a specification (<code>PASVPORT</code>) to support passive FTP transfers for clients that require that mode. <li>The <code>FTPDCLIENT</code> port is defined to support active FTP transfers for clients that require that mode. <li>The <var>[[JANUS FTP#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]</var> command maps the directory orientation seen by an FTP client onto the <var class="product">Model 204</var> file and procedure structure that actually exists in <var class="product">Model 204</var>. In this example, the <var>FTP ASSIGN</var> command maps the folder <code>/MY</code> to the file <code>MYPROC</code>. Any file uploaded to the <code>/MY</code> directory becomes a procedure in file <code>MYPROC</code>. <li>The user <code>CARTMAN</code> is the only user allowed to upload to the port, as defined by the <var>[[JANUS FTP#JANUS FTP ALLOW|JANUS FTP ALLOW]]</var> command. <li>The "home folder" <code>/MY</code>, defined by the <var>[[JANUS FTP#JANUS FTP HOME|JANUS FTP HOME]]</var> command is the folder into which the user is automatically placed when they connect to the port. </ul> Once these <var class="product">User Language</var> statements are executed in the <var class="product">Model 204</var> online, client FTP users anywhere can connect to the Janus server port and execute PUTs or their GUI equivalents for the files they want to upload. FTP clients will need both the host ID (198.242.244.100) and port (3205) of the FTP server to connect. Command line clients, for example, might use: <p class="code">open 198.242.244.100 3205 </p> Users can upload files containing binary or text information. The FTP Server correctly handles the type of upload that the client FTP package indicates. By default, the server assumes type <code>A</code> (ASCII, with translation to EBCDIC) until notified otherwise. Users can upload multiple files at a time, executing MPUTs with a command-line client or taking GUI-equivalent measures. And users can upload entire directories and subdirectories (if and only if a matching directory structure is predefined for the server). The dynamic creation of directories (FTP protocol MKD command) is not currently supported by Janus FTP. For uploading individual files or sets of files, Janus FTP is a fast and convenient utility, suitable for any type of user. ==How uploads work with Janus Web Server== Whether HTTP PUT or form-based upload is being used, <var class="product">Janus Web Server</var> copies the file being uploaded into CCATEMP. This way, if a network or browser problem prevents the entire file from being transferred, the request can simply be discarded without a risk of leaving partial data in a procedure. Once all the data from a request has been received into <var class="product">Model 204</var>, the web rules are scanned to determine the appropriate action. If the upload was the result of an HTTP PUT, and the appropriate action ("RECEIVE") is indicated in a <var>JANUS WEB ON</var> rule, the file is simply copied into the target procedure, perhaps being converted to the special <var class="product">Janus Web Server</var> binary or base64 formats if the input file consists of binary non-text data. If the <var>JANUS WEB ON</var> rule associated with the upload request indicates that a command should be executed, or if the request is a form-based upload, <var class="product">User Language</var> $functions (<var>[[$Web_Proc_Receive]]</var>, <var>[[$Web_List_Receive]]</var>) can be used to upload the file(s) into a procedure or into a [[$lists|$list]]. When a procedure is being updated either as the result of a <var>JANUS WEB ON</var> rule or a <var>[[$Web_Proc_Receive]]</var> function, <var class="product">Janus Web Server</var> attempts to get an exclusive lock on the procedure before doing the update. If it is unable to obtain an exclusive procedure lock, the request fails. The exclusive lock is only held while data is copied from CCATEMP to the procedure. This means two things: <ol> <li>Once the copy operation is started, it will complete regardless of the status of the connection with a browser. Put another way, there is no danger of an HTTP PUT or form-based upload leaving around a partial procedure. <li>The exclusive lock on a procedure is generally held very briefly (typically a few milliseconds), so it is not likely to disrupt download operations for the same procedures. </ol> '''Note:''' Although the preceding discussion concerns <var class="product">Janus Web Server</var> handling of HTTP PUT and form-based uploads, the Janus FTP Server handling of uploaded files uses CCATEMP and locking in the same way to safeguard your procedures. ==Choosing the correct upload method== There are many options for doing file upload to <var class="product">Model 204</var> with <var class="product">Janus Web Server</var>. None of them is perfect and each has its advantages. The following table summarizes the advantages and disadvantages of each technique to help determine the correct technique for any application. <table> <tr><th>FTP and SIRPIPE|SIRPUT </th><td> <table> <tr><th>Advantages </th><td>Easy to configure and automate. Can be initiated from mainframe. Not dependent on any browsers. </td></tr> <tr><th>Disadvantages </th><td>Cannot be initiated from a workstation. BATCH2 is extremely slow, so SIRPUT is preferred to SIRPIPE. </td></tr> <tr><th>Likely users </th><td>System administrators, operators (running canned procedures), and mainframe-oriented developers. </td></tr> </table> </td></tr> <tr><th>HTTP PUT </th><td> <table> <tr><th>Advantages </th><td> Can upload entire directories. Can be initiated from a workstation. Can be set up without programming in <var class="product">Model 204</var>. </td></tr> <tr><th>Disadvantages </th><td>Not widely supported beyond ''Netscape Composer''. Can't be integrated into web application. Some training required. </td></tr> <tr><th>Likely users </th><td>Web developers and designers. </td></tr> </table> </td></tr> <tr><th>Form-based upload </th><td> <table> <tr><th>Advantages </th><td> Can be integrated into web applications. Little or no training required. </td></tr> <tr><th>Disadvantages </th><td>No way to upload directories or groups of files. Some <var class="product">User Language</var> programming is required to set it up. </td></tr> <tr><th>Likely users </th><td>End-users. </td></tr> </table> </td></tr> <tr><th>Janus FTP Server </th><td> <table> <tr><th>Advantages </th><td>Fast transfers, including both uploads and downloads. Can be initiated from a workstation. Easy-to-use interface. Can upload multiple files and directories. </td></tr> <tr><th>Disadvantages </th><td>Can't be integrated into web application. Must be set up with <var class="product">User Language</var> programming. Might need to acquire an FTP client tool. Requires <var class="product">Janus Sockets</var>. Can't dynamically create subdirectories. </td></tr> <tr><th>Likely users </th><td>Web developers, designers, and end users. </td></tr> </table> </td></tr> </table> [[Category:Janus Web Server]]

Uploading files to a Janus Web Server - Revision history

ELowell at 21:46, 5 January 2016

JAL at 23:56, 10 October 2014