%title 'VAXHELP'
%sbttl 'VAX help routines'
MODULE VAXHELP (IDENT = '01.00'
	,addressing_mode(external=general,nonexternal=general)) =
BEGIN
!+
!
!			  Free software BY
!		Project Software & Development, Inc.
!
! This  software  is  furnished  for  free and may be used and copied as
! desired.  This software or any other copies thereof may be provided or
! otherwise  made  available  to  any  other  person.  No  title  to and
! ownership of the software is hereby transferred or allowed. 
!
! The  information  in this software is subject to change without notice
! and  should  not  be  construed  as  a commitment  by PROJECT SOFTWARE
! AND DEVELOPMENT, INC.
!
! PROJECT SOFTWARE assumes no responsibility for the use or  reliability  
! of this software on any equipment whatsoever.
!
!	Project Software & Development, Inc.
!	14 Story St.
!	Cambridge, Ma. 02138
!	617-661-1444
!
!
! FACILITY:
!	
!	VAXNET
!
! ABSTRACT:
!
!	General routines to get help from help libraries.
!
! ENVIRONMENT:
!
!	VAX/VMS user mode, native code
!
! AUTHOR:	R. Miller,	CREATION: December 2, 1982
!
! MODIFIED BY:
!
! 	, : VERSION
! 01	- 
!--

!
! TABLE OF CONTENTS:
!

FORWARD ROUTINE
	vax_get_help,
	format_output;

!
! INCLUDE FILES:
!
library
	'SYS$LIBRARY:LIB';

!
! MACROS:
!

!
! EQUATED SYMBOLS:
!

!
! EXTERNAL REFERENCES:
!
external routine
	lib$get_input,
	lib$put_output,
	lbr$output_help;

!
! OWN STORAGE:
!
own
	help_flags : initial (hlp$m_process+
				hlp$m_group+hlp$m_system+hlp$m_liblist),
	line_count : initial (0),	! Used for counting lines output.
	max_line_count : initial (24),	! Maximum number of lines to output.
	library_ptr : initial (0);	! Pointer to library descriptor to use.

bind
	def_lib_nam = $descriptor('SYS$HELP:HELPLIB.HLB'),
	lib_log_nam = $descriptor('HELPLIB');


%sbttl 'vax_get_help'
GLOBAL ROUTINE vax_get_help	(outrtn_adr
				,line_width
				,max_count
				,key_desc) =

!++
!
! FUNCTIONAL DESCRIPTION:
!	
!	General Help Utility interface
!
! FORMAL PARAMETERS:
!
!	outrtn_adr	Optional address of an output routine (linkage call)
!			the output routine must return a status value.
!	line_width	Optional address of a value specifying the width
!			of the output line.
!	max_count	Optional address of a value specifying the number
!			of times the output routine gets called before
!			a pause occurs.
!	key_desc	Help string descriptor to pass to lbr$output_help.
!
! IMPLICIT INPUTS:
!
!	NONE
!
! IMPLICIT OUTPUTS:
!
!	NONE
!
! ROUTINE VALUE:
! COMPLETION CODES:
!
!	returns lbr status return values
!
! SIDE EFFECTS:
!
!	signals all lbr errors
!
!--

BEGIN

builtin
	actualcount,
	nullparameter;
literal
	buflen = 128;
own
	rslog_buf  : vector[buflen,byte],
	rslog_desc : vector[2];

local
	outrtn,
	width,
	status;

	status = ss$_normal;		! Assume success.

!	Return failure if not enough parameters.

	if (actualcount() neq 4) then return (0);

	if .library_ptr eql 0 then
	begin
	rslog_desc[0] = buflen;		! Maximum length of logical name.
	rslog_desc[1] = rslog_buf;	! Store translated name here.

!	Setup a pointer to the help library to use.

	if ($trnlog	(lognam = lib_log_nam
			,rsllen = rslog_desc
			,rslbuf = rslog_desc) eql ss$_normal)
	then
		library_ptr = rslog_desc
	else
		library_ptr = def_lib_nam;
	end;

	outrtn =(if not nullparameter(1) then .outrtn_adr else format_output);
	width = (if not nullparameter(2) then .line_width else 80);
	max_line_count = (if not nullparameter(3) then .max_count else 24);

	line_count = 0;			! Initialize starting line count.

	if not (status = lbr$output_help (
			.outrtn		! Output routine.
			,width		! Maximum line width.
			,.key_desc	! Address of string descriptor.
			,.library_ptr	! Pointer to library descriptor.
			,help_flags	! Help flags.
			,0
			)
		) then signal (.status);

	return .status;

END;			!End of vax_get_help

routine format_output(hlptxt,flags,data,keylev) =
begin
!++
!
!  This is the default output routine used when the caller does not
!  specify his own output routine.
!
!--
bind
	txtdesc = .hlptxt : vector;

	line_count = .line_count + 1;		! Count this line of text.

!	If the screen is full, pause until the user types something.

	if .line_count geq .max_line_count then 
	    begin
	    literal bufsiz = 80;
	    local resp_str : vector[bufsiz,byte],
		  resp_desc: vector[2];
	    resp_desc[0] = bufsiz;
	    resp_desc[1] = resp_str;
	    ch$fill (%C' ',.resp_desc[0],.resp_desc[1]);
	    lib$get_input(resp_desc,$descriptor(''));
	    line_count = 0;
	    if .resp_str[0] eql %C'E' or .resp_str[0] eql %C'e' then return 0;
	    end;

!	Output the help text.

	lib$put_output(txtdesc);
	return ss$_normal;
end;

END				!End of module
ELUDOM