GET_MESSAGE存储过程

存储过程 GET_MESSAGE 根据 SQLCODE 返回短消息文本。

开始通用编程接口信息。

更改开始 GET_MESSAGE存储过程仅支持SBCS CCSID。也就是说，所有数据（输入和输出）必须以Unicode CCSID 367格式存在。更改结束

更改开始对片假名CCSID 290的支持有限。 xml_input文档中指定的任何用户特定信息（例如 SQLCODE 和 Message Tokens 的字符串输入）必须仅包含有效的EBCDIC CCSID 37字符，且这些EBCDIC字符必须在Unicode CCSID 367中存在。同样，任何转换为Unicode CCSID 367并写入xml_output文档的请求信息，也必须仅包含有效的EBCDIC CCSID 37字符，且这些EBCDIC字符必须在Unicode CCSID 367中存在。更改结束

授权

要执行CALL语句，包含CALL语句的程序包或计划的所有者必须对GET_MESSAGE存储过程具有EXECUTE权限。

语法

下面的语法图显示了调用此存储过程的SQL CALL语句：

模式为 SYSPROC。

选项说明

MAJOR_VERSION

一个整数类型的输入和输出参数，用于指示主要文档版本。在输入时，此参数指示您为存储过程（xml_input 、xml_output 和xml_message ）中作为参数传递的XML文档所支持的主要文档版本。存储过程处理指定版本的所有XML文档，如果版本无效，则返回错误（-20457）。

在输出方面，此参数指定了存储过程所支持的最高主要文档版本。要确定所支持的文档版本，请将此输入参数和所有其他必需参数指定为 NULL。目前，支持的最高且唯一的主要文档版本是1。

如果 xml_input参数中的 XML文档指定了 Document Type Major Version 键，则该键的值必须等于 major_version参数中提供的值，否则将引发错误（+20458）。

此参数与minor_version参数结合使用。因此，您必须同时指定这两个参数。例如，您必须将两者指定为 NULL 或非 NULL。

MINOR_VERSION

一个整数类型的输入和输出参数，用于指示次要文档版本。在输入时，此参数指定您为作为此存储过程参数传递的XML文档（xml_input 、xml_output 和 xml_message ）所支持的次要文档版本。存储过程处理指定版本的所有XML文档，如果版本无效，则返回错误（-20457）。

在输出方面，此参数表示最高支持的主要版本所支持的次要文档的最高版本。要确定所支持的文档版本，请将此输入参数和所有其他必需参数指定为 NULL。目前，支持的最高且唯一的次要文档版本是0（零）。

如果 xml_input参数中的 XML文档指定了 Document Type Minor Version 键，则该键的值必须等于 minor_version参数中提供的值，否则将引发错误（+20458）。

此参数与major_version参数结合使用。因此，您必须同时指定这两个参数。例如，您必须将两者指定为 NULL 或非 NULL。

requested_locale

一个VARCHAR(33)类型的输入参数，用于指定区域设置。如果服务器支持指定的语言，则翻译后的内容将以 xml_output 和xml_message参数的形式返回。否则，内容将以默认语言返回。仅使用语言和可能来自区域设置的信息。区域设置不用于设置数字格式或影响文档编码。例如，关键名称不予翻译。 XML输出和XML消息文档中唯一翻译的部分是 Display Name、 Display Unit 和 Hint。在适用的情况下，价值可能会全球化。您应该始终将所请求的语言与XML输出文档中使用的语言进行比较（请参阅XML输出文档中的 Document Locale 条目）。

目前 ，requested_locale 支持的值为en_US和NULL。如果指定空值，结果与指定en_US相同。

xml_input

一个BLOB类型的输入参数（ 2G ），用于指定 UTF-8 中数据服务器消息输入类型的XML输入文档，其中包含存储过程的输入值。

对于这个存储过程，XML输入文档的一般结构如下：

<?xml version="1.0"  encoding="UTF-8"?>
<plist version="1.0">
<dict>
   <key>Document Type Name</key><string>Data Server Message Input</string>
   <key>Document Type Major Version</key><integer>1</integer>
   <key>Document Type Minor Version</key><integer>0</integer>
   <key>Document Locale</key><string>en_US</string>
   <key>Complete</key><false/>
   <key>Required Parameters</key>
   <dict>
      <key>SQLCODE</key>
      <dict>
         <key>Value</key><integer>sqlcode</integer>
      </dict>
   </dict>
   <key>Optional Parameters</key>
   <dict>
      <key>Message Tokens</key>
      <dict>
         <key>Value</key>
         <array>
            <string>token1 in SQLCA</string>
            <string>token2 in SQLCA</string>
         </array>
      </dict>
   </dict>
</dict>
</plist>

关于在完整模式下无法运行的XML输入文档示例，请参见示例2。

完整模式 ：有关在完整模式下运行存储过程时xml_output参数返回的XML输入文档示例，请参阅示例部分中的示例1。

xml_filter

UTF-8 中类型为BLOB（ 4K ）的输入参数，用于指定有效的XPath查询字符串。当您想从XML输出文档中检索单个值时，请使用过滤器。更多信息，请参阅用于过滤输出的XPath表达式。

以下示例从XML输出文档中选择短消息文本的值：

/plist/dict/key[.='Short Message Text']/following-sibling::dict[1]/key
[.='Value']/following-sibling::string[1]

如果键后没有指定的同级，则返回错误。

xml_output

一个名为BLOB( 2G )的输出参数，用于返回一个完整的XML输出文档，其类型为 UTF-8 中的数据服务器消息输出。如果指定了过滤器，则此参数将返回一个字符串值。如果存储过程无法返回完整的输出文档（例如，如果发生导致 SQL 警告或错误的处理错误），则此参数设置为 NULL。

XML输出文档示例，请参见示例3。

xml_message

一个名为BLOB( 64K )的输出参数，用于返回一个完整的XML输出文档，该文档的类型为 UTF-8 中的数据服务器消息，用于提供有关SQL警告条件的详细信息。当调用该过程时出现 SQL 警告，且警告消息指出 XML 消息输出文档中返回了附加信息时，将返回此文档。如果警告信息未指示返回其他信息，则此参数设置为 NULL。

XML消息文档示例，请参见示例4。

示例

示例 1

以下示例显示了一个XML输入文档，当存储过程在完整模式下运行时， xml_output参数会返回该文档。

  <?xml version="1.0" encoding="UTF-8" ?> 
  <plist version="1.0">
  <dict>
     <key>Document Type Name</key> 
     <string>Data Server Message Input</string> 
     <key>Document Type Major Version</key> 
     <integer>1</integer> 
     <key>Document Type Minor Version</key> 
     <integer>0</integer> 
     <key>Document Locale</key> 
     <string>en_US</string> 
     <key>Required Parameters</key>  
     <dict>
        <key>Display Name</key> 
        <string>Required Parameters</string> 
        <key>SQLCODE</key> 
        <dict>
           <key>Display Name</key> 
           <string>SQLCODE</string> 
           <key>Value</key> 
           <integer /> 
           <key>Hint</key> 
           <string /> 
        </dict>
        <key>Hint</key> 
        <string /> 
     </dict>
     <key>Optional Parameters</key> 
     <dict>
        <key>Display Name</key> 
        <string>Optional Parameters</string> 
        <key>Message Tokens</key> 
        <dict>
           <key>Display Name</key> 
           <string>Message Tokens</string> 
           <key>Value</key> 
           <array>
              <string /> 
           </array>
           <key>Hint</key> 
           <string /> 
        </dict>
        <key>Hint</key> 
        <string /> 
     </dict>
  </dict>
  </plist>

示例 2

以下示例显示了GET_MESSAGE存储过程的XML输入文档的完整示例。

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
   <key>Document Type Name</key>
   <string>Data Server Message Input</string>
   <key>Document Type Major Version</key><integer>1</integer>
   <key>Document Type Minor Version</key><integer>0</integer>
   <key>Document Locale</key><string>en_US</string>
   <key>Required Parameters</key>
   <dict>
      <key>SQLCODE</key>
      <dict>
         <key>Value</key><integer>-104</integer>
      </dict>
   </dict>
   <key>Optional Parameters</key>
   <dict>
      <key>Message Tokens</key>
      <dict>
         <key>Value</key>
         <array>
            <string>X</string>
            <string>( . LIKE AS</string>
         </array>
      </dict>
   </dict>
</dict>
</plist>

示例 3

以下示例显示了存储过程GET_MESSAGE的XML输出文档的完整示例。 SQLCODE的短消息文本将封装在字典条目中，该条目由 Display Name、 Value 和 Hint 组成。

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
   <key>Document Type Name</key>
   <string>Data Server Message Output</string>
   <key>Document Type Major Version</key><integer>1</integer>
   <key>Document Type Minor Version</key><integer>0</integer>
   <key>Data Server Product Name</key><string>DSN</string>
   <key>Data Server Product Version</key><string>9.1.5</string>
   <key>Data Server Major Version</key><integer>9</integer>
   <key>Data Server Minor Version</key><integer>1</integer>
   <key>Data Server Platform</key><string>z/OS</string>
   <key>Document Locale</key><string>en_US</string>

   <key>Short Message Text</key>
   <dict>
      <key>Display Name</key><string>Short Message Text</string>
      <key>Hint</key><string />
   </dict>
 
</dict>
</plist>

示例 4

以下示例显示了存储过程GET_MESSAGE的XML消息文档示例。与XML输出文档类似，SQL警告条件的详细信息将封装在一个字典条目中，该条目由 Display Name、 Value 和 Hint 组成。

  <?xml version="1.0" encoding="UTF-8" ?> 
  <plist version="1.0">
  <dict>
     <key>Document Type Name</key><string>Data Server Message</string> 
     <key>Document Type Major Version</key><integer>1</integer> 
     <key>Document Type Minor Version</key><integer>0</integer> 
     <key>Data Server Product Name</key><string>DSN</string> 
     <key>Data Server Product Version</key><string>9.1.5</string> 
     <key>Data Server Major Version</key><integer>9</integer> 
     <key>Data Server Minor Version</key><integer>1</integer> 
     <key>Data Server Platform</key><string>z/OS</string> 
     <key>Document Locale</key><string>en_US</string> 
     <key>Short Message Text</key> 
     <dict>
        <key>Display Name</key><string>Short Message Text</string> 
        <key>Value</key> 
        <string>DSNA630I DSNADMGM A PARAMETER FORMAT OR CONTENT ERROR WAS FOUND.
                The value for key 'Document Type Minor Version' is '2'. It does
                not match the value '0', which was specified for parameter 2 of
                the stored procedure. Both values must be equal.</string> 
        <key>Hint</key><string /> 
     </dict>
  </dict>
  </plist>

示例 5

本例展示了一个简单静态的Java™程序，该程序使用XML输入文档和XPath查询SQLCODE短消息文本，调用存储过程GET_MESSAGE。

XML输入文档最初保存为名为 xml_input.xml 的文件，该文件与 GetMessageDriver 类位于同一目录中。该示例程序使用以下 xml_input.xml 文件：

  <?xml version="1.0" encoding="UTF-8" ?> 
  <plist version="1.0">
    <dict>
      <key>Document Type Name</key> 
      <string>Data Server Message Input</string> 
      <key>Document Type Major Version</key> 
      <integer>1</integer> 
      <key>Document Type Minor Version</key> 
      <integer>0</integer> 
      <key>Document Locale</key> 
      <string>en_US</string> 
      <key>Complete</key> 
      <false /> 
      <key>Required Parameters</key> 
      <dict>
        <key>SQLCODE</key> 
        <dict>
          <key>Value</key> 
          <integer>-204</integer> 
        </dict>
      </dict>
      <key>Optional Parameters</key> 
      <dict>
        <key>Message Tokens</key> 
        <dict>
          <key>Value</key> 
          <array>
            <string>SYSIBM.DDF_CONFIG</string> 
          </array>
        </dict>
      </dict>
    </dict>
  </plist>

XPath由程序静态创建为字符串对象，然后转换为BLOB，作为 xml_filter参数的输入。调用存储过程后， xml_output参数只包含一个字符串，而没有XML文档。输出结果以名为 xml_output.xml 的文件的形式存在，该文件与 GetMessageDriver 类位于同一目录下。

使用有效的XML输入文档和有效的XPath调用存储过程GET_MESSAGE的示例：

//***************************************************************************
// Licensed Materials - Property of IBM
// 5635-DB2
// (C) COPYRIGHT 1982, 2006 IBM Corp. All Rights Reserved.
//
// STATUS = Version 9
//***************************************************************************
// Source file name: GetSystemDriver.java
//
// Sample: How to call SYSPROC.GET_SYSTEM_INFO with a valid XML input document
// and a valid XPath to extract the operating system name and release.
//
// The user runs the program by issuing:
// java GetSystemDriver <alias or //server/database> <userid> <password>
//
// The arguments are:
// <alias> - DB2 subsystem alias for type 2 or //server/database for type 4
//    connectivity
// <userid> - user ID to connect as
// <password> - password to connect with
//***************************************************************************
import java.io.*;
import java.sql.*;

public class GetSystemDriver
{
   
   public static void main (String[] args)
   {
      Connection con = null;
      CallableStatement cstmt = null;
      String driver = "com.ibm.db2.jcc.DB2Driver";
      String url = "jdbc:db2:";
      String userid = null;
      String password = null;
      
      // Parse arguments
      if (args.length != 3)
      {
        System.err.println("Usage: GetSystemDriver <alias or //server/database> 
<userid> <password>");
        System.err.println("where <alias or //server/database> is DB2 subsystem 
alias or //server/database for type 4 connectivity");
        System.err.println(" <userid> is user ID to connect as");
        System.err.println(" <password> is password to connect with");
        return;
      }
      url += args[0];
      userid = args[1];
      password = args[2];
      
      try {
      
        String str_xmlfilter = new String(    
          "/plist/dict/key[.='Operating System Information']/following-sibling::
dict[1]" +
          "/key[.='Name and Release']/following-sibling::dict[1]" +
          "/key[.='Value']/following-sibling::string[1]");
        
        // Convert XML_FILTER to byte array to pass as BLOB 
        byte[] xml_filter = str_xmlfilter.getBytes("UTF-8");        
        
	      // Read XML_INPUT from file 
	      File fptr = new File("xml_input.xml"); 
	    
	      int file_length =  (int)fptr.length();
	      byte[] xml_input = new byte[file_length];
	
	      FileInputStream instream = new FileInputStream(fptr);
	      int tot_bytes = instream.read(xml_input,0, xml_input.length);
	      if (tot_bytes == -1) {
	        System.out.println("Error during file read");
          return;   
        }
	      instream.close();
               
        // Load the DB2 Universal JDBC Driver
        Class.forName(driver);
        
        // Connect to database
        con = DriverManager.getConnection(url, userid, password);
        con.setAutoCommit(false);
        
        cstmt = con.prepareCall("CALL SYSPROC.GET_SYSTEM_INFO(?,?,?,?,?,?,?)");
        
        // Major / Minor Version / Requested Locale
        cstmt.setInt(1, 1);
        cstmt.setInt(2, 1);
        cstmt.setString(3, "en_US");
        
        // Input documents
        cstmt.setObject(4, xml_input, Types.BLOB);
        cstmt.setObject(5, xml_filter, Types.BLOB);
        
        // Output Parms
        cstmt.registerOutParameter(1, Types.INTEGER);
        cstmt.registerOutParameter(2, Types.INTEGER);
        cstmt.registerOutParameter(6, Types.BLOB);
        cstmt.registerOutParameter(7, Types.BLOB);
        
        cstmt.execute();
        con.commit();
       
        SQLWarning ctstmt_warning = cstmt.getWarnings();
        if (ctstmt_warning != null) {
          System.out.println("SQL Warning: " + ctstmt_warning.getMessage());
        }
        else {
          System.out.println("SQL Warning: None\r\n");
        }
        
        System.out.println("Major Version returned " + cstmt.getInt(1) );
        System.out.println("Minor Version returned " + cstmt.getInt(2) );
        
        // Get output BLOBs 
        Blob b_out = cstmt.getBlob(6);
        
        if(b_out != null)
        {
          int out_length = (int)b_out.length();
          byte[] bxml_output = new byte[out_length];
          
          // Open an inputstream on BLOB data 
          InputStream instr_out = b_out.getBinaryStream();
          
          // Copy from inputstream into byte array 
          int out_len = instr_out.read(bxml_output, 0, out_length);
          
          // Write byte array content into FileOutputStream 
          FileOutputStream fxml_out = new FileOutputStream("xml_output.xml");
          fxml_out.write(bxml_output, 0, out_length );
          
          //Close streams
          instr_out.close();
          fxml_out.close();
        }
        
        Blob b_msg = cstmt.getBlob(7);
        
        if(b_msg != null)
        {
          int msg_length = (int)b_msg.length();
          byte[] bxml_message = new byte[msg_length];
          
          // Open an inputstream on BLOB data 
          InputStream instr_msg = b_msg.getBinaryStream();
          
          // Copy from inputstream into byte array 
          int msg_len = instr_msg.read(bxml_message, 0, msg_length);
          
          // Write byte array content into FileOutputStream 
          FileOutputStream fxml_msg = new FileOutputStream(new File
("xml_message.xml"));
          fxml_msg.write(bxml_message, 0, msg_length);
          
          //Close streams
          instr_msg.close();
          fxml_msg.close();
        }
      }
      
      catch (SQLException sqle) {
         System.out.println("Error during CALL "
               + " SQLSTATE = " + sqle.getSQLState()
               + " SQLCODE = " + sqle.getErrorCode()
               + " : " + sqle.getMessage());
      }
      
      catch (Exception e) {
         System.out.println("Internal Error " + e.toString());
      }
      
      finally
      {
         if(cstmt != null)
            try { cstmt.close(); } catch ( SQLException sqle) 
{ sqle.printStackTrace(); }
         if(con != null)
            try { con.close(); } catch ( SQLException sqle) 
{ sqle.printStackTrace(); }
      }
   }
}

通用编程接口信息结束。