CD Actual 8/CDACTUAL8.iso/share/os2/varios/hyperacc/haos2d.z/API_REF.TXT

Text File | 1996-06-24 | 275.7 KB | 6,232 lines

HyperACCESS Application Programming Interface (HAPI) Manual (disk
version) Copyright 1995, Hilgraeve, Inc.
_________________________________________________________________
(The best way to view API_REF.TXT in OS/2 Enhanced Editor, Windows
Notepad, or Windows WordPad is to turn on Word Wrap. The best way
to print API_REF.TXT is to open this a word processor, select the
entire file, and format the text in 10 point Courier before printing.)

__________________________________________________________________

Introduction

This disk copy of the HyperACCESS Application Programming
Interface (HAPI) Manual provides information for programmers who
want to take advantage of powerful customization and programming
features available with HyperACCESS.  The HyperACCESS User's
Manual contains information required by everyday users of
HyperACCESS.  The printed copy of this manual contains additional
information for both novice and advanced programmers.  It is
available from Hilgraeve for $20 U.S.  Call 1-800-826-2760 to
order your copy.


About This Manual

This manual provides a common source of application programming
information for HyperACCESS for OS/2 (HA/OS2),  HyperACCESS for
Windows 95 (HA/Win95), and HyperACCESS for Windows 3.1 (HA/Win).
HAPI maintains cross-platform compatiblity among these systems so that
you can create one application program that will run in any of these
environments. When a function isn't applicable to a particular environment,
it is either a no-op (no operation), or has a reasonable default behavior.
Differences between environments are noted where appropriate.

In this manual you will see how to use HyperACCESS's automation tools.
You'll find:

    - Benefits of an external API and automatic program generation
             using a standard programming language.
    - Program requirements.
    - Programming examples using C, REXX, and other languages.
    - Complete reference for HAPI.
    - A brief tutorial on the C language.


This introduction continues with overview information about
programming in HyperACCESS.  The printed version of this manual
includes the following chapters and appendices:

Chapter 1, Creating and Editing Programs, provides a brief
            overview of tools available within HyperACCESS, and
            HyperACCESS's program requirements.
Chapter 2, Using External Languages, includes a description of
            external programming requirements for HyperACCESS, and how to
            use HAPI.
Chapter 3, Examples, includes simple procedural operations
            using internal or external C language programs, REXX, and
            Visual Basic.
Chapter 4, API Reference, provides a complete reference to
            HAPI.
Appendix A, C Language Tutorial, provides a simple tutorial
            for users interested in learning C language programming as
            it's used in HyperACCESS.
Appendix B, Built-in C Language Interpreter, lists exclusions
            from standard C for programs that will use the built-in C
            language interpreter found in HyperACCESS for Windows. It also
            includes a complete operator precedence table.


Manual Conventions

            This manual uses a mix of terminology from HAOS2 and HAWin. In
            particular, we use the terms panels and phonebook entries from
            HAOS2 instead of windows and sessions from HAWin. There are
            technical differences between the multiple document interface
            (MDI) windows used in HAWin and panels use in HAOS2. The most
            important distinction is that HAWin permits access to multiple
            remote systems (sessions) from within one executing instance
            of the program, while HAOS2 can connect to only one remote
            system per executing instance of the program.

            To maintain backward compatibility with HAWin, the term
            session continues to appear in the context of connections to
            remote systems. In HAOS2, there is only one "session" per
            executing instance of the program, while an HAWin program
            instance could have multiple concurrent session windows
            communicating at one time. Whenever a function refers to a
            session window, the HAOS2 analog is the Terminal panel.


Text Conventions

            This manual uses a few special symbols and conventions. Words
            and characters shown as ALL CAPITALS in courier font are
            directory or file names. For example, \HAOS2 is a directory
            name; MYPROG.C is a filename. Specific programming language
            statements and examples also appear in courier font in mixed
            case.

            This manual uses the C language mixed case conventions, and
            most examples appear in C. Even though reserved words and
            functions in REXX programs generally appear in upper case, you
            can type HAPI functions in mixed case or all upper case if you
            use the definition files included with HyperACCESS.

            Words and characters in bold in a san-serif font indicate
            anything you must type exactly as it appears. For example,
            COM1 specifies that you should type the bold characters
            exactly as shown. Bold is also used to identify command
            buttons or key words and phrases found in dialog boxes. For
            example, "click the Settings... button." names of HAPI
            functions or variables also appear in bold in a san-serif
            font. For example, haInitialize is the name of a function used
            extensively. In some cases, words and characters in bold also
            indicate emphasis.

            Words and characters in italics indicate a new term. An
            explanation generally follows the italicized term. Italics
            also indicate references to specific chapter or section
            titles.

            In a few places, you'll see mnemonic command letters used in
            menus and dialog boxes (e.g., F for File menu). These appear
            in bold with an underline to be consistent with the screen
            displays.


Hilgraeve Customer Support

            If you have a question about HyperACCESS and can't find the
            answer in this manual, the User's Manual, or in the
            HyperACCESS Help system, you can reach us by:


            Hilgraeve BBS

            Call the Hilgraeve BBS at [phone] and send a message to
            our Customer Support staff. For your convenience, the
            HyperACCESS Phonebook already contains the Hilgraeve BBS
            telephone number and correct settings, and Chapter 2 of the
            User's Manual explains what you can expect to see in Placing
            Your First Call on page 2-13. We will try to respond to you on
            the BBS within one business day, so you can call back at your
            convenience to get the answer. Asking questions on our BBS is
            easy and confidential - messages exchanged with our Customer
            Support staff are private and never seen by other callers.


            CompuServe

            If you prefer, you can reach Hilgraeve Customer Support
            through CompuServe. Use the GO HILGRAEVE command. You'll be
            sent to the PC Vendor F forum. Then look for the Hilgraeve
            section. Send us a message in the category of your choice.


            Internet

            To send mail to Hilgraeve Customer Support via the Internet,
            use the address:
            [e-mail]

            or for access via the World Wide Web use:
            //http://www.hilgraeve.com


            Telephone Support

            If you need answers quickly, or simply prefer talking to
            humans, call [phone], between 9:00 am and 6:00 pm
            Eastern Time. Our Customer Support staff will give you the
            advice you need to get the most from HyperACCESS. Before you
            call, please register your copy of HyperACCESS by returning
            the Registration Card or by calling the Hilgraeve BBS.

            We suggest that you try to duplicate the problem, and as you
            do so, write down each step as well as any error messages you
            see. So that we can provide you with the best possible
            customer support, we recommend that you be at your computer
            when you call, and try to have the following available:
              - HyperACCESS Application Programming Interface Manual (this
                manual).
              - The version and serial number on your HyperACCESS disk
                label.
              - The operating system version number.
              - Computer information - including type and model of
                computer, monitor, and video card. Amount and type of
                installed memory are also important.

            Hilgraeve Inc.
            Genesis Centre
            111 Conant Avenue, Suite A
            Monroe, MI 48161
            [phone]
            FAX [phone]
            BBS [phone] (8N1 ANSI)
            Internet: [e-mail]
            WWW: //http://www.hilgraeve.com



API Programming Requirements

            This section describes those rules and conventions that you
            must follow regardless of programming language. Although the
            examples use C language constructs, you must execute similar
            statements in whatever language you're using. You'll find
            language-dependent requirements in Chapter 2, Using External
            Languages.

            HAPI functions are available through a Dynamic Link Library
            (DLL). You can call functions in this DLL from any programming
            environment that can call standard DLLs. HAPI functions use
            standard calling conventions, and you can link them with an
            import library or load them dynamically.


Script Handles

            Every external program that accesses HyperACCESS must call the
            function haInitialize. This function returns a script handle.
            Script handles maintain the connection between HyperACCESS and
            the program communicating with it.

            The script handle is a numeric value that's meaningful to HAPI
            functions, and your program must keep it available for use by
            HAPI functions. All other HAPI function calls you make must
            pass a script handle as an argument. A script handle is like a
            confirmation number for a hotel. The sequence of numbers you
            receive has no meaning in and of itself. However, that number
            lets the hotel quickly and easily access your reservation.

            Script handles provide a similar service for your program and
            its connections to HyperACCESS. Since a program can have more
            than one connection, the script handle lets HyperACCESS know
            which connection you're referring to.

            Most programs have a single connection, or script handle,
            associated with a single open session. More advanced
            applications may require multiple connections to a session
            and/or connection to multiple sessions. The discussions that
            follow assume the simple, single script handle case.

            To coordinate operation between sessions and external
            programs, haInitialize blocks sessions from receiving
            characters from the communications driver until one of the
            HAPI functions processes incoming data. This is required
            because it's impossible to write a reliable script unless it
            has access to all data received.

            By blocking incoming data, haInitialize ensures that your
            program has access to every received character. You accomplish
            this by calling one of the HAPI functions that looks at
            received data. Only a few HAPI functions actually process
            incoming characters. For example, haGetInput, haWaitForPrompt,
            and haWaitForString all process incoming data, while
            characters remain blocked if you call haBlockRemoteInput,
            haGetConnectTime, haMenuString, and most other HAPI functions.
            When HyperACCESS blocks a session, the driver continues to
            accumulate characters in the communications buffer until
            they're processed by the program, or the buffer fills. When
            the buffer is full, normal flow control suspends character
            transmission from the remote system.

            In programs generated by HyperACCESS, the statement:
                    ScriptHandle = haInitialize(0,0,0,0);
            uses the variable ScriptHandle to store the connection between
            the external program and the session. It also blocks the
            communications driver from releasing characters to the session
            until they're released by other function calls. All subsequent
            calls in the generated program use this variable as an
            argument. For example, the following statement would send a
            carriage return character to the session's remote system:
                    haTypeText(ScriptHandle, 0, "\r");

          Note: \r represents the carriage return character in C.

            The following function would search for the character string
            "ssword:", and release all characters to the Terminal panel
            until that string is found:
                    haWaitForPrompt(ScriptHandle, 1, "ssword:", 300L,
                            100000L);

            In addition, it sets two timeout values: 300 msec. is the
            pause that must be seen after the string is identified, and
            100,000 msec (100 seconds) is the timeout value used to
            indicate that the operation has failed if the string still
            hasn't been seen.

           Note: The L in 300L and 100000L indicates a long integer in C.



Disconnecting an External Program from a Session

            You must always call the HAPI function haTerminate when your
            external program has completed its operations. haTerminate
            lets HAPI free any resources it may have allocated. It also
            releases characters that your program didn't process from the
            communications buffer. The function call looks like:
                    haTerminate(ScriptHandle, 0);

           Caution: If you forget to call this function at the end of
            your program, the session remains blocked and characters from
            the remote system aren't processed.



REXX Programming Requirements in OS/2

            The REXX interpreter requires registration of external
            functions before you call them. HAPI provides a simplified
            technique for registering its functions. You register one
            function, haLoadFuncs. Calling it registers all other HAPI
            functions.

            In addition, you need to explicitly parse the command line for
            any arguments. To accomplish these two functions, all OS/2
            REXX programs should include the following statements:

            /* Parse the command line for arguments passed to this program */
                         PARSE ARG pipename

                      /* Register external functions with REXX */
                      CALL RxFuncAdd `haLoadFuncs', `HA_AUTO',`RxhaLoadFuncs'
                      CALL haLoadFuncs

                      /* Establish a link between this script program and
          HyperACCESS */
                      scripthandle = haInitialize(1, pipename)
                      DROP pipename

            At the end of the program, you should include the following
            statements:
                      /* Terminate link between HyperACCESS and script
          program */
                      CALL haTerminate scripthandle

                      DROP scripthandle

                      /* Remove HAPI functions from REXX registration */
                      CALL haDropFuncs
                      exit


Standard Values and Return Codes

            All HAPI examples, supplied programs, and documentation use
            names for parameter values and return codes.

            HyperACCESS provides the file ha_auto.h for use with
            external C language development systems. This file includes
            prototypes of all HAPI functions with declarations for all
            parameters.

            Using ha_auto.h, you can use names instead of numbers as
            parameters to HAPI function calls. For example, if
            you want to set the send transfer protocol to HyperProtocol
            from your program, you could write:
                    ReturnCode = haSetXferProtocol(ScriptHandle,
                            HA_XFER_SEND, HA_HYPERP);

            Alternatively, since the value of both HA_XFER_SEND and
            HA_HYPERP is 11, you could type:
                    ReturnCode = haSetXferProtocol(ScriptHandle, 1, 1);

            The reason these two examples are the same is because of the
            following two lines in ha_auto.h:
                    #define HA_FER_SEND  1
                     #define HA_HYPERP    1

            Programmers use this technique to make their programs more
            readable.


            C Programming in OS/2

            In OS/2, you must write your C programs from scratch. You can
            easily convert learned REXX programs to C, but you need to
            include the following statements for your program to compile
            correctly:
                 #include <os2.h>
                  #include <ha_auto.h>
            For more information about using compiling C language
            programs, see Chapter 2, Using External Languages.


            Error Code Values

            Most HAPI functions return an integer value and are declared
            int or long. Functions that return a session or window handle
            (i.e., they are declared HSESS, HWND, or SCRIPTHANDLE) return
            a value of zero when they fail. Integer functions return a
            value greater than or equal to zero if they're successful, and
            a value less than zero (HA_ERR_OK) and greater than or equal
            to HA_ERR_MAX_ERR if an error has occurred.

            Most integer functions return some standard error codes.
            HA_ERR_BUSY, for example, indicates that you attempted to call
            a function while another function call was active. Other error
            codes provide information that's appropriate to only a few
            functions. For example, functions that have a timeout value as
            one of their arguments may return HA_ERR_TIMED_OUT.

            Whenever you call a HAPI function, you should check the return
            code and perform appropriate error correction procedures. In
            many cases, you'll simply report the error via haMessageBox
            (or some similar API call available through your development
            environment), call haTerminate, and then exit.

            For example, if your program calls haWaitForPrompt, you should
            check for the possibility that a timeout occurred before the
            string was detected. Your program code could look like:
                    ReturnCode = haWaitForPrompt(ScriptHandle, 1,
                            "r name: ", 300L, 100000L);
                    if (ReturnCode == HA_ERR_TIMEOUT)
                        {
                        haTerminate(ScriptHandle, 0)
                        exit();
                        }
                    . . .

            In this example, haWaitForPrompt will wait until it finds the
            string "r name: " followed by a 300 millisecond pause. If it
            doesn't find that string with the following pause within
            100000 milliseconds (100 seconds), it returns the error code
            HA_ERR_TIMEOUT. This error code is defined to be the value -6
            in defines.h and ha_auto.h. Therefore the program segement
            shown above could have been written as:
                    ReturnCode = haWaitForPrompt(ScriptHandle, 1,
                 "r name: ", 300L, 10000L);
                    if (ReturnCode == -6)
                        {
                        haTerminate(ScriptHandle, 0)
                        exit();
                        }

            The following is a list of errors that HAPI may return.

                      Return
Return Code Name      Value    Description
HA_ERR_BAD_CMD          -1       An API message was
                             received with a
                             command that could
                             not be recognized.
HA_ERR_BAD_PARAM        -2       A parameter was out
                             of range or an
                             unrecognized value.
HA_ERR_BAD_HANDLE       -3       The script, session,
                             or window handle was
                             invalid.
HA_ERR_BUFFER_TOO_SMALL -9       A function was passed
                             a pointer to a buffer
                             with a buffer size
                             parameter that was
                             too small to hold the
                             data to be returned.
HA_ERR_BUSY             -7       An attempt was made
                             to call a function
                             while another
                             function call was
                             active.
HA_ERR_COMMAND_FAILED  -12       The function failed
                             because it is
                             unsupported in this
                             version or for some
                             other reason not
                             enumerated in another
                             error code.
HA_ERR_CONNECTION_LOST  -8       A function waiting
                             for some on-line
                             event to occur (like
                             haWaitForPrompt)
                             failed because the
                             connection was lost
                             while waiting.
HA_ERR_DDE_TIMED_OUT   -10       An internal timeout
                             occurred in the code
                             that communicates
                             between the external
                             process and HAWin.
HA_ERR_MAX_ERR         -13       The most negative
                             number used for an
                             error code.
HA_ERR_NOMORE          -13       FindNext function
                             could match no
                             further entries.
HA_ERR_NO_MEMORY        -4       A function could not
                             allocate memory to
                             use to perform the
                             specified task.
HA_ERR_NO_SESSION       -5       A function could not
                             complete the
                             requested task
                             because there was no
                             session handle
                             currently associated
                             with the script
                             handle.
HA_ERR_NOT_SUPPORTED   -11       This function call or
                             option requested
                             isn't supported in
                             this version of
                             HyperACCESS. This
                             return code may also
                             indicate that the
                             currently loaded COM
                             or connection driver
                             doesn't support the
                             requested function or
                             option.
HA_ERR_OK                0       The function executed
                             without error.
HA_ERR_TIMED_OUT        -6       A function waiting
                             for some set of
                             conditions to be met
                             exceeded its timeout
                             duration.


_______________________________
  1.   You can find these values in ha_auto.h (OS/2) or defines.h.




API Reference



Function Reference



Functions by group

            The following is a list of HyperACCESS Application Programming
            Interface functions organized by category. These divisions are
            somewhat arbitrary.


            Connection Functions

            These functions let programs connect to and disconnect from
            remote systems.
              - haConnectAndDial
              - haConnectSession
              - haDisconnectSession
              - haGetConnectionStatus
              - haGetConnectTime
              - haSkipConnection
              - haWaitForConnection


            Control Functions

            These functions provide critical HAPI operations, start
            another external task, and let programs voluntarily give up
            processor time.
              - haInitialize
              - haSleep
              - haSpawn
              - haTerminate
              - haWait


            Device-Specific Functions

            These functions deal mostly with external devices used for
            communications.
              - haComDriverSpecial
              - haCreateConnection
              - haDeleteConnection
              - haFindComTypes
              - haFindComTypeDevices
              - haFindConnection
              - haFindConnectionTypeDevices
              - haFindConnectionTypes
              - haGetBaudRate
              - haGetConnectionDetails
              - haGetCurrentConnection
              - haGetDefaultConnection
              - haGetDialingPrefix
              - haGetPortMode
              - haGetPortName
              - haGetPortPrefs
              - haGetPortType
              - haGetRingsForAnswer
              - haSelectDialingPrefix
              - haSetBaudRate
              - haSetConnectionDetails
              - haSetCurrentConnection
              - haSetDialingPrefix
              - haSetPortMode
              - haSetPortName
              - haSetPortPrefs
              - haSetPortType
              - haSetPulseTone
              - haSetRingsForAnswer


            Drag and Drop Functions

            These functions are only valid in HyperACCESS for Windows.
            They let an external API task respond to Drag and Drop
            operations on the HyperACCESS session window. HyperACCESS
            calls an external API task when a file or group of files is
            dropped on an open session.
              - haClearXferDropList
              - haGetXferDropList
              - haXferDropSend


            External File Functions

            These functions record data in files. This does not include
            data received during a file transfer.
              - haCaptureBegin
              - haCaptureControl
              - haCaptureToPrinterBegin
              - haCaptureToPrinterControl
              - haGetCaptureFileName
              - haGetLogFileName
              - haGetPrinterStatus
              - haSetCaptureFileName
              - haSetLogFileName
              - haSetLogonTask
              - haWriteLogEntry


            General Functions

            These functions perform general housekeeping tasks for an
            external API task. They have very little to do with actual
            communications.
              - haGetNameString
              - haGetSerNumString
              - haGetVersion
              - haSetNameString


            GUI API-Related Functions

            These functions let you write an external API task that takes
            advantage of some of the features of the operating system
            graphical user interface without writing this code yourself.
            The external API task can remain procedural in nature and
            still be perceived as a non-procedural GUI program.
              - haGetHWND
              - haGetWindowStateBits
              - haMenuString
              - haMessageBox
              - haNotifyOnTerminate
              - haRestrictMenus
              - haSetMessageTimer
              - haSizeHyperACCESS
              - haSizePhonebook
              - haSizeSession


            Learning Functions

            These functions let programs control recording of new keyboard
            sequences.
              - haGetLearnFileName
              - haLearnControl
              - haSetLearnFileName


            Phonebook Functions

            These functions control which phonebook entry is in use.
              - haGetDisplay
              - haGetPhonebookEntry
              - haReloadPhonebook
              - haSavePhonebook
              - haSetDisplay


            REXX-Specific Functions

            These functions are valid for REXX OS/2 only. They provide
            REXX-specific tools to facilitate programming with HAPI.
              - haDropFuncs
              - haGetConstantString
              - haGetConstantValue
              - haGetErrorString
              - haLoadFuncs


            Runtime Values Functions

            These functions let programs access and set
              - haGetRuntimeValue
              - haGetSessionDataString
              - haSetRuntimeValue
              - haSetSessionDataString


            Session Manipulation Functions

            The term session is used for backward compatibility with
            HyperACCESS for Windows (HAWin). In HAWin a session is the
            main focus for communications, and one instance of HAWin can
            have multiple sessions. These functions manipulate a session
            handle, and let an external API identify a HyperACCESS
            session. In HyperACCESS for OS/2 (HAOS2), there is only one
            sesson per instance of HyperACCESS.
              - haCloseSession
              - haCreateNewSession
              - haGetOpenSession
              - haGetSession
              - haGetSessionName
              - haOpenSession
              - haSetSession


            Terminal-Specific Functions

            These functions control the local terminal display.
              - haGetAsciiSettings
              - haGetCursorPosition
              - haGetEmulator
              - haGetSelectedText
              - haGetTextFromScreen
              - haSetAsciiSettings
              - haSetCursorPosition
              - haSetEcho
              - haSetEmulator
              - haSetLocalDisplay
              - haSetLocalEcho
              - haSetStripTo7Bits


            Text I/O Functions

            These functions let an external API task communicate with the
            local user or remote system.
              - haBlockRemoteInput
              - haClearOutputBuffer
              - haGetInput
              - haReleaseRemoteInput
              - haTypeLocalText
              - haTypeText
              - haWaitForActivity
              - haWaitForLines
              - haWaitForLull
              - haWaitForOutputDone
              - haWaitForPrompt
              - haWaitForString


            Transfer Functions

            These external API functions relate to transferring files.
              - haClearXferSendList
              - haGetXferDirectory
              - haGetXferFinalStatus
              - haGetXferParameters
              - haGetXferProtocol
              - haGetXferSendList
              - haGetXferStatus
              - haSetAdlOverride
              - haSetXferDirectory
              - haSetXferParameters
              - haSetXferProtocol
              - haTextSend
              - haWaitForXfer
              - haXferAddToSendList
              - haXferReceive
              - haXferSend
              - haXferSendBatch
              - haXferSendFromList
              - haXferSendList


Function Reference Format

            The following pages list the HyperACCESS Application
            Programming Interface functions in alphabetical order. The
            discussion of each function is divided into the following
            sections:
              - Description. A summary of the routine's effect immediately
                following the function name. (There is no sub-head for the
                description.)
              - Syntax. Illustrates the syntax with definition of the
                function type and arguments. A summary list of arguments
                with their type immediately follows the syntax prototype.
              - Arguments. A more complete description of the arguments
                and valid values.
              - Remarks. A more detailed description of the routine and
                how it is used.
              - Return Value. Describes values returned by the routine.
              - See Also. Names related routines.
              - Example. A short example in C that illustrates function
                use in context.


Examples

            The examples that appear with function references are in C.
            Modifying these examples for REXX or other programming
            languages is straightforward. The examples assume following C
            language variable definitions:
                        long SESS;
                        long bRate;
                        long ScriptHandle = 0;
                        long haTime;
                        int ReturnCode;
                        int SubReturnCode;
                        char LogName[128];
                        char Emulator[128];
                        char RuntimeValue[128];
                        char PNumber[128];
                        char PType[128];
                        char DName[128];
                        char PortName[128];
                        char DataBits[1];
                        char StopBits[1];
                        char Buffer[128];
                        char Parity[128];
                        char BPS[128];
                        char FName[128];
                        char Vers[128];
                        char UName[128];
                        char UID[128];
                        char PWord[128];


haBlockRemoteInput

            Increments the counter used to determine how and when a
            session processes characters received from the remote system.
            Syntax:
               INT haBlockRemoteInput(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               When the counter is greater than zero, a session does not
               process received characters. When the counter is zero, a
               session processes characters. When a session is opened, the
               counter is set to zero. If a program is run from within a
               session, the counter is incremented automatically when the
               program calls haInitialize. If the program exits from within
               a session, the counter is decremented automatically when the
               program calls haTerminate. This function would normally be
               called only if you switch control to a new session using
               haOpenSession or haSetSession, or when more than one program
               is running in a session.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haReleaseRemoteInput


haCaptureBegin

            Turns the Capture to File function on for the currently active
            session.
            Syntax:
               INT haCaptureBegin(ScriptHandle, nMode, nAppend)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Determines how data is captured
                 INT nAppend         Determines what happens if capture
                                      file already exists
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 This is a constant value that determines when capturing
                 takes place and which data is captured.
                 Value       Meaning
                 HA_C_LINES  Capture each line from the terminal display
                              as the cursor moves off the line.
                 HA_C_CHAR   Capture each displayable character as it is
                              displayed.
                 HA_C_RAW    Capture all characters (printable and control
                              codes) as they are received.
                 HA_C_SCREEN Capture lines as they scroll off the screen
                              and all lines on a screen when the screen is
                              cleared. Captures exactly the same data as
                              appears in the backscroll buffer.
               nAppend
                 This argument determines what happens if the file used
                 for capturing already exists. (See Remarks for valid
                 values for HAWin.)
                 Value       Meaning
                 HA_C_OVERWRITE   Overwrites the existing file.
                 HA_C_APPEND Appends new captured data to end of file.
                 HA_C_REN_SEQCreates a new file by adding a sequential
                              number to the filename. If the name is
                              already at its maximum length, the sequence
                              number replaces characters at the end of the
                              name.
                 HA_C_REN_DATHyperACCESS creates filenames by appending
                              the date/sequence to the original name. If
                              appending the date/sequence creates a
                              filename that is too long, HyperACCESS
                              deletes the required number of characters
                              from the end of the original name to fit the
                              date/sequence.
            Remarks:
               This function behaves as if the user selected File/Capture
               to File and completed the dialog.
               In HyperACESS for Windows, nAppend is either TRUE (non-zero,
               usually 1) or FALSE (zero). If TRUE any new captured data is
               appended to the existing file. Otherwise, the previous file
               is overwritten.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haCaptureControl, haGetCaptureFileName, haSetCaptureFileName
            Example:
            /* -----------------------------------------------------------
  --------- */
            /* Capture data to disk.
              This program segment:
               - Waits for prompt string ("Press Enter to begin...").
               - Begins capturing all incoming data -- one line at a time
  as the
                 carriage return character is received.
               - Appends incoming data to the end of the default capture
  file
                 if the file already exists.
               - Stops capturing data when an end string appears ("End of
  Data"). */

              ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Press Enter
  to begin...",
                           300L, 60000L);
              ReturnCode = haCaptureBegin(ScriptHandle, HA_C_LINES, TRUE);
              ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data",
  100000L);
              ReturnCode = haCaptureControl(ScriptHandle, HA_C_END);

            /* -----------------------------------------------------------
  --------- */


haCaptureControl

            Changes the way capturing operates after it has been started
            by haCaptureBegin.
            Syntax:
               INT haCaptureControl(ScriptHandle, nFunction)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFunction       The function code
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFunction
                 The function code determines what change is to be made
                 Value       Meaning
                 HA_C_END    Terminate capturing and close the capture
                              file.
                 HA_C_PAUSE  Stop capturing temporarily.
                 HA_C_RESUME Start capturing after a pause.
            Remarks:
               This function provides the same options available to the
               user from the File/Capture to File cascade menu after
               capture has been started.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haCaptureBegin


haCaptureToPrinterBegin

            Turns the Capture to Printer function on for the currently
            active session.
            Syntax:
               INT haCaptureToPrinterBegin(ScriptHandle, nMode, nMethod)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Determines how data is captured
                 INT nMethod         Determines when to release printed
                                      information from the print spooler
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 This is a constant value that determines when printing
                 takes place and which data is printed.
                 Value       Meaning
                 HA_CP_LINES Print each line from the terminal display as
                              the cursor moves off the line.
                 HA_CP_CHAR  Print each displayable character as it is
                              displayed.
                 HA_CP_SCREENPrint lines as they scroll off the screen and
                              all lines on a screen when the screen is
                              cleared. Prints exactly the same data as
                              appears in the backscroll buffer.
               nMethod
                 This is a constant value that determines when data will
                 be released from the spooler to the printer.
                 Value       Meaning
                 HA_CP_PAGE  As each page is filled, it is released to the
                              printer.
                 HA_CP_SESSION    Printed data is accumulated in the
                              spooler until the session is closed or
                              Capture to Printer is turned off.
            Remarks:
               This function behaves as if the user selected File/Capture
               to Printer and completed the dialog.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haCaptureToPrinterControl, haGetPrinterStatus
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Capturing data to printer
              This program segment:
               - Waits for prompt string ("Turn printer on and press Enter
  to
                 begin...") from the remote system.
               - Begins capturing all incoming data -- one line at a time
  as the
                 cursor moves off the line.
               - Releases each page to the printer as it fills.
               - Stops capturing data when an end string appears ("End of
  Data"). */

              ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Turn printer
  on and press
                           Enter to begin...", 300L, 60000L);
              ReturnCode = haCaptureToPrinterBegin(ScriptHandle,
  HA_CP_LINES,
                           HA_CP_PAGE);
              ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data",
  100000L);
              ReturnCode = haCaptureToPrinterControl(ScriptHandle,
  HA_CP_END);
            /* -----------------------------------------------------------
  --------- */


haCaptureToPrinterControl

            Changes the way capturing to printer operates after it has
            been started by the haCaptureToPrinterBegin.
            Syntax:
               INT haCaptureToPrinterControl(ScriptHandle, nFunction)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFunction       The function code
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFunction
                 The function code determines what change is to be made
                 Value       Meaning
                 HA_CP_END   Terminate printing and release data from the
                              spooler.
                 HA_CP_PAUSE Stop printing temporarily.
                 HA_CP_RESUMEStart printing after a pause.
            Remarks:
               This function provides the same options available to the
               user from the File/Capture to Printer cascade menu after
               printing has been started.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haCaptureToPrinterBegin, haGetPrinterStatus


haClearOutputBuffer

            Clears the HyperACCESS output buffer of characters waiting to
            be sent.
            Syntax:
               INT haClearOutputBuffer(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               You call this function when your program has already sent
               text data out the connected communications device and you
               want to cancel whatever portion of the data remains in the
               internal buffers. Depending on the type of communications
               device being used, there may be situations when HyperACCESS
               is unable to clear portions of the buffer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haTypeText, haWaitForOutputDone


haClearXferDropList

            Clears the internal list that keeps track of files that have
            been dropped on an open session.
            Syntax:
               INT haClearXferDropList(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               This function lets you remove all files from the drop list.
               It may be desirable to do this when an error occurs during
               transfer of a dropped file, and you want the user to take
               corrective action.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferDropList, haXferDropSend


haClearXferSendList

            Clears the internal list that keeps track of files that have
            been queued up to be sent to the remote system.
            Syntax:
               INT haClearXferSendList(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               This function lets you remove all files from the send list.
               Under normal circumstances, the list clears automatically
               after files are sent by haXferSendFromList. You may find it
               desirable to call this function when an error occurs during
               transfer, and you want the user to take corrective action.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferSendList, haXferAddToSendList, haXferSendFromList


haCloseSession

            In HAWin, closes the current session.
            Syntax:
               INT haCloseSession(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               This function closes the session associated with the script
               handle. If the session is connected, it is disconnected
               before the session is closed. If there is no session
               associated with the script handle, an error is returned.
               In HAOS2, this function disconnects, if connected, and saves
               any changes made to the phonebook entry settings.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haOpenSession
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Close an open session. */

              ReturnCode = haCloseSession(ScriptHandle);

            /* -----------------------------------------------------------
  --------- */


haComDriverSpecial

            Passes a device specific command string to the currently
            loaded communications driver.
            Syntax:
               INT haComDriverSpecial (ScriptHandle, pszCmd, nSize,
               pszResponse)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszCmd        The command string
                 INT nSize           The size of the following buffer.
                 LPSTR pszResponse   A buffer that receives the response
                                      from the communications driver.
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszCmd
                 The command string that you want to pass to comm driver.
                 Depends on device.
               nSize
                 The size of the following buffer.
               pszResponse
                 A response string that may contain information in
                 response to the command.
            Remarks:
            This function is for advanced communications programming and
            is beyond the scope of this manual.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.


haConnectAndDial

            Starts the connection process and dials the supplied phone
            number rather than the phone number that is stored in the
            session settings file.
            Syntax:
               INT haConnectAndDial(ScriptHandle, nMode, pszNumber)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Determines how the session is to be
                                      connected
                 LPSTR pszNumber     The number to dial
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 Determines what type of connection is to be initiated.
                 Value             Meaning
                 HA_CNCT_STANDARD   Do a normal connection sequence.
                 HA_CNCT_LEARN_LOGINStart learning a new login script
                                    after connection.
                 HA_CNCT_DO_NOT_LOGIN    Make the connection but do not
                                    run any login script or task
                                    associated with this session.
               pszNumber
                 A pointer to a null terminated string containing the
                 telephone number to be dialed.
            Remarks:
               This function is similar to the haConnectSession function
               except that it takes an additional parameter for an
               alternate phone number to be used in dialing. This phone
               number is dialed instead of the number stored in the session
               Communications dialog box.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haDisconnectSession, haGetConnectionStatus, haOpenSession,
               haSetSession, haWaitForConnection
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Dial a remote system from within a script.
            This program segment:
               - Displays a message box to ask if user wants to change the
  phone number.
               - If yes, it displays another message box to get the new
  phone number.
               - Connects and dials using the new phone number or uses a
  standard
                 session connect if the user doesn't want to change the
  number.*/



              ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
                           "Change Phone Number?", 0, 0, HA_MB_YN);
              if (ReturnCode == 1)
               {
               SubReturnCode = haMessageBox(ScriptHandle, "HAOS2 Query:",
                    "Enter Phone Number:", sizeof(PNumber), PNumber,
  HA_MB_OK);
               SubReturnCode = haConnectAndDial(ScriptHandle,
  HA_CNCT_STANDARD,
                           PNumber);
               }
              else if (ReturnCode == 0)
               SubReturnCode = haConnectSession(ScriptHandle,
  HA_CNCT_STANDARD);

            /* -----------------------------------------------------------
  --------- */


haConnectSession

            Starts the connection process within the current session.
            Syntax:
               INT haConnectSession(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Determines how the session is to be
                                      connected
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 Determines what type of connection is to be initiated.
                 Value             Meaning
                 HA_CNCT_STANDARD   Do a normal connection sequence.
                 HA_CNCT_LEARN_LOGINStart learning a new login script
                                    after connection.
                 HA_CNCT_DO_NOT_DIALOpen the device but do not dial the
                                    associated phone number.
                 HA_CNCT_DO_NOT_LOGIN    Make the connection but do not
                                    run any login script or task
                                    associated with this session.
                 HA_CNCT_ANSWER_MODEConnect the session in standard answer
                                    mode. In this mode, the port will be
                                    surrended if another session attempts
                                    to connect using the same port.
                 HA_CNCT_ANSWER_HOLDConnect the session in answer and hold
                                    mode. In this mode, the port will not
                                    be surrendered if another session
                                    attempts to connect using the same
                                    port.
            Remarks:
               This function only starts the connection process. A
               connection process may have a number of steps and can take
               an extended period of time, depending on the process the
               device requires. You must use haWaitForConnection or
               haGetConnectionStatus to determine when it is OK to
               continue. A session cannot perform communications related
               functions unless it is connected.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haDisconnectSession, haGetConnectionStatus, haOpenSession,
               haSetSession, haWaitForConnection
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Connect without dialing and transfer all typed characters
  to the modem. */

            /* This is often referred to as "Terminal Mode". */

            /*   This program segment:
               - Tells HyperACCESS not to call the remote system on
  connection.
                 The function haSkipConnection is required in case the
  program
                 is run as a preconnection program. Otherwise it is
  ignored.
               - Checks the current connection status, and if already
  connected
                 releases resources and returns control to HyperACCESS.
               - If not connected, request HyperACCESS to connect the
  session
                 (without dialing).
               - Don't wait for connection because there won't be one
  until the
                 user types commands at keyboard.
               - Release resources and return control to HyperACCESS. */

              ReturnCode = haSkipConnection(ScriptHandle);
              if (HA_CONNECTED == haGetConnectionStatus(ScriptHandle))
               ReturnCode = haTerminate(ScriptHandle, 0);

              ReturnCode = haConnectSession(ScriptHandle,
  HA_CNCT_DO_NOT_DIAL);
              ReturnCode = haTerminate(ScriptHandle, 0);

            /* -----------------------------------------------------------
  --------- */


haCreateConnection

            Creates a new connection combination.
            Syntax:
               HKCNCT haCreateConnection(ScriptHandle, pszDetails)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszDetails    A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszDetails
                 A null-terminated string containing the connection
                 details for the new connection.
            Remarks:
            See haGetConnectionDetails for the format of this string.
            This function is supported in HAOS2. For HAWin, use
            haSetPortPrefs.
            Return Value:
            Returns the connection key handle for the new connection if
            successful. Otherwise, zero.
            See also:
               haDeleteConnection, haFindComTypes, haFindConnection,
               haFindConnectionTypes, haFindConnectionTypeDevices,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection


haCreateNewSession

            Opens a new session and creates a new session file.
            Syntax:
               HSESS haCreateNewSession(ScriptHandle, pszName)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       The name used for the session
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 The name of the new session. This is the name that shows
                 up in the title bar of the new session, as well as the
                 Phonebook. It is also used to generate the filename, the
                 first eight characters being used, with non alphanumeric
                 characters being replaced by an underscore.
            Remarks:
               The session is not connected when it is initially created.
               The newly created session becomes the current session for
               the script. A script can interact with several sessions
               simultaneously by storing the session handles in variables
               and using haSetSession to move among them.
               In HAOS2, this function fails if the current session is
               connected.
            Return Value:
               Returns a session handle if successful. Otherwise a standard
               API error code.
            See Also:
               haCloseSession, haConnectSession, haOpenSession


haDeleteConnection

            Deletes the connection from the list.
            Syntax:
               INT haDeleteConnection(ScriptHandle, hCnctKey)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 HKCNCT hCnctKey     A connection key handle
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hCnctKey
                 A connection key handle returned from
                 haGetCurrentConnection, haGetDefaultConnection or
                 haCreateConnection.
            Remarks:
            This function is supported in HAOS2. There is no comparable
            function in HAWin.
            Return Value:
            Returns 0 if successful. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haFindComTypes, haFindConnection,
               haFindConnectionTypes, haFindConnectionTypeDevices,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection


haDisconnectSession

            This function disconnects a session.
            Syntax:
               INT haDisconnectSession(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               A session cannot perform communications related operations
               once it is disconnected.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haConnectSession, haCloseSession, haGetConnectionStatus,
               haOpenSession
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Disconnecting from a remote system. */

              ReturnCode = haDisconnectSession(ScriptHandle);

            /* -----------------------------------------------------------
  --------- */


haDropFuncs

            Removes registration of all HyperACCESS API functions with
            REXX.
            Syntax:
                   haDropFuncs
            Remarks:
               Call this function when HyperACCESS API functions are no
               longer needed.  For simple scripts, this is usually at the
               end of your script. Valid for HAOS2 REXX programs only.
               If an API function has not been registered, haDropFuncs
               still gives a successful return code.
            Return Values:
                   Returns 0 if successful.  Otherwise, a standard API
               error code.
            See Also:
                   haLoadFuncs
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Remove registration of all API functions from Rexx. */

            CALL haDropFuncs

            /* -----------------------------------------------------------
  --------- */


haFindComTypes

            Enumerates a list of communication interface types compatible
            with a connection type.
            Syntax:
               INT haFindComTypes(ScriptHandle, nFindFlag, nSize,
               pszComType,
                              nCompatibility)
                 SCRIPTHANDLE ScriptHandleThe program - HAOS2 link
                 INT nFindFlag       Find first / find next flag
                 INT nSize           Size of the following buffer
                 LPSTR pszComType    A pointer to a buffer
                 INT nCompatibility  Compatibility flags.
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFindFlag
                 Search flag:
                 Value       Meaning
                 HA_FINDFIRSTBegin searching.
                 HA_FINDNEXT Continue searching.
               nSize
                 The size of the following buffer.
               pszComType
                 A pointer to a buffer that will receive a null-terminated
                 string corresponding to a communication interface type.
               nCompatibility
                 An integer value returned from haFindConnectionTypes that
                 describes which communication interface types are
                 compatible with the connection type.
            Remarks:
            This function returns the list that appears in the Type of
            interface drop-down list in the Connect through dialog box.
            Pass the nCompatibility parameter from haFindConnectionTypes.
            This function is supported in HAOS2.
            Return Value:
            Returns 0 if successful, or HA_ERR_NOMORE if no other matches
            found. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindConnection,
               haFindConnectionTypes, haFindConnectionTypeDevices,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection


haFindConnection

            Enumerates a list of defined connections.
            Syntax:
               HKCNCT haFindConnection(ScriptHandle, nFindFlag)
                 SCRIPTHANDLE ScriptHandle     The program - HyperACCESS
                                      link
                 INT nFindFlag       Find first / find next flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFindFlag
                 Search flag:
                 Value       Meaning
                 HA_FINDFIRSTBegin searching for connections.
                 HA_FINDNEXT Continue searching for connections.
            Remarks:
            This function returns the list that appears in the Existing
            Connections dialog box. Returns zero if no connections remain.
            This function is supported in HAOS2.
            Return Value:
            Returns a connection key handle if successful. Otherwise,
            zero.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnectionTypes, haFindConnectionTypeDevices,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection


haFindConnectionTypeDevices

            Enumerates a list of devices recognized by a connection type.
            Syntax:
               INT haFindConnectionTypeDevices(ScriptHandle, nFindFlag,
               nSize, pszDevice)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFindFlag       Find first / find next flag
                 INT nSize           Size of the following buffer
                 LPSTR pszDevice     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFindFlag
                 Search flag:
                 Value       Meaning
                 HA_FINDFIRSTBegin searching for connection type devices.
                 HA_FINDNEXT Continue searching for connection type
                              devices.
               nSize
                 The size of the following buffer.
               pszDevice
                 A pointer to a buffer that will receive a null-terminated
                 string corresponding to a device.
            Remarks:
            This function returns the list that appears in the Connect
            Through dialog box. Returns zero if no connections remain.
            This function is supported in HAOS2.
            Return Value:
            Returns 0 if successful, or HA_ERR_NOMORE if no other entries
            are in the list. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Remove registration of all API functions from Rexx. */

            CALL haDropFuncs

            /* -----------------------------------------------------------
  --------- */


haFindConnectionTypes

            Enumerates a list of connection types.
            Syntax:
               INT haFindConnectionTypes(ScriptHandle, nFindFlag, nSize,
               pszCnctType,
                             pnCompatibility)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFindFlag       Find first / find next flag
                 INT nSize           Size of the following buffer
                 LPSTR pszCnctType   A pointer to a buffer
                 INT *pnCompatibilityA pointer to an integer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFindFlag
                 Search flag:
                 Value       Meaning
                 HA_FINDFIRSTBegin searching for connection types.
                 HA_FINDNEXT Continue searching for connection types.
               nSize
                 The size of the following buffer.
               pszCnctType
                 A pointer to a buffer that receives a null-terminated
                 string corresponding to a connection type.
               pnCompatibility
                 A pointer to an integer that will contain compatibility
                 flags for use in haFindComTypes.
            Remarks:
            This function returns the list of available connection types
            that appears in the Type of New Connection dialog box. This
            function is supported in HAOS2.
            Return Value:
            Returns 0 if successful, or HA_ERR_NOMORE if no other entries
            are in the list. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypeDevices,
               haGetConnectionDetails, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection
            Example:
            /* -----------------------------------------------------------
  --------- */

            /*This program segment displays supported connection types and
             *list of modems.
             */

            int  returnvalue;
            int  nCompat;
            char szCnctType[200];
            char szModem[200];

            printf("The supported connection types are:\n");
            returnvalue = haFindConnectionTypes(scripthandle, 1, 200,
  szCnctType,
                       &nCompat);
            while (returnvalue == 0)
              {
              printf("%s\n", szCnctType);
              returnvalue = haFindConnectionTypes(scripthandle, 2, 200,
  szCnctType,
               &nCompat);
              }
            printf( "\nThe current list of modems is:\n");
            returnvalue = haFindConnectionTypeDevices(scripthandle, 1,
  200, szModem);
            while (returnvalue == 0)
              {
              printf ("%s\n", szModem);
              returnvalue = haFindConnectionTypeDevices(scripthandle, 2,
  200,
                 szModem);
              }
            /* -----------------------------------------------------------
  --------- */


haGetAsciiSettings

            Gets settings that are found in the ASCII Settings dialog box.
            Syntax:
               INT haGetAsciiSettings(ScriptHandle, nCount, pnData)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCount          The number of integers that follow
                 INT FAR *pnData     A pointer to an array of integers
                                      (16 bit values)
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCount
                 The number of integers in the array pointed to by pnData.
               pnData
                 A pointer to an array of integers that are used to get
                 the ASCII Settings. Each array element has a value that
                 can be indexed by the following constants:
                 Value       Meaning
                 HA_AI_FLAGS Various individual flags (bits), described
                              below.
                 HA_AI_WFCHARInput wait for character.
                 HA_AI_OTABS Output tab expansion value.
                 HA_AI_CWAIT Character delay value.
                 HA_AI_LWAIT Line delay value.
                 HA_AI_ITABS Input tab conversion value.
                 The following flags(bits) are used in the HA_AI_FLAGS
                 word to determine the state of individual check box
                 items:
                 Value       Meaning
                 HA_AFS_LF   Append LF to line ends sent.
                 HA_AFS_BLS  Expand blank lines sent to include a space.
                 HA_AFS_ECHO Echo typed characters locally.
                 HA_AFS_WAIT Enable wait for line end character.
                 HA_AFS_TABS Enable tab expansion for sent characters.
                 HA_AFR_LF   Append LF to received line ends.
                 HA_AFR_7BIT Force incoming characters to 7 bits.
                 HA_AFR_ECHO Echo received characters to sender.
                 HA_AFR_WRAP Wrap lines that exceed terminal width.
                 HA_AFR_HEX  Show hex value of non-printing characters.
            Remarks:
               The integer HA_AI_FLAGS has individual flags (bits) which
               are either TRUE (1) or FALSE (0). Determining the value of
               individual bits is language dependent operation. You can
               test the value of a particular bit by performing a bitwise
               AND operation of HA_AI_FLAGS with the desired flag name
               defined above.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetAsciiSettings


haGetBaudRate

            Returns the baud rate of the currently open session if the
            port type in use supports baud rates.
            Syntax:
               LONG haGetBaudrate(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:

            Return Value:
               Returns the baud rate if successful. Otherwise, a standard
               API error code.
            See Also:
               haSetBaudRate


haGetCaptureFileName

            Returns the name of the capture file for the currently active
            session.
            Syntax:
               INT haGetCaptureFileName(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to contain the filename.
            Remarks:
               The buffer should be large enough to accomodate a complete
               path and filename. If the buffer is too small, only as much
               of the name as will fit will be copied.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetCaptureFileName
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Get the capture filename and let the user change it.
              This program segment:
               - Gets the capture filename.
                           - Uses a standard C function to write formatted
                         data to a string.
               - Displays the filename in a message box and asks if user
  wants to it.
               - If the user selects the Yes response, another message box
  request
                 a new filename.
               - If the user enters a new filename, it's saved as the
  default
                 capture file. */

              ReturnCode = haGetCaptureFileName(ScriptHandle,
  sizeof(FName), FName);
                        sprintf(Buffer, "Change Capture Filename: %s",
                         FName);
                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS", Buffer, 0, 0, HA_MB_YN);
              if (ReturnCode >= 0)
               {
               SubReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
                           "Enter new Capture File:", sizeof(FName),
  FName);
               SubReturnCode = haSetCaptureFileName(ScriptHandle, FName);
               }

            /* -----------------------------------------------------------
  --------- */


haGetConnectionDetails

            Returns specific information about a connection handle.
            Syntax:
               INT haGetConnectionDetails(ScriptHandle, hCnctKey, nSize,
               pszDetails)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 HKCNCT hCnctKey     The connection key handle
                 INT nSize           The size of the following buffer
                 LPSTR pszDetails    A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hCnctKey
                 A connection key handle returned from
                 haGetCurrentConnection, haGetDefaultConnection, or
                 haCreateConnection.
               nSize
                 The size of the following buffer.
               pszDetails
                 A pointer to the buffer that will receive a null-
                 terminated string containing the connection details
                 associated with the connection key handle.
                 The connection details string has the following fields:
                 Field       Description
                 Key         A numeric value that uniquely identifies the
                              connection.
                 Connection Type  Currently, the only valid connection
                              types are:
                              Direct Cable
                              Modem or Modem Pool
                              TCP/IP
                 Connection DeviceCurrently, one of the following:
                              A modem name for Modem or Modem Pool type.
                              blank for Direct Cable and TCP/IP types.
                 Interface Type Currently, one of the following:
                              For Modem or Modem Pool type:
                                   Standard Comm Port
                                   Shared Comm Port
                              For TCP/IP type:
                                   The TCP/IP stack installed (e.g., IBM
                              TCP/IP)
                              For Direct Cable:
                                   Blank
Communicat   For Modem or Modem Pool or
ions         Direct Cable, the
Device       communications port (e.g.,
            COM1, COM2, or a shared port
            name). Blank for TCP/IP.
Connection   The description of the
Descriptio   connection as shown to the user
n            (e.g., Hayes compatible high-
            speed, COM2).
                 Internal Data  For Modem or Modem Pool, the default baud
                              rate. For Direct Cable, 1 if hardware
                              handshaking on, 0 if off.
            Remarks:
            This function is supported in HAOS2.
            Return Value:
            Returns 0 if successful. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haFindConnectionTypeDevices, haGetCurrentConnection,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection
            Examples:
            13160933;Direct Cable;undefined;Standard Com Port;COM4;Direct
  Cable, COM4;1
            13025901;Modem or Modem Pool;Hayes compatible high-
                 speed;Standard Com Port;COM2;Hayes compatible high-speed,
                 COM2;19200


haGetConnectionStatus

            Returns the connection status of the currently active session.
            Syntax:
               INT haGetConnectionStatus(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:

            Return Value:
               Returns one of the following connection status codes if OK.
               Otherwise, a standard API error code.
                 Value       Meaning
                 HA_NOTSTARTED    Connection sequence has not started.
                 HA_CONNECTEDSession is connected.
                 HA_DISCONNECTED  Session is disconnected.
                 HA_CONNECTING    Session is attempting to connect.
                 HA_DISCONNECTING Session is in the process of
                              disconnecting.
                 HA_WAITING  Session is in answer mode, waiting for a
                              call.
                 HA_SURRENDERED   Session is in answer mode, waiting for a
                              call, but has surrendered its port to another
                              session for an outgoing call.
            See Also:
               haConnectSession, haDisconnectSession
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Check the status of the current connection. If offline,
  make connection.
              This program segment:
               - Checks connection status.
               - If disconnected, performs a standard connection sequence.
               - Wait for connection.
               - If connected on entry or connected successfully display
  messge.
               - If connection fails for any reason, display message. */

              ReturnCode = haGetConnectionStatus(ScriptHandle);
              if (ReturnCode == HA_DISCONNECTED)
               {
               SubReturnCode = haConnectSession(ScriptHandle,
  HA_CNCT_STANDARD);
               if (SubReturnCode == 0)
                 SubReturnCode = haWaitForConnection(ScriptHandle,
  HA_CONNECTED,
                             60000L);
               if (SubReturnCode == 0)
                 ReturnCode = HA_CONNECTED
               }
              if (ReturnCode == HA_CONNECTED)
               haMessageBox(ScriptHandle, "HyperACCESS", "Online!",
  0,0,HA_MB_OK);
              else
               haMessageBox(ScriptHandle, "HyperACCESS", "Connection
  Failed!",
                           0,0,HA_MB_OK);

            /* -----------------------------------------------------------
  --------- */


haGetConnectTime

            Returns the number of seconds that the session has been
            connected.
            Syntax:
               LONG haGetConnectTime(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               If the session is not connected, zero is returned.
            Return Value:
               Returns the number of seconds that the session has been
               connected if successful. Otherwise, if the return value is a
               negative number, it is a standard API error code.
            See Also:
               haConnectSession, haDisconnectSession


haGetConstantString

            Returns a string representation of a return value from a
            HyperACCESS REXX API function.
            Syntax:
                   haGetConstantString(pszContext, nRetVal)
                 pszContext          The name of the function that
                                      returned the constant
                 nRetVal             The return value
            Arguments:
                   pszContext
                 The name of a Hilgraeve API function.  As of this
                 writing, the only function names recognized are
                 haGetConnectionStatus, haGetDisplay, haGetPrinterStatus,
                 and haGetXferFinalStatus.
                   nRetVal
                 The return value from one of the functions named above.
            Remarks:
               Use this function for debugging.  Rather than remember what
               each return code represents, use this function to convert
               the code to a more meaningful description, and use it in a
               debug message. Valid for HAOS2 REXX programs only.
            Return Values:
               Returns a string representing the return value.  If nRetVal
               is not a valid API return code, or pszContext is not one of
               the recognized functions, this function returns the value
               unchanged.
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Get the connection status, and display a debug message
  stating the
             * status returned.
             */

            returnvalue = haGetConnectionStatus(ScriptHandle)
            retstr = haGetConstantString('haGetConnectionStatus',
  returnvalue)
            SAY 'Connection status is' retstr
            /* -----------------------------------------------------------
  --------- */


haGetConstantValue

            Returns an integer value corresponding to a constant string
            returned by a HyperACCESS REXX API function.
            Syntax:
                   haGetConstantValue(pszConstString)
                 pszConstantString   A pre-defined Hilgraeve API constant
                                      string
            Arguments:
                   pszConstantString
                 A string representation of a Hilgraeve API constant.
                 This constant could be an argument to an API function,
                 such as HA_MB_YN in a call to haMessageBox, or a return
                 value from an API function, like HA_ERR_OK.
            Remarks:
               This function tests return values of API functions that
               return a state rather than an error or success code.  It
               helps write code that is self-documenting. Valid for HAOS2
               REXX programs only.
            Return Values:
               Returns an integer corresponding to the constant string
               passed in.  If pszConstString is not a valid API constant
               string, it is returned unchanged.
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Get the connection status.  Use haGetConstantValue to
  interpret the
             * return code.
             */

            returnvalue = haGetConnectionStatus(ScriptHandle)
            if returnvalue == haGetConstantValue('HA_CONNECTED') THEN
              DO
               CALL haTypeText ScriptHandle, 0, 'Hello, world!'
              END

            /* -----------------------------------------------------------
  --------- */


haGetCurrentConnection

            Returns the connection handle for the currently opened
            session.
            Syntax:
               HKCNCT haGetCurrentConnection(ScriptHandle)
                 SCRIPTHANDLE ScriptHandle   The program - HyperACCESS
                                      link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
            This function is supported in HAOS2.
            Return Value:
            Returns a connection key handle if successful. Otherwise,
            zero.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haFindConnectionTypeDevices, haGetConnectionDetails,
               haGetDefaultConnection, haSetConnectionDetails,
               haSetCurrentConnection


haGetDefaultConnection

            Returns the default connection key.
            Syntax:
               HKCNCT haGetDefaultConnection(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HAOS2 link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
            This function is supported in HAOS2.
            Return Value:
            Returns the connection key handle used by the default
            phonebook entry.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haFindConnectionTypeDevices, haGetConnectionDetails,
               haGetCurrentConnection, haSetConnectionDetails,
               haSetCurrentConnection


haGetDialingPrefix

            Returns one of the dialing prefixes defined in the program.
            Syntax:
               INT haGetDialingPrefix(ScriptHandle, nIndex, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which prefix string
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 This parameter determines which prefix string to return.
                 Valid numbers are 1 thru 10.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to the buffer that is to receive the prefix
                 string.
            Remarks:
               There is only one set of ten dialing prefix strings that is
               shared by all sessions. Only the number of the prefix string
               being used for a session is stored in each session file.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetDialingPrefix, haSelectDialingPrefix
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Let the user change the dialing prefix if necessary.
              This program segment:
               - Gets the first dialing prefix.
                           - Uses a standard C function to write formatted
                         data to a string.
               - Displays the current prefix in a message box and asks for
  Yes/No
                 response to question.
               - If response is Yes, asks user for new prefix.
               - Sets new prefix (for all phonebook entries). */

              ReturnCode = haGetDialingPrefix(ScriptHandle, 1,
  sizeof(PNumber),
                           PNumber);
                        sprintf(Buffer, "Is this string correct: %s",
                         PNumber);
              ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
  Buffer, 0, 0,
                           HA_MB_YN);
              if (ReturnCode == 0)
               {
               ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
                           "Enter new prefix:", sizeof(PNumber), PNumber);
               ReturnCode = haSetDialingPrefix(ScriptHandle, 1, PNumber);
               }

            /* -----------------------------------------------------------
  --------- */


haGetDisplay

            Returns a value indicating the type of view currently being
            displayed by the current phonebook.
            Syntax:
               INT haGetDisplay(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:

            Return Value:
               Returns one of the following codes if successful. Otherwise,
               a standard API error code.
                 Value       Meaning
                 HA_ICONIC   The Phonebook is being displayed as icons.
                 HA_STATS    The Statistics view is being displayed in the
                              Phonebook.
                 HA_DETAILS  The Details view is being displayed in the
                              Phonebook.
                 HA_NAMES    The Phonebook is being displayed as system
                              names.
                 HA_FILES    The Phonebook is being displayed as
                              filenames.
            See Also:
               haSetDisplay


haGetEmulator

            Returns the name of the terminal emulator for the currently
            active session.
            Syntax:
               INT haGetEmulator(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the emulator
                 name.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetEmulator
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Change the screen color regardless of terminal emulator in
  use.
              This program segment:
               - Gets the current terminal emulator.
               - Change the terminal emulator to ANSI so that local
  commands can
                 change screen color.
               - Type local text to change screen color to blue letters on
  white
                 background (see DOS help for ANSI.SYS).
               - Sets the terminal emulator back to its original type. */

              ReturnCode = haGetEmulator(ScriptHandle, sizeof(Emulator),
  Emulator);
              ReturnCode = haSetEmulator(ScriptHandle, "ANSI");
              ReturnCode = haTypeLocalText(ScriptHandle, "\x1b[37;44;1m");
              ReturnCode = haSetEmulator(ScriptHandle, Emulator);

            /* -----------------------------------------------------------
  --------- */


haGetErrorString

            Return a REXX string representing an error code.
            Syntax:
                   haGetErrorString(nErrorCode)
                 nErrorCode           An API error code
            Arguments:
                   nErrorCode
                         An error code returned from an API function.
            Remarks:
               Use this function for debugging REXX programs.  Rather than
               remember what each error code represents, use this function
               to convert the code to a more meaningful description, and
               use it in a debug message. Valid for HAOS2 REXX programs
               only.
            Return Values:
               Returns a string representing the error code.  If nErrorCode
               is not a valid API error code, it is returned unchanged.
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Wait for one of several prompts, with a debug message so
  you know
             * which prompt was matched.
             */

            prompts = 'Name:'||'00'x||'Rank:'||'00'x||'Serial
  Number:'||'00'x||'00'x
            returnvalue = haWaitForPrompt(ScriptHandle, 3, prompts, 300,
  10000)
            SAY 'returnvalue is' haGetErrorString(returnvalue)

            /* -----------------------------------------------------------
  --------- */


haGetHWND

            Returns the window handle created by haInitialize to
            synchronize message traffic between the external program and
            HyperACCESS.
            Syntax:
               HWND haGetHWND(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link.
            Arguments:
               ScriptHandle
                 The ScriptHandle returned from haInitialize for
                 connection to the HyperACCESS window.
            Remarks:
               The window handle is used for message passing to and from
               HyperACCESS. These messages are synchronized automatically
               by API functions. Use this window handle with caution.
            Return Value:
               Returns a window handle if successful. Otherwise, zero.


haGetInput

            Gets data received from the remote system.
            Syntax:
               INT haGetInput(ScriptHandle, nMode, nCount, lStartTimeout,
               lCharTimeout, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Additional processing options
                 INT nCount          The number of characters to wait for
                 LONG lStartTimeout  The timeout for the first character
                 LONG lCharTimeout   The intercharacter timeout
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 Determines what, if any, extra processing of the input is
                 to be performed.
                 Value             Meaning
                 HA_GI_BACKSPACE    Process backspaces.
                 HA_GI_NOBACKSPACE  Do not process backspaces.
               nCount
                 The count determines the number of characters to wait
                 for. If the count is
                 (-1), wait for a carriage return.
               lStartTimeout
                 This timeout value, measured in milliseconds, determines
                 how long to wait for the first character before returning
                 to the caller. If this timeout is exceeded before any new
                 characters are received, the error code HA_ERR_TIMED_OUT
                 is returned.
               lCharTimeout
                 This timeout value, measured in milliseconds, determines
                 how long to wait between characters before returning to
                 the caller. If this timeout is exceeded, after at least
                 one character has been received, but before a new
                 character is received, the function returns the number of
                 characters already received. If the function returns
                 fewer characters than were requested, it is because an
                 intercharacter timeout occurred.
               pszBuffer
                 A pointer to a buffer to hold the acquired characters.
            Remarks:
               If nMode is HA_GI_NOBACKSPACE, backspace characters are
               stored in the buffer. If nMode is HA_GI_BACKSPACE, backspace
               characters are processed before the buffer is returned.
            Return Value:
               Returns the number of characters received if successful.
               Otherwise, a standard API error code.
            See Also:
               haWaitForPrompt, haWaitForString
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Prompt remote user for data, and respond.
              This program segment:
               - Sends text to remote system requesting input from remote
  user.
               - Gets input from communications port, but lets HyperACCESS
  process
                 any backspace characters. Waits 100 sec. for first
  character.
                 Waits 30 sec. between characters.
               - If remote user responds, formats response and types
  message to
                 remote user. */

              ReturnCode = haTypeText(ScriptHandle, 0, "Enter First Name:
  ");
              ReturnCode = haGetInput(ScriptHandle, HA_GI_BACKSPACE, -1,
  100000L,
                           30000L, FName);
              if (ReturnCode >= 0)
               {
                           sprintf(Buffer, "Welcome to the system, %s",
                         FName);
                           ReturnCode = haTypeText(ScriptHandle, 0,
                         Buffer);
               }

            /* -----------------------------------------------------------
  --------- */


haGetLearnFileName

            Returns the name of the learn file (script) for the currently
            active session.
            Syntax:
               INT haGetLearnFileName(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguements:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to contain the filename.
            Remarks:
               The buffer should be large enough to accomodate a complete
               path and filename. If the buffer is too small, only as much
               of the name as will fit will be copied.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetLearnFileName, haGetCaptureFileName


haGetLogFileName

            Returns the name of the current log file.
            Syntax:
               INT haGetLogFileName(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to the buffer that is to receive the log
                 filename.
            Remarks:
               The buffer should be large enough to accomodate a complete
               path and filename.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetLogFileName
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Get the log filename and let the user change files if
  desired.
              This program segment:
               - Gets the log filename for the current session.
                           - Uses a standard C function to write formatted
                         data to a string.
               - Displays log filename in a message box and asks for
  Yes/No
                 response to question.
               - If response is Yes, asks user for new filename and sets
  new file. */

              ReturnCode = haGetLogFileName(ScriptHandle, 128, LogName);
                        sprintf(Buffer, "Change Log Filename: %s",
                         LogName);
                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS", Buffer, 0, 0, HA_MB_YN);
              if (ReturnCode == 0)
               {
               ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
                           "Enter new Log File:", sizeof(LogName),
  LogName);
               ReturnCode = haSetLogFileName(ScriptHandle, LogName);
               }

            /* -----------------------------------------------------------
  --------- */


haGetNameString

            Returns the identification strings entered by the user during
            program installation.
            Syntax:
               INT haGetNameString(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to the buffer that will receive the strings.
            Remarks:
               The user name data string gets set during program
               installation. This string consists of six lines in HAWin and
               seven lines in HAOS2. Each line is terminated with a
               carriage return, linefeed pair. Any of the strings may be
               blank, with only the terminating pair. The strings are name,
               company, street address, city, state, zip code, and country.
               HAWin Version 2.1 and prior don't support country.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetNameString


haGetOpenSession

            Returns a session handle from the list of open sessions.
            Syntax:
               HSESS haGetOpenSession(ScriptHandle, nIndex)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which session handle to return
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 An index indicating which session handle from the list to
                 return. This index can range from 0 to n-1 where n is the
                 number of open sessions.
            Remarks:
               As sessions are opened, they are added to a list of open
               sessions within HyperACCESS. This function returns session
               handles from that list. In HAOS2, there is only one open
               session, so nIndex must be 0. Any other value is an error.
            Return Value:
               Returns a session handle if successful. Otherwise, zero.
            See Also:
               haGetPhonebookEntry, haGetSession, haOpenSession,
               haSetSession


haGetPhonebookEntry

            Returns the filename for an entry in the current phonebook.
            Syntax:
               INT haGetPhonebookEntry(ScriptHandle, nIndex, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which entry in the phonebook
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 The index into Phonebook that selects the session
                 filename desired.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the filename.
            Remarks:
               The buffer should be large enough to accomodate a complete
               path and filename.
               Remember that the order of sessions in Phonebook can change
               depending on sorting type selected. An entry that was
               previously at one index may not be there at a later time.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetOpenSession
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Open the first phonebook entry in the phonebook and connect
  to it.
              This program segment:
               - Gets the filename of the first phonebook entry.
               - Requests HyperACCESS to open and connect to it.
                 (Don't wait for connection to complete.) */

              ReturnCode = haGetPhonebookEntry(ScriptHandle, 1,
  sizeof(FName), FName);
              ReternCode = haOpenSession(ScriptHandle, FName);
              ReturnCode = haConnectSession(ScriptHandle,
  HA_CNCT_STANDARD);

            /* -----------------------------------------------------------
  --------- */


haGetPortMode

            Returns the current settings for the number of bits per
            character, the number of stop bits, and the parity type.
            Syntax:
               INT haGetPortMode(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               The integer value returned has flags (bits) which are either
               TRUE (1) or
               FALSE (0). Determining the value of individual bits is
               language dependent operation. You can test the value of a
               particular bit by performing a bitwise AND operation of the
               returned value with the desired flag name defined below.
            Return Value:
               Returns a value that may be one or more of the following
               values ORed together if successful. Otherwise, a standard
               API error code.
                 Value       Meaning
                 HA_M_AUTO   Auto-detect is set.
                 HA_M_7_BITS Characters contain 7 bits.
                 HA_M_8_BITS Characters contain 8 bits.
                 HA_M_E_PRTY Characters have even parity.
                 HA_M_O_PRTY Characters have odd parity.
                 HA_M_N_PRTY Characters have no parity.
                 HA_M_M_PRTY Characters have mark parity.
                 HA_M_S_PRTY Characters have space parity.
                 HA_M_1_STOP Characters have one stop bit.
                 HA_M_1_5_STOP    Characters have 1.5 stop bits.
                 HA_M_2_STOP Characters have two stop bits.
            See Also:
               haSetPortMode
            Example:
            /* -----------------------------------------------------------
  --------- */
            /* Get and display all port mode settings.
                        This program segment:
                           - Gets the port mode.
                           - Uses HyperACCESS bit masks to determine
                         settings and translate
                             bit settings to understandable character
                         strings.
                           - Uses standard C functions to convert the baud
                         rate to a string
                             and write formatted data to a string.
                           - Displays the resulting string in a message
                         box. */

                        ReturnCode = haGetPortMode(ScriptHandle);
                        if (ReturnCode & HA_M_8_BIT)
                           strcpy(DataBits, "8");
                        if (ReturnCode & HA_M_7_BIT)
                           strcpy(DataBits, "7");
                        if (ReturnCode & HA_M_N_PRTY)
                           strcpy(Parity, "None");
                        if (ReturnCode & HA_M_O_PRTY)
                           strcpy(Parity, "Odd");
                        if (ReturnCode & HA_M_E_PRTY)
                           strcpy(Parity, "Even");
                        if (ReturnCode & HA_M_M_PRTY)
                           strcpy(Parity, "Mark");
                        if (ReturnCode & HA_M_S_PRTY)
                           strcpy(Parity, "Space");
                        if (ReturnCode & HA_M_1_STOP)
                           strcpy(StopBits, "1");
                        if (ReturnCode & HA_M_2_STOP)
                           strcpy(StopBits, "2");

                        sprintf(Buffer, "Port Mode: %s,%s,%s",
                         Parity,DataBits,StopBits);

                        ReturnCode = haMessageBox(ScriptHandle,
                         "Communications", Buffer, 0, 0, HA_MB_OK);

            /* -----------------------------------------------------------
  --------- */


haGetPortName

            Returns the name of the port for the currently active session.
            Syntax:
               INT haGetPortName(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to the buffer that will receive the port name.

            Remarks:
               A port is identified by a port type and a port name. The
               format and range of values of the port name depend on the
               port type selected. For example, if the port type is
               Standard Com Port, the port name will be COM1, COM2, etc. If
               the port type specifies a network connection, the port name
               might be a server name or a named network resource.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
                        ReturnCode = haGetPortName(ScriptHandle,
                         sizeof(PortName), PortName);


haGetPortPrefs

            Returns strings identifying the type and name of the port
            being used for communications. It also returns the name of the
            connection device (modem).
            Syntax:
               INT haGetPortPrefs(ScriptHandle, nSizeType, pszType,
               nSizeName, pszName, nSizeDevice, pszDevice)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSizeType       The size of the type buffer
                 LPSTR pszType       A pointer to the type buffer
                 INT nSizeName       The size of the name buffer
                 LPSTR pszName       A pointer to the name buffer
                 INT nSizeDevice     The size of the device buffer
                 LPSTR pszDevice     A pointer to the device buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSizeType
                 The size of the type buffer.
               pszType
                 A pointer to a buffer that will receive the
                 communications port type.
               nSizeName
                 The size of the name buffer.
               pszName
                 A pointer to a buffer that will receive the
                 communications port name.
               nSizeDevice
                 The size of the device buffer.
               pszDevice
                 A pointer to a buffer that will receive the
                 communications port device.
            Remarks:
               The port type and port name values are stored per session in
               the session settings file. The name of the connection device
               (commonly a modem name) associated with each port applies to
               all sessions using that port.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortName, haGetPortType, haSetPortPrefs
            Example:
            /* -----------------------------------------------------------
  --------- */

            /* Gather and display port information.
              This program segment:
               - Gets the port type, name, and device name.
               - Displays the resulting string in a message box. */

                        ReturnCode = haGetPortPrefs(ScriptHandle,
                         sizeof(PType), PType, sizeof(PortName), PortName,
                         sizeof(DName), DName);
                        sprintf(Buffer, "Port Info: %s:%s, %s", PType,
                         PortName, DName);
                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS", Buffer, 0, 0, HA_MB_OK);

            /* The function "haGetPortType" also gets port type, but none
  of the other
              information: */
              ReturnCode = haGetPortType(ScriptHandle, sizeof(PType),
  PType);

            /* -----------------------------------------------------------
  --------- */


haGetPortType

            Returns the type of communications port associated with the
            currently active session.
            Syntax:
               INT haGetPortType(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSIze
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that will receive the
                 communications port type.
            Remarks:
               A port type and name identify a port. For each port type
               supported, there is a driver file implemented as a DLL
               module with a name of the form HAC*.DLL. Adding driver
               modules adds port types. Removing driver modules removes the
               associated port type from the list of those available.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortName, haGetPortPrefs
            Example:
            /* -----------------------------------------------------------
  --------- */
            /* Get and display port type.
              This program segment:
               - Gets the port type and displays it in a message box. */

              ReturnCode = haGetPortType(ScriptHandle, sizeof(PType),
  PType)
              ReturnCode = haMessageBox(ScriptHandle,
            /* -----------------------------------------------------------
  --------- */


haGetCursorPosition

            Returns the current cursor position on the emulator screen.
            Syntax:
               INT haGetCursorPosition(ScriptHandle, pnRow, pnCol)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT FAR* pnRow      The row number
                 INT FAR* pnCol      The column number
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pnRow
                 A pointer to integer sized storage for the row number.
               pnCol
                 A pointer to integer sized storage for the column number.
            Remarks:
               Row and column numbers start at zero and are limited by the
               emulator.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetTextFromScreen, haSetCursorPosition


haGetPrinterStatus

            Returns the current state of capturing to the printer.
            Syntax:
               INT haGetPrinterStatus(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:

            Return Value:
               Returns one of the following codes if successful,
               Otherwise,a standard API error code.
                 Value       Meaning
                 HA_PRINTER_ON    Print capture has been started
                 HA_PRINTER_PAUSEDPrint capture has been paused
                 HA_PRINTER_OFF   Print capture is not running
            See Also:
               haCaptureToPrinterBegin, haCaptureToPrinterControl


haGetRingsForAnswer

            Returns the current number of times an incoming call rings
            before the call is answered.
            Syntax:
               INT haGetRingsForAnswer(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               This function returns the value set by an earlier call to
               haSetRingsForAnswer or the default value for the device
               being used if haSetRingsForAnswer has not been called.
            Return Value:
               Returns the number of rings to wait if successful.
               Otherwise, a standard API error code.
            See Also:
               haSetRingsForAnswer


haGetRuntimeValue

            Returns one of the runtime strings stored with each session.
            Syntax:
               INT haGetRuntimeValue(ScriptHandle, nValue, nPrompt, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nValue          Which runtime string to return
                 INT nPrompt         To prompt or not to prompt
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nValue
                 Which runtime string to return:
                 Value             Meaning
                 HA_RV_USERNAME     The currently defined user name.
                 HA_RV_USERID       The currently defined user ID.
                 HA_RV_PASSWORD     The currently defined password.
               nPrompt
                 If TRUE (non-zero), HyperACCESS prompts the user for a
                 value if none has been stored in the session.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that will receive the runtime
                 string.
            Remarks:
               If the string is not currently set, the function call can
               instruct HyperACCESS to prompt for the string by setting
               nPrompt to TRUE. The dialog that is used to prompt the user
               has a checkbox in it that allows the user to specify that
               they want the value they enter to be stored for future use.
               The user can view and change values they store by using the
               Runtime Values dialog selected from the Properties menu. If
               the session has a stored value, it is returned without input
               from the user regardless of the setting of nPrompt.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Get runtime values for NAME, USERID, and PASSWORD. Then use
                         those values.
                        This program segment:
                           - Gets runtime values if they exist. The TRUE
                         parameter indicates
                             that HyperACCESS should automatically prompt
                         for a value if one
                             isn't already stored.
                           - Use the UserId and password as part of a
                         login sequence with a
                             remote system.*/

                        ReturnCode = haGetRuntimeValue(ScriptHandle,
                         HA_RV_USERNAME, TRUE, sizeof(UName), UName);
                        ReturnCode = haGetRuntimeValue(ScriptHandle,
                         HA_RV_USERID, TRUE, sizeof(UID), UID);
                        ReturnCode = haGetRuntimeValue(ScriptHandle,
                         HA_RV_PASSWORD, TRUE, sizeof(PWord), PWord);

                        /* Assume a connection has been made for this
                         example to talk to. */
                           ReturnCode = haWaitForPrompt(ScriptHandle, 1,
                         "LOGON ID:", 1000L, 60000L);
                           ReturnCode = haTypeText(ScriptHandle, 0, UID);
                           ReturnCode = haWaitForPrompt(ScriptHandle, 1,
                         "Password:", 1000L, 60000L);
                           ReturnCode = haTypeText(ScriptHandle, 0,
                         PWord);

            /* -----------------------------------------------------------
                         --------- */


haGetSelectedText

            Get the selected (highlighted) text from the associated
            session window.
            Syntax:
                 INT haGetSelectedText(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the selected
                 text.
            Remarks:
               Since there is no way to predict how much text the user is
               going to select, make the buffer as big as is possible and
               still be reasonable. Remember, it still won't be large
               enough every time.
            Return Value:
               Returns 0 if successful. Otherwise a standard API error
               code.
            See Also:
               haGetTextFromScreen


haGetSerNumString

            Returns the serial number string from HyperACCESS.
            Syntax:
               INT haGetSerNumString(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer to receive the serial number
                 string.
            Remarks:
               The serial number is initially set by the installation
               procedure and is visible in the program's Help About
               HyperACCESS dialog box. This function returns the serial
               number as a string.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:



haGetSession

            Returns the session handle currently associated with the
            program - HyperACCESS link.
            Syntax:
               HSESS haGetSession(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               Each open session in HyperACCESS is uniquely identified by a
               session handle. Several other API functions operate on the
               current session handle.
            Return Value:
               This function returns a session handle associated with the
               script, or zero if no session is currently associated with
               the script.
            See Also:
               haCloseSession, haOpenSession, haSetSession


haGetSessionName

            Returns the name of the current session.
            Syntax:
               INT haGetSessionName(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to recieve the string.
            Remarks:
               The session name is the string that is displayed in the
               title bar of an open session. It is also displayed in some
               of the Phonebook views.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetSessionDataString


haGetSessionDataString

            Returns one of the 20 internal data strings associated the
            session.
            Syntax:
               INT haGetSessionDataString(ScriptHandle, nIndex, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Indicates which string to return
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 An index (0 - 19) indicating which string is to be
                 returned.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the data string.
            Remarks:
               Each session has 20 internal data strings associated with
               it. The first ten strings are always blank when a session is
               opened. They can be used in situations where new data must
               be received before being used. The second ten strings are
               stored in the session file when a session is closed and
               restored when the session is reopened. You can use these
               strings in a program for storing user settings, file
               locations, etc.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetSessionDataString


haGetTextFromScreen

            Returns text from the emulator screen.
            Syntax:
               INT haGetTextFromScreen(ScriptHandle, nRow, nCol, nCount,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nRow            The row number
                 INT nCol            The column number
                 INT nCount          The number of bytes to return
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nRow
                 The row number used to address the screen. Addresses
                 start at zero and are limited by the emulator in use.
               nCol
                 The column number used to address the screen. Addresses
                 start at zero and are limited by the emulator in use.
               nCount
                 The number of characters of text to return.
               pszBuffer
                 A pointer to a buffer large enough to hold the specified
                 number of characters.
            Remarks:
               Row and column addresses start at zero and are limited by
               the emulator. You can retrieve text from only one row at a
               time.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetInput, haTypeText
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Get text from specific screen positions.
                        This program segment:
                           - Requests 10 characters starting at screen
                         position 0,35
                             where           0 is vertical position (from
                         top),
                                            35 is horizontal position
                         (from left). */

                        ReturnCode = haGetTextFromScreen(ScriptHandle, 0,
                         35, 10, Buffer);

            /* -----------------------------------------------------------
                         --------- */


haGetVersion

            Returns a string indicating the version of HyperACCESS.
            Syntax:
               INT haGetVersion(ScriptHandle, nSize, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the version
                 number string.
            Remarks:
               The version number is returned formatted as a string.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Gets HyperACCESS version number, and display it.
                        This program segment:
                           - Gets HyperACCESS version number
                           - Uses a standard C function to write formatted
                         data to a string.
                           - Displays the version number in a message box
                         that only accepts an OK
                             response. */

                        ReturnCode = haGetVersion(ScriptHandle,
                         sizeof(Vers), Vers);
                        sprintf(Buffer, "Version: %s", Vers);
                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS", Buffer, 0, 0, HA_MB_OK);
            /* -----------------------------------------------------------
                         --------- */


haGetWindowStateBits

            Returns a group of flags (bits) that describe the visibility
            and state of HyperACCESS.
            Syntax:
               INT haGetWindowStateBits(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               The integer value returned has flags (bits) which are either
               TRUE (1) or FALSE (0). Determining the value of individual
               bits is language dependent operation. You can test the value
               of a particular bit by performing a bitwise AND operation of
               the returned value with the desired flag name defined below.
            Return Value:
               Any of the following flags may be ORed together and returned
               if the call is successful. Otherwise, a standard API error
               code is returned.
                 Value             Meaning
                 HA_FRAME_IS_ACTIVE The frame is active.
                 HA_FRAME_IS_ICONIC The frame is iconic.
                 HA_SESSION_IS_ACTIVE    The session is active.
                 HA_SESSION_IS_ICONIC    The session is iconic.
            See Also:
               haGetSession, haSetSession


haGetXferDirectory

            Returns the default transfer directory for the current
            session.
            Syntax:
               INT haGetXferDirectory(ScriptHandle, nDirection, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nDirection      Select which directory
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nDirection
                 Selects sending or receiving.
                 Value       Meaning
                 HA_XFER_SENDSelects the sending directory.
                 HA_XFER_RECVSelects the receiving directory.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer to receive the name of the transfer
                 directory.
            Remarks:
               The buffer should be large enough to accomodate a complete
               path.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetXferDirectory
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Get (and set) directory path to receive files.
                        This program segment:
                           - Gets default receive directory path.
                           - Use a message box to ask if the user wants to
                         change the default path.
                           - If the user responds Yes, request a new
                         directory path using a
                             message box.
                           - Sets the new directory as the default. */

                        ReturnCode = haGetXferDirectory(ScriptHandle,
                         HA_XFER_RECV, sizeof(DName), DName);
                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS:",
                                            "Change Receive Directory
                         Path?", 0, 0, HA_MB_YN);
                        if (ReturnCode == 1)
                           {
                           SubReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS:",
                                            "Enter Receive Directory:",
                         sizeof(DName), DName, HA_MB_OK);
                           SubReturnCode =
                         haSetXferDirectory(ScriptHandle, HA_XFER_RECV,
                                            DName);
                           }

            /* -----------------------------------------------------------
                         --------- */


haGetXferDropList

            Returns a path and filename from an internal list of files
            dropped on the session.
            Syntax:
               INT haGetXferDropList(ScriptHandle, nIndex, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which item to return
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 Selects which item in the list of dropped files is to be
                 returned. Selections start at zero.
               nSize
                 The size of the following buffer.
               pszBuffer
                 A pointer to a buffer that is to receive the filename
                 from the list of dropped files.
            Remarks:
               HyperACCESS supports drag and drop operations on open
               sessions as well as selected dialog boxes. When files are
               dropped on an open session, an external task is run to
               handle the dropped files. Use this function to get the path
               and filename of dropped files from the list, one at a time.
               Not currently supported in HAOS2.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haClearXferDropList, haGetXferSendList, haXferDropSend


haGetXferFinalStatus

            Returns the final status of the most recent file transfer.
            Syntax:
               INT haGetXferFinalStatus(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               A file transfer started with nFlag TRUE completes before the
               function call returns (see haXferReceive, haXferSend,
               haXferDropSend). In that case, call haGetXferFinalStatus
               upon return from function that initiated transfer to get the
               final status. If nFlag is FALSE, the function call that
               starts the transfer returns while transfer continues. In
               that case, haGetXferStatus can monitor progress of the
               transfer. When haGetXferStatus or haWaitForXfer indicates
               that transfer has completed, use haGetXferFinalStatus to
               determine whether the transfer completed successfully.
            Return Value:
               Returns one of the following values if successful.
               Otherwise, a standard API error code.
                 Value             Meaning
                 HA_XFS_OK          Transfer completed successfully.
                 HA_XFS_RMT_CANNED  Transfer cancelled at other end.
                 HA_XFS_USER_CANNED Transfer cancelled locally (by the
                                    user).
                 HA_XFS_LOST_CARRIERCarrier lost during transfer.
                 HA_XFS_ERROR_LIMIT The protocol-defined error limit
                                    exceeded.
                 HA_XFS_NO_RESPONSE The remote end of the transfer stopped
                                    responding.
                 HA_XFS_OUT_OF_SEQ  A protocol packet was received out-of-
                                    sequence and recovery was not
                                    possible.
                 HA_XFS_BAD_FORMAT  A protocol packet was received with a
                                    correct checksum but with an illegal
                                    format.
                 HA_XFS_TOO_MANY    The remote sender tried to send
                                    multiple files but the receiver could
                                    accept only one.
                 HA_XFS_DISK_FULL   The disk filled up before transfer
                                    completed.
                 HA_XFS_CANT_OPEN   A file could not be opened to store a
                                    received file.
                 HA_XFS_DISK_ERROR  A disk error occurred during transfer.
                 HA_XFS_NO_MEM      The program could not allocate
                                    sufficient memory to complete
                                    transfer.
                 HA_XFS_FILE_EXISTS A file was received with the same name
                                    as an existing file and no option to
                                    rename the file was specified.
                 HA_XFS_COMPLETE    The transfer completed successfully.
                 HA_XFS_CANT_START  The protocol could not successfully
                                    negotiate start of a transfer.
                 HA_XFS_OLDER_FILE  An option to accept only newer files
                                    was specified, and the received file
                                    is older than the existing file.
                 HA_XFS_NO_FILETIME An option to accept only newer files
                                    was specified, and the sender did not
                                    include the date and time of the file
                                    being sent.
                 HA_XFS_WONT_CANCEL An attempt was made to negotiate a
                                    graceful cancel of the transfer with
                                    the remote system, but it did not
                                    respond to the request.
                 HA_XFS_GEN_FAILURE Any error not explicitly covered in
                                    the other return codes.
                 HA_XFS_NO_VSCAN    Virus scanning requested, but no virus
                                    data file is available. (Not available
                                    in OS/2.)
                 HA_XFS_VIRUS_DETECTVirus scanning requested, and a virus
                                    was detected in the file being
                                    received. (Not available in OS/2.)
                 HA_XFS_USER_SKIP   The user used the skip button.
                 HA_XFS_REFUSE      The remote system refused to accept a
                                    file that we attempted to send.
            See Also:
               haGetXferStatus, haWaitForXfer, haXferSend, haXferReceive


haGetXferParameters

            Returns an integer value composed of flags (bits) that
            determine how a transfer operation is carried out.
            Syntax:
               INT haGetXferParameters(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               The integer value returned has flags (bits) which are either
               TRUE (1) or FALSE (0). Determining the value of individual
               bits is language dependent operation. You can test the value
               of a particular bit by performing a bitwise AND operation of
               the returned value with the desired flag name defined below.
               Keep in mind that some file transfer protocols, such as
               Xmodem, have no provision for sending filenames, file sizes,
               or modification times with files.
            Return Value:
               Returns one or more of the following flags, if successful.
               Otherwise, a standard API error code.
                 Value       Meaning
                 XF_DN_MASK  A mask for the next 6 flags. These flags are
                              used if the selected filename is already
                              being used.
                 XF_DN_APPENDAppend if filename is already used.
                 XF_DN_OVERWRT    Overwrite if filename is already used.
                 XF_DN_REFUSERefuse the transfer if filename is already
                              used.
                 XF_DN_NEWER Overwrite if the received file is newer than
                              the current file.
                 XF_DN_DATE  Generate a new filename based on the old name
                              and the current date.
                 Value       Meaning
                 XF_DN_SEQ   Generate a new filename based on the old name
                              and a sequence number.
                 XF_CHECK_VIRUS   Enable virus detection.
                 XF_USE_FILENAME  Use received filename, if any, in naming
                              file.
                 XF_USE_DIRECTORY Use received directory, if any, in
                              naming file.
                 XF_SAVE_PARTIAL  Save partial file if transfer is
                              interrupted.
                 XF_USE_DATETIME  Use received file date and time, if any.
            See Also:
               haSetXferParameters, haXferReceive, haXferSend
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Check a current transfer parameter, and changes its value.
                        This program segment:
                           - Gets a current transfer parameter
                             (checks save partial received files).
                           - Sets transfer parameter (to save). */

                        ReturnCode = haGetXferParameters(ScriptHandle);
                        if ( !(ReturnCode & XF_SAVE_PARTIAL) )
                           {
                           ReturnCode |= XF_SAVE_PARTIAL ;      // Add
                         save partial

                           haSetXferParameters(ScriptHandle, ReturnCode);

            /* -----------------------------------------------------------
                         --------- */



haGetXferProtocol

            Returns the current default transfer protocol.
            Syntax:
               INT haGetXferProtocol(ScriptHandle, nDirection)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nDirection      Selects send or receive
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nDirection
                 Selects sending or receiving.
                 Value       Meaning
                 HA_XFER_SENDGets the sending protocol.
                 HA_XFER_RECVGets the receiving protocol.
            Remarks:

            Return Value:
               Returns one of the following values if successful.
               Otherwise, a standard API error code.
                 Value       Meaning
                 HA_HYPERP   Hilgraeve's HyperProtocol.
                 HA_COMPUSERV_B   CompuServe B+.
                 HA_KERMIT   Kermit.
                 HA_XMODEM   XMODEM.
                 HA_XMODEM_1K1K XMODEM.
                 HA_YMODEM   YMODEM.
                 Value       Meaning
                 HA_YMODEM_G YMODEM-G.
                 HA_ZMODEM   ZMODEM.
            See Also:
               haSetXferProtocol, haXferReceive, haXferSend


haGetXferSendList

            Returns a path and filename from the internal file send list.
            Syntax:
               INT haGetXferSendList(ScriptHandle, nIndex, nSize,
               pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which item to return
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 Selects which item in the list of files is to be
                 returned. Selections start at zero.
               nSize
                 The size of the following buffer. The buffer should be
                 large enough to accomodate a complete path and filename.
               pszBuffer
                 A pointer to a buffer that is to receive the path and
                 filename from the list of files.
            Remarks:
               You can build a list of files that HyperACCESS maintains
               internally and then send all files in the list by using
               haXferSendFromList. Files are normally added to the list by
               haXferAddToSendList. You can examine the list using this
               function.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haClearXferSendList, haGetXferDropList, haXferAddToSendList,
               haXferSendFromList


haGetXferStatus

            Returns a percentage value that indicates how much of a
            transfer has completed.
            Syntax:
               INT haGetXferStatus(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               The number returned is between 0 and 99. This function is
               only useful if a transfer is started with the nFlag argument
               set FALSE. See the remarks under haXferSendFromList for an
               explanation.
            Return Value:
               Returns 0 thru 99 if successful. Otherwise, a standard API
               error code.
            See Also:
               haWaitForXfer, haXferReceive, haXferSend, haXferSendBatch,
               haXferSendFromList, haXferSendList


haInitialize

            This required function must be called before any other API
            functions. The arguments for haInitialize are operating system
            dependent, so a program that runs on multiple platforms will
            require conditional compilation to account for the different
            calling sequences.
            HAOS2 Syntax:
               SCRIPTHANDLE haInitialize(argc, argv)
                 INT argc            Number of arguments in the command
                                      line
                 LPSTR * argv        Array of pointers to strings of
                                      command line arguments
            HAWin Syntax:
               SCRIPTHANDLE haInitialize(hParentHwnd, hInst, hPrevInst,
               lpCmdLine)
                 HWND hParentHwnd    The parent window handle
                 HANDLE hInst        The current instance handle
                 HANDLE hPrevInst    The previous instance handle
                 LPSTR lpCmdLine     The command line
            Arguments:
               argc
                 A count of the number of arguments in the command line.
                 This value is returned by OS/2.
               argv
                 An array of pointers to strings of command line
                 arguments. This array is provided by OS/2.
               hParentHwnd
                 A window handle that the external API is to be a child
                 of.
               hInst
                 The current instance of the task.
               hPrevInst
                 The previous instance of the task, if any.
               lpCmdLine
                 The command line that started the task.
            Remarks:
               This function performs necessary initialization so that an
               external API task can communicate with HyperACCESS. It must
               be called before any other external API function is called.
               All of the parameters are those generally passed in to a C
               program by the operating system. Programmers using C or a
               similar Software Development Kit (SDK) should pass the
               parameters to haInitialize without modification.
               For Visual Basic there is no WinMain entry point available
               to the user. Visual Basic users need to use the Command$
               function to retrieve the command line. The C interpreter
               used by HyperACCESS is a special case. The function must be
               called, but the parameters may be NULL, because WinMain is
               handled internally. Users of other SDKs are encouraged to
               search appropriate documentation to find the necessary
               functions.
               A single external program may call haInitialize more than
               once to create multiple simultaneous control scripts. Doing
               so allows the program to execute multiple tasks in
               HyperACCESS simultaneously or to control more than one
               HyperACCESS session at the same time. Each call to
               haInitialize must be matched with a call to haTerminate when
               the program is done.
            Return Value:
               Returns an external API script handle if successful.
               Otherwise, zero.
            See Also:
               haTerminate


haLearnControl

            Turns learning(recording) on or off for the currently active
            session.
            Syntax:
               INT haLearnControl(ScriptHandle, nCmd)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCmd            The control command
            Arguements:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCmd
                 This is a constant value that represents the command to
                 be applied to the HyperACCESS learning(recording) system.
                 Value       Meaning
                 HA_L_START  Start learning(recording).
                 HA_L_STOP   Stop learning(recording) and save the learned
                              script in the default file.
                 HA_L_ABORT  Stop learning(recording) but do not save the
                              learned script.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetLearnFileName, haCaptureControl


haLoadFuncs

            Register additional HyperACCESS API functions in REXX.
            Syntax:
                   haLoadFuncs
            Remarks:
               This function provides a simple way of registering all
               HyperACCESS API functions with REXX.  You should call this
               API function before any other in a REXX script. To call
               haLoadFuncs, you must use the OS/2 built-in function
               RxFuncAdd. Valid for HAOS2 REXX programs only.
               All REXX entry points in the API actually have an 'Rx'
               prefix.  So, for example, the REXX entry point for
               haInitialize is RxhaInitialize.  If you prefer to register
               only those functions used by your script because of memory
               constraints, you must use the 'Rx' entry point name in your
               RxFuncAdd call.
               If functions are already registered, haLoadFuncs still gives
               a successful return code.
            Return Value:
                   Returns 0 if successful.  Otherwise, a standard API
               error code.
            See Also:
                   haDropFuncs
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Register the API function haLoadFuncs.  It's located in the
  file
             * HA_AUTO.DLL, and is internally named RxhaLoadFuncs.  Then
  call
             * haLoadFuncs to register all other API functions with Rexx.
             */

            CALL RxFuncAdd 'haLoadFuncs', 'HA_AUTO', 'RxhaLoadFuncs'
            CALL haLoadFuncs

            /* -----------------------------------------------------------
  --------- */


haMenuString

            Performs HyperACCESS menu actions as if mnemonic keystrokes
            were used.
            Syntax:
               INT haMenuString(ScriptHandle, pszString)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszString     A pointer to a string of characters
                                      terminated by a null
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszString
                 A pointer to a string of characters representing menu
                 actions. For example, "FX" would represent the menu
                 selections File and Exit.
            Remarks:
               This function lets a programmer perform actions in
               HyperACCESS by specifying the menu mnemonic keystrokes that
               would perform the operation. This function can be said to
               follow the menus to perform the requested function. For
               example, to exit HyperACCESS the string "FX" for File and
               Exit would be used.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Let the user set default transfer protocols.
                        This program segment:
                           - Uses the Properties/Transfer Protocols...
                         menu item to display
                             the File Transfer properties sheet (Transfer
                         Protocols dialog in
                             HAWin) so the user can select new protocols.
                         */

                        ReturnCode = haMenuString(ScriptHandle, "PT");

            /* -----------------------------------------------------------
                         --------- */


haMessageBox

            Displays a dialog box and accepts keyboard or mouse input from
            the user.
            Syntax:
               INT haMessageBox(ScriptHandle, pszTitle, pszMessage, nSize,
               pszBuffer, nButtons)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszTitle      The title of the message box
                 LPSTR pszMessage    The message to be displayed
                 INT nSize           The size of the following buffer
                 LPSTR pszBuffer     A pointer to a buffer
                 INT nButtons        What buttons to display
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszTitle
                 The title of the message box. No commas or NULLs are
                 allowed.
               pszMessage
                 The message in the message box. No commas or NULLs are
                 allowed.
               nSize
                 The size of the following buffer. If the message box does
                 not need an input field, this must be set to zero.
               pszBuffer
                 A pointer to a buffer to receive user keyboard input. If
                 the message box does not need an input field, this
                 pointer must be set to NULL.
               nButtons
                 The following button groups are available:
                 Value       Meaning
                 HA_MB_OK    Use a single OK button.
                 HA_MB_OKC   Use OK and Cancel buttons.
                 HA_MB_YN    Use Yes and No buttons.
            Remarks:
               This function brings up a dialog box similar to a
               HyperACCESS display box. It allows the external API task to
               display messages on the local desktop and get local input.
               The external task is not required to use this function to
               create a message box. It can use standard operating system
               function calls instead. This function is made available as a
               helpful alternative.
            Return Value:
               Returns 0 if Cancel or No is selected, 1 if OK or Yes is
               selected. Otherwise, a standard API error code.


haNotifyOnTerminate

            Posts a message to a specified window when the session closes.
            Syntax:
               INT haNotifyOnTerminate(ScriptHandle, hWnd, nMsg)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 HWND hWnd           A window handle to post to
                 INT nMsg            The message to be posted
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hWnd
                 The handle of the window that the following message is to
                 be posted to.
               nMsg
                 The message that is to be posted to the previous window
                 handle.
            Remarks:
               Posting messages across tasks is not a standard method in a
               Windows program. However, it can sometimes be useful. In
               this case, the message is posted if the script handle is
               still valid and the window handle is still valid. There is
               no type of checking done on the message. It is up to the
               user to correctly deal with it.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetHWND


haOpenSession

            Opens an existing phonebook entry. In HAOS2, displays the
            Terminal panel. In HAWin, opens a new session window.
            Syntax:
               HSESS haOpenSession(ScriptHandle, pszName)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       Name of a session file
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 The path and filename of the session file to use.
            Remarks:
               The session is not connected when it is initially opened.
               The newly opened session becomes the current session for the
               script. In HAWin, a script can interact with several
               sessions simultaneously by storing the session handles in
               variables and using haSetSession to move among them. In
               HAOS2, there is only one session for each instance of
               HyperACCESS, so you must call haInitialize for each instance
               and use the correct script handle.
            Return Value:
               Returns a session handle if successful. Otherwise, a
               standard API error code.
            See Also:
               haCloseSession, haConnectSession, haGetPhonebookEntry,
               haGetSession, haInitialize, haSetSession


haReleaseRemoteInput

            Decrements the counter used to determine how and when a
            session processes characters.
            Syntax:
               INT haReleaseRemoteInput(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               When the counter is greater than zero, a session does not
               process characters. When the counter is zero, a session
               processes characters. When a session is opened, the count is
               set to zero. If a script is run from within a session, the
               counter is incremented. If the script exits from within a
               session, the counter is decremented.
               If you create a script that doesn't process received
               characters using functions such as haGetInput or
               haWaitForPrompt, and you want the current session to
               continue to process received data normally, you must call
               haReleaseRemoteInput for the session.
               If you create scripts that change control among several
               sessions using haSetSession, you can use haBlockRemoteInput
               and haReleaseRemoteInput to control when the sessions
               process received data. This ensures that your script doesn't
               miss any characters.
               If you have multiple scripts for one session, only one
               script at a time should process received data using
               haGetInput or haWaitForPrompt. The others should use
               haReleaseRemoteInput, otherwise data remains blocked.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haBlockRemoteInput


haReloadPhonebook

            Causes HyperACCESS to rescan for Phonebook files.
            Syntax:
               INT haReloadPhonebook(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               This function is useful to notify HyperACCESS that something
               in Phonebook has changed. If you add or remove session files
               from the phonebook directory or modify session files
               directly, you can use this function to force HyperACCESS to
               redisplay the phonebook with the changes.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPhonebookEntry


haSavePhonebook

            Writes the HyperACCESS preferences file to disk.
            Syntax:
               INT haSavePhonebook(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               HyperACCESS stores program-wide settings. It keeps this
               information in memory while it is running, and writes these
               settings to the disk file as it exits. This function writes
               these settings immediately.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haReloadPhonebook


haSelectDialingPrefix

            Specifies the dialing prefix that is to be used by the current
            session.
            Syntax:
               INT haSelectDialingPrefix(ScriptHandle, nIndex)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which prefix to use
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 Specifies which prefix to use. A value of zero means no
                 prefix is used. Valid choices are 1 - 9.
            Remarks:
               HyperACCESS uses the dialing prefix as part of the phone
               number when it attempts to establish a connection.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetDialingPrefix, haSetDialingPrefix
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Select dialing prefix.
                        This program segment:
                           - Selects the first dialing prefix as the one
                         to use
                             for this session */

                        ReturnCode = haSelectDialingPrefix(ScriptHandle,
                         1);

            /* -----------------------------------------------------------
                         --------- */


haSetAdlOverride

            Changes the automatic download override setting.
            Syntax:
               INT haSetAdlOverride(ScriptHandle, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFlag           The new setting of the automatic
                                      download override switch
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFlag
                 If TRUE (non-zero), the automatic download feature for
                 Hyperprotocol, and ZModem transfers is disabled. If FALSE
                 (zero), the automatic download capability is controlled
                 by user settings available in the interface.
            Remarks:
               This override of the setting in the HyperProtocol Settings
               and Zmodem Settings dialog boxes is not available from the
               user interface. This override is available only when
               controlling HyperACCESS from an external program. It allows
               you to disable the automatic downloading capabilities built
               into HyperACCESS to avoid situations where an automatic
               download might compromise security restrictions built into a
               program.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Turn off automatic download feature of Zmodem and
                         HyperProtocol. */

                        ReturnCode = haSetAdlOverride(ScriptHandle, TRUE);

            /* -----------------------------------------------------------
                         --------- */


haSetAsciiSettings

            Change settings that are found in the ASCII Settings dialog
            box.
            Syntax:
               INT haSetAsciiSettings(ScriptHandle, nCount, pnData)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCount          The number of integers that follow
                 INT FAR *pnData     A pointer to an array of integers
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCount
                 The number of integers that are in the pnData array.
               pnData
                 A pointer to an array of integers that are used to set
                 ASCII settings values. Each array element sets a
                 different value and can be indexed by the following
                 constants:
                 Value       Meaning
                 HA_AI_FLAGS Various individual flags(bits), described
                              below.
                 HA_AI_WFCHARInput wait for character.
                 HA_AI_OTABS Output tab expansion value.
                 HA_AI_CWAIT Character delay value.
                 HA_AI_LWAIT Line delay value.
                 HA_AI_ITABS Input tab conversion value.
                 The following flags(bits) are used in the HA_AI_FLAGS
                 word to set the state of individual check box items:
                 Value       Meaning
                 HA_AFS_LF   Append LF to sent line ends.
                 HA_AFS_BLS  Expand blank lines sent to include a space.
                 HA_AFS_ECHO Echo typed characters locally.
                 HA_AFS_WAIT Enable wait for line end character.
                 HA_AFS_TABS Enable tab expansion for sent characters.
                 HA_AFR_LF   Append LF to received line ends.
                 HA_AFR_7BIT Force incoming characters to 7 bits.
                 HA_AFR_ECHO Echo received characters to sender.
                 HA_AFR_WRAP Wrap lines that exceed terminal width.
                 HA_AFR_HEX  Show hex value of non-printing characters.
            Remarks:
               The integer at index HA_AI_FLAGS has individual flags
               (bits), which are either TRUE (1) or FALSE (0). Setting the
               value of individual bits is a language dependent operation.
               You can set the value of a particular bit by performing a
               bitwise OR operation. You can also add all the flagnames
               that you want set (TRUE) and assign the result to the array
               location identified by HA_AI_FLAGS.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetAsciiSettings
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set ASCII Settings for a communications session.
            This program segment sets HyperACCESS to:
               - Append LF to sent lines.
               - Expand blank lines to include a space.
               - Append LF to received line ends.        */

            nSettings =                                   HA_AFS_LF  |
  HA_AFS_BLS | HA_AFR_LF;

            haSetAsciiSettings(hScriptHandle, 3, &nSettings);

            /* -----------------------------------------------------------
                         --------- */


haSetBaudRate

            Changes the speed, generally referred to as the baud rate, of
            the communications device associated with the current session.
            The port type of the communications device determines the
            range of acceptable values.
            Syntax:
               INT haSetBaudRate(ScriptHandle, lSpeed)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lSpeed         The new speed for the device
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lSpeed
                 The new speed for the device.
            Remarks:
               Some device types do not need a baud rate setting. For those
               that don't, this setting is ignored. For those that do, it
               is checked when a connection is attempted.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetBaudRate
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Change the baud rate of the current session.
                           - This program segment sets the baud rate to
                         19,200. */

                        ReturnCode = haSetBaudRate(ScriptHandle, 19200L);

            /* -----------------------------------------------------------
                         --------- */


haSetCaptureFileName

            Changes the default name of the capture file for the currently
            active session.
            Syntax:
               INT haSetCaptureFileName(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to a path and filename
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the new capture path and
                 filename.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haCaptureBegin, haCaptureControl, haGetCaptureFileName
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set capture filename.
            This program segment:
               - Sets a string to a program defined path and filename.
               - Calls haSetCaptureFileName to set the name.   */

            strcpy(szFilename, "C:\\HAOS2\\HAOS2.CAP");

            ReturnCode = haSetCaptureFileName(hScriptHandle, szFilename);

            /* -----------------------------------------------------------
                         --------- */


haSetConnectionDetails

            Changes the connection details associated with a connection
            key handle.
            Syntax:
               INT haSetConnectionDetails(ScriptHandle, hCnctKey,
               pszDetails)
                 SCRIPTHANDLE ScriptHandleThe program - HAOS2 link
                 HKCNCT hCnctKey     A connection key handle
                 LPSTR pszDetails    A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hCnctKey
                 A connection key handle returned from
                 haGetCurrentConnection, haGetDefaultConnection, or
                 haCreateConnection.
               pszDetails
                 A null-terminated string containing new connection
                 details.
            Remarks:
            For details on the buffer format, see haGetConnectionDetails.
            This function is supported in HAOS2.
            Return Value:
            Returns 0 if successful. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haFindConnectionTypeDevices, haGetConnectionDetails,
               haGetCurrentConnection, haGetDefaultConnection,
               haSetCurrentConnection


haSetCurrentConnection

            Set the connection handle used by the currently opened
            session.
            Syntax:
               INT haSetCurrentConnection(ScriptHandle, hCnctKey)
                 SCRIPTHANDLE ScriptHandleThe program - HAOS2 link
                 HKCNCT hCnctKey     The connection key handle to use
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hCnctKey
                 A connection key handle returned from
                 haGetCurrentConnection, haGetDefaultConnection, or
                 haCreateConnection.
            Remarks:
            This function is supported in HAOS2.
            Return Value:
            Returns 0 if successful. Otherwise, a standard API error code.
            See also:
               haCreateConnection, haDeleteConnection, haFindComTypes,
               haFindConnection, haFindConnectionTypes,
               haFindConnectionTypeDevices, haGetConnectionDetails,
               haGetCurrentConnection, haGetDefaultConnection,
               haSetConnectionDetails


haSetCursorPosition

            Positions the cursor on the emulator screen.
            Syntax:
               INT haSetCursorPosition(ScriptHandle, nRow, nCol)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nRow            The row number
                 INT nCol            The column number
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nRow
                 The row number of the new cursor position.
               nCol
                 The column number of the new cursor position.
            Remarks:
               Row and column numbers start at zero and are limited by the
               emulator.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetCursorPosition, haGetTextFromScreen


haSetDialingPrefix

            Sets one of the dialing prefix strings stored by HyperACCESS.
            Syntax:
               INT haSetDialingPrefix(ScriptHandle, nIndex, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which string to change
                 LPSTR pszPtr        A pointer to the new string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 Which string to change. Valid choices are 1 thru 9.
               pszPtr
                 A pointer to a string containing the new prefix string.
            Remarks:
               Dialing prefix strings are stored globally in the
               preferences file, and all sessions use the same set of
               strings. If, for example, string 1 is changed from within a
               particular session, all sessions that use dialing prefix
               string 1 will be affected.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetDialingPrefix, haSelectDialingPrefix
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Changes a dialing prefix to a new value.
                        This program segment:
                           - Changes the first dialing prefix (for all
                         sessions) to "1-313" */

                        ReturnCode = haSetDialingPrefix(ScriptHandle, 1,
                         "1-313");

            /* -----------------------------------------------------------
                         --------- */


haSetDisplay

            Changes display mode of the Phonebook.
            Syntax:
               INT haSetDisplay(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           The mode to change to
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 The valid display modes are:
                 Value       Meaning
                 HA_ICONIC   The Phonebook will be displayed as icons.
                 HA_STATS    The Statistics view will be displayed in the
                              Phonebook.
                 HA_DETAILS  The Details view will be displayed in the
                              Phonebook.
                 HA_NAMES    The Phonebook will be displayed as system
                              names.
                 HA_FILES    The Phonebook will be displayed as filenames.
            Remarks:
               Changing the display mode of the phonebook causes the
               phonebook window to redisplay with the proper format.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetDisplay


haSetEcho

            Enables and disables echo of received characters.
            Syntax:
               INT haSetEcho(ScriptHandle, nEcho)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nEcho           To echo or not to echo
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nEcho
                 If the value is TRUE, echoing is enabled. If it is FALSE,
                 echoing is disabled.
            Remarks:
               When this setting is TRUE, every character received from a
               remote system is transmitted back to the remote system for
               display. This setting is normally set to TRUE only when
               HyperACCESS is serving as a host system.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetLocalEcho
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set character echo for half duplex operation.
                        This program segment:
                           - Disables echo of characters received.
                           - Enables echo of characters sent so they
                         display locally. */

                        ReturnCode = haSetEcho(ScriptHandle, FALSE);
                        ReturnCode = haSetLocalEcho(ScriptHandle, TRUE);

            /* -----------------------------------------------------------
                         --------- */


haSetEmulator

            Changes the emulator that is used by the currently active
            session.
            Syntax:
               INT haSetEmulator(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to the new emulator
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the name of the new
                 emulator.
            Remarks:
               Only valid emulator names are accepted. The type of emulator
               loaded determines how HyperACCESS decodes received control
               sequences.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetEmulator


haSetLearnFileName

            Changes the default name of the learn file(script) for the
            currently active session.
            Syntax:
               INT haSetLearnFileName(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A ponter to a filename
            Arguements:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the new learn filename.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise a standard API error
               code.
            See Also:
               haGetLearnFileName, haSetCaptureFileName


haSetLocalDisplay

            Enable or disable display of data on the local emulator
            screen.
            Syntax:
               INT haSetLocalDisplay(ScriptHandle, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFlag           The local display flag.
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFlag
                 If TRUE, displays all characters on the local emulator
                 screen. If FALSE, suppresses display.
            Remarks:
               If FALSE, will suppress display of both incoming and locally
               echoed characters.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Hide received characters.
                        This program segment:
                           - Disables display of received characters.
                           - Waits for a carriage return (or 30 seconds).
                           - Enables display of received characters after
                         one line */

                        ReturnCode = haSetLocalDisplay(ScriptHandle,
                         TRUE);
                        ReturnCode = haWaitForLines(ScriptHandle, 1,
                         30000L);
                        ReturnCode = haSetLocalDisplay(ScriptHandle,
                         FALSE);

            /* -----------------------------------------------------------
                         --------- */


haSetLocalEcho

            Enable or disables local display of transmitted characters.
            Syntax:
               INT haSetLocalEcho(ScriptHandle, nEcho)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nEcho           To echo or not to echo
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nEcho
                 If TRUE, transmitted characters are displayed locally. If
                 FALSE, transmitted characters are not diplayed unless
                 they are echoed back by the remote system.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetEcho


haSetLogFileName

            Changes the name of the log file for the currently active
            session.
            Syntax:
               INT haSetLogFileName(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to the new path and
                                      filename
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the new log file path
                 and filename.
            Remarks:
               All calls and file transfers are recorded in the log file.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetLogFileName


haSetLogonTask

            Sets the task that is run when the currently active session
            successfully completes a connection.
            Syntax:
               INT haSetLogonTask(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to a path and filename
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the new path and
                 filename.
            Remarks:
               Normally, a logon task calls haInitialize and runs as a
               script, however, any executable file can be run.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set connect program for the current session. */

                        ReturnCode = haSetLogonTask(ScriptHandle,
                         "C:\\MYDIR\\BOB.C");

            /* -----------------------------------------------------------
                         --------- */


haSetMessageTimer

            Sets a timer for dismissing message boxes that report errors
            and unusual conditions.
            Syntax:
               INT haSetMessageTimer(ScriptHandle, nSeconds)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSeconds        The number of seconds before timeout
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSeconds
                 The number of seconds before timeout. A value of zero (0)
                 means that the message box is not displayed at all. A
                 value of minus one (-1) means no timeout is to be used
                 and the message box will be displayed until the user
                 responds to it. Minus one (-1) is the initial session
                 default.
            Remarks:
               An external task can perform most of the operations that a
               user can perform. One of the few exceptions is dismissing
               message boxes that report errors and unusual conditions.
               This function changes the way standard HyperACCESS message
               boxes function by setting a timeout value. If no user
               interaction dismisses the message box within the timeout
               value, the box times out and dismisses itself. Each message
               box attempts to perform an appropriate action upon timeout.
               The timeout affects only the current session and is valid
               for as long as the session lasts, even if the script
               terminates before the session is closed.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Dismiss message boxes after fixed period of time.
              This lets a user respond, or continues with default actions
                         if no user
               response received in fixed time interval (10 seconds, in
                         example). */

                        ReturnCode = haSetMessageTimer(ScriptHandle, 10);
            /* -----------------------------------------------------------
                         --------- */


haSetNameString

            Sets the internal HyperACCESS user name and address field.
            Syntax:
               INT haSetNameString(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to the new string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string. This string is six lines in HAWin
                 and seven lines in HAOS2. Each line is terminated by a
                 carriage return - line feed pair. The first line is the
                 name line. The second line is the company line. The third
                 line is the street address. The fourth line is the city.
                 The fifth line is the state. The sixth line is the zip
                 code. The seventh line is country.
            Remarks:
               These values are normally established by the setup program
               at installation.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetNameString
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set the User name and address information.

            This program segment:
               - Defines a character string variable.
               - Sets the variable to the name and address desired.
               - Sets the internal HyperACCESS user name and address
  field.
               - This example assumes the HAOS2 definition that includes
                 a country field.   */

            char szNameString[128];       // Variable to store the name
  string

            strcpy(szNameString, "Mr. Joel Pendergast\r\n"
                                "Pendergast Consulting\r\n"
                                "123 Main St.\r\n"
                                "Anywhere\r\n"
                                "MI\r\n"
                                "48999\r\n"
                                "USA\r\n");
            ReturnValue = haSetNameString(hScriptHandle, szNameString);

            /* -----------------------------------------------------------
                         --------- */


haSetPortMode

            Changes current settings for number of bits per character,
            number of parity bits, and parity type.
            Syntax:
               INT haSetPortMode(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Flags for the new settings
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 The mode is set by ORing selected flags together:
                 Value       Meaning
                 HA_M_AUTO   Auto-detect is set.
                 HA_M_7_BITS Characters contain 7 bits.
                 HA_M_8_BITS Characters contain 8 bits.
                 HA_M_E_PRTY Characters have even parity.
                 HA_M_O_PRTY Characters have odd parity.
                 HA_M_N_PRTY Characters have no parity.
                 HA_M_M_PRTY Characters have mark parity.
                 HA_M_S_PRTY Characters have space parity.
                 HA_M_1_STOP Characters have one stop bit.
                 HA_M_1_5_STOP    Characters have 1.5 stop bits.
                 HA_M_2_STOP Characters have two stop bits.
            Remarks:
               The integer nMode has individual flags (bits) which are
               either TRUE (1) or FALSE (0). Setting the value of
               individual bits is language dependent. However, in C, you
               can set the value of a particular bit by performing a
               bitwise OR operation of nMode with the desired flag name
               defined above. You can also add all the flagnames that you
               want set (TRUE) and assign the result to nMode.
               For example:

              haSetPortMode(ScriptHandle, HA_M_8BITS + HA_M_N_PRTY +
                        HA_M_1_STOP);
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortMode
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Change communications parameters.
                        This program segment:
                           - Sets the port mode to 8 bit, no parity, 1
                         stop bit.
                           - Sets the port name to "COM1".
                           - Sets the port type to "Standard COM Port".
                         */

                        ReturnCode = haSetPortMode(ScriptHandle,
                         HA_M_8_BITS + HA_M_N_PRTY + HA_M_1_STOP);
                        ReturnCode = haSetPortName(ScriptHandle, "COM1");
                        ReturnCode = haSetPortType(ScriptHandle, "STANDARD
                         COM PORT");

            /* -----------------------------------------------------------
                         --------- */


haSetPortName

            Changes the device name that is associated with the currently
            active session.
            Syntax:
               INT haSetPortName(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to the new name
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the new name.
            Remarks:
               The setting for port type determines which values are
               acceptable as port names. For example, the port type
               Standard Com Port can have values such as COM1 and COM2.
               Other port types accept different names as appropriate. In
               general, HyperACCESS doesn't attempt to prescreen names.
               Instead, they are passed to the communications driver for
               verification. This function is only supported in HAWin.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortName, haSetPortPrefs, haSetPortType


haSetPortPrefs

            Changes the connection device associated with a communications
            port.
            Syntax:
               INT haSetPortPrefs(ScriptHandle, pszType, pszName,
               pszDevice)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszType       A pointer to the port type
                 LPSTR pszName       A pointer to the port name
                 LPSTR pszDevice     A pointer to the commumications
                                      device
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszType
                 A pointer to a string containing the device type.
               pszName
                 A pointer to a string containing the port name.
               pszDevice
                 A pointer to a string containing the connection device
                 name.
            Remarks:
               This function lets you set the three values that, together,
               define a connection path. The device type and port name can
               also be set by haSetPortType and haSetPortName,
               respectively. This function also lets you set the connection
               device (modem). Acceptable values for port name and
               connection device depend on the port type in use.
               Each session has an assigned port type and port name. The
               connection device name, however, is defined globally for
               each port type - port name combination. The user defines
               these combinations, and HyperACCESS stores them along with
               the connection devices associated with them. As a result,
               changing a connection device in one session impacts all
               sessions that use the same port type - port name
               combination. For example, if in the session MCI Mail, you
               specify that an XYZ SuperModem is attached to Standard Com
               Port, COM1, then any session that is set up to use Standard
               Com Port, COM1, will now also expect to use an XYZ
               SuperModem. This is supported in HAWin.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortPrefs, haSetPortName, haSetPortType
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Change communications parameters and modem.
                        This program segement:
                           - Uses one function call to set port name, port
                         type, and modem */

                        ReturnCode = haSetPortPrefs(ScriptHandle,
                         "STANDARD COM PORT", "COM1", "Amstrad Quad");

            /* -----------------------------------------------------------
                         --------- */


haSetPortType

            Changes the device type associated with the currently active
            session.
            Syntax:
               INT haSetPortType(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to the device type
            Arguments:
               ScriptHandle
                 The context handle returned from haInitialize.
               pszPtr
                 A pointer to a string containing the device type.
            Remarks:
               HyperACCESS supports many types of communications devices.
               Each device type may consist of one or more actual ports.
               For example, if the port type is Standard Com Port, you may
               have COM1 and COM2 available as port names. Each port type
               is implemented as a driver module in a *.DLL file on the
               disk. Changing the port type changes the values acceptable
               as port name and connection device name (modem). This
               function is only supported in HAWin.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetPortType


haSetPulseTone

            Sets the device dialing method to pulse or tone.
            Syntax:
               INT haSetPulseTone(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           Select pulse or tone
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 Valid values are:
                 Value       Meaning
                 HA_PT_PULSE Set to pulse mode dialing.
                 HA_PT_TONE  Set to tone mode dialing.
            Remarks:
               This setting will be used only by connection devices that
               place calls over dial-up phone lines.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Change dialing type to PULSE */

                        ReturnCode = haSetPulseTone(ScriptHandle,
                         HA_PT_PULSE);

            /* -----------------------------------------------------------
                         --------- */


haSetRingsForAnswer

            Changes the number of rings that the modem should wait before
            answering a call.
            Syntax:
               INT haSetRingsForAnswer(ScriptHandle, nCount)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCount          The number of rings to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCount
                 The number of rings that the modem is instructed to wait
                 for before answering.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haConnectSession, haGetRingsForAnswer
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set the number of rings to answer the phone, and put modem
                         in answer mode.
                        This program segment:
                           - Sets the number of rings before answer to 3.
                           - Connects the session to its port in answer
                         mode. */

                        ReturnCode = haSetRingsForAnswer(ScriptHandle, 3);
                        ReturnCode = haConnectSession(ScriptHandle,
                         HA_CNCT_ANSWER_MODE);

            /* -----------------------------------------------------------
                         --------- */


haSetRuntimeValue

            Changes one of the runtime strings stored with each session.
            Syntax:
               INT haSetRuntimeValue(ScriptHandle, nValue, pszBuffer)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nValue          Which runtime string to set
                 LPSTR pszBuffer     A pointer to a buffer
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nValue
                 Which runtime string to return:
                 Value       Meaning
                 HA_RV_USERNAME   Set the user name.
                 HA_RV_USERIDSet the user ID.
                 HA_RV_PASSWORD   Set the password.
               pszBuffer
                 A pointer to a buffer that has the runtime string.
            Remarks:
               Unconditionally sets a stored runtime value without
               prompting the user.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.


haSetSession

            Changes the session handle that is accociated with the current
            program - HyperACCESS link.
            Syntax:
               INT haSetSession(ScriptHandle, hSession)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 HSESS hSession      A session handle
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hSession
                 A session handle returned by haGetSession or
                 haOpenSession.
            Remarks:
               The session handle identifies which session an external task
               is associated with. This is necessary because HAWin allows
               multiple concurrent communications sessions within the same
               task. In HAOS2, there is only one session for each instance
               of HyperACCESS.
               haSetSession doesn't save the session handle that was
               previously associated with the ScriptHandle, but a program
               can save the previous session handle in a variable and
               restore it later using haSetSession.
               If you write a program that attempts to control more than
               one session, you should read the remarks for functions
               haBlockRemoteInput and haReleaseRemoteInput.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haBlockRemoteInput, haCloseSession, haGetSession,
               haOpenSession, haReleaseRemoteInput


haSetSessionDataString

            Sets one of the data strings stored with each session.
            Syntax:
               INT haSetSessionDataString(ScriptHandle, nIndex, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nIndex          Which string to set
                 LPSTR pszPtr        A pointer to a string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nIndex
                 The index of the string to be set. Valid numbers are 0
                 thru 19.
               pszPtr
                 A pointer to the new string.
            Remarks:
               The first ten session data strings (0 - 9) are not stored in
               the session file and will be blank when a session is opened.
               The second ten (10 - 19) are available for general script
               use and are saved with the session. They can be used to
               store any values that should be maintained unchanged from
               one execution to the next.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetSessionDataString


haSetStripTo7Bits

            Enables and disables stripping of received characters to 7
            bits.
            Syntax:
               INT haSetStripTo7Bits(ScriptHandle, nStrip)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nStrip          Enable or disable stripping
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nStrip
                 If TRUE, stripping is enabled. If FALSE, stripping is
                 disabled.
            Remarks:
               When this setting is TRUE, the high order bit of each
               received character is forced to zero prior to display. This
               is done regardless of the parity or data bits settings for
               the communications channel.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSetAsciiSettings (HA_AI_FLAGS value HA_AFR_7BIT)


haSetXferDirectory

            Changes one of the default transfer directories for the
            currently active session.
            Syntax:
               INT haSetXferDirectory(ScriptHandle, nDirection, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nDirection      Which directory to change
                 LPSTR pszPtr        A pointer to a string containing the
                                      directory path
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nDirection
                 Describes which directory to change:
                 Value       Meaning
                 HA_XFER_SENDSelects the sending directory.
                 HA_XFER_RECVSelects the receiving directory.
               pszPtr
                 A pointer to a string containing the new directory path.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferDirectory


haSetXferParameters

            Provides an integer value composed of flags (bits) that
            determine how a transfer operation is carried out.
            Syntax:
               INT haSetXferParameters(ScriptHandle, lParams)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lParams        The new parameters
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lParams
                 The transfer parameters are describe by the following
                 flags which may be used to modify the current parameters:
                 Value             Meaning
                 XF_DN_MASK         A mask for the next 6 flags. These
                                    flags are used if the selected
                                    filename is already being used.
                 XF_DN_APPEND       Append if filename is already used.
                 XF_DN_OVERWRT      Overwrite if filename is already used.
                 XF_DN_REFUSE       Refuse the transfer if filename is
                                    already used.
                 XF_DN_NEWER        Overwrite if the received file is
                                    newer than the current file.
                 XF_DN_DATE         Generate a new filename based on the
                                    old name and the current date.
                 XF_DN_SEQ          Generate a new filename based on the
                                    old name and a sequence number.
                 XF_CHECK_VIRUS     Enable virus detection.
                 XF_USE_FILENAME    Use received filename in naming file.
                 XF_USE_DIRECTORY   Use received directory in naming file.
                 Value             Meaning
                 XF_SAVE_PARTIAL    Save partial file from interrupted
                                    transfer.
                 XF_USE_DATETIME    Use received file date and time.
            Remarks:
               The integer lParams has individual flags (bits), which are
               either TRUE (1) or FALSE (0). Setting the value of
               individual bits is a language dependent operation. You can
               set the value of a particular bit by performing a bitwise OR
               operation of lParams with the desired flag name defined
               above. You can also add all the flag names that you want set
               (TRUE) and assign the result to lParams.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferParameters
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Check a current transfer parameter, and changes its value.
                        This program segment:
                           - Gets a current transfer parameter (checks
                         append mask).
                           - Sets transfer parameter (to overwrite). */

                        ReturnCode = haGetXferParameters(ScriptHandle);
                        if (ReturnCode == XF_DN_APPEND)
                           ReturnCode = haSetXferParameters(ScriptHandle,
                         XF_DN_OVERWRT);

            /* -----------------------------------------------------------
                         --------- */


haSetXferProtocol

            Changes one of the default transfer protocols for the
            currently active session.
            Syntax:
               INT haSetXferProtocol(ScriptHandle, nDirection, nProtocol)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nDirection      Selects the direction
                 INT nProtocol       Selects the protocol
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nDirection
                 Describes which direction to change:
                 Value             Meaning
                 HA_XFER_SENDSets the sending protocol.
                 HA_XFER_RECVSets the receiving protocol.
               nProtocol
                 Select the new protocol
                 Value             Meaning
                 HA_HYPERP   Hilgraeves HyperProtocol.
                 HA_COMPUSERV_B   CompuServ B+.
                 HA_KERMIT   Kermit.
                 HA_XMODEM   XMODEM.
                 HA_XMODEM_1K1K XMODEM.
                 HA_YMODEM   YMODEM.
                 HA_YMODEM_G YMODEM-G.
                 HA_ZMODEM   ZMODEM.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferProtocol, haXferDropSend, haXferReceive,
               haXferSend, haXferSendBatch, haXferSendFromList,
               haXferSendList
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set the default receive protocol
                        This program segment:
                           - Sets the default receive protocol to
                         HyperProtocol. */

                        ReturnCode = haSetXferProtocol(ScriptHandle,
                         HA_XFER_RECV, HA_HYPERP);

            /* -----------------------------------------------------------
                         --------- */


haSizeHyperACCESS

            Changes the size and visibility of the HyperACCESS application
            window.
            Syntax:
               INT haSizeHyperACCESS(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           What to do to the program
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 The following GUI operations can be performed by
                 HyperACCESS:
                 Value       Meaning
                 HA_S_MAX    Maximize HyperACCESS.
                 HA_S_MIN    Minimize HyperACCESS.
                 HA_S_RSTR   Restore HyperACCESS.
                 HA_S_HIDE   Hide HyperACCESS.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSizePhonebook, haSizeSession
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Set HyperACCESS window sizes.
                        This program segment:
                           - Maximizes the HyperACCESS application
                         window.*/

                        ReturnCode = haSizeHyperACCESS(ScriptHandle,
                         HA_S_MAX);
            /* -----------------------------------------------------------
                         --------- */


haSizePhonebook

            Changes the size of the Phonebook window within HyperACCESS.
            Syntax:
               INT haSizePhonebook(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           How to change the Phonebook
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 The following Windows operations can be performed on the
                 Phonebook:
                 Value       Meaning
                 HA_S_MAX    Maximize the Phonebook.
                 HA_S_MIN    Minimize the Phonebook.
                 HA_S_RSTR   Restore the Phonebook.
            Remarks:
               Used in HAWin. Ignored in HAOS2 (always gives a successful
               return).
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSizeHyperACCESS, haSizeSession


haSizeSession

            Changes the size of the currently active session window.
            Syntax:
               INT haSizeSession(ScriptHandle, nMode)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nMode           How to change the session
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nMode
                 The following Windows operations can be performed on the
                 session:
                 Value       Meaning
                 HA_S_MAX    Maximize the session.
                 HA_S_MIN    Minimize the session.
                 HA_S_RSTR   Restore the session.
            Remarks:
               Used in HAWin. Ignored in HAOS2 (always gives a successful
               return).
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haSizeHyperACCESS, haSizePhonebook


haSkipConnection

            Clears the perform connection flag.
            Syntax:
               INT haSkipConnection(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
            Remarks:
               In HyperACCESS, you can define a program that runs before a
               connection is attempted and one that runs (as a logon) after
               a connection has been completed. Normally, HyperACCESS runs
               the preconnection program, attempts to connect to the remote
               system, and then, if the connection is successful, runs the
               logon program.
               If you write a preconnection program that does some advance
               processing and then determines that the connection should
               not proceed, or you want to make the connection from within
               the preconnection program, you can disable the automatic
               connection that is normally attempted when the preconnect
               program ends.
               If haSkipConnection is called during the preconnect program,
               HyperACCESS doesn't attempt to automatically connect the
               session when it terminates and won't run the logon program.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haOpenSession, haConnectSession


haSleep

            Causes the API interface to enter the HyperACCESS server idle
            loop for a specified period of time.
            Syntax:
               INT haSleep(ScriptHandle, lTime)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lTime          How long to sleep
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lTime
                 The amount of time to sleep, measured in milliseconds.
            Remarks:
               While an application sleeps, the session neither sends nor
               receives characters. During this time, however, windows
               messages continue to be dispatched to prevent the Windows
               environment from becoming inactive.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haWait
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Pause execution of the API program. haSleep doesn't block
                         other tasks from
              getting CPU time, and lets HyperACCESS continue to send and
                         receive data.
                        This program segment:
                           - Pauses for 10 seconds. */

                        ReturnCode = haSleep(ScriptHandle, 10000L);

            /* -----------------------------------------------------------
                         --------- */


haSpawn

            Starts up another external task (or script).
            Syntax:
               INT haSpawn(ScriptHandle, pszName)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName                 The name of the external
                                      task
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 A buffer containing the file name of the external task
                 that is to be run.
            Remarks:

            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.


haTerminate

            Releases any resources that are allocated to the external API
            task interface.
            HAOS2 Syntax:
               INT haTerminate(ScriptHandle)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
            HAWin Syntax:
               INT haTerminate(ScriptHandle, hWndParent)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 HWND hWndParent     A window handle
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               hWndParent
                 The same window handle that was passed to haInitialize.
            Remarks:
               You call this function after all external API operations
               have been performed. It releases any resources that are
               allocated to the external API task interface. Any later use
               of the program - HyperACCESS link results in an error. This
               function makes an implicit call to haReleaseRemoteInput for
               its current session.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haInitialize, haReleaseRemoteInput


haTextSend

            Queues a text file for transmission through the port of a
            connected session.
            Syntax:
               INT haTextSend(ScriptHandle, pszFilename)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszFilename   The name of the path and filename to
                                      be sent
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszFilename
                 A pointer to a null terminated string containing the path
                 and filename of the file to be sent.
            Remarks:
               The file is sent out the port as though it were being typed
               rapidly by the user. If any other data is waiting to be
               transmitted, it will be sent first.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haTypeText, haWaitForOutputDone
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Send a text file as if it were typed.
                        This program segment:
                           - Sends a text file as typed data. */

                        ReturnCode = haTextSend(ScriptHandle,
                         "C:\\MYDIR\\LETTER.TXT");

            /* -----------------------------------------------------------
                         --------- */


haTypeLocalText

            Displays text on screen using the current emulator.
            Syntax:
               INT haTypeLocalText(ScriptHandle, nSize, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The number of characters
                 LPSTR pszPtr        A pointer to a string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The number of characters in the string to follow. If the
                 following string is a zero terminated string, this value
                 can be 0. If the string has embedded zero characters,
                 then this value must be the number of characters in the
                 string, including the zero characters.
               pszPtr
                 A pointer to a string of characters.
            Remarks:
               The text is treated as though it had been received from the
               remote system. It is displayed on screen, captured as
               appropriate, passed into the backscroll buffer, etc.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haTypeText, haWaitForPrompt, haWaitForString


haTypeText

            Transmits a string of characters through the port of a
            connected session.
            Syntax:
               INT haTypeText(ScriptHandle, nSize, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nSize           The number of characters
                 LPSTR pszPtr        A pointer to a string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nSize
                 The number of characters in the string to follow. If the
                 following string is a zero terminated string, this value
                 can be 0. If the string has embedded zero characters,
                 then this value is the number of characters in the
                 string, including the embedded zero characters.
               pszPtr
                 A pointer to a string of characters.
            Remarks:
               The characters are buffered as necessary.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haTypeLocalText, haWaitForPrompt, haWaitForString


haWait

            Wait for a specified period of time without blocking remote
            input.
            Syntax:
               INT haWait(ScriptHandle, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lTimeout       How long to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lTimeout
                 How long to wait in milliseconds.
            Remarks:
               This function is similar to haSleep, except that it permits
               processing of received characters while haSleep blocks
               remote input.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetInput, haSleep, haWaitForActivity, haWaitForLull,
               haWaitForPrompt, haWaitForString


haWaitForActivity

            Waits for any character to be received from the remote system.
            Syntax:
               INT haWaitForActivity(ScriptHandle, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lTimeout       How long to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lTimeout
                 How long to wait for a character, measured in
                 milliseconds.
            Remarks:
               If no character is received before the timer expires, an
               error is returned. This function is most often used to wait
               for the remote system to complete an operation that doesn't
               generate output.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetInput, haWaitForLines, haWaitForLull


haWaitForConnection

            Waits for the connection status to match the supplied
            parameter.
            Syntax:
               INT haWaitForConnection(ScriptHandle, nStatus, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nStatus         The status to wait for
                 LONG lTimeout       How long to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nStatus
                 The function waits for one of the following:
                 Value             Meaning
                 HA_CONNECTED       The session is currently connected.
                 HA_DISCONNECTED    The session is currently disconnected.
                 HA_CONNECTING      The session is currently in the
                                    process of attempting a connection.
               lTimeout
                 How long to wait for the connection state before timing
                 out, measured in milliseconds.
            Remarks:
               This function should be used to wait for a connection to
               complete rather than calling haGetConnectionStatus
               repeatedly. In an event driven environment like Windows, it
               is important to make sure that a program doesn't hog the
               system while waiting for an external event.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haConnectSession, haDisconnectSession, haGetConnectionStatus


haWaitForLines

            Waits for a specified number of lines to be received.
            Syntax:
               INT haWaitForLines(ScriptHandle, nLines, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nLines          Number of lines to wait for
                 LONG lTimeout       How long to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nLines
                 The number of lines to wait for.
               Argument
                 How long to wait before returning an error, measured in
                 milliseconds.
            Remarks:
               A line is considered to be received when a carriage return
               character is received. If the function does not receive the
               specified number of lines within the time limit, an error is
               returned.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haWaitForActivity, haWaitForLull


haWaitForLull

            Waits for a pause or a gap in the input data stream of a
            specified minimum size.
            Syntax:
               INT haWaitForLull(ScriptHandle, lPause, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lPause         The size of the pause
                 LONG lTimeout       The timeout limit
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lPause
                 The size of the pause or gap to wait for, measured in
                 milliseconds.
               lTimeout
                 How long to wait for the pause or gap, measured in
                 milliseconds.
            Remarks:
               If a pause or gap is not found within the specified timeout
               interval, an error is returned.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haWaitForActivity, haWaitForLines, haWaitForPrompt
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Wait for activity from remote system.
                        This program segment:
                           - Waits up to 100 seconds for HyperACCESS to
                         receive a character
                             from the remote system. */

                        ReturnCode = haWaitForActivity(ScriptHandle,
                         100000L);

            /* Wait for no activity from remote system.
                        This program segment:
                           - Waits up to 100 seconds for HyperACCESS to
                         stop receiving
                            characters from the remote system. It defines
                         a lull as 5 seconds
                            without activity. */

                        ReturnCode = haWaitForLull(ScriptHandle, 5000L,
                         100000L);


            /* -----------------------------------------------------------
                         --------- */


haWaitForOutputDone

            Waits for a session to finish sending any text that may be in
            the buffer and hasn't been transmitted.
            Syntax:
               INT haWaitForOutputDone(ScriptHandle, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lTimeout       How long to wait before returning
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lTimeout
                 The number of milliseconds to wait for the output to
                 finish before returning an error.
            Remarks:
               Because different types of communication devices buffer
               outgoing data differently, this function can't always
               determine when all data has actually been transmitted. It
               will return after HyperACCESS has passed all outgoing data
               from its internal buffers to the communications device.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haTextSend, haTypeText


haWaitForPrompt

            Checks characters read from the connected device to see if
            they match any of a number of specified character strings.
            Syntax:
               INT haWaitForPrompt(ScriptHandle, nCount, pszText, lPause,
               lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCount          The number of strings to follow
                 LPSTR pszText       A pointer to a string sequence
                 LONG lPause         How long a pause to require
                 LONG lTimeout       How long to wait before timeout
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCount
                 This variable determines the number of strings that are
                 to be searched for.
               pszText
                 A pointer to the first of a series of strings to search
                 for. The strings follow one another in memory and are
                 separated by a single NULL ('\0') character. The last
                 string is also terminated by an additional NULL ('\0')
                 character.
               lPause
                 This value, measured in milliseconds, is how long a pause
                 must be seen after one of the strings is seen before a
                 positive return is generated.
               lTimeout
                 This value, measured in milliseconds, is how long to wait
                 for one of the strings to arrive before returning an
                 error.
            Remarks:
               Once a match is made, the function checks for a pause or gap
               in the input stream of a specified period. If no characters
               are received during this period, the index of the string
               that was matched is returned. Otherwise, the search
               continues until the timeout value is exceeded. If the
               timeout is exceeded, an error is returned.
               When responding to prompts from a remote system, this
               function is often more reliable than haWaitForString. If,
               for example, you needed to wait for a prompt such as "Enter
               password ", a call to haWaitForString(..., "password", ...)
               could match the word "password" prematurely as it was
               displayed in a paragraph of instructions. Alternatively, if
               you use haWaitForPrompt(..., "password", 500L, ...), you
               would skip the descriptive paragraph because additional text
               would immediately follow "password"and the prompt delay
               wouldn't be satisfied.
            Return Value:
               Returns the index of the string that matched, if successful.
               Otherwise, a standard API error code.
            See Also:
               haGetInput, haWaitForString


haWaitForString

            Checks characters read from the connected device to see of
            they match any number of specified character strings.
            Syntax:
               INT haWaitForString(ScriptHandle, nCount, pszText, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nCount          The number of strings to follow
                 LPSTR pszText       A pointer to a string sequence
                 LONG lTimeout       How long to wait before timeout
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nCount
                 This variable determines the number of strings that are
                 to be searched for.
               pszText
                 A pointer to the first of a series of strings to search
                 for. The strings follow one another in memory and are
                 separated by a single NULL ('\0') character. The last
                 string is also terminated by a NULL ('\0') character.
               lTimeout
                 This value, measured in milliseconds, is how long to wait
                 for one of the strings to arrive before returning an
                 error.
            Remarks:
               Unlike haWaitForPrompt, this function doesn't require a
               pause after a string match.
            Return Value:
               Returns the index of the string that matched, if successful.
               Otherwise, a standard API error code.
            See Also:
               haGetInput, haWaitForPrompt


haWaitForXfer

            Waits for a transfer to complete.
            Syntax:
               INT haWaitForXfer(ScriptHandle, lTimeout)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LONG lTimeout       How long to wait
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               lTimeout
                 The number of milliseconds to wait for the transfer to
                 end before returning an error.
            Remarks:
               This function can be called any time after the transfer is
               started. It returns when the transfer is complete. It is
               only needed if the call that started the transfer did not
               specify the wait flag itself.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haXferDropSend, haXferReceive, haXferSend, haGetXferStatus


haWriteLogEntry

            Appends a time and date stamped entry to the log file for the
            currently active session.
            Syntax:
               INT haWriteLogEntry(ScriptHandle, pszPtr)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to a string
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to the string that is to be appended to the log
                 file.
            Remarks:
               Several events are automatically entered into the log file
               by HyperACCESS. This function lets you add your own entries.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetLogFileName, haSetLogFileName


haXferAddToSendList

            Adds a path and filename to the internal list of files queued
            for sending.
            Syntax:
               INT haXferAddToSendList(ScriptHandle, pszName)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       A pointer to a path and filename
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 A pointer to an array or string containing the null
                 terminated path and filenames.
            Remarks:
               HyperACCESS maintains an internal list of files that can be
               sent to a remote system using one of the supported file
               transfer protocols. The list is empty when a session is
               opened. You can insert any number of files into this list
               using haXferAddToSendList. When you've completed adding
               files to the list, you would normally use haXferSendFromList
               to send them to the remote system using the current transfer
               protocol. The list can be examined using haGetXferSendList
               or explicitly cleared using haClearXferSendList. The list is
               also cleared after all files are sent.
               Several other functions send files from the send list
               although they are not normally used for that purpose.
               haXferSend, haXferSendBatch, and haXferSendList are self-
               contained send functions, but they also send files from the
               list if any are present.
               No checking for duplicate files or actual existence of files
               is performed. Placing duplicate names in the list results in
               multiple copies of the file being sent. Placing invalid
               filenames or the names of non-existent files in the list
               will usually cause an error during the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haClearXferSendList, haGetXferSendList, haXferSendFromList
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Send multiple files specified by the user.
                        This program segment:
                           - Uses a message box to ask if the user has
                         file(s) to send.
                           - Loops until user finished adding.
                           - Sends list of files. */

                        ReturnCode = haMessageBox(ScriptHandle,
                         "HyperACCESS",
                                                                "Do you
                         want to send files" , 0 , 0, HA_MB_YN);
                        if (ReturnCode == 1)
                        {
                           while (ReturnCode == 1)
                           {           ReturnCode =
                         haMessageBox(ScriptHandle, "HyperACCESS",
                                                          "Enter a file to
                         send:" , sizeof(FName), FName, HA_MB_YN);
                                       if (ReturnCode == 1)
                                            ReturnCode =
                         haXferAddToSendList(ScriptHandle, FName);
                           }
                           ReturnCode = haXferSendFromList(ScriptHandle,
                         TRUE);
                        }

            /* -----------------------------------------------------------
                         --------- */


haXferDropSend

            This function sends files that have been placed on the
            internal dropped-files list using the current default
            protocol.
            Syntax:
               INT haXferDropSend(ScriptHandle, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nFlag           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nFlag
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               If the user drags files and drops them on an open
               HyperACCESS session window, HyperACCESS builds an internal
               list of dropped filenames. If the File Usage dialog contains
               the name of a program to run when files are dropped, that
               program is executed. It can either examine the list of
               dropped files using haGetXferDropList, or send them to the
               remote system using this function. The list is cleared after
               all files are sent.
               Normally, nFlag should be TRUE. This causes file transfer to
               proceed to completion before the function call returns. If
               nFlag is FALSE, however, the function starts the transfer
               and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haClearXferDropList, haGetXferDropList, haGetXferStatus,
               haWaitForXfer, haXferSend, haXferSendBatch,
               haXferSendFromList, haXferSendList


haXferReceive

            Starts to receive a file or group of files sent by the remote
            system.
            Syntax:
               INT haXferReceive(ScriptHandle, pszName, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       A pointer to a string
                 INT nFlag           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 This parameter points to the filename or directory to
                 receive into, depending on requirements of the protocol.
               nFlag
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               You should call haSetXferProtocol, haSetXferDirectory, and
               haSetXferParameters, if necessary, prior to calling
               haXferReceive.
               If the filename doesn't include a directory path, the
               default directory path is used.
               Normally, nFlag should be TRUE. This causes file transfer to
               proceed to completion before the function call returns. If
               nFlag is FALSE, however, the function starts the transfer
               and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferStatus, haSetXferDirectory, haSetXferParameters,
               haSetXferProtocol, haXferSend
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Receive a specific file.
                        This program segment:
                           - Uses the default receive protocol and
                         directory.
                           - Starts to receive a particular file assuming
                         the protocol supports
                 filename transfers. The TRUE parameter indicates that
  HyperACCESS
                 shouldn't return to the function until the transfer is
  complete. */

                        ReturnCode = haXferReceive(ScriptHandle,
                         "MYFILE.TXT", TRUE);

            /* -----------------------------------------------------------
                         --------- */


haXferSend

            Adds a single file to the internal list of files to be
            transferred and starts to send the contents of the list to the
            remote using the current default protocol.
            Syntax:
               INT haXferSend(ScriptHandle, pszName, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       A pointer to a string
                 INT nFlag           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 This parameter points to a string containing the path and
                 filename of the file that is to be sent.
               nFlag
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               If the filename doesn't include directory information, the
               default transfer directory is used.
               By default, the list of queued files is empty, resulting in
               one file being transferred. Calling this function clears the
               internal file list.
               Normally, nFlag should be TRUE. This causes file transfer to
               proceed to completion before the function call returns. If
               nFlag is FALSE, however, the function starts the transfer
               and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferStatus, haSetXferDirectory, haSetXferProtocol,
               haWaitForXfer, haXferReceive, haXferSendFromList
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Send a specifice file.
                        This program segment:
                           - Sends a particular file using an absolute
                         path.
                             Note double slash (\\). Required because
                         single slash is C escape
                             character.
                           - The FALSE parameter indicates that
                         HyperACCESS
                             should return to the function as soon as the
                         transfer starts.
                           - Minimizes the HyperACCESS application window.
                           - Allow up to 1 hour for transfer to complete.
                           - If timeout, display an error message. */

                           ReturnCode = haXferSend(ScriptHandle,
                         "C:\\MYDIR\\DOOM.ZIP", FALSE);
                           ReturnCode = haSizeHyperACCESS(ScriptHandle,
                         HA_S_MIN);
                           if (haWaitForXfer(ScriptHandle, 3600000L) ==
                         HA_ERR_TIMED_OUT)
                                       ReturnCode =
                         haMessageBox(ScriptHandle, "Transfer Error",
                         "Transfer timed out.", 0, 0, HA_MB_OK);

            /* -----------------------------------------------------------
                         --------- */


haXferSendBatch

            Adds a batch of files to the internal list of files queued to
            be transferred and sends the files on the list to the remote
            system using the default protocol.
            Syntax:
               INT haXferSendBatch(ScriptHandle, pszName, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszName       A pointer to a string
                 INT nFlag           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszName
                 A pointer to a string that contains the name of the batch
                 file. The file is an ASCII text file that contains the
                 names of the files to be transferred. The file contains
                 one file description per line.
               nFlag
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               A batch file is a list of paths and filenames in a file. By
               default the internal list of files to be sent is empty.
               Calling this function clears the internal file list.
               Normally, nFlag should be TRUE. This causes file transfer to
               proceed to completion before the function call returns. If
               nFlag is FALSE, however, the function starts the transfer
               and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferStatus, haSetXferDirectory, haSetXferParameters,
               haSetXferProtocol, haWaitForXfer, haXferSend,
               haXferSendFromList


haXferSendFromList

            Sends files that are on the internal list of files queued to
            be transferred using the current default protocol.
            Syntax:
               INT haXferSendFromList(ScriptHandle, nWait)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 INT nWait           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               nWait
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               By default, the list of queued file is empty and filenames
               must be explicitly added to the list via API calls. See the
               remarks in the description of haXferAddToSendList for
               information on how to prepare the list. The internal list of
               files is cleared after this operation.
               Normally, nFlag should be TRUE. This causes file transfer to
               proceed to completion before the function call returns. If
               nFlag is FALSE, however, the function starts the transfer
               and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haClearXferSendList, haGetXferSendList, haGetXferStatus,
               haSetXferDirectory, haSetXferParameters, haSetXferProtocol,
               haXferAddToSendList, haXferReceive, haXferSend,
               haWaitForXfer


haXferSendList

            Adds a list or array of filenames to the the internal list of
            files queued to be transferred. It sends the files in the list
            to the remote system using the current default protocol.
            Syntax:
               INT haXferSendList(ScriptHandle, pszPtr, nFlag)
                 SCRIPTHANDLE ScriptHandleThe program - HyperACCESS link
                 LPSTR pszPtr        A pointer to a string
                 INT nFlag           The wait flag
            Arguments:
               ScriptHandle
                 The script handle returned from haInitialize.
               pszPtr
                 A pointer to an array of string pointers. Each entry in
                 the array is a far pointer to a string containing a
                 filename. The last entry in the array must be 0.
               nFlag
                 If TRUE, the function waits until the transfer has
                 completed before returning. If FALSE, the function
                 returns as soon as the transfer is started.
            Remarks:
               This function provides an alternative to adding files
               individually to the internal file list and then using
               haXferSendFromList to send them. You can specify all the
               files to send and start the transfer with one call.
               By default, the internal list of files to be transferred is
               empty. If there are files already on the list, however, they
               will be sent along with the files specified in the array.
               Sending the files clears the internal file list.
               Normally, nFlag should be TRUE. This causes the file
               transfer to proceed to completion before the function call
               returns. If nFlag is FALSE, however, the function starts the
               transfer and returns immediately. Your program can then use
               haGetXferStatus and haWaitForXfer to monitor the transfer.
            Return Value:
               Returns 0 if successful. Otherwise, a standard API error
               code.
            See Also:
               haGetXferStatus, haSetXferDirectory, haSetXferParameters,
               haSetXferProtocol, haWaitForXfer, haXferSend
            Example:
            /* -----------------------------------------------------------
                         --------- */

            /* Check the first file in the list.
                        This program segment:
                           - Gets the first file in the send list (index
                         starts at 0)
                           - Uses a message box to display the filename
                         and ask if OK. */


                        ReturnCode = haGetXferSendList(ScriptHandle, 0,
                         sizeof(FName), FName);
                        ReturnCode = haMessageBox(ScriptHandle, "First
                         file to send:", FName,
                                                                0, 0,
                         HA_MB_OK);

            /* -----------------------------------------------------------
                         --------- */