User mapping plug-in (C programming language)

Initialize – FSUMPluginInit

Immediately after the federated server loads the plug-in library, the server calls the FSUMPluginInit function, which initializes the plug-in and passes the pointers for the other functions to the federated server. These functions are global and must be externally resolvable. If the plug-in is written in C++, these functions must be declared with extern "C". The federated server passes in the pointers to a set of utility functions, which the plug-in can obtain, as necessary.

The plug-in is loaded into a threaded db2fmp process. All applications that use the plug-in share the same plug-in library, which must be thread-safe. Each application uses one thread in the db2fmp process. After the application successfully retrieves a user mapping and cleans up, the federated server returns the thread to the thread pool for future use. Because the federated server can serve multiple applications simultaneously, multiple threads that share the same plug-in library can be activated at the same time. Each thread has a separate connection handle to the user mapping repository. The FSUMPluginInit API also provides a way for each thread to handle global plug-in resources, for example to increase the reference count to the plug-in.

Connect to repository – FSUMconnect

The federated server calls the FSUMconnect function to connect to the user mapping repository. The plug-in must include a descriptor that stores all of the information that is required to make the connection to the repository. For example, the information might include a handle to an opened file or a connection handle to an LDAP server. Depending on how you implement security for the external repository, the information might also include a user ID and a password. If credentials are required, you must set up the way that the credentials are managed. For example, if you put credentials in a configuration file, when the plug-in tries to connect to the external repository, the plug-in reads the credentials from that file.

Retrieve user mapping – FSUMfetchUM

The plug-in calls the FSUMfetchUM function to retrieve the user mapping from the external repository and calls the FSUMaddUMOption utility function to send the remote ID and remote password to the federated server. In the repository, each user mapping is identified by the federated server instance name, the database name, the remote server name, and the local authorization ID. In addition, each user mapping must include the REMOTE_AUTHID and REMOTE_PASSWORD options. If a remote password is encrypted, the plug-in must decrypt it before sending it to the federated server.

Disconnect from repository – FSUMdisconnect

The federated server calls the FSUMdisconnect function to disconnect from the user mapping repository. To disconnect, this function disassociates the thread with the user mapping repository. For example, this function might close an opened file or close a connection to an LDAP server.

Release global resources – FSUMPluginTerm

As the last step, the federated server calls the FSUMPluginTerm function to release any global resources that the FSUMPluginInit function allocated. To terminate, this function disassociates the thread with the plug-in.