@(#)README	1.1 1.1 92/03/18 Copyright 1986-1992 SMI

This is the README file for HLI Release 7.0.1, and supplements the information
to be found in the SunLink(R) 3270 Programmer's Guide.  This file is for this
release only, and is subject to removal when the information is incorporated
into referenced document.

--------------------------------------------------------------------------------
Name:
	attach
Synopsis:
	attach( name )
	char   *name;
Description:
	Connects to an already running session.  The named session becomes the
	current session.
Input:
	name		Name of the session (max 255 characters; must be exactly
			one character if EHLLAPI compatability is desired.
Output:
	N/A 
Return codes:
	HLI_OK		Named session is now the current session
	HLI_UNAVAIL	Unable to find the session
Side effects:
	The current session does not change if there is an error.  If the
	requested session has failed, this function will complete the
	termination process and return an error.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	clock_status
Synopsis:
	clock_status( )
Description:
	Return the keyboard lock status of the current session.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The session keyboard is not locked.
	HLI_BUSY	The session keyboard is inhibited by host activity.
	HLI_KLOCKED	The session keyboard is locked.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	clock_wait
Synopsis:
	clock_wait( )
Description:
	Wait for the current session to unlock.  Behavior of this function
	depends on the setting of the session parameter xWAIT, as follows:

	TWAIT (Timed wait)
	    Blocking wait for session unlock.  This function will wait for
		1. the current command to be completed by the daemon, and
		2. the host to release the keyboard lock condition.
	    The command will time-out after the period specified by the TIMEOUT=
	    session parameter, at which point the daemon will be reset.

	LWAIT (Long wait - not recommended)
	    Long wait for session unlock.  This function will wait indefinitely
	    for the events described above.

	NWAIT (No wait)
	    Checks the lock status of the session and returns immediately.
EHLLAPI function implemented:
	 4: WAIT
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The function completed normally; additional information
			is given by the value of global variable _return_code:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard in inhibited by host
				action.
	HLI_ERROR	An error was detected, as further described by the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_SYSTEM_ERROR   The daemon has timed out.
		HLI_BUSY	   The session keyboard is inhibited by data
				   entry.
		HLI_KLOCKED	   The session keyboard in inhibited by host
				   action.
Side effects:
	May cause a daemon reset, with unpredictable results.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	close_session
Synopsis:
	close_session()
Description:
	Terminate the current session and release all associated local system
	resources, including the supporting daemon.  NOTE: the caller must have
	already terminated the host session by the appropriate logoff or other
	action.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		   The current HLI session was terminated successfully.
	HLI_CONNECT_ERROR  There is no current session.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	connect_host
Synopsis:
	connect_host( host, show )
	char   *host;
	int     show;
Description:
	Start a HLI session having the given session name;  if show is nonzero,
	start a hliscope for the session as well.
Input:
	host		Pointer to the name of the session.
	show		hliscope indicator.
Output:
	N/A
Return codes:
	HLI_OK		The session was connected and is ready to accept HLI
			commands.
	HLI_ERROR	The function failed, for the reason detailed in global
			variable _return_code as follows:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
	HLI_UNAVAIL	The session could not be connected.
	HLI_DAEMON	The daemon is in an error status from a previous
			command, and a notation is in the stderr for the daemon.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	convert_pos
Synopsis:
	convert_pos( row, col, pos )
	int    *row;
	int    *col;
	int     pos;
Description:
	Convert position pos to row-column format and store the results in row
	and col; use the current session.
Input:
	row		Pointer to the integer variable to receive the
			one-origin row number.
	col		Pointer to the integer variable to receive the
			one-origin column number.
	pos		One-origin position to be converted to row-column
			format.
Output:
	row		Points to the returned row number.
	col		Points to the returned column number.
Return codes:
	HLI_OK		The conversion succeeded.
	HLI_ERROR	The conversion failed, as detailed by the value in
			global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_ZERO	The position was not within the P/S.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	    convert_row_col
Synopsis:
	convert_row_col( row, col, pos )
	int      row;
	int      col;
	int     *pos;
Description:
	Convert row "row" and column "col" to position format and store the
	result in "pos"; use the current session.
Input:
	row		One-origin row number to be converted to position
			format.
	col		One-origin column number to be converted to position
			format.
	pos		Pointer to the integer variable to receive the
			one-origin position.
Output:
	pos		pointer to the returned position.
Return codes:
	HLI_OK		The conversion succeeded.
	HLI_ERROR	The conversion failed, as detailed by the value in
			global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_ZERO	The row or column was not within the P/S.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	copy_oia
Synopsis:
	copy_oia( str, len )
	char   *str;
	int     len;
Description:
	Copy the contents of the Operator Information Area (OIA) of the current
	session into the string pointed to by str, whose length is at least len
	bytes.
EHLLAPI function implemented:
	13: COPY OIA
Input:
	len		Length of the area pointed to by str.
	str		Pointer to a character string at least 81 bytes long.
Output:
	str		Poins to the following data:
1234567 101234567 201234567 301234567 401234567 501234567 601234567 701234567 80
LUnnn   INACTIV LOCKED  WAIT    nnn       nnn         * 
BSCnnn  APPL
LCLxxxx SSCP
	UNOWNED
	UNAVAIL
	?STATE?
Return codes:
	HLI_OK		The OIA was successfully copied.
	HLI_ERROR	The OIA was not copied, for the reason given in the
			value of global variable _return_code:
		HLI_PARM_ERROR	The length given in len was less than 81.
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	copy_ps
Synopsis:
	copy_ps( str )
	char   *str;
Description:
	Copy the entire presentation space of the current session to the user's
	area pointed to by "str".  This routine replaces any null's "\0" in the
	source area with ascii space ' ' characters.  If the ATTRB option is
	set, attributes will be copied to the users buf with the high-order bit
	on.  The user is responsible for these non-standard characters.  If the
	NOATTRB option in set or defaulted, attributes in the source area are
	copied as space (' ') characters.
EHLLAPI function implemented:
	 5: COPY PRESENTATION SPACE
Input:
	str		Pointer to a character array long enough to hold the
			entire presentation space plus a null terminator byte.
Output:
	str		Contains a copy of the P/S.
Return codes:
	HLI_OK		The copy is complete without error.  Additional status
			is given by the value of global variable _return_code:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard is inhibited by host
				action.
	HLI_ERROR	No data was copied, or not all data was copied;  for
			more information, refer to the value of global variable
			_return_code:
		HLI_POSITION_ERROR	pos does not describe a position in the
					P/S.
		HLI_PARM_ERROR		len is not positive.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	dump_screen
Synopsis:
	dump_screen()
Description:
	Copy the screen image from the current Presentation Space to the stdout
	file, in the standard HLI screen output format.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The dump was successful.
	HLI_ERROR	The dump failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	field_to_string
Synopsis:
	field_to_string( str, pos, len )
	char   *str;
	int     pos;
	int     len;
Description:
	Copy the contents of the field of the current Presentation Space into
	the character string pointed to by str, up to a maximum of len bytes.
EHLLAPI function implemented:
	34: COPY FIELD TO STRING
Input:
	str		String into which to copy the data (length is at least
			(len+1) bytes.
	pos		Offset in the presentation space of a position within
			the desired field.
	len		Number of bytes to be copied.
Output:
	str		The copied contents of the field
Return codes:
	HLI_OK		The data was copied successfully.
	HLI_ERROR	An error prevented the data from being completely
			copied.  The detailed reason is in the value of global
			variable _return_code, as follows:
		HLI_CONNECT_ERROR   There is no current session.
		HLI_SYSTEM_ERROR    The daemon has terminated.
		HLI_PARM_ERROR      The string was null or len was non-positive.
		HLI_POSITION_ERROR  Position pos is not within the P/S.
		HLI_DATA_ERROR      The P/S is not formatted or the length of
				    the field is not len characters.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	find_field_length
Synopsis:
	find_field_length( method, position )
	char   *method;
	int     position;
Description:
	Find the length of a field in the current presentation space.  The
	field is located by reference to the field which contains position
	pos; method tells how to find the field.
EHLLAPI function implemented:
	32: FIND FIELD LENGTH
Input:
	method		A coded indication of how to find the desired field:
		""	This field
		"T"	This field
		"P"	Previous field, protected or unprotected
		"N"	Next field, protected or unprotected
		"NP"	Next protected field
		"NU"	Next unprotected field
		"PP"	Previous protected field
		"PU"	Previous unprotected field
	position	Position within the Presentation Space of a character
			within the reference field (The attribute is considered
			to be within the reference field).
Output:
	N/A
Return codes:
	positive	The length of the desired field.
	0 (zero)	The field has zero length, and global variable
			_return_code is set as follows:
		HLI_FIELD_ERROR	 Field was found and has length 0 (zero).
	HLI_ERROR	An error occurred in finding the field.  The exact
			meaning is to be found in the value of global variable
			_return_code, as follows:
		HLI_CONNECT_ERROR   There is no current session.
		HLI_SYSTEM_ERROR    The daemon has terminated.
		HLI_POSITION_ERROR   pos is not within the P/S.
		HLI_UNFORMATTED	     The P/S is not formatted.
		HLI_PARM_ERROR       method is not of the proper form.
		HLI_NOT_FOUND        No fields of the desired type.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	find_field_position
Synopsis:
	find_field_position( method, pos )
	char   *method;
	int     pos;
Description:
	Find the position of a field in the current presentation space.  The
	field is located by reference to the field which contains position
	pos; method tells how to find the field.
EHLLAPI function implemented:
	31: FIND FIELD POSITION
Input:
	method		A coded indication of how to find the desired field:
		""	This field
		"T"	This field
		"P"	Previous field, protected or unprotected
		"N"	Next field, protected or unprotected
		"NP"	Next protected field
		"NU"	Next unprotected field
		"PP"	Previous protected field
		"PU"	Previous unprotected field
	position	Position within the Presentation Space of a character
			within the reference field (The attribute is considered
			to be within the reference field).
Output:
	N/A
Return codes:
	positive	The position of the desired field.
	HLI_ZERO	An error occurred in finding the field.  The exact
			meaning is to be found in the value of global variable
			_return_code, as follows:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_POSITION_ERROR   pos is not within the P/S.
		HLI_UNFORMATTED	     The P/S is not formatted.
		HLI_PARM_ERROR       method is not of the proper form.
		HLI_NOT_FOUND        No fields of the desired type.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	hli_pause
Synopsis:
	hli_pause( len )
	int     len;
Description:
	Pause for the length of time len, expressed in half-seconds.  If IPAUSE
	is in effect and a monitored host event occurs before the time interval
	expires, return with a special return code.
EHLLAPI function implemented:
	18: PAUSE
Input:
	len		Length of time, in half-seconds.
Output:
	N/A
Return codes:
	HLI_OK		The pause interval has been satisfied, and no events
			have been detected.
	HLI_HOST_EVENT	A monitored event has been detected.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	hllc
Synopsis:
	hllc( func, str, len, pos )
	int    *func;
	char   *str;
	int    *len;
	int    *pos;
Description:
	EHLLAPI compatibility function.  See the EHLLAPI reference manual for
	complete description of this function.
Input:
	func		Pointer to the function number.
	str		Pointer to the associated character string.
	len		Pointer to the associated length.
	pos		Pointer to the associated position.
Output:
	pos		Pointer to the returned code; values returned by hllc
			are:
		HLI_ERROR	FUnction not implemented by HLI.
		HLI_UNDEFINED	Function not defined in EHLLAPI.
			Other errors may be generated by subordinate functions.
Return codes:
	N/A
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	kill_screen
Synopsis:
	kill_screen()
Description:
	Terminate any active hli_scope or set screen output for the current
	Presentation Space.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The kill was successful.
	HLI_ERROR	The kill failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	ps_to_string
Synopsis:
	ps_to_string( buf, pos, len )
	char   *buf;
	int     pos; 
	int     len;
Description:
	Copy a portion of the current session's presentation space, starting at 
	presentation space position "pos", to the user's buffer "buf", running
	for "len" bytes.  This routine replaces any null's "\0" in the source
	area with ascii space ' ' characters.  If the ATTRB option is set,
	attributes will be copied to the users buf with the high-order bit on.
	The user is responsible for these non-standard characters.  If the
	NOATTRB option in set or defaulted, attributes in the source area are
	copied as space (' ') characters.
EHLLAPI function implemented:
	 8: COPY PRESENTATION SPACE TO STRING
Input:
	buf		Pointer to a character array long enough to hold the
			len bytes of the presentation space plus a null
			terminator byte.
	pos		Starting position of the P/S to copy.
	len		Number of byutes to copy.
Output:
	pos		Contains a copy of the portion of the P/S.
Return codes:
	HLI_OK		The copy is complete without error.  Additional status
			is given by the value of global variable _return_code:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard is inhibited by host
				action.
	HLI_OK		The copy is complete without error.
	HLI_ERROR	No data was copied, or not all data was copied;  for
			more information, refer to the value of global variable
			_return_code:
		HLI_CONNECT_ERROR       There is no current session.
		HLI_SYSTEM_ERROR        The daemon has terminated.
		HLI_POSITION_ERROR	pos does not describe a position in the
					P/S.
		HLI_PARM_ERROR		len is not positive.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	query_cursor
Synopsis:
	query_cursor()
Description:
	Get the position of the cursor within the current Presentation Space.
EHLLAPI function implemented:
	 7: QUERY CURSOR LOCATION
Input:
	N/A
Output:
	N/A
Return codes:
	positive	Cursor position within the current P/S.
	HLI_ERROR	The cursor position could not be determined.  Global
			variable _return_code has detailed information:
		HLI_CONNECT_ERROR 	There is no current session.
		HLI_SYSTEM_ERROR  	The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	query_field_attribute
Synopsis:
	query_field_attribute( pos )
	int     pos;
Description:
	Returns the integer value of the attribute associated with position
	"pos" of the current presentation space.
EHLLAPI function implemented:
	14: QUERY FIELD ATTRIBUTE
Input:
	pos		Position within a field of the current P/S.
Output:
	N/A
Return codes:
	positive	Value of the attribute.  The attribute bits are 
			interpreted as follows:
		0x80 Always on for an attribute in HLI.
		0x40 No meaning.
		0x20 Protected.
		0x10 Numeric (Skip if also Protected).
		0x08 Display
		0x04   control.
		0x02 Must be zero.
		0x01 Modification Data Tag (MDT) - set when field is modified.
	HLI_ERROR	The attribute could not be determined.  Global variable
			_return_code has detailed information:
		HLI_CONNECT_ERROR 	There is no current session.
		HLI_SYSTEM_ERROR  	The daemon has terminated.
		HLI_UNFORMATTED	  	The P/S is not formatted.
		HLI_POSITION_ERROR	The position is not within the P/S.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	query_sessions
Synopsis:
	query_sessions( str, len )
	char   *str;
	int     len;
Description:
	Build a list of the session names of all active sessions, returning the
	list in the character string pointed by str whose maximum length is len.
EHLLAPI function implemented:
	10: QUERY SESSIONS
Input:
	str		Pointer to the output character string.
	len		Length of the output string, including a one-byte null
			terminator.
Output:
	str		Contains a blank-separated string of names of active HLI
			sessions.
Return codes:
	HLI_OK		The string was completely built.
	HLI_ERROR	Not all sessions could be listed in the string.  Global
			variable _return_code contains additional information:
		HLI_PARAM_ERROR		The string was too short to contain all
					the information.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	query_update
Synopsis:
	query_update( str )
	char   *str;
Description:
	Determine if the named session has been updated since monitoring was
	started or since the last call to query_update().  Session monitoring
	must be in effect.
EHLLAPI function implemented:
	24: QUERY HOST UPDATE
Input:
	str		Pointer to a one-byte character string naming the
			Session to be queried.
Output:
	N/A
Return codes:
	HLI_OK		The query completed successfully.  Global variable
			_return_code has detailed information:
		HLI_OK			No monitored updates.
		HLI_PS_UPDATED		P/S was updated.
		HLI_OIA_UPDATED		OIA was updated.
		HLI_BOTH_UPDATED	Both P/S and OIA were updated.
	HLI_ERROR	The query could not be completed.  Global variable
			_return_code has detailed information:
		HLI_CONNECT_ERROR 	The indicated session does not exist.
		HLI_SYSTEM_ERROR  	The daemon has terminated.
		HLI_SEQUENCE_ERROR	The indicated session is not being
					monitored.
Side effects:
	This function does not support long (more that one character) P/S
	names.  To query update for a non-EHLLAPI P/S name, first attach()
	the desired P/S by name, then issue query_update() with the P/S name
	being blank (implies current P/S).
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	recv_file
Synopsis:
	recv_file( command, transparent )
	char   *command;
	int     transparent;
Description:
	Receive a file from the host, as specified in the command string
	"command", by way of the current session;  if transparent is non-zero
	do not check for CR/LF sequences.
EHLLAPI function implemented:
	91: RECEIVE FILE
Input:
	command		A character string specifying the file transfer:
			"local_file host_file [options]"
	transparent	If non-zero, do not process CR/LF sequences.
Output:
	N/A
Return codes:
	HLI_OK		File transfer completed.  Global variable _return_code
			gives additional status information:
		HLI_FILE_TRANSFER_COMPLETE     File transfer completed normally.
		HLI_FILE_TRANSFER_COMPLETE_SEG File transfer completed normally,
					       with segmented records.
		HLI_PARM_ERROR		       Error message listed on the
					       td stderr file.
	HLI_ERROR	File transfer did not complete.  Global variable
			_return_code details the failure:
		HLI_PARM_ERROR		"command" length was zero or >128.
		HLI_SYSTEM_ERROR	There is no current P/S, or the local 
					file could not be created/used.
		HLI_ACCESS_DENIED	The local file could not be written.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	search_field
Synopsis:
	search_field( str, pos )
	char   *str;
	int     pos;
Description:
	Find the string pointed to by str in the field containing position pos,
	in the current Presentation Space, returning the position as the
	function value.
EHLLAPI function implemented:
	30: SEARCH FIELD
Input:
	str		Pointer to the (non-null) string to be searched for.
	pos		Position within the field to be searched for the string.
Output:
	N/A
Return codes:
	positive	The string was found at the returned position.
	HLI_ZERO	The string was not found;  the detailed reason is in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR   There is no current session.
		HLI_SYSTEM_ERROR    The daemon has terminated.
		HLI_PARM_ERROR	    The string has zero length.
		HLI_POSITION_ERROR  The position is not within the P/S.
		HLI_UNFORMATTED	    The P/S is not formatted.
		HLI_NOT_FOUND       The string was not found in the field.
		session_find_field_position
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	search_ps
Synopsis:
	search_ps( str, pos )
	char   *str;
	int     pos;
Description:
	Search for the character string str in the current Presentation Space,
	starting at position pos.  The function return value is the position of
	the string in the P/S.  If global parameter SRCHALL is set, start the
	search at the beginning of the P/S.
EHLLAPI function implemented:
	 6: SEARCH PRESENTATION SPACE
Input:
	str		Pointer to the (non-null) string to be searched for.
	pos		Starting position for the search.
Output:
	N/A
Return codes:
	positive	The string was found at this position.
	HLI_ZERO	The string was not found.  Global variable _return_code
			contains a detailed indication of the failure:
		HLI_CONNECT_ERROR      There is no current session.
		HLI_SYSTEM_ERROR       The daemon has terminated.
		HLI_POSITION_ERROR     The position is not within the P/S.
		HLI_PARM_ERROR         The string has zero length.
		HLI_NOT_FOUND          The string was not found.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	search_string
Synopsis:
	search_string( str )
	char   *str;
Description:
	Search for the character string str in the current Presentation Space,
	starting from the beginning.  The function return value is the position
	of the string in the P/S.
Input:
	str		Pointer to the (non-null) string to be searched for.
Output:
	N/A
Return codes:
	positive	The string was found at this position.
	HLI_ZERO	The string was not found.  Global variable _return_code
			contains a detailed indication of the failure:
		HLI_CONNECT_ERROR      There is no current session.
		HLI_SYSTEM_ERROR       The daemon has terminated.
		HLI_POSITION_ERROR     The position is not within the P/S.
		HLI_PARM_ERROR         The string has zero length.
		HLI_NOT_FOUND          The string was not found.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	search_string_from
Synopsis:
	search_string_from( str, pos )
	char   *str;
	int     pos;
Description:
	Search for the character string str in the current Presentation Space,
	starting at position pos.  The function return value is the position of
	the string in the P/S.  If global parameter SRCHALL is set, start the
	search at the beginning of the P/S.
Input:
	str		Pointer to the (non-null) string to be searched for.
	pos		Starting position for the search.
Output:
	N/A
Return codes:
	positive	The string was found at this position.
	HLI_ZERO	The string was not found.  Global variable _return_code
			contains a detailed indication of the failure:
		HLI_CONNECT_ERROR      There is no current session.
		HLI_SYSTEM_ERROR       The daemon has terminated.
		HLI_POSITION_ERROR     The position is not within the P/S.
		HLI_PARM_ERROR         The string has zero length.
		HLI_NOT_FOUND          The string was not found.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	send_file
Synopsis:
	send_file( command, transparent )
	char   *command;
	int     transparent;
Description:
	Send a file to the host, as specified in the command string "command",
	by way of the current session;  if transparent is non-zero do not change
	LF to CR/LF sequences.
EHLLAPI function implemented:
	90: SEND FILE
Input:
	command		A character string specifying the file transfer:
			"local_file host_file [options]"
	transparent	If non-zero, do not process CR/LF sequences.
Output:
	N/A
Return codes:
	HLI_OK		File transfer completed.  Global variable _return_code
			gives additional status information:
		HLI_FILE_TRANSFER_COMPLETE     File transfer completed normally.
		HLI_FILE_TRANSFER_COMPLETE_SEG File transfer completed normally,
					       with segmented records.
		HLI_PARM_ERROR		       Error message listed on the
					       td stderr file.
	HLI_ERROR	File transfer did not complete.  Global variable
			_return_code details the failure:
		HLI_PARM_ERROR		"command" length was zero or >128.
		HLI_SYSTEM_ERROR	There is no current P/S, or the local 
					file could not be used.
		HLI_FILE_NOT_FOUND	The local file could not be found.
		HLI_ACCESS_DENIED	The local file could not be read.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	send_keystrokes
Synopsis:
	send_keystrokes( keys )
	char   *keys;
Description:
	Send characters from the string keys to the Presentation Space for the
	current session, as if they had come from the keyboard of a "real" 3278.
EHLLAPI function implemented:
	 3: SEND KEY
Input:
	keys		Pointer to a string of keys and mnemonics to be sent.
Output:
	N/A
Return codes:
	HLI_OK		All keystrokes were sent properly.
	HLI_ERROR	The function encountered an error before all keystrokes
			were sent;  global variable _return_code gives further
			indication of the error:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_KLOCKED	   Keyboard locked due to invalid input.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_cursor
Synopsis:
	set_cursor( pos )
	int     pos;
Description:
	Set the cursor for the current Presentation Space to position pos.
EHLLAPI function implemented:
	40: SET CURSOR
Input:
	pos		Position within the P/S to set the cursor.
Output:
	N/A
Return codes:
	HLI_OK		The cursor is set as requested;  additional information
			is found in global variable _return_code, as follows:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard in inhibited by host
				action.
	HLI_ERROR	The cursor was not set, for the reason detailed in
			global variable _return_code, as follows:
		HLI_CONNECT_ERROR  	There is no current session.
		HLI_SYSTEM_ERROR   	The daemon has terminated.
		HLI_POSITION_ERROR	Position pos is not in the P/S.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_device
Synopsis:
	set_device( dev )
	int     dev;
Description:
	Set the device number to be used for subsequently started HLI sessions
	to dev; the number is used for all succeeeding sessions (use of this
	function is not normally advised).
Input:
	dev		Device number, in range acceptable to the gateway being
			used;  default is -1 (gateway selects device).
Output:
	N/A
Return codes:
	HLI_OK		The device was set (only return code).
Side effects:
	The device number is not verified until the next session is started. 
	Specification of an illegal device will cause that session to fail.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_model
Synopsis:
	set_model( model )
	int     model )
Description:
	Set the model number to the value in model;  subsequent sessions will be
	of that type until the next call to set_model().
Input:
	model		Value of the model number of 3278 being emulated.  The
			valid range is 2 thru 5, the default is 2.
Output:
	N/A
Return codes:
	HLI_OK		Model number is set.
	HLI_ERROR	Model number is not valid, and has not been set.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_notrace_new
Synopsis:
	set_notrace_new()
Description:
	Causes all new sessions to start without tracing in effect (this is the
	default trace option).  Tracing may be enabled specifically by a call
	to start_trace().
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The call was successful (only return code).
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_screen
Synopsis:
	set_screen( name )
	char   *name;
Description:
	This routine tells the daemon to use the file specified by name as its
	diagnostic screen device.  The name is usually some form of "/dev/tty?"
	and names a window's tty device address.  May be discontinued by issuing
	kill_screen() below.
Input:
	name		Pointer to the file name.
Output:
	N/A
Return codes:
	HLI_OK		The file specification was accepted.
	HLI_ERROR	The file specification failed, for the reason given in
			the value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_session_parms
Synopsis:
	set_session_parms( char *str, int *len )
	char   *str;
	int    *len;
Description:
	Set the global HLI parameters to the values sspecified in the string
	pointed to by str.  The number of valid parameters is returned in
	the integer pointed to by len.
EHLLAPI function implemented:
	 9: SET SESSION PARAMETERS
Input:
	str		Pointer to the (space- or comma-delimited) string of
			parameters.
	len		Pointer to an int to receive the number of valid
			parameters.
Output:
	len		Points to the number of valid parameters.
Return codes:
	HLI_OK		All parameters were accepted.
	HLI_ERROR	Not all parameters were accepted;  further details are
			found in global variable _return_code:
		HLI_PARM_ERROR	The parameter string was empty or at least one
				parameter was invalid or unrecognized.
Side effects:
	Unsupported parameters are accepted without comment.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_sna_host
Synopsis:
	set_sna_host( host )
	char   *host;
Description:
	This routine sets the default sna host name to the string pointed to by
	host, for use with subsequent start_session() calls.
Input:
	host		Pointer to the host name string.
Output:
	N/A
Return codes:
	HLI_OK		The host name is set (only return code).
Side effects:
	The host name can also be set from environment variable SNAHOST at 
	initialization time.  There is not default; failure to set the host
	name will result in subsequent failures in the library.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	set_trace_new
Synopsis:
	set_trace_new()
Description:
	Cause all new sessions to start with tracing in effect.  Tracing may be
	disabled for a session by a call to stop_trace().  This is in effect
	until the next set_notrace_new call.  (See start_trace for a description
	of the trace.)
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The call was successful (only return code).
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	show_screen
Synopsis:
	show_screen()
Description:
	Update the hli_scope window, if active, for the current Presentation
	Space.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The update was successful.
	HLI_ERROR	The update failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	start_hn
Synopsis:
	start_hn( str )
	char   *str;
Description:
	Start session monitoring for the indicated session.  Updates to the
	Presentation Space, the Operator Information Area, or both may be
	monitored.
EHLLAPI function implemented:
	23: START HOST NOTIFICATION
Input:
	str		Pointer to the two-byte notification string:
	    Byte 0 names the P/S to be monitored; blank means the current P/S.
	    Byte 1 indicates the type of notification requested:
		P means notify on update of Presentation Space.
		O means notify on update of Operator Information Area.
		B means notify of update to either P/S or OIA.
Output:
	N/A
Return codes:
	HLI_OK		Session monitoring is active for the indicated session.
	HLI_ERROR	Session monitoring has not been started, for the reason
			detailed by the value of global variable _return_code:
		HLI_CONNECT_ERROR  The indicated session does not exist.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_PARM_ERROR     The character string is not "P", "O", or "B".
Side effects:
	This function does not support long (more that one character) P/S
	names.  To start session monitoring for a non-EHLLAPI P/S name,
	first attach() the desired P/S by name, then issue start_hn() with 
	the P/S name being blank (implies current P/S).
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	start_screen
Synopsis:
	start_screen( name )
	char   *name;
Description:
	This routine tells the daemon to start a hli_scope display and route all
	diagnostic output to it.  May be turned off using the kill_screen()
	command.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The start was successful.
	HLI_ERROR	The start failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	start_session
Synopsis:
	start_session( id, show )
	char   *id;
	int     show;
Description:
	Start a HLI host session whose name is pointed to by id, starting a
	hli_scope terminal window if showscreen is not zero.  
Input:
	id		Pointer to a non-empty character string of up to 255
			bytes, to name the session.
	show		If not zero, start a hli_scope window for this Session.
Output:
	N/A
Return codes:
	HLI_OK		The session was started successfully.
	HLI_ERROR	No host name specified for the session.
	HLI_UNAVAIL	Resources are not available to start the session.
	start_daemon
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	start_trace
Synopsis:
	start_trace()
Description:
	Cause the daemon to begin a HLI buffer trace of its communication with
	the host, for this session, writing the output to the stdout for the
	daemon.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		Trace start was successful.
	HLI_ERROR	Trace start failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	stop_hn
Synopsis:
	stop_hn( str )
	char   *str;
Description:
	Stop monitoring the named session.
EHLLAPI function implemented:
	25: STOP HOST NOTIFICATION
Input:
	str		Pointer to the one-byte session name string.
Output:
	N/A
Return codes:
	HLI_OK		Session monitoring has been stopped for the indicated
			session.
	HLI_ERROR	Session monitoring has not been stopped, for the reason
			detailed by the value of global variable _return_code:
		HLI_CONNECT_ERROR  The indicated session does not exist.
		HLI_SYSTEM_ERROR   The daemon has terminated.
		HLI_SEQUENCE_ERROR The current session is not being monitored.
Side effects:
	This function does not support long (more that one character) P/S
	names.  To stop session monitoring for a non-EHLLAPI P/S name,
	first attach() the desired P/S by name, then issue stop_hn() with 
	the P/S name being blank (implies current P/S).
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	stop_trace
Synopsis:
	stop_trace()
Description:
	Cause the daemon to cease HLI buffer tracing.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		Trace stop was successful.
	HLI_ERROR	Trace stop failed, for the reason given in the
			value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	string_to_field
Synopsis:
	string_to_field( str, pos )
	char   *str;
	int     pos;
Description:
	Copy the  string pointed to by str into the field containing position
	pos, using the current Presentation Space.
EHLLAPI function implemented:
	33: COPY STRING TO FIELD
Input:
	str		Pointer to the character string to copy.
	pos		Position within the field to which the string is to be
			copied.
Output:
	N/A
Return codes:
	HLI_OK		The copy completed normally; the global variable
			_return_code contains detail information about the copy:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard in inhibited by host
				action.
	HLI_ERROR	An error was detected, either before or during the copy;
			global variable _return_code contains detail information
			about the error:
		HLI_CONNECT_ERROR 	There is no current session.
		HLI_SYSTEM_ERROR  	The daemon has terminated.
		HLI_PARM_ERROR		String str has zero length.
		HLI_POSITION_ERROR	Position pos is not in the P/S.
		HLI_UNFORMATTED		The P/S is not formatted.
		HLI_KLOCKED		A character could not be copied into
					a protected position.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	string_to_ps
Synopsis:
	string_to_ps( str, pos )
	char   *str;
	int     pos;
Description:
	Write the null-terminated string pointed to by str into the current
	presentation space;  pos points to the first PS position to write,
	which must not be a field attribute or protected string.  The write
	will proceed until the string is exhausted or a field attribute is
	encountered.
	Note: this function is not to be used for sending aid (@char) sequences.
EHLLAPI function implemented:
	15: COPY STRING TO PRESENTATION SPACE
Input:
	str		Pointer to the character string to be copied to the
			current presentation space.
	pos		Starting position within the P/S for the copy.
Output:
	N/A
Return codes:
	HLI_OK		The copy is complete without error.  Additional status
			is given by the value of global variable _return_code:
		HLI_OK		The session keyboard is not locked.
		HLI_BUSY	The session keyboard is inhibited by data entry.
		HLI_KLOCKED	The session keyboard is inhibited by host
				action.
	HLI_ERROR	No data was copied, or not all data was copied;  for
			more information, refer to the value of global variable
			_return_code:
		HLI_CONNECT_ERROR       There is no current session.
		HLI_SYSTEM_ERROR        The daemon has terminated.
		HLI_POSITION_ERROR	pos does not describe a position in the
					P/S.
		HLI_PARM_ERROR		The string pointer was null.
		HLI_SYSTEM_ERROR	Could not find start of field.
		HLI_KLOCKED		Copy stopped by an attribute or protect
					field.
Side effects:
	None
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	wait_complete
Synopsis:
	wait_complete()
Description:
	Waits for the daemon for the current Session to acknowledge completion
	of the current command.
	NOTE: (clock) inhibit condition may still be active - call clock_wait()
	to insure that new keystrokes may be sent to the session.
Input:
	N/A
Output:
	N/A
Return codes:
	HLI_OK		The current command complete without error.
	HLI_UNAVAIL	The daemon was disconnected by session reset.
	HLI_ERROR	The function failed; additionaal information is given in
			the value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	This command is subject to timeout after the time interval defined by
	global session parameter TIMEOUT=x.  After such timeout, the status of
	the daemon is not certain.
Notes:
	This function is externally known.

--------------------------------------------------------------------------------
Name:
	wait_for_text
Synopsis:
	wait_for_text( str, tmout )
	char   *str;
	int     tmout;
Description:
	Wait for the text pointed to by str to appear in the current
	presentation space;  wait at most tmout seconds before returning
	an error.
Input:
	str		Pointer to he desired string.
	tmout		Time in seconds to wait.
Output:
	N/A
Return codes:
	positive	The string was found at the position which is returned.
	HLI_ZERO	The string was not found before the time interval
			expired.
	HLI_ERROR	The function failed; additional information is given in
			the value of global variable _return_code:
		HLI_CONNECT_ERROR  There is no current session.
		HLI_SYSTEM_ERROR   The daemon has terminated.
Side effects:
	None
Notes:
	This function is externally known.
