Overview
Documentum Sessions
Documentum job scheduler
Tracing levels
Xense Session Manager
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Understanding Documentum Sessions
This article illustrates some of the concepts involved with Content Server sessions. First lets look at what happens when a user connects to the content server. Whatever the type of client application (WDK, DFC or plain old API) the code ends up calling the API 'connect'. The connect call is processed as follows:
  • First memory is set aside in the DMCL (Documentum Client Library) to represent the state of the client-side session. The DMCL is a set of library routines that is linked in to the client process.
  • An RPC (Remote Procedure Call) is issued from the client process to the Content Server requesting a new session. Assuming the username and password are accepted by the Content Server a new session is created. Associated with this session is a new OS thread (or process if the Content Server is running on Unix) and a connection created with the database. The session is marked as 'Active'
  • Whilst the DMCL continues to make RPC calls to the Content Server the Content Server session remains 'Active'. Every time the Content Server completes processing an RPC is starts a timer. The timer is set to expire after a period defined by the client_session_timeout server.ini parameter - by default this is 5 minutes.
  • If another RPC is received from the DMCL for this session the timer is cleared. However if the timer expires the Content Server session is marked 'Inactive' and the OS thread (or process) and the database connection are dropped. It's important to note that the DMCL is not notified at this time of the inactivation of the Content Server session.
  • If the DMCL issues an RPC on an Inactive Content Server session, the session is transparently re-activated; an OS thread (or process) is created, a new database connection is initiated and the session is marked as 'Active'. The fact that the Content Server session had to be 'activated' is not visible to the calling WDK/DFC/API code.

It should be clear from the description above that there are 2 different sessions involved here:
  • A client-side DMCL session
  • A Content Server session
The two sessions are distinct entities.

DMCL Connection Pooling
 So how does connection pooling affect this process? Well first of all it is important to appreciate that connection pooling is implemented in the DMCL not by the Content Server. The handling of sessions by the Content Server is the same whether connection pooling is enabled or not.

When connection pooling is enabled in the DMCL the following behaviour occurs:
  • If a connect call is issued and a free DMCL session is found in the pool, this session is returned.
  • If a connect call is issued and no free DMCL session is found a new one is created and added to the pool. This session is then returned. However if the number of existing sessions has reached the dmcl.ini parameter max_session_count then no session is created and an error message is returned to the caller.
  • If a disconnect call is issued on the DMCL session, the session is marked as 'free' and can no longer be used by the calling code. No disconnect is transmitted to the Content Server so the Content Server session is not released at this point. If the Content Server session is still active and the client_session_timeout timer expires the Content Server session is set to inactive.
Seeing Documentum Sessions In Action
 Now we have the concepts in place let's see how connecting and disconnecting affect the DMCL, Content Server and database sessions - here I am using Oracle database.

In the example below I execute a number of connect calls in IAPI32, followed by a disconnect. The number of DMCL sessions is measured using the dumpconnectpool API command, the number of Content Server sessions is measured using the Xense Session Manager tool and the number of database sessions is measured using a query on the Oracle V$SESSION view.

 We start off by observing the number of database sessions:
 
select sid,username from v$session where username = 'DM3';

SQL> select sid,username from v$session where username = 'DM3';

       SID USERNAME
---------- ------------------------------
         9 DM3
        10 DM3
        15 DM3
        18 DM3
These 4 sessions represent the core content server processes and also the dm_agent_exec job scheduler. Lets start Xense Session Manager :
This shows 2 sessions, 1 for Robin East which is the user running SessionManager, and 1 for dmadmin which is the dm_agent_exec session. We can now check the database sessions and see that an extra database sessions has been created for the Robin East session:
 
SQL> select sid,username from v$session where username = 'DM3';

       SID USERNAME
---------- ------------------------------
         9 DM3
        10 DM3
        14 DM3
        15 DM3
        18 DM3

Now let's start IAPI32 and create 5 sessions (the first one is created when we log in):

 
Connected to Documentum Server running Release 5.2.5.225 SP2 Win32.Oracle
Session id is s0
API> connect,dm3,dmadmin,dmadmin
...
s1
API> connect,dm3,dmadmin,dmadmin
...
s2
API> connect,dm3,dmadmin,dmadmin
...
s3
API> connect,dm3,dmadmin,dmadmin
...
s4
API> dumpconnectpool,c
...
Connect Pool has 5 entries

sess docbase server host       user     status
==== ======= ====== =========  =======  ======
s0   dm3     dm3    xenselap3  dmadmin  used
s1   dm3     dm3    xenselap3  dmadmin  used
s2   dm3     dm3    xenselap3  dmadmin  used
s3   dm3     dm3    xenselap3  dmadmin  used
s4   dm3     dm3    xenselap3  dmadmin  used
We can see that 5 DMCL sessions have been created in the connection pool and they are all used. We can see the 5 Content Server sessions in Xense SessionManager:

Notice the status of all sessions is 'Active'. Looking at the database we have 5 new database sessions to make a total of 10 sessions:
 
SQL> select sid,username from v$session where username = 'DM3';

       SID USERNAME
---------- ------------------------------
         9 DM3
        10 DM3
        14 DM3
        15 DM3
        16 DM3
        18 DM3
        19 DM3
        20 DM3
        21 DM3
        22 DM3

10 rows selected.

Now we disconnect a DMCL session:
 
API> disconnect,s0
...
OK
API> dumpconnectpool,c
...
Connect Pool has 5 entries

sess docbase server host       user     status
==== ======= ====== =========  =======  ======
s0   dm3     dm3    xenselap3  dmadmin  free
s1   dm3     dm3    xenselap3  dmadmin  used
s2   dm3     dm3    xenselap3  dmadmin  used
s3   dm3     dm3    xenselap3  dmadmin  used
s4   dm3     dm3    xenselap3  dmadmin  used
We now have 4 DMCL sessions used and 1 free. Since we have connection pooling turned on we don't expect any change in the status of the Content Server session:

All sessions are still 'Active'.

 If we now wait for 5 minutes (client_session_timeout is not set in the server.ini so the default is 5 minutes) and check SessionManager again, this time selecting 'Both' in the Status drop-down to display Active and Inactive sessions:

One of our IAPI sessions (0100000380071d03) has been set to 'Inactive'. The number of database sessions is now:

 
SQL> select sid,username from v$session where username = 'DM3';

       SID USERNAME
---------- ------------------------------
         9 DM3
        10 DM3
        14 DM3
        15 DM3
        16 DM3
        18 DM3
        19 DM3
        21 DM3
        22 DM3

9 rows selected.
When the Content Server session was set to Inactive the database session is released.