# Integrating with Information Manager

The `dtinfo` facility enables CDE users to browse and search large collections of SGML-formatted on-line documentation containing graphics and hypertext links. These collections are referred to as information libraries. An information library consists of a collection of book cases, each of which contains a collection of books.

The information manager is available on the CDE desktop from a number of locations. `dtinfo` is started automatically by the session manager as part of the initial user session. Information libraries are available as DtInfoLib objects on the desktop from File Manager. The `dtinfo` application can be started directly from the front panel or from the `Info Manager` action in the `Desktop_Apps` application group in `Application Manager`.

A CDE application calls a small API to integrate the `dtinfo` browser and so enable access to information libraries. Should `dtinfo` be unsuited to your application environment, you can extend it or replace it with your own browser, using the dtinfo database engine API. Following some general discussions of the dtinfo facility, this chapter summarizes both the `dtinfo` API and the `dtinfo` database engine API.

## Server Architecture

Information management in CDE is based on a server architecture. This means that only one instance of the main book list window for `dtinfo` is normally displayed at any time within a CDE desktop session. User or application requests for new document library connections within the session are handled by the one instance, maximizing the user's ability to organize and search on-line documentation, and minimizing system response time.

An exception to this behavior occurs when the user or application requests access to an infolib that is not accessible from any host on which an existing `dtinfo` instance is running. When this situation occurs, the desktop mechanisms automatically launch a new instance of `dtinfo` on a host that has access to the requested information library. A similar situation occurs when the user or application requests access to an infolib in a locale that is different from those used by any currently executing `dtinfo` process. In this case, the desktop mechanisms launch a new instance of `dtinfo` on the same host but in the new locale. If both conditions apply, the new `dtinfo` instance is started on a host that has access to the information library in the requested locale.

It is possible to create multiple instances on a given execution host in a given locale by invoking `dtinfo` from the command line. In this case, `dtinfo` does not take advantage of the ToolTalk mechanisms to ensure that a single instance only is running on the desktop.

## Search Path

The `DTINFOLIBSEARCHPATH` and `DTINFOLIBDEFAULT` environment variables are defined at installation time by `dtsearchpath`. The infolib search path directs the desktop to search specified locations for information libraries that are to be be registered on your system.

### Default Infolib Search Path

The default infolib search path includes system-wide and built-in locations:

- System-wide location &mdash `/etc/dt/infolib/%L/%I.dti`

- Built-in location &mdash `/usr/dt/infolib/%L/%I.dti`

The default language is C. The value of `DTINFOLIBDEFAULT` is substituted for %I. The initial default value for `DTINFOLIBDEFAULT` is `cde`.

### How the Application Search Path Affects the Infolib Search Path

When a location is added to the application search path, the appropriate infolib subdirectory is automatically added to the infolib search path. For example, if the application server `hosta:` is added to the application search path, the directory `hosta:/etc/dt/infolib/%L` is automatically added to the infolib search path.

### Infolib Search Path Environment Variables

The infolib search path is assembled from the built-in locations and the following input variables:

- `DTSPSYSINFOLIB` &mdash System-wide infolib search path input variable

- `DTSPUSERINFOLIB` &mdash Personal infolib search path input variable

Use these input variables to specify locations outside the application search path. The assembled database search path is specified by the output variable `DTINFOLIBSEARCHPATH`.

### Syntax for the Infolib Search Path Input Variables

The syntax for the variables `DTSPSYSINFOLIB` and `DTSPUSERINFOLIB` is:

VARIABLE `=` location [,location...]

where location can have the syntax, `/`path, which specifies a directory on the local (session server) system. Use this syntax to add a local directory. To specify a location on another system, use its network file name &mdash for example, `/nfs/servera/projects/infolib`.

### How the Infolib Search Path Is Assembled

The value of the infolib search path (`DTINFOLIBSEARCHPATH`) is created by assembling the following locations, listed in order of precedence:

- Locations specified using the `DTSPUSERINFOLIB` variable

- Locations derived from the `DTSPUSERAPPHOSTS` variable

- The default location: `/etc/dt/infolib/%L/%I.dti`

- Locations specified using the `DTSPSYSINFOLIB` variable

- Locations derived from the `DTSPSYSAPPHOSTS` variable

- `/usr/dt/infolib/%L/%I.dti`

## Workspace Management

The browser is workspace-aware to provide predictable behavior regardless of the workspace in which it is running at the time of a connection request. Windows are mapped to workspaces according to the following rules:

- When primary windows are mapped to a new workspace, all associated secondary windows are also mapped to the new workspace

- When secondary windows are mapped to a new workspace, the associated primary window and all its associated secondary windows are also mapped to the new workspace

- When a primary window is mapped to a new workspace, any other primary windows associated with the application remain in the current workspace

The `DtInfo_LoadInfoLib` and `DtInfo_ShowInfoAtLoc` messages cause the browser window to be mapped to the current workspace. The user can also map application windows to a new workspaces through the `dtwm` menu.

## Application Linkage

Applications are provided with a means to activate `dtinfo` for specific on-line documentation display purposes. One use of the `dtinfo` External API might be an application that manages or automates information display or navigation.

Connecting to `dtinfo` from an application (using an explicit locator value with the `DtShowInfoAtLoc` action) displays the browser if it is not already visible. The following situations vary this result:

- Only an infolib path is specified for the browser to access (using the `DtLoadInfoLib` action), in which case only the top `dtinfo` (booklist) window is presented, including the newly loaded infolib's bookcases.

- `dtinfo` is active in the workspace, but the Book List window and/or a browser is iconified.

  - The Book List window and any "pinned" browser window(s) remains iconified. If there is no unpinned browser window (iconified or not), a new browser window is presented for the requested topic.

  - If an iconified Browser window is not pinned, it is mapped and the requested topic supplants the previous topic.

- The desktop and a `dtinfo` instance were started on one host (`host1`) in a locale (`locale1`), but an application that uses `dtinfo` is started from a remote shell on a different (`host2`) and/or a different locale (`locale2`) during the same CDE session.

  - The request from the application is examined by all `dtinfo` processes in the current session to determine if it can be processed. For a `dtinfo` process to accept the request it must be running in the same locale and be able to access the specified information libraries.

  - If no such process exists, an independent copy of the browser is started on `host2` in `locale2`. The original message is forwarded to the new instance for processing.

## ToolTalk Messages

The `dtinfo` command registers with ToolTalk to handle the following messages:

- `DtInfo_LoadInfoLib` (scope TT_SESSION)

- `DtInfo_ShowInfoAtLoc` (scope TT_SESSION)

A `dtinfo` instance observes the following messages:

- `DtInfo_Quit` (scope TT_SESSION)

The Information Management system also defines a ptype "DtInfo" that is used to launch a `dtinfo` process if there is not a currently available `dtinfo` process that can handle a ToolTalk request.

## Generalized Locator Format

For the purpose of addressing infolibs as document collections with external navigation references, a generalized locator format is defined for use in applications and by the end-user. This mechanism is more precise than those that operate on the DtInfoLib level. This mechanism can be used by applications that want to integrate their on-line documentation tightly, within the action system, or for printing specific sections from a command line.

The following BNF defines the syntax of a generalized locator format string:

    <GLF> ::= <MMDB> | <ULV> | <URI>
    <MMDB> ::= mmdb:  <IBL> | <IB> | <IL> | <INFOLIB> | <BL> | <BOOKCASE> |
               <LOCATOR>
    <IBL> ::= <INFOLIB> & <BOOKCASE> & <LOCATOR>
    <IB> ::= <INFOLIB> & <BOOKCASE>
    <IL> ::= <INFOLIB> & <LOCATOR>
    <BL> ::= <BOOKCASE> & <LOCATOR>
    <INFOLIB> ::= INFOLIB= <NAME>
    <BOOKCASE> ::= BOOKCASE= <NAME>
    <LOCATOR> ::= LOCATOR= <ULV> <NAME>
    <ULV> ::= uuid_ | xsm_ | isbn_
    <NAME> ::= <CHAR> { <CHAR>)
    <CHAR> ::= a-z | A-Z | 0-9 | <SPECIAL_CHAR>
    <SPECIAL_CHAR> ::= everything but ":" and "&"
    <URI> ::= Uniform Resource Identifier (as defined by the Web Consortium)

As shown above, there are several reserved terms that are used to identify locator format, including `uuid` (for DCE-style Universal Unique ID), `xsm` (for XSession Manager style Unique ID), and `isbn` (for International Standard Book Number). Of these, only `xsm` is supported directly in the sample implementation.

## Summary of the DtInfo API

Following is a summary of the Desktop Information Manager API.

`DtInfoLib`

- `DtInfoLib` is a desktop object that represents a collection of bookcases of documents that can be accessed through the Information Manager. DtInfoLib data criteria and data attributes are identified for use by desktop facilities. These are part of the CDE built-in data types.

`DtInfoShowTopic`

- This is a C API callable by an application to provide the user access to body of information at a specific location. The location may identify anything from the top of a bookcase to a specific topic or to a section within a bookcase. Targets within sections are also possible, where they have been given externally unique link IDs during construction of the data.

`DtActionInvoke`

- This function displays a specified topic under `dtinfo` using the available CDE desktop action API from a desktop application. It invokes (or connects to) `dtinfo`. The anchor point may be as broad as the top of a bookcase, or as fine as a specific topic (section). Targets within sections are also possible, where they have been given externally unique link IDs during construction of the data.

`Browse`

- The `Browse` for an infolib is a remap to the `DtLoadInfoLib` action.

`Open`

- The `Open` action is used to invoke `DtLoadInfoLib` for the associated `DtInfoLib` object.

`DtShowInfoAtLoc`

- The `DtShowInfoAtLoc` action distributes a ToolTalk message for the browser to display a specific point in the infolib. A client application requests that `dtinfo` display a particular section of data, or topic, by invoking this action. The browser is started if it is not already running. This corresponds to invoking the `dtinfo` command with the `-sect` option from the command line.

`DtLoadInfoLib`

- The `DtLoadInfoLib` action distributes a ToolTalk message for `dtinfo` to load a specific infolib. A client application can request that `dtinfo` load a particular information library by invoking this action. The browser is started if it is not already running. This corresponds to invoking the `dtinfo` command with the `-l` option from the command line.

`DtInfo_LoadInfoLib`

- The `DtInfo_LoadInfoLib` ToolTalk operation is used to load a specified infolib. A client application can request that `dtinfo` load a particular information library by sending this request. The browser is started if it is not already running. This corresponds to invoking the `dtinfo` command with the `-l` option from the command line.

`DtInfo_ShowInfoAtLoc`

- A client application requests that `dtinfo` display a particular section of data, or topic, by sending this process-oriented ToolTalk message. ToolTalk starts the browser if it is not already running. This corresponds to invoking the `dtinfo` command with the `-sect` option from the command line.

`DtInfo_Quit`

- This is a process-oriented ToolTalk message for observers interested only in the status of `dtinfo`. The browser posts this message when it exits normally. It is not sent for desktop session-wide exit.

## Summary of the DtInfo Database Engine API

This section summarizes the application programming interface to the DtInfo Database Engine. The DtInfo Database Engine stores and provides access to the on-line document data for the DtInfo.

### Functions

`DtMmdbInit`

- Prepare the database engine to provide access service.

`DtMmdbQuit`

- Free memory resource allocated by the database engine and ask the engine to stop service.

`DtMmdbOpenInfoLib`

- Obtain an infolib descriptor.

`DtMmdbInfoLibGetInfo`

- Get descriptive information about an infolib.

`DtMmdbInfoLibFreeInfo`

- Free space occupied by an infolib structure.

`DtMmdbCloseInfoLib`

- Declare that the infolib is no longer needed.

`DtMmdbGetBookCaseByName`

- Obtain a descriptor to a bookcase identified by name.

`DtMmdbGetBookCaseByIndex`

- Obtain a descriptor to a bookcase identified by index.

`DtMmdbGetBookCaseByLoc`

- Obtain a descriptor to a bookcase identified by location.

`DtMmdbGetBookCaseByLocs`

- Obtain a list of bookcase descriptors.

`DtMmdbBookCaseGetInfo`

- Get information about a bookcase.

`DtMmdbBookCaseFreeInfo`

- Free space occupied by a bookcase information structure.

`DtMmdbSectionGetLoc`

- Get a section's locator.

`DtMmdbSectionGetLongTitle`

- Return the long title of the section, given its identifier.

`DtMmdbSectionGetShortTitle`

- Get a section's short title.

`DtMmdbSectionGetData`

- Get a section's data.

`DtMmdbSectionGetDataSize`

- Get the number of bytes for the section's data.

`DtMmdbSectionGetTocLoc`

- Given a section's identifier, get the locator of its TOC section.

`DtMmdbSectionGetBookId`

- Given a section's identifier, get the DtInfo Database object identifier of the book in which this section appears.

`DtMmdbSectionGetStyleSheetId`

- Given a section's identifier, get the DtInfo Database object Identifier of the stylesheet applicable to this section.

`DtMmdbTocGetParentId`

- Get the DtInfo Database object identifier of the section that is the parent of this section.

`DtMmdbTocGetChildIds`

- Get a list of DtInfo Database object identifiers for the child sections.

`DtMmdbTocGetNumOfChildren`

- Get the number of child sections.

`DtMmdbLocatorGetSectionLoc`

- Get the locator of a section, given the locator of a component inside the section.

`DtMmdbLocatorGetSectionObjectId`

- Get the DtInfo Database object identifier of the section, given the locator of a component inside the section.

`DtMmdbGraphicGetData`

- Obtain the data of a graphic object.

`DtMmdbGraphicGetInfo`

- Obtain the information of a graphic object.

`DtMmdbStylesheetGetName`

- Obtain the name of a stylesheet object.

`DtMmdbStylesheetGetData`

- Obtain the data of a stylesheet object.

`DtMmdbBookGetTocObjectId`

- Obtain the locator of a TOC section.

`DtMmdbBookGetShortTitle`

- Obtain the short title of a book.

`DtMmdbBookGetLongTitle`

- Obtain the long title of a book.

`DtMmdbBookGetSeqNum`

- Obtain the sequence number of a book.

`DtMmdbBookGetLicense`

- Obtain the license terms of a book.

`DtMmdbBookGetTabList`

- Obtain the list of tabbed sections in the book.

`DtMmdbDlpGetPrevSectionId`

- Obtain the DtInfo Database object identifier of the previous section, given the identifier of this section.

`DtMmdbDlpGetNextSectionId`

- Obtain the DtInfo Database object identifier of the next section.

`DtMmdbFreeHandle`

- Free memory resource used by a DtMmdbHandle.

`DtMmdbFreeHandleList`

- Free memory resource used by a DtMmdbHandle array, including the contained handlers.

`DtMmdbFreeGraphicInfo`

- Free memory used by a DtMmdbGraphicInfo structure.

### Data Structures

DtMmdbInfoLib

- Contains information about an information library (infolib).

DtMmdbBookCase

- Contains information about a bookcase.

DtMmdbHandle

- Contains information about the identifier of a DtInfo object.

DtMmdbInfoRequest

- Describes a request to get information from the DtInfo Database Engine.

DtMmdbGraphicInfo

- Describes various features of a graphic object.