Troubleshooting the user mapping plug-in

After you configure the federated server to use the user mapping plug-in, there are several ways that you can troubleshoot problems.

Before you test the plug-in in the federated server, you should develop a Java™ application to test if the plug-in can connect to and retrieve user mappings from the external repository. If the test is successful, then you can try to integrate the plug-in with the federated server.

JAVA_HEAP_SZ parameter

The JAVA_HEAP_SZ parameter determines the maximum size of the heap that is used by the Java interpreter to service Java stored procedures and user defined functions. If you encounter memory problems with a user mapping that was written in Java, set the heap size to 1024 or higher.

Error messages

If an error message is returned when using the plug-in, the information in the error message can help you to determine the problem. There are reason codes and user responses in the error messages that should help you determine the problem.

SQL20349N: The federated server cannot access the user mappings that are in the external repository. One reason why you might receive this error is that the user mapping plug-in is not in the correct location. If you use the sample LDAP plug-in on a UNIX federated server, ensure that UserMappingRepositoryLDAP.jar file and the UserMappingRepositoryLDAP.cfg file are in sqllib/function directory.
SQL20350N: The authentication at the user mapping repository failed. The proper credentials, such as passwords or certificates, to retrieve the user mappings were not communicated to the user mapping repository.
SQL20351W: You specified the DB2_UM_PLUGIN option on a wrapper and the DB2_UM_PLUGIN option is already specified on a server definition that uses the wrapper. The value that is set on the server definition takes precedence over the value that you set on the wrapper.
SQL20352W: You specified DB2_UM_PLUGIN option for the server. User mappings for this server are read from the external user mapping repository. The CREATE USER MAPPING, ALTER USER MAPPING, and DROP USER MAPPING statements only affect user mappings in the federated catalog table.

db2diag.log file

The diagnostic log is a file that contains text information that is logged by the federated database. This information is used for problem determination and is intended for IBM® customer support.

You can view the file with a text editor. You can also use the db2diag tool can help you to analyze the information that is contained in the db2diag.log file to troubleshoot problems with your user mapping plug-in.

Example 1

In the db2diag.log file, search for the term JNI_Env::check_exception. This term marks the first error record for the user mapping plug-in. The record indicates the line in the plug-in source code where an error has occurred. In the following example, the line in the code that is in error is line 119 of the UserMappingRepositoryLDAP.java file.

2006-02-18-19.05.43.966176-480 I6780A253          LEVEL: Severe 
PID     : 3932214              TID  : 2828        PROC : db2fmp (Java)
INSTANCE: einstein               NODE : 000 
FUNCTION: DB2 UDB, Query Gateway, Sqlqg_JNI_Env::check_exception, probe:150
2006-02-18-19.05.43.966953-480 I7034A388          LEVEL: Error 
PID     : 3932214              TID  : 2828        PROC : db2fmp (Java) 
INSTANCE: einstein               NODE : 000 
FUNCTION: DB2 UDB, Query Gateway, Sqlqg_JNI_Env::check_exception, probe:190
DATA #1 : String, 108 bytes
com.ibm.ii.um.UserMappingException 
    at UserMappingRepositoryLDAP.<init>(UserMappingRepositoryLDAP.java:119)

Example 2

In the db2diag.log file, search for the term

Error
fetching user mappings

. The record for this error includes the plug-in name, the instance name, the database name, the remote server name, and the local authentication ID. These values are passed from the federated server to the plug-in as input. Ensure that the values , including the case sensitivity, are correct.

2006-02-18-19.05.43.967308-480 I7423A371          LEVEL: Severe 
PID     : 3932214              TID  : 2828        PROC : db2fmp (Java) 
INSTANCE: einstein               NODE : 000 
MESSAGE : Error fetching user mappings through plugin: 
DATA #1 : String, 110 bytes 
   plugin=UserMappingRepositoryLDAP,instance=EINSTEIN,database=SAMPLE,
   remote_server=DRDASERVER1,local_authid=NEWTON

db2trc - trace command

If you are unable to troubleshoot the problem. you can use db2trc command to generate a trace. You will need to send the trace record to IBM for analysis.