.XML IMPORT

This subroutine processes an XML file and optionally imports it.

Usage:

      SET      0DX .XML IMPORT                =
      PASS         <key>                      FIELD            SHARE? Y
      PASS         <XML_file>                 FIELD            SHARE? N
      PASS         <XML_Map>                  FIELD            SHARE? N
      PASS         <Import_Flag>              FIELD            SHARE? N
      PASS         <Delete XML File>          FIELD            SHARE? N
      PASS         <Create XVALUE>            FIELD            SHARE? N
      SUBR     0DX .XML IMPORT                      DETACHED     END? N  FAIL 0
      *        Check for errors
      IF       0DX .XML IMPORT                NE                  

Description:

This subroutine processes an XML file and optionally imports it. The first 2 parameters are required. If any required parameters are missing, the subroutine will CANCEL.

<key> is the numeric key that will be assigned to this import (Required). This must be PASSed with Share "Y" to return the value.

<XML_file> is the XML file to be processed and optionally imported (Required). This must be a file accessible to the Appx session on the server.

<XML_Map> is the mapping to use (Optional). If PASSed, must refer to a previously defined mapping. If you want the API to import your data, the mapping must include a subroutine name and the subroutine must exist. If you are planning to process the extracted identifiers and data yourself, you do not need to pass a map name.

<Import_Flag> A Y/N flag to indicate if the data import subroutine specified on the mapping should be run (Optional). If you pass Y, you must pass a valid Map Name in the previous parameter.

<Delete_Flag> A Y/N flag to indicate if the XML Source File should be deleted (Optional - Release 5.4 and later only). This flag is not present in releases 5.3.3 and earlier, your XML file will be automatically deleted. In 5.4 and up, if you do not pass this flag, the XML Source File will not be deleted.

<Create XVALUE> A Y/N flag to indicate if the XVALUE file should be created (Optional - Release 5.4.3 and later only). This flag is not present in releases 5.4.2 and earlier, the 0DX XVALUE file will always be created. For performance reasons, you may want to skip creating the XVALUE file and read the RAWXML and RAWXMLAT files direclty yourself.

After the API is complete, your extracted data will be available in the 0DX XVALUE file (or the RAWXML/RAWXMLAT files if you did not create the XVALUE file). This is true, regardless of whether the API imported the data or not. The XVALUE, RAWXML and RAWAMLAT files are keyed on the <key> that is returned from the API. Remember that there can be more than one imported file in these, you should use <key> in a BEG AT/END AT to only read the data records for this import. Note that you can manage the amount of data in these work files via the .XML PURGE API.

XVALUE, RAWXML and RAWXMLAT are temporary files and the contents will be lost when the session ends.

NOTE: This subroutine must be invoked DETACHED, and cannot be invoked via GOSUB. The 0DX .XML IMPORT field must be intialized in your process before invoking the API, or you will not get a return value.

Comments:

Read what other users have said about this page or add your own comments.

IMPORTANT - In APPX versions up to and included 5.3.3, this subroutine will DELETE the original XML file. So if this is not the desired behavior, designers should make a copy of the file first, and pass the path to the copy instead of the original.

-- AlKalter - 2014-10-03

-- JeanNeron - 2013-10-02