NAME
        OpenAmigaGuideA - open a synchronous amigaguide database.

    SYNOPSIS
        handle = OpenAmigaGuideA (nag, attrs);
        d0                         a0   a1

        amigaguidecontext openamigaguidea (struct newamigaguide *,
                                           struct tagitem *);

        handle = OpenAmigaGuide (nag, tag1, ...);

        amigaguidecontext openamigaguide (struct newamigaguide *,
                                          tag tag1, ...);

    FUNCTION
        Opens a AmigaGuide database, complete with the first viewing
        window, for synchronous activity.

        Before you call OpenAmigaGuide(), you must initialize a newamigaguide
        structure.  newamigaguide is a structure that contains all the
        information needed to open a database.  The newamigaguide structure
        must be retained until the call returns.

        The function will not return until the user closes all the
        windows.

    INPUTS
        nag - Pointer to an instance of a newamigaguide structure.  that
            structure is initialized with the following data.

                  nag_Lock
                  lock on the directory that the database is located in.
                  Not needed if nag_Name contains the complete path name.

                  nag_Name
                  Name of the AmigaGuide database.

                  nag_Screen
                  screen to open the viewing windows on, null for the
                  Workbench screen.

                  nag_PubScreen
                  Pointer to the name of the public screen to open on.
                  Must already be opened.

                  nag_HostPort
                  Name of the applications' ARexx port (currently not used).

                  nag_ClientPort
                  Base name to use for the databases' ARexx port.

                  nag_Flags
                  Used to specify the requirements of this database.  The
                  flags are defined in <libraries/amigaguide.h>.

                  nag_Context
                  NULL terminated array of context nodes, in the form of:

                        /* context array */
                        strptr context[] =
                        {
                            "MAIN",
                            "INTRO",
                            "GADGETS",
                            NULL
                        };

                  The context array is not copied, but referenced,
                  therefore must remain static throughout the useage of
                  the AmigaGuide system.  This array is only referenced
                  when using the SetAmigaGuideContext() function.

                  nag_Node
                  node to start at (does not work with openamigaguideasync())
.

                  nag_Line
                  line to start at (does not work with openamigaguideasync())
.

                  nag_Extens
                  Used by V37 and beyond to pass additional arguments.

                  nag_Client
                  This is a private pointer, MUST be initialized to NULL.

        attrs - Additional attributes.

    TAGS
        AGA_HelpGroup (ULONG) -- Unique identifier used to identify the
            AmigaGuide help windows.  See openwindow() and getuniqueid().

            Default for this tag is NULL.  Applicability is (I). (V39)

    EXAMPLE

        /* Short example showing synchronous AmigaGuide access */
        long showamigaguidefile (strptr name, strptr node, long line)
        {
            struct newamigaguide nag = {null};
            amigaguidecontext handle;
            long retval = 0l;

            /* Fill in the newamigaguide structure */
            nag.nag_Name = name;
            nag.nag_Node = node;
            nag.nag_Line = line;

            /* open the amigaguide client */
            if ( handle = OpenAmigaGuide(&nag, NULL))
            {
                /* close the amigaguide client */
                CloseAmigaGuide(handle);
            }
            else
            {
                /* Get the reason for failure */
                retval = IoErr();
            }

            return (retval);
        }

    RETURNS
        handle - Handle to a AmigaGuide system.

    SEE ALSO
        openamigaguideasynca(), closeamigaguide()