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);

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().