DtInfoShowTopic(API)                                   DtInfoShowTopic(API)




 NAME    [Toc]    [Back]
      DtInfoShowTopic - provide the user access to a local information
      corpus at a specific location

 SYNOPSIS    [Toc]    [Back]
      #include <Dt/Info.h>
      DtIfnoShowStatus DtInfoShowTopic(
      const char *info_lib,
      const char *locator);

 DESCRIPTION    [Toc]    [Back]
      By invoking DtInfoShowTopic, a client application requests that dtinfo
      display a particular section of data, or topic. DtInfoShowTopic sends
      a ToolTalk message to any active dtinfo process that can access the
      requested information in the current locale.  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.

      The locator parameter must be a valid, resolvable location in the
      specified or default infolib for dtinfo to display the location.
      Unfortunately, there is no way to determine this from the calling
      application as DtInfoShowTopic will return an ok status as long as the
      message has been delivered to dtinfo.  In the case of an invalid
      locator, dtinfo will still map to the current workspace of the
      invoking application and display an error dialog.

      This API is implemented in the Desktop Services library, DtSvc. To
      access the DtShowInfoTopic API, include the header file Dt/Info.h and
      link with -lDtSvc.

 ARGUMENTS    [Toc]    [Back]
      *info_lib Specifies a file path, relative or absolute, to an
                information library. If info_lib is NULL, the browser
                displays the default information library(s).

      *locator  Specifies the information library section in generalized
                locator format.

 RETURN VALUE    [Toc]    [Back]
      DtINFO_SHOW_OK
                ToolTalk request succesfully sent.

      DtINFO_SHOW_BAD_LOCATOR    [Toc]    [Back]
                The locator argument is NULL.

      DtINFO_SHOW_TT_OPEN_FAIL    [Toc]    [Back]
                Call to tt_open() failed.

      DtINFO_SHOW_MSG_CREATE_FAIL    [Toc]    [Back]
                Call to tt_message_create() failed.




                                    - 1 -       Formatted:  January 24, 2005






 DtInfoShowTopic(API)                                   DtInfoShowTopic(API)




      DtINFO_SHOW_MSG_SEND_FAIL    [Toc]    [Back]
                Call to tt_message_send() failed.

 ENVIRONMENT    [Toc]    [Back]
      DTINFOLIBSEARCHPATH
                Search path environment variable for locating information
                libraries on local and remote mounted systems.

      DTINFOLIBDEFAULT    [Toc]    [Back]
                Specifies the name of the default information library(s) to
                load if the locator argument is NULL. Multiple information
                libraries can be specified by a comma separated list.


                                    - 2 -       Formatted:  January 24, 2005