HP OpenVMS Systems Documentation
Content starts here
Common Desktop Environment: Programmer's Guide

4 Integrating with Session Manager

Contents of Chapter:
How Session Manager Saves Sessions and Applications
How to Program the Application for Session Management
How Session Manager Restores a Session
Session Manager saves information about the Desktop environment and the applications running when the user logs out (of the current session) or when the user saves the environment (in a home session). For an application to be saved as part of the current session or the home session and then restarted as part of the next session, it must participate in the X Inter-Client Communication Conventions Manual (ICCCM) 1.1 Session Management Protocol. This chapter outlines how Session Manager saves and restores sessions and details the steps necessary for an application to participate in session management.

How Session Manager Saves Sessions and Applications

When you exit a session or when you save a Home session, Session Manager:

  1. Saves the selected resource settings and X server settings

  2. Allows each application to save its state and waits for the save to be completed

  3. Obtains the command line required to restart the application

How to Program the Application for Session Management

Setting the Program Environment

This section describes the programming steps necessary for an application to be saved as part of the integration process.

Follow these steps to set the program environment:

  1. Include the following header files:
    • Xm/Xm.h
    • Xm/Protocols.h
    • Dt/Session.h

  2. Link with libXm and libDtSvc.

  3. Initialize the toolkit and create a top-level widget.

Setting the WM_SAVE_YOURSELF Atom

Use the Motif XmAddWMProtocol() function to set the WM_SAVE_YOURSELF atom on the WM_PROTOCOLS property for the top-level window of your application, as shown in the following example.

Atom XaWmSaveYourself;
Display *dsp;

dsp = XtDisplay(toplevel);
XaWmSaveYourself =
XmInternAtom(dsp, "WM_SAVE_YOURSELF", False);
XmAddWMProtocols(toplevel, &XaWmSaveYourself, 1);
Note: Do not set the WM_SAVE_YOURSELF atom for more than one window.

Prepare to Receive the WM_SAVE_YOURSELF Message

Use the Motif XmAddWMProtocolCallback() function to establish a callback procedure to be called when the application receives a WM_SAVE_YOURSELF client message:

XmAddWMProtocolCallback(toplevel, XaWmSaveYourself, SaveYourselfProc,
   toplevel);

Processing the WM_SAVE_YOURSELF Message

When Session Manager sends a WM_SAVE_YOURSELF client message to this sample application's top-level window, the SaveYourselfProc() callback procedure is called. Use thecallback to save the application's state. The application can save its state by any means you want, but cannot interact with the user during the save.

Session Manager provides the DtSessionSavePath() function as a way to return a full path name and a base file name to use for saving the application's state.

Setting the WM_COMMAND Property

After the application has finished processing the WM_SAVE_YOURSELF message, either by saving its state or ignoring the message, the application must set the WM_COMMAND property on its top-level window to tell Session Manager that the save operation is complete.

Use the Xlib XsetCommand() function to set the WM_COMMAND property on the application's top-level window. Setting this property lets Session Manager know that the application has finished processing the WM_SAVE_YOURSELF message and gives Session Manager the command line it needs to restart the application.

XsetCommand() accepts an array of command-line arguments. If the application uses the DtSessionSavePath() function as part of the save process, XsetCommand() needs an additional command-line argument: -session basename, where basename is the base file name returned by DtSessionSavePath().

How Session Manager Restores a Session

Session Manager restores a session by:

  1. Restoring the resource database and server settings

  2. Restarting applications using the saved command lines

If the application used DtSessionSavePath() to find a path for its saved state, the application can pass the base file name from the -session argument to the DtSessionRestorePath() function to find the full path name of its saved-state file.