Switch to Italian
Giovanni's logo
Externally defined HTML

"The same power and flexibility as an externally defined Display File!"

 this means Version 2
index
M
power search
blue line
To provide an answer from your program to the web user, your program should send out an HTML string.

In a RPG program, without using Mel's service program, you should prepare your html string and write it out using the Write to Stdout (QtmhWrStout) API. Preparing such a string in a program, while not easy, suffers of unflexibility. Any time you want to change something in the output HTML (texts, fonts, alignments, href, gifs, etc.), you must change your program.

In a normal AS/400 program you would have greater flexibility just using an externally defined display file.

Mel's service program provides a technique as flexible as DDS, but even simpler to use.
This technique is called

Externally defined HTML

There are two ways you can develop external HTML

  1. using a source physical file (for beginners)
  2. using IFS stream files (recommended)
blue line
1. Using a source physical file

This is how you implement it (it takes more to tell than to use it):

  1. Create a source physical file named HTMLSRC (record format name MUST be HTMLSRC) with record length 240 (MUST not be more than 240). You may then rename this source physical file, if you want; its record format would still be HTMLSRC.
    Note 1. A file HTMLSRC is automatically created in your object (production) library when you use command setcgilib.
  2. Add a member named as you like (we recommend to specify HTML for the SEU type).
  3. Divide your source into sections.
    • In a sense, a section is the same as a record format in a display file.
      A section is a single piece of html your program will output under given conditions.
      Examples of sections could be
      • starting html, starting body, defining title and headers
      • a table start
      • a table row
      • a table end
      • body and html end
    • A section is identified by a source record containing
      • /$section_name starting in column 1, where section_name can be up to 20 characters (Prefix /$ is the standard one for section identification; however, the developer may define other prefixes.
        As a matter of fact, our developer decision was NOT to use that /$ default, but to use the section identifier <as400> instead. In our experience it provides better results when undergoing automated CCSID conversion.)
      • <as400>top, for instance, identifies the beginning of section top.
    • The section which is issued as first must start as follow
      <as400>section_name
      Content-type: text/html

      <html>
      Please pay attention to the blank line just before the one containing <HTML>. If you miss it, the client browser may not interpret your html and respond with error code 500!
      • NOTE - The Content-type is a so called http header. HTTP headers instruct the browser about its behavior. HTTP headers must be at the beginning of a script. They end with two consecutive CRLF (Carriage Return Line Feed) control sequences (this explains why an empty line is needed to end the HTTP headers).
        For a complete list of HTTP headers, see this page.
  • HTML texts in your sections may contain variables. A trivial case is that of a table row (subfile line) with table definitions <TD> (subfile line fields) containing variables, such as item and price
    • You specify a variable in your html text by using the following syntax
          /%variable_name%/
      where variable_name can be up to 30 non-case sensitive characters. Delimiters /% and %/ are the standard ones. However, the developer may decide to use his own delimiters.
      There is no naming convention for variables. For instance, they do not need to have the same name of their corresponding database fields, though if you do so you may improve understanding of your programs.
  • Your CGI program will
    1. Read the external html source member into memory using Mel's service program subprocedure gethtml.
    2. Fill the html /%variables%/ (which are character fields in your RPG) from e.g. database records fields using updhtmlvar subprocedure.
    3. Call subprocedure wrtsection to output html sections.
  • Section and variable delimiters
       
    1. Section name delimiters.
      A section is identified by the following sequence starting in column 1 of a dedicated line:
      xxxsection_nameyyy
      where
      • xxx is the section name starting delimiter (10 char max) that you would mention in the RPG program when calling subprocedure gethtml.
        The default section name starting delimiter is /$. This default section name starting delimiter may be omitted when calling subprocedure gethtml.
        Note- Instead of the default prefix /$, we - as developers - preferred using prefix <as400>. In such a case, this prefix must be specified when calling subprocedure gethtml.
      • section_name is the name of the section (mandatory) that you would mention when calling subprocedure wrtsection. Section name must be an alphanumeric string up to 20 characters.
      • yyy is the section name ending delimiter (optional, 10 char max). If specified, you must mention it in the RPG program when calling subprocedure gethtml.
      Notes on section name delimiters
      1. Default section name starting delimiter /$ may cause problems when the external HTML is on the IFS. This is because character $ may not be correctly converted for the CGISRVPGM2 service program.
      2. We suggest you use
        • <as400>, OR
        • "<! -- Sec_" as section name starting delimiter
          and " -->" as section name ending delimiter.
          Example:
          <! -- Sec_top -->
          for section top.
          This approach defines the HTML section as a comment and is therefore transparent to the HTML editors.
       
    2. Variable name delimiters
      The default starting and ending delimiters for a variable name are
            /% and %/
      User-defined delimiters can also be used, provided thay do not exceed 10 characters.
      Non-default variable delimiters must be specified as parameters to the gethtml subprocedure.

  • The following restrictions apply:
    Description Maximum
    Source record length 240 bytes (228 bytes for source data)
    Number of records 32,764
    Number of unique substitution variables (each may appear multiple times in the source) 16,221
    Number of occurrences of substitution variables in the source file member 32,767
    Substitution variable name length 30 characters
    Substitution variable value 1,000 characters
    Substitution variables' delimiters length 10 characters
    Number of sections 200
    Section name length 20 characters
    Section name delimiters' length 10 characters
    blue line
    2. Using IFS stream files

    Instead of writing the external HTML in members of a source physical file, you could decide to create PC files (stream files) in one or more directories of the OS/400 Integrated File System (IFS). This approach may have some advantages:

    1. the restriction of 228 characters per line no longer applies (the other restrictions stay the same)
    2. it would be possible design external HTML scripts using HTML authoring tools, such as Microsoft Front Page, IBM Websphere Studio, or other.
    Performance would be the same as for members of a physical file.

    Directories containing externally defined HTML:
    • do not require any HTTP directive to be accessed
    • for performance reasons, it is recommended to store the external HTML files in directories different from the ones accessed from the HTTP server (such as the directories containing static HTML pages and/or images).
    blue line
    Examples
    1. Giovanni's html skeleton member using <as400> section name delimiter
    2. Mel's html skeleton member using <AS400> section name delimiter