Click above to get retro games delivered to your door ever month!

Function:    RH_TEXT()

Purpose:     Get help text for specified help key from compiled .HLP file

Syntax:      RH_TEXT( rhelpfile, help_key )

Arguments:   rhelpfile   - This parameter may be either the rhelp compiled
                           filename, or the numeric file handle returned
                           from a previous call to FOPEN() to open the
                           help file.

             help_key    - Character value indicating the text associated
                           as the key for the desired help.  This text can
                           any length but only the first 16 characters are
                           significant.  Case is insensitive.

Returns:     The associated help text block as a character string.  If the
             specified help key is not found, or an error occurs, a null
             string ("") is returned.

Description: This function reads and returns a block of help text
             associated with the specified help key from a help file that
             was compiled with the Rhelp compiler.  The help key is a
             unique character string that identifies an entry in the Rhelp
             compiled help file.  This allows help systems to be queried
             by supplying a descriptive character string.  RH-TEXT()
             function does all the work.

             See Appendix C entitled The RHELP Compiler for more detailed
             information and examples.

Notes:       If the helpfile parameter is supplied as a character string,
             it is deemed to be the name of the Rhelp file.  In this case
             the help file is opened (using FOPEN()), the header is then
             extracted, the help file closed, and the header returned.  If
             the FOPEN() fails, a null is returned, and RLIBERROR() set.

             If the helpfile parameter is supplied as a numeric value, it
             is deemed to be the numeric file handle returned by
             previously FOPEN()ing the help file.  In this case, the text
             is read and returned, but the file is not closed.  This
             feature allows you the flexibility of leaving the help file
             open during the course of your application, therefore
             speeding up access by not having to constantly open and close
             the help file.  This method of access is not recommended if
             you are short on file handles or you are not comfortable with
             low level file operations.  If you use this method, always
             remember to FCLOSE() your files.

             After reading the help text, the file pointer position is
             left after the text (perhaps at the next text location.)

Example:     helpText = RH_TEXT("myapp.hlp", "MENU HELP" )

             *-- or

             helpHandle = FOPEN("myapp.hlp")
             helpText = RH_TEXT( helpHandle, "MENU HELP" )

Source:      RL_RHELP.PRG

See also:    RH_HEADER(), RH_WIDTH(), RH_LINES()