To enable your program to read XML data:

Step 1: Prepare your ACUCOBOL-GT application

  1. Obtain a representative XML document from the anticipated source of your files. For the best results, the document should refer to a DTD or schema.
  2. Use the xml2fd utility to create FDs and SELECT statements for the XML document. See The XML-to-FD Utility for more information on using this utility.
  3. Include the new FDs and SELECT statements in your program as you would any FD and SELECT.
  4. Compile your program with the "-Fa" option specified. This option tells the compiler to generate XFDs for each COBOL data file included in the program. The "-Fa" option is described in Compiler File Options. To prevent naming errors, you should also include the "-Fc" option, which tells the compiler that the field names in the resulting XFDs must match the element names in the COBOL source exactly, including case, hyphen usage, etc.

Step 2: Set up and configure the runtime system

  1. Install the ACUCOBOL-GT runtime, object code, data dictionaries, and COBOL data files on the end-user system.
  2. Acquire XML data from your data source, or if reading data from the Internet, acquire the exact URL of the XML data stream.
  3. Create a configuration file for the runtime. In the configuration file:
    • Specify the location of your data files. If the files are local or accessed via AcuServer, use the FILE_PREFIX configuration variable to specify the location. If the files will be accessed over the Internet, map the data files directly to a URL. For example, to read "bookfile.xml" over the Internet, you could add the following line to the configuration file: 
      bookFILE  http://myserver.mycomp.com/data/bookfile.xml
    • Specify which files should be treated as XML data files by setting the filename_HOST variable to "XML", where filename is the base name of the XML document with no file extension (e.g., "custdata_HOST XML"). Include a separate entry for each XML document name. Make sure that the files you indicate are sequential files. For example: 
      bookFILE_HOST XML
    • Tell the runtime to keep the case of your XFD field names intact by setting the 4GL-COLUMN-CASE variable to "unchanged". XML (unlike HTML) is case sensitive. If you do not set 4GL-COLUMN-CASE, the runtime converts the field names to lower case and hyphens to underscores. Then the runtime may not be able to read your XML data properly.
    • Configure the XML output as desired using a set of AcuXML-specific configuration variables. (These variables all start with the "AXML" prefix. See AcuXML Configuration Variables.) With these variables, you can tell the runtime whether to create a DTD or schema when creating XML data, whether to associate a style sheet with the output, and more.
    • Perform additional configuration as desired. You can use any configuration variables that affect XFD parsing, such as XFD-PREFIX and XFD-DIRECTORY. Note that XFD files must be available in the named XFD_DIRECTORY even when the XML data stream is read over the Internet via HTTP.

    See Configuration Variables for details on any of these configuration file entries. Following is a sample cblconfig file for use with AcuXML: 

    file-prefix           . /usr/data
orderfile-host        xml
bookfile-host         xml
customer-host         xml
4gl-column-case       unchanged
  4. Run your ACUCOBOL-GT program normally.

The rest is automatic. When your ACUCOBOL-GT program READs a file designated as XML, the AcuXML interface converts the XML data to COBOL using XFDs, your program performs the request, and then returns data in desired format. Your program automatically WRITEs output in sequential XML format as specified in configuration file.

Parent topic: Using AcuXML