Declaring XML host variables in ILE RPG applications that use SQL

ILE RPG does not have variables that correspond to the SQL data type for XML.

To create host variables that can be used with this data type, use the SQLTYPE keyword. The SQL precompiler replaces this declaration with an ILE RPG language structure in the output source member. XML declarations can be either standalone or within a data structure.

XML host variables in ILE RPG applications that use SQL

Here are some examples of XML host variables in ILE RPG applications.

It is recommended that the CCSID keyword be used on the XML_CLOB or XML_DBCLOB declaration to explicitly indicate the CCSID to the RPG compiler.

XML AS CLOB example

  • The following declaration in free-form:
      DCL-S MYXMLCLOB SQLTYPE(XML_CLOB:3000) CCSID(37);
    results in the generation of the following structure:
      DCL-DS MYXMLCLOB;           
        MYXMLCLOB_LEN UNS(10);    
        MYXMLCLOB_DATA CHAR(3000) CCSID(37);
      END-DS MYXMLCLOB;    
  • The following declaration in fixed-form:
      D MYXMLCLOB       S          SQLTYPE(XML_CLOB:3000)
    results in the generation of the following structure:
      D MYXMLCLOB       DS
      D MYXMLCLOB_LEN              10U
      D MYXMLCLOB_DATA           3000A  

XML AS DBCLOB example

  • The following declaration in free-form:
      DCL-S MYXMLDBCLOB SQLTYPE(XML_DBCLOB:400);

    results in the generation of the following structure:

      DCL-DS MYXMLDBCLOB;                            
        MYXMLDBCLOB_LEN UNS(10);                     
        MYXMLDBCLOB_DATA UCS2(400) CCSID(13488);     
      END-DS MYXMLDBCLOB;                             
  • The following declaration in fixed-form:
      D MYXMLDBCLOB       S          SQLTYPE(XML_DBCLOB:400)

    results in the generation of the following structure:

      D MYXMLDBCLOB       DS
      D MYXMLDBCLOB_LEN              10U
      D MYXMLDBCLOB_DATA            400C   

XML AS BLOB example

  • The following declaration in free-form:
      DCL-S MYXMLBLOB SQLTYPE(XML_BLOB:780);

    results in the generation of the following structure:

      DCL-DS MYXMLBLOB;                       
        MYXMLBLOB_LEN UNS(10);                
        MYXMLBLOB_DATA CHAR(780) CCSID(*HEX); 
      END-DS MYXMLBLOB;
  • The following declaration in fixed-form:
      D MYXMLBLOB       S          SQLTYPE(XML_BLOB:780)

    results in the generation of the following structure:

      D MYXMLBLOB       DS
      D MYXMLBLOB_LEN              10U
      D MYXMLBLOB_DATA            780A CCSID(*HEX)  
Notes:
  1. For XML_BLOB and XML_CLOB host variables, the length must be in the range 1 to 16 773 100.
  2. For XML_DBCLOB host variables, the length must be in the range 1 to 8 386 550.
  3. XML host variables are allowed to be declared in host structures.
  4. XML host variables are not allowed in host structure arrays. XML locators should be used instead.
  5. XML host variables declared in structure arrays cannot be used as standalone host variables.
  6. SQLTYPE, XML_BLOB, XML_CLOB, XML_DBCLOB can be in mixed case.
  7. SQLTYPE must be between positions 44 to 80 for fixed-form declarations.
  8. The CCSID value for an XML host variable can be explicitly set by using the CCSID keyword or the DECLARE VARIABLE statement. Otherwise, the value specified by the SQL_XML_DATA_CCSID QAQQINI option will be used. The default for this QAQQINI option is CCSID 1208.
  9. When XML is declared as a standalone host variable, position 24 must contain the character 'S' and position 25 must be blank for fixed-form declarations.
  10. The stand-alone field indicator S in position 24 for fixed-form declarations should be omitted when XML is declared in a host structure.
  11. XML host variables cannot be initialized.

XML locators in ILE RPG applications that use SQL

Here is an example of an XML locator.

XML locator example

  • The following declaration in free-form:
      DCL-S MYXMLLOC SQLTYPE(XML_LOCATOR);

    results in the following generation:

      DCL-S MYXMLLOC UNS(10); 
  • The following declaration in fixed-form:
      D MYXMLLOC        S          SQLTYPE(XML_LOCATOR)

    results in the following generation:

      D MYXMLLOC        S          10U
Notes:
  1. XML locators are allowed to be declared in host structures.
  2. SQLTYPE, XML_LOCATOR can be in mixed case.
  3. SQLTYPE must be between positions 44 to 80 for fixed-form declarations.
  4. When an XML locator is declared as a standalone host variable, position 24 must contain the character 'S' and position 25 must be blank for fixed-form declarations.
  5. The standalone field indicator S in position 24 for fixed-form declarations should be omitted when an XML locator is declared in a host structure.
  6. XML locators cannot be initialized.

XML file reference variables in ILE RPG applications that use SQL

Here is an example of a XML file reference variable in ILE RPG.

XML file reference example

  • The following declaration in free-form:
      DCL-S MY_XMLFILE SQLTYPE(XML_CLOB_FILE);

    results in the generation of the following structure:

      DCL-DS MY_XMLFILE;                            
        MY_XMLFILE_NL UNS(10);                      
        MY_XMLFILE_DL UNS(10);                      
        MY_XMLFILE_FO UNS(10);                      
        MY_XMLFILE_NAME CHAR(255);
      END-DS MY_XMLFILE;  
  • The following declaration in fixed-form:
      D MY_XMLFILE         S        SQLTYPE(XML_CLOB_FILE)

    results in the generation of the following structure:

      D MY_XMLFILE         DS
      D MY_XMLFILE_NL               10U
      D MY_XMLFILE_DL               10U
      D MY_XMLFILE_FO               10U
      D MY_XMLFILE_NAME             255A

XML_BLOB_FILE and XML_DBCLOB_FILE file reference variables have similar syntax.

Notes:
  1. XML file reference variables are allowed to be declared in host structures.
  2. SQLTYPE, XML_BLOB_FILE, XML_CLOB_FILE, XML_DBCLOB_FILE can be in mixed case.
  3. SQLTYPE must be between positions 44 to 80 for fixed-form declarations.
  4. When an XML file reference is declared as a standalone host variable, position 24 must contain the character 'S' and position 25 must be blank for fixed-form declarations.
  5. The standalone field indicator 'S' in position 24 for fixed-form declarations should be omitted when an XML file reference variable is declared in a host structure.
  6. XML file reference variables cannot be initialized.

The precompiler will generate declarations for the following file option constants. You can use these constants to set the xxx_FO variable when you use file reference host variables.

  • SQFRD (2)
  • SQFCRT (8)
  • SQFOVR (16)
  • SQFAPP (32)