home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / haotd1_1.zip / API_REF.TXT next >
Text File  |  1995-10-12  |  198KB  |  7,191 lines
  1. HyperACCESS Application Programming Interface (HAPI) Manual (disk
  2. version) Copyright 1995, Hilgraeve, Inc.
  3.  
  4.  
  5. Introduction
  6.  
  7. This disk copy of the HyperACCESS Application Programming
  8. Interface (HAPI) Manual provides information for programmers who
  9. want to take advantage of powerful customization and programming
  10. features available with HyperACCESS.  The HyperACCESS User's
  11. Manual contains information required by everyday users of
  12. HyperACCESS.  The printed copy of this manual contains additional
  13. information for both novice and advanced programmers.  It is
  14. available from Hilgraeve for $20 U.S.  Call 1-800-826-2760 to
  15. order your copy.
  16.  
  17.  
  18. About This Manual
  19.  
  20. This manual provides a common source of application programming
  21. information for HyperACCESS for OS/2 (HA/OS2), HyperACCESS for
  22. Windows 95 (HA/Win95), and HyperACCESS for Windows 3.1 (HA/Win).
  23. HAPI maintains cross-platform compatiblity among these systems so
  24. that you can create one application program that will run in any
  25. of these environments.  When a function isn't applicable to a
  26. particular environment, it is either a noop (no operation), or
  27. has a reasonable default behavior.  Differences between environ
  28. ments are noted where appropriate.  In this manual you will see
  29. how to use HyperACCESS's automation tools.  You'll find:
  30.  
  31.     - Benefits of an external API and automatic program
  32.       generation using a standard programming language.
  33.     - Program requirements.
  34.     - Programming examples using C, REXX, and other languages.
  35.     - Complete reference for HAPI.
  36.     - A brief tutorial on the C language.
  37.  
  38. This introduction continues with overview information about
  39. programming in HyperACCESS.  The printed version of this manual
  40. includes the following chapters and appendices:
  41.  
  42. Chapter 1,
  43. Creating and Editing Programs, provides a brief overview of tools
  44. available within HyperACCESS, and HyperACCESS's program
  45. requirements.
  46.  
  47. Chapter 2,
  48. Using External Languages, includes a description of external
  49. programming requirements for HyperACCESS, and how to use HAPI.
  50.  
  51. Chapter 3,
  52. Programming Examples, includes simple procedural operations using
  53. REXX, internal (HA/Win and HA/Win95) or external C language
  54. programs, and Visual Basic.  It also includes expert level
  55. examples using external languages.
  56.  
  57. Chapter 4,
  58. API Reference, provides a complete reference to HAPI. Appendix A,
  59. C Language Tutorial, provides a simple tutorial for users
  60. interested in learning C language programming as it's used
  61. in HyperACCESS.  Appendix B, Built-in C Language Interpreter,
  62. lists exclusions from standard C for programs that will use the
  63. built-in C language interpreter found in HA/Win and HA/Win95.  It
  64. also includes a complete operator precedence table.
  65.  
  66. Manual Conventions
  67.  
  68. This manual uses a mix of terminology from HA/OS2, HA/Win95, and
  69. HA/Win.  In particular, we use the terms panels and phonebook
  70. entries from HA/OS2 and HA/Win95 instead of windows and sessions
  71. from HA/Win.  There are technical differences between the multipl
  72. e document interface (MDI) windows used in HA/Win and panels use
  73. in HA/Win95 and HA/OS2.  The most important distinction is that
  74. HA/Win permits access to multiple remote systems (sessions) from
  75. within one executing occurence of the program, while HA/OS2 an d
  76. HA/Win95 can connect to only one remote system per executing
  77. occurrence of the program.
  78.  
  79. To maintain backward compatibility with HA/Win, the term session
  80. continues to appear in the context of connections to remote
  81. systems.  In HA/OS2 and HA/Win95, there is only one "session" per
  82. executing instance of the program, while a HA/Win program instanc
  83. e could have multiple concurrent session windows communicating at
  84. one time.  Whenever a function refers to a session window, the
  85. HA/OS2 and HA/Win95 analog is the Terminal panel.
  86.  
  87. Hilgraeve Customer Support
  88.  
  89. If you have a question about HyperACCESS and can't find the
  90. answer in this manual, the User's Manual, or in the HyperACCESS
  91. Help system, you can reach us by:
  92.  
  93. Hilgraeve BBS
  94.  
  95. Call the Hilgraeve BBS at (313) 243-5915 and send a message to
  96. our Customer Support staff.  For your convenience, the
  97. HyperACCESS Phonebook already contains the Hilgraeve BBS
  98. telephone number and correct settings, and Chapter 2 of the
  99. User's Manual explains what you can expect to see in Placing Your
  100. First Call on page 2-13.  We will try to respond to you on the
  101. BBS within one business day, so you can call back at your
  102. convenience to get the answer.  Asking questions on our BBS is
  103. easy and confidentia messages exchanged with our Customer
  104. Support staff are private and never seen by other callers.
  105.  
  106. CompuServe
  107.  
  108. If you prefer, you can reach Hilgraeve Customer Support through
  109. CompuServe.  Use the GO HILGRAEVE command.  You'll be sent to the
  110. PC Vendor F forum.  Then look for the Hilgraeve section.  Send us
  111. a message in the category of your choice.
  112.  
  113. Internet
  114.  
  115. To send mail to Hilgraeve Customer Support via the Internet, use
  116. the address:  custsupt@hilgraeve.com or www.hilgraeve.com
  117.  
  118. Telephone Support
  119.  
  120. If you need answers quickly, or simply prefer talking to humans,
  121. call (313) 243-0576, between 9:00 am and 6:00 pm Eastern Time.
  122. Our Customer Support staff will give you the advice you need to
  123. get the most from HyperACCESS.  Before you call, please register
  124. your copy of HyperACCESS by returning the Registration Card or by
  125. calling the Hilgraeve BBS.  We suggest that you try to duplicate
  126. the problem, and as you do so, write down each step as well as
  127. any error messages you see.  So that we can provide you with the
  128. best possible customer support, we recommend that you be at your
  129. computer when you call, and try to have the following available:
  130.  
  131.     - HyperACCESS User's Manual (this manual).
  132.     - The version and serial number on your HyperACCESS disk
  133.       label.
  134.     - The operating system version number.
  135.     - Computer information _ including type and model of
  136.       computer, monitor, and video card.  Amount and type
  137.       of installed memory are also important.
  138.  
  139. Hilgraeve Inc.
  140. Genesis Centre
  141. 111 Conant Avenue, Suite A
  142. Monroe, MI 48161
  143. PHONE: (313) 243-0576
  144. FAX:   (313) 243-0645
  145. BBS:   (313) 243-5915 (8N1 ANSI)
  146. Internet:  custsupt@hilgraeve.com
  147.            www.hilgraeve.com
  148.  
  149.  
  150.  
  151. API Programming Requirements
  152.  
  153. This section describes those rules and conventions that you must
  154. follow regardless of programming language.  Although the examples
  155. use C language constructs, you must execute similar statements in
  156. whatever language you're using.  You'll find language-dependent
  157. requirements in Chapter 2, Using an External Language.
  158.  
  159. HAPI functions are available through a Dynamic Link Library
  160. (DLL).  You can call functions in this DLL from any programming
  161. environment that can call standard DLLs.  HAPI functions use
  162. standard calling conventions, and you can link them with an
  163. import library or load them dynamically.
  164.  
  165.  
  166. Script Handles
  167.  
  168. Every external program that accesses HyperACCESS must call the
  169. function haInitialize.  This function returns a script handle.
  170. Script handles maintain the connection between HyperACCESS and
  171. the program communicating with it.
  172.  
  173. The script handle is a numeric value that's meaningful to HAPI
  174. functions, and your program must keep it available for use by
  175. HAPI functions.  All other HAPI function calls you make must pass
  176. a script handle as an argument.  A script handle is like a
  177. confirm ation number for a hotel.  The sequence of numbers you
  178. receive has no meaning in and of itself.  However, that number
  179. lets the hotel quickly and easily access your reservation.
  180.  
  181. Script handles provide a similar service for your program and its
  182. connections to HyperACCESS.  Since a program can have more than
  183. one connection, the script handle lets HyperACCESS know which
  184. connection you're referring to.
  185.  
  186. Most programs have a single connection, or script handle,
  187. associated with a single open session.  More advanced
  188. applications may require multiple connections to a session and/or
  189. connection to multiple sessions.  The discussions which follow
  190. assume the simple, single script handle case, until you get to
  191. the section Advanced Communications Programming.
  192.  
  193. To coordinate operation between sessions and external programs,
  194. haInitialize blocks sessions from receiving characters from the
  195. communications driver until one of the HAPI functions processes
  196. the incoming data.  This is required because it's impossible to
  197. write a reliable script unless it has access to all data
  198. received.
  199.  
  200. By blocking incoming data, haInitialize ensures that your program
  201. has access to every received character.  You accomplish this by
  202. calling one of the HAPI functions that looks at received data.
  203. Only a few HAPI functions actually process incoming characters.
  204. For example, haGetInput, haWaitForPrompt, and haWaitForString all
  205. process incoming data, while characters remain blocked if you
  206. call haBlockRemoteInput, haGetConnectTime, haMenuString, and most
  207. other HAPI functions.
  208.  
  209. When HyperACCESS blocks a session, the driver continues to
  210. accumulate characters in the communications buffer until they're
  211. processed by the script, or the buffer fills.  When the buffer is
  212. full, normal flow control suspends character transmission from
  213. the remote system.
  214.  
  215. In programs generated by HyperACCESS, the statement:
  216.  
  217. ScriptHandle = haInitialize(0,0,0,0); uses the variable
  218. ScriptHandle to store the connection between the external program
  219. and the session.  It also blocks the communications driver from
  220. releasing characters to the session until they're released by
  221. other function calls.  All subsequent calls in the generated
  222. program use this variable as an argument.  For example, the
  223. following statement would send a carriage return character to the
  224. session's remote system:  haTypeText(ScriptHandle, 0, "\r");
  225. Note:  \r represents the carriage return character in C.
  226.  
  227. The following function would search for the character string
  228. "ssword:", and release all characters to the session until that
  229. string is found:
  230.  
  231. haWaitForPrompt(ScriptHandle, 1, "ssword:",300L, 100000L);
  232.  
  233. In addition, it sets two timeout values:  300 msec.is the pause
  234. that must be seen after the string is identified, and 100 seconds
  235. is the timeout value used to indicate that the operation has
  236. failed if the string still hasn't been seen.  Note:  The L in
  237. 300L and 100000L indicates a long integer in C.
  238.  
  239.  
  240.  
  241. Disconnecting an External Program from a Session
  242.  
  243. You must always call the HAPI function haTerminate when your
  244. external program has completed its operations.  haTerminate lets
  245. HAPI free any resources it may have allocated.  It's also
  246. required to release characters that your program didn't process
  247. from the communications buffer.  The function call looks like:
  248. haTerminate(ScriptHandle, 0);
  249.  
  250. Caution:  If you forget to call this function at the end of your
  251. program, the session remains blocked and characters from the
  252. remote system aren't processed.
  253.  
  254.  
  255.  
  256. Standard Values and Return Codes
  257.  
  258. All HAPI examples, supplied programs, and documentation use names
  259. for parameter values and return codes.  Your compiler or the
  260. HyperACCESS interpreter translates these names into numeric
  261. values or other C language definitions.  Using the C interpreter
  262. included with HA/Win or HA/Win95, you must include a special
  263. file called defines.h that is supplied on your distribution
  264. diskettes.  The required C language statement is:  #include
  265. <defines.h>
  266.  
  267. HyperACCESS also provides the file ha_auto.h for use with
  268. external C language development systems.  This file is a superset
  269. of information contained in defines.h, and includes prototypes of
  270. all HAPI functions with declarations for all parameters.  If you
  271. us e defines.h with a C compiler, your program will function
  272. properly, but you may get compiler warning messages that you can
  273. ignore.
  274.  
  275. Using defines.h or ha_auto.h, you can use names instead of
  276. numbers as parameters to HAPI function calls.  For example, if
  277. you want to set the send transfer protocol to HyperProtocol from
  278. your program, you could write:
  279. ReturnCode = haSetXferProtocol(ScriptHandle,HA_XFER_SEND,
  280. HA_HYPERP);
  281.  
  282. Alternatively, since the value of both HA_XFER_SEND and HA_HYPERP
  283. is 1 (you can find these values in ha_auto.h or defines.h.), you
  284. could type:  ReturnCode = haSetXferProtocol(ScriptHandle, 1, 1);
  285.  
  286. The reason these two examples are the same is because of the
  287. following two lines in defines.h and ha_auto.h:  #define
  288. HA_XFER_SEND 1 #define HA_HYPERP 1
  289.  
  290. Programmers use this technique to make their programs more
  291. readable.
  292.  
  293.  
  294. Programming in OS/2
  295.  
  296. Since the standard script language in OS/2 is REXX, HyperACCESS
  297. generates recorded programs in this language.  REXX doesn't have
  298. a capability similar to the C language define construct.
  299. Therefore, if you want to use names for parameter and return code
  300. values you will have to include assignment statements in your
  301. program.  The OS/2 readme.api file includes assignment statements
  302. that you can cut and paste into your programs.
  303.  
  304. #include <os2.h>
  305. #include <stdio.h>
  306. #include "c:\haos2\ha_auto.h"
  307.  
  308. Programming in Windows
  309.  
  310. Other values used as part of standard Windows DLL calling
  311. conventions appear in the file windows.h included with Windows
  312. development software.  If you're using an external C language
  313. development system, it must generate windows compatible
  314. executables, and therefore, this file or its equivalent is
  315. available.  You should include the following statements in a C
  316. language program that you intend to compile:
  317.  
  318. #include <windows.h>
  319. #include <ha_auto.h>
  320.  
  321. Files containing similar information for other languages are
  322. identified in the readme.api file on the distribution diskettes.
  323. If there is no "include" file for the language you're using, you
  324. should be able to construct one of your own by editing one of
  325. the supplied files.  If the language has documentation on how to
  326. make calls to the Windows API, the information will apply to
  327. HAPI.  For assistance, contact Hilgraeve Customer Support.
  328.  
  329.  
  330. Error Code Values
  331.  
  332. Most HAPI functions return an integer value and are declared int
  333. or long.  Functions that return a session or window handle (i.e.,
  334. they are declared HSESS, HWND, or SCRIPTHANDLE) return a value of
  335. zero when they fail.  Integer functions return a value greater
  336. than or equal to zero if they're successful, and a value less
  337. than zero (HA_ERR_OK) and greater than or equal to HA_ERR_MAX_ERR
  338. if an error has occurred.
  339.  
  340. Most integer functions return some standard error codes.
  341. HA_ERR_BUSY, for example, indicates that you attempted to call a
  342. function while another function call was active.  Other error
  343. codes provide information that's appropriate to only a few
  344. functions.  For example, functions that have a timeout value as
  345. one of their arguments may return HA_ERR_TIMED_OUT.
  346.  
  347. Whenever you call a HAPI function, you should check the return
  348. code and perform appropriate error correction procedures.  In
  349. many cases, you'll simply report the error via haMessageBox (or
  350. some similar API call available through your development
  351. environment), call haTerminate, and then exit.
  352.  
  353. For example, if your program calls haWaitForPrompt, you should
  354. check for the possiblity that a timeout occurred before the
  355. string was detected.  Your program code could look like:
  356.  
  357. ReturnCode = haWaitForPrompt(ScriptHandle, 1, "r name:  ", 300L
  358. 100000L);
  359. if (ReturnCode == HA_ERR_TIMEOUT)
  360.     {
  361.     haTerminate(ScriptHandle, 0)
  362.     exit();
  363.     }
  364. . . .
  365.  
  366. In this example, haWaitForPrompt will wait until it finds the
  367. string "r name:  " followed by a 300 millisecond pause.  If it
  368. doesn't find that string with the following pause within 100
  369. seconds (100000 milliseconds), it returns the error code
  370. HA_ERR_TIMEOUT
  371. .
  372.  
  373. This error code is defined to be the value -6 in defines.h and
  374. ha_auto.h.  Therefore the program segement shown above could have
  375. been written as:
  376.  
  377. ReturnCode = haWaitForPrompt(ScriptHandle, 1, "r name:  ", 300L
  378. 10000L);
  379. if (ReturnCode == -6)
  380.     {
  381.     haTerminate(ScriptHandle, 0)
  382.     exit();
  383.     }
  384.  
  385. The following is a list of errors that HAPI may return.
  386.  
  387. Return Code Name      Value      Description
  388. HA_ERR_BAD_CMD          -1       An API message was received
  389.                                  with a command that could not be
  390.                                  recognized.
  391.  
  392. HA_ERR_BAD_PARAM        -2       A parameter was out of range
  393.                                  or an unrecognized value.
  394.  
  395. HA_ERR_BAD_HANDLE       -3       The script handle was invalid.
  396.  
  397. HA_ERR_BUFFER_TOO_      -9       A function was passed SMALL a
  398.                                  pointer to a buffer with a
  399.                                  buffer size parameter that was
  400.                                  too small to hold the data to be
  401.                                  returned.
  402.  
  403. HA_ERR_BUSY             -7       An attempt was made to call a
  404.                                  function while another function
  405.                                  call was active.
  406.  
  407. HA_ERR_COMMAND_FAI     -12       An error occurred LED that
  408.                                  caused the API function to fail.
  409.                                  For example, an attempt was made
  410.                                  to overwrite a read-only file.
  411.  
  412. HA_ERR_CONNECTION_      -8       A function waiting LOST for some
  413.                                  on-line event to occur (like
  414.                                  haWaitForPrompt) failed because
  415.                                  the connection was lost while
  416.                                  waiting.
  417.  
  418. HA_ERR_DDE_TIMED_O     -10       An internal timeout UT occurred
  419.                                  in the code that communicates
  420.                                  between the external process and
  421.                                  HA/Win.
  422. HA_ERR_MAX_ERR         -12       The most negative number used
  423.                                  for an error code.
  424.  
  425. HA_ERR_NO_MEMORY        -4       A function could not allocate
  426.                                  memory to use to perform the
  427.                                  specified task.
  428.  
  429. HA_ERR_NO_SESSION       -5       A function could not complete
  430.                                  the requested task because there
  431.                                  was no session handle currently
  432.                                  associated with the script
  433.                                  handle.
  434. HA_ERR_NOT_SUPPORT     -11       This function call or ED option
  435.                                  requested isn't supported in
  436.                                  this version of HyperACCESS.
  437.  
  438. HA_ERR_OK                0       The function executed without
  439.                                  error.
  440.  
  441. HA_ERR_TIMED_OUT        -6       A function waiting for some set
  442.                                  of conditions to be met exceeded
  443.                                  its timeout duration.
  444.  
  445.  
  446. API Reference
  447.  
  448.  
  449. Function Reference
  450.  
  451.  
  452. Functions by group
  453.  
  454. The following is a list of HyperACCESS Application Programming
  455. Interface functions organized by category.  These divisions are
  456. somewhat arbitrary.
  457.  
  458.  
  459. General Functions
  460.  
  461. These functions perform general housekeeping tasks for an
  462. external API task.  They have very little to do with actual
  463. communications, but are needed to run HyperACCESS.
  464.  
  465. - haGetNameString
  466. - haGetPhonebookEntry
  467. - haGetSelectedPhonebookEntry
  468. - haGetSerNumString
  469. - haInitialize
  470. - haReloadPhonebook
  471. - haRestrictMenus
  472. - haSavePhonebook
  473. - haSetNameString
  474. - haSetSerNumString
  475. - haPause
  476. - haSleep
  477. - haTerminate
  478.  
  479. Operating System Related Functions
  480.  
  481. These functions let you write an external API task that takes
  482. advantage of some of the features of the operating system without
  483. writing this code yourself.  The external API task can remain
  484. procedural in nature and still be perceived as a non-procedural
  485. GUI program.
  486.  
  487. - haGetDisplay
  488. - haGetHWND
  489. - haGetWindowStateBits
  490. - haMenuString
  491. - haMessageBox
  492. - haSetDisplay
  493. - haSetMessageTimer
  494. - haSizeHyperACCESS
  495. - haSizePhonebook
  496. - haSizeSession
  497. - haSpawn
  498.  
  499. External File Functions
  500.  
  501. These functions record data in files.  This does not include data
  502. received during a file transfer.
  503.  
  504. - haCaptureBegin
  505. - haCaptureControl
  506. - haGetCaptureFileName
  507. - haGetLearnFileName
  508. - haGetLogFileName
  509. - haSetCaptureFileName
  510. - haSetLearnFileName
  511. - haSetLogfileName
  512. - haSetLogonTask
  513. - haWriteLogEntry
  514.  
  515. Drag and Drop Functions
  516.  
  517. These functions are only valid in HyperACCESS for Windows.  They
  518. let an external API task respond to Drag and Drop operations on
  519. the HyperACCESS session window.  HyperACCESS calls an external
  520. API task when a file or group of files is dropped on an open
  521. session.
  522.  
  523. - haClearXferDropList
  524. - haClearXferSendList
  525. - haGetXferDropList
  526. - haXferDropSend
  527.  
  528. Session-based Functions
  529.  
  530. The term session is used for backward compatibility with
  531. HyperACCESS for Windows (HA/Win).  In HA/Win a session is the
  532. main focus for communications, and one instance of HA/Win can
  533. have multiple sessions.  These functions manipulate a session
  534. handle, and let an external API identify a HyperACCESS session.
  535. In HyperACCESS for OS/2 (HA/OS2) and HyperACCESS for Windows 95
  536. (HA/Win95), there is only one sesson per instance of HyperACCESS.
  537.  
  538. - haBlockRemoteInput
  539. - haCloseSession
  540. - haConnectAndDial
  541. - haConnectSession
  542. - haCreateNewSession
  543. - haDisconnectSession
  544. - haGetConnectionStatus
  545. - haGetConnectTime
  546. - haGetOpenSession
  547. - haGetSession
  548. - haGetSessionName
  549. - haGetSessionDataString
  550. - haNotifyOnTerminate
  551. - haOpenSession
  552. - haReleaseRemoteInput
  553. - haSetSession
  554. - haSetSessionDataString
  555. - haSkipConnection
  556. - haWaitForConnection
  557.  
  558. Device Specific Functions
  559.  
  560. These functions deal mostly with external devices used for
  561. communications.
  562.  
  563. - haGetAsciiSettings
  564. - haGetBaudRate
  565. - haGetComDriverSpecial
  566. - haGetDialingPrefix
  567. - haGetEmulator
  568. - haGetPortMode
  569. - haGetPortName
  570. - haGetPortPrefs
  571. - haGetPortType
  572. - haGetRingsForAnswer
  573. - haSelectDialingPrefix
  574. - haSetAsciiSettings
  575. - haSetBaudRate
  576. - haSetDialingPrefix
  577. - haSetEmulator
  578. - haSetPortMode
  579. - haSetPortName
  580. - haSetPortPrefs
  581. - haSetPortType
  582. - haSetPulseTone
  583. - haSetRingsForAnswer
  584.  
  585. Transfer Functions
  586.  
  587. These external API functions relate to transfering files.
  588.  
  589. - haGetXferDirectory
  590. - haGetXferParameters
  591. - haGetXferProtocol
  592. - haGetXferStatus
  593. - haSetXferDirectory
  594. - haSetXferParameters
  595. - haSetXferProtocol
  596. - haTextSend
  597. - haWaitForXfer
  598. - haXferAddToSendList
  599. - haXferReceive
  600. - haXferSend
  601. - haXferSendBatch
  602. - haXferSendFromList
  603. - haXferSendList
  604.  
  605. Text I/O Functions
  606.  
  607. These functions let an external API task communicate with the
  608. local user or remote system.
  609.  
  610. - haClearOutputBuffer
  611. - haGetInput
  612. - haGetRuntimeValue
  613. - haGetSelectedText
  614. - haGetTextFromScreen
  615. - haGetVersion
  616. - haHideInput
  617. - haSetEcho
  618. - haSetLocalDisplay
  619. - haSetLocalEcho
  620. - haSetStripTo7Bits
  621. - haTypeLocalText
  622. - haTypeText
  623. - haWaitForActivity
  624. - haWaitForLines
  625. - haWaitForLull
  626. - haWaitForOutputDone
  627. - haWaitForPrompt
  628. - haWaitForString
  629.  
  630. Function Reference Format
  631.  
  632. The following pages list the HyperACCESS Application Programming
  633. Interface functions in alphabetical order.  The discussion of
  634. each function is divided into the following sections:
  635.  
  636.  
  637. - Description.  A summary of the routine's effect immediately
  638.   following the function name.  (There is no sub-head for the
  639.   description.)
  640.  
  641. - Syntax.  Illustrates the syntax with definition of the function
  642.   type and arguments.  A summary list of arguments with their type
  643.   immediately follows the syntax prototype.
  644.  
  645. - Arguments.  A more complete description of the arguments and
  646.   valid values.
  647.  
  648. - Remarks.  A more detailed description of the routine and how it
  649.   is used.
  650.  
  651. - Return Value.  Describes values returned by the
  652.   routine.
  653.  
  654. - See Also.  Names related routines.
  655.  
  656. - Example.  A short example in C that illustrates function use in
  657.   context.
  658.  
  659. Summary of Data Types
  660.  
  661. HAPI uses the following data types:
  662.  
  663. int          A two-byte signed integer.
  664. long         A four-byte signed integer.
  665. int far *    A four-byte memory address (selector and offset) of
  666.              an integer.
  667. void far     A four-byte memory address that can point to
  668.              any type of data.
  669. LPVOID       Same as void far *. LPSTR A four-byte memory address
  670.              of a zero-terminated, variable length text string.
  671. HANDLE       A two-byte numeric value used by the operating
  672.              system API.
  673. HSESS        A four-byte value used as a session handle.  This
  674.              variable type appears in the ha_auto.h file.
  675. HWND         A four-byte value used as a pointer to a window.
  676.              This variable type appears in the windows.h file.
  677. PSZ          A pointer to a null-terminated string.
  678. PVOID        Same as LPVOID in OS/2.  In Windows, which you use
  679.              depends on the memory model of your program.
  680. SCRIPTHANDLE A four-byte value used to make the connection
  681.              between your program and HyperACCESS.  Using the
  682.              scripthandle, you can control one or more
  683.              sessions.  This variable type appears in the
  684.              ha_auto.h file. ULONG Unsigned long integer.
  685.  
  686.  
  687.  
  688. Examples
  689.  
  690. The examples that appear with function references are in C.
  691. Modifying these examples for REXX or other programming languages
  692. is straightforward.  The examples assume following C language
  693. variable definitions:
  694.  
  695. long SESS;
  696. long bRate;
  697. long ScriptHandle = 0;
  698. long haTime;
  699. int ReturnCode;
  700. int SubReturnCode; char
  701. LogName[128];
  702. char Emulator[128];
  703. char RuntimeValue[128];
  704. char PNumber[128];
  705. char PType[128];
  706. char DName[128];
  707. char PortName[128];
  708. char DataBits[1];
  709. char StopBits[1];
  710. char Buffer[128];
  711. char Parity[128];
  712. char BPS[128];
  713. char FName[128];
  714. char Vers[128];
  715. char UName[128];
  716. char UID[128];
  717. char PWord[128];
  718.  
  719.  
  720. haBlockRemoteInput
  721.  
  722. Increments the counter used to determine how and when a session
  723. processes characters received from the remote system.
  724.  
  725. Syntax:
  726.  
  727.     INT haBlockRemoteInput(ScriptHandle)
  728.  
  729.     SCRIPTHANDLE ScriptHandle The program - HyperACCESS link
  730.  
  731. Arguments:
  732.  
  733.    ScriptHandle
  734.  
  735.    The script handle returned from haInitialize.
  736.  
  737. Remarks:
  738.  
  739.     When the counter is greater than zero, a session does not
  740.     process received characters.  When the counter is zero, a
  741.     session processes characters.  When a session is opened, the
  742.     counter is set to zero.  If a program is run from within a
  743.     session, the counter is incremented automatically when the
  744.     program calls haInitialize.  If the program exits from within
  745.     a session, the counter is decremented automatically when the
  746.     program calls haTerminate.  This function would normally be
  747.     called only if you switch control to a new session using
  748.     haOpenSession or haSetSession.
  749.  
  750. Return Value:
  751.  
  752.     Returns 0 if successful.  Otherwise, a standard API error
  753.     code.
  754.  
  755. See Also:
  756.  
  757.     haReleaseRemoteInput
  758.  
  759.  
  760. haCaptureBegin
  761.  
  762. Turns the Capture to File function on for the currently active
  763. session.
  764.  
  765. Syntax:
  766.  
  767.     INT haCaptureBegin(ScriptHandle, nMode, nAppend)
  768.  
  769. SCRIPTHANDLE
  770.  
  771.     ScriptHandle The program - HyperACCESS link
  772.  
  773. INT nMode Determines how data is captured
  774. INT nAppend Determines what happens if capture file already exists
  775.  
  776. Arguments:
  777.  
  778. ScriptHandle
  779.  
  780.     The script handle returned from haInitialize.
  781.  
  782. nMode
  783.  
  784.     This is a constant value that determines when capturing takes
  785.     place and which data is captured.
  786.  
  787. Value                 Meaning
  788.  
  789. HA_C_LINES            Capture each line from the terminal
  790.                       display as the cursor moves off the line.
  791.  
  792. HA_C_CHAR             Capture each displayable character as it
  793.                       is displayed.
  794.  
  795. HA_C_RAW              Capture all characters (printable and
  796.                       control codes) as they are received.
  797.  
  798. HA_C_SCREEN           Capture lines as they scroll off the screen
  799.                       and all lines on a screen when the screen is
  800.                       cleared.  Captures exactly the same data as
  801.                       appears in the backscroll buffer.
  802.  
  803. nAppend
  804.  
  805.     This argument determines what happens if the file used for
  806.     capturing already exists.  (See Remarks for valid values for
  807.     HA/Win.)
  808.  
  809. Value                 Meaning
  810.  
  811. HA_C_OVERWRITE        Overwrites the existing file.
  812.  
  813. HA_C_APPEND           Appends new captured data to end of file.
  814.  
  815. HA_C_REN_SEQ          Creates a new file by adding a sequential
  816.                       number to the filename.  If the name is
  817.                       already at its maximum length (254 or 8), the
  818.                       sequence number replaces characters at the
  819.                       end of the name.
  820.  
  821. HA_C_REN_DAT          HyperACCESS creates filenames by appending
  822.                       the date/sequence to the original name.  If
  823.                       appending the date/sequence creates a
  824.                       filename that is too long, HyperACCESS
  825.                       deletes the required number of characters
  826.                       from the end of the original name to fit the
  827.                       date/sequence.
  828. Remarks:
  829.  
  830.     This function behaves as if the user selected File/Capture to
  831.     File and completed the dialog.  In HyperACESS for Windows,
  832.     nAppend is either TRUE (non-zero, usually 1) or FALSE (zero).
  833.     If TRUE any new captured data is appended to the existing file.
  834.     Otherwise, the previous file is overwritten.
  835.  
  836. Return Value:
  837.  
  838.     Returns 0 if successful.  Otherwise, a standard API error code.
  839.  
  840. See Also:
  841.  
  842.     haCaptureControl, haGetCaptureName, haSetCaptureName
  843.  
  844. Example:
  845.  
  846. /* -------------------------------------------------------------- */
  847.  
  848. /* Capture data to disk.
  849.    This program segment:
  850.   - Waits for prompt string ("Press Enter to begin...").
  851.   - Begins capturing all incoming data -- one line at a time as
  852.     the carriage return character is received.
  853.   - Appends incoming data to the end of the default capture file
  854.     if the file already exists.
  855.   - Stops capturing data when an end string appears ("End of
  856.     Data").  */
  857.  
  858. ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Press Enter to
  859.                begin...", 300L, 60000L);
  860. ReturnCode = haCaptureBegin(ScriptHandle, HA_C_LINES, TRUE);
  861. ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data",
  862.                100000L);
  863. ReturnCode = haCaptureControl(ScriptHandle, HA_C_END);
  864.  
  865. /* -------------------------------------------------------------- */
  866.  
  867.  
  868. haCaptureControl
  869.  
  870.     Changes the way capturing operates after it has been started by
  871.     haCaptureBegin.
  872.  
  873.  Syntax:
  874.  
  875.     INT haCaptureControl(ScriptHandle, nFunction)
  876.  
  877. SCRIPTHANDLE
  878.  
  879.    ScriptHandle                    The program - HyperACCESS link
  880.  
  881.    INT nFunction                   The function code
  882.  
  883. Arguments:
  884.  
  885.    ScriptHandle 
  886.  
  887.       The script handle returned from haInitialize.
  888.  
  889.    nFunction 
  890.  
  891.       The function code determines what change is to be
  892.       made
  893.  
  894. Value                 Meaning
  895.  
  896. HA_C_END              Terminate capturing and close the capture
  897.                       file.
  898.  
  899. HA_C_PAUSE            Stop capturing temporarily.  HA_C_RESUME Start
  900.                       capturing after a pause.  Remarks:  This
  901.                       function provides the same options available
  902.                       to the user from the File/Capture to File
  903.                       cascade menu after capture has been started.
  904.  
  905. Return Value:
  906.  
  907.     Returns 0 if successful.  Otherwise, a standard API error code.
  908.  
  909. See Also:
  910.  
  911.     haCaptureBegin
  912.  
  913. haCaptureToPrinterBegin
  914.  
  915.     Turns the Capture to Printer function on for the currently
  916.     active session.
  917.  
  918. Syntax:
  919.  
  920.     INT haCaptureToPrinterBegin(ScriptHandle, nMode, nMethod)
  921.  
  922. SCRIPTHANDLE
  923.  
  924.     ScriptHandleThe program - HyperACCESS link
  925.  
  926. INT nMode Determines how data is captured
  927.  
  928. INT nMethod Determines when to release printed information from the
  929. print spooler
  930.  
  931. Arguments:
  932.  
  933.     ScriptHandle The script handle returned from haInitialize.
  934.  
  935. nMode
  936.  
  937.     This is a constant value that determines when printing
  938.     takes place and which data is printed.
  939.  
  940. Value                 Meaning
  941.  
  942. HA_CP_LINES           Print each line from the terminal display as
  943.                       the cursor moves off the line.
  944.  
  945. HA_CP_CHAR            Print each displayable character as it is
  946.                       displayed.
  947. HA_CP_SCREEN          Printlines as they scroll off the screen and
  948.                       all lines on a screen when the screen is
  949.                       cleared.  Prints exactly the same data as
  950.                       appears in the backscroll buffer.
  951.  
  952. nMethod
  953.  
  954.     This is a constant value that determines when data will be
  955.     released from the spooler to the printer.
  956.  
  957. Value                 Meaning
  958.  
  959. HA_CP_PAGE            As each page is filled, it is released to the
  960.                       printer.
  961.  
  962. HA_CP_SESSION         Printed data is accumulated in the spooler
  963.                       until the session is closed or Capture to
  964.                       Printer is turned off.
  965.  
  966. Remarks:
  967.  
  968.     This function behaves as if the user selected File/Capture to
  969.     Printer and completed the dialog.
  970.  
  971. Return Value:
  972.  
  973.     Returns 0 if successful.  Otherwise, a standard API error code.
  974.  
  975. See Also:
  976.  
  977.     haCaptureToPrinterControl
  978.  
  979. Example:
  980.  
  981. /* -------------------------------------------------------------- */
  982.  
  983. /* Capturing data to printer 
  984.    This program segment:
  985.    - Waits for prompt string ("Turn printer on and press Enter to
  986.      begin...") from the remote system.
  987.    - Begins capturing all incoming data -- one line at a time as
  988.      the cursor moves off the line.
  989.    - Releases each page to the printer as it fills.
  990.    - Stops capturing data when an end string appears ("End of
  991.      Data").  */
  992.  
  993. ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Turn printer on
  994.                and press Enter to begin...", 300L, 60000L);
  995. ReturnCode = haCaptureToPrinterBegin(ScriptHandle, HA_CP_LINES,
  996.                HA_CP_PAGE);
  997. ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data",
  998.                100000L);
  999. ReturnCode = haCaptureToPrinterControl(ScriptHandle, HA_CP_END);
  1000.  
  1001. /* -------------------------------------------------------------- */
  1002.  
  1003.  
  1004. haCaptureToPrinterControl
  1005.  
  1006. Changes the way capturing to printer operates after it has been
  1007. started by the haCaptureToPrinterBegin.
  1008.  
  1009. Syntax:
  1010.  
  1011.     INT haCaptureToPrinterControl(ScriptHandle, nFunction)
  1012.  
  1013. SCRIPTHANDLE
  1014.  
  1015.     ScriptHandleThe program - HyperACCESS link
  1016.  
  1017. INT nFunction
  1018.  
  1019.     The function code
  1020.  
  1021. Arguments:
  1022.  
  1023.     ScriptHandle The script handle returned from haInitialize.
  1024.  
  1025. nFunction
  1026.  
  1027.     The function code determines what change is to be made.
  1028.  
  1029. Value                 Meaning
  1030.  
  1031. HA_CP_END             Terminate printing and release data from the
  1032.                       spooler.
  1033.  
  1034. HA_CP_PAUSE           Stop printing temporarily.
  1035.  
  1036. HA_CP_RESUME          Start printing after a pause.
  1037.  
  1038. Remarks:
  1039.  
  1040.     This function provides the same options available to the user
  1041.     from the File/Capture to Printer cascade menu after printing has
  1042.     been started.
  1043.  
  1044. Return Value:
  1045.  
  1046.     Returns 0 if successful.  Otherwise, a standard API error code.
  1047.  
  1048. See Also:
  1049.  
  1050.     haCaptureToPrinterBegin
  1051.  
  1052.  
  1053. haClearOutputBuffer
  1054.  
  1055. Clears the HyperACCESS output buffer of characters waiting to be
  1056. sent.
  1057.  
  1058. Syntax:
  1059.  
  1060.     INT haClearOutputBuffer(ScriptHandle)
  1061.  
  1062.  
  1063. SCRIPTHANDLE
  1064.  
  1065.     ScriptHandle The program - HyperACCESS link
  1066.  
  1067.  
  1068. Arguments:
  1069.  
  1070.     ScriptHandle The script handle returned from haInitialize.
  1071.  
  1072. Remarks:
  1073.  
  1074.     You call this function when your program has already sent text
  1075.     data out the connected communications device and you want to
  1076.     cancel whatever portion of the data remains in the internal
  1077.     buffers.  Depending on the type of communications device being
  1078.     used, there may be situations when HyperACCESS is unable to
  1079.     clear portions of the buffer.
  1080.  
  1081. Return Value:
  1082.  
  1083.     Returns 0 if successful.  Otherwise, a standard API error code.
  1084.  
  1085. See Also:
  1086.  
  1087.     haTypeText, haWaitForOutputDone
  1088.  
  1089.  
  1090. haClearXferDropList
  1091.  
  1092. Clears the internal list that keeps track of files that have been
  1093. dropped on an open session.
  1094.  
  1095. Syntax:
  1096.  
  1097.     INT haClearXferDropList(ScriptHandle)
  1098.  
  1099. SCRIPTHANDLE
  1100.  
  1101.     ScriptHandle The program - HyperACCESS link
  1102.  
  1103. Arguments:
  1104.  
  1105.     ScriptHandle The script handle returned from haInitialize.
  1106.  
  1107. Remarks:
  1108.  
  1109.     This function lets you remove all files from the drop list.  It
  1110.     may be desirable to do this when an error occurs during transfer
  1111.     of a dropped file, and you want the user to take corrective
  1112.     action.
  1113.  
  1114. Return Value:
  1115.  
  1116.     Returns 0 if successful.  Otherwise, a standard API error code.
  1117.  
  1118. See Also:
  1119.  
  1120.     haGetXferDropList, haXferDropSend
  1121.  
  1122.  
  1123. haClearXferSendList
  1124.  
  1125. Clears the internal list that keeps track of files that have been
  1126. queued up to be sent to the remote system.
  1127.  
  1128. Syntax:
  1129.  
  1130.     INT haClearXferSendList(ScriptHandle)
  1131.  
  1132. SCRIPTHANDLE
  1133.  
  1134.     ScriptHandle The program - HyperACCESS link
  1135.  
  1136. Arguments:
  1137.  
  1138.     ScriptHandle The script handle returned from haInitialize.
  1139.  
  1140. Remarks:
  1141.  
  1142.     This function lets you remove all files from the send list.
  1143.     Under normal circumstances, the list clears automatically after
  1144.     files are sent by haXferSendFromList.  You may find it desirable
  1145.     to call this function when an error occurs during transfer, and
  1146.     you want the user to take corrective action.
  1147.  
  1148. Return Value:
  1149.  
  1150.     Returns 0 if successful.  Otherwise, a standard API error code.
  1151.  
  1152. See Also:
  1153.  
  1154.   haGetXferSendList, haXferAddToSendList, haXferSendFromList
  1155.  
  1156.  
  1157. haCloseSession
  1158.  
  1159. In HA/Win, closes the current session.
  1160.  
  1161. Syntax:
  1162.  
  1163.     INT haCloseSession(ScriptHandle)
  1164.  
  1165. SCRIPTHANDLE
  1166.  
  1167.     ScriptHandle The program - HyperACCESS link.
  1168.  
  1169. Arguments:
  1170.  
  1171.     ScriptHandle The script handle returned from haInitialize.
  1172.  
  1173. Remarks:
  1174.  
  1175.     This function closes the session associated with the script
  1176.     handle.  If the session is connected, it is disconnected before
  1177.     the session is closed.  If there is no session associated with
  1178.     the script handle, an error is returned.  In HA/OS2 and
  1179.     HA/Win95, this function disconnects, if connected, and saves any
  1180.     changes made to the phonebook entry settings.
  1181.  
  1182. Return Value:
  1183.  
  1184.     Returns 0 if successful.  Otherwise, a standard API error code.
  1185.  
  1186. See Also:
  1187.  
  1188.     haOpenFunction
  1189.  
  1190. Example:
  1191.  
  1192. /* -------------------------------------------------------------- */
  1193.  
  1194. /* Close an open session.  */
  1195.  
  1196. ReturnCode = haCloseSession(ScriptHandle);
  1197.  
  1198. /* -------------------------------------------------------------- */
  1199.  
  1200.  
  1201. haComDriverSpecial
  1202.  
  1203. Passes a device specific command string to the comm driver.
  1204.  
  1205. Syntax:
  1206.  
  1207.       haComDriverSpecial (ScriptHandle, LPSTR pszCmd)
  1208.  
  1209. SCRIPTHANDLE
  1210.  
  1211.     ScriptHandle The program - HA\Win link.
  1212.  
  1213. LPSTR pszCmd
  1214.  
  1215.     The command string.
  1216.  
  1217. Arguments:
  1218.  
  1219.     ScriptHandle The script handle returned from haInitialize.
  1220.  
  1221.     pszCmD The command string that you want to pass to comm driver.
  1222.     Depends on device.
  1223.  
  1224. Remarks:
  1225.  
  1226. Return Value:
  1227.  
  1228.     Returns 0 if successful.  Otherwise, a standard API error code.
  1229.  
  1230.  
  1231. haConnectAndDial
  1232.  
  1233. Starts the connection process and dials the supplied phone number
  1234. rather than the phone number that is stored in the session
  1235. settings file.
  1236.  
  1237. Syntax:
  1238.  
  1239.     INT haConnectAndDial(ScriptHandle, nMode, pszNumber)
  1240.  
  1241. SCRIPTHANDLE
  1242.  
  1243.     ScriptHandleThe program - HyperACCESS link.
  1244.  
  1245. INT nMode
  1246.  
  1247.     Determines how the session is to be connected.
  1248. LPSTR pszNumber
  1249.  
  1250.     The number to dial
  1251.  
  1252. Arguments:
  1253.  
  1254.     ScriptHandle The script handle returned from haInitialize.
  1255.  
  1256.     nMode Determines what type of connection is to be initiated.
  1257.  
  1258. Value                 Meaning
  1259.  
  1260. HA_CNCT_STANDARD      Do a normal connection sequence.
  1261.  
  1262. HA_CNCT_LEARN_LOGIN   Start learning a new login script after
  1263.                       connection.
  1264.  
  1265. HA_CNCT_DO_NOT_LOGIN  Make the connection but do not run any login
  1266.                       script or task associated with this session.
  1267.  
  1268. pszNumber
  1269.  
  1270.      A pointer to a null terminated string containing the telephone
  1271.      number to be dialed.
  1272.  
  1273. Remarks:
  1274.  
  1275.     This function is similar to the haConnectSession function except
  1276.     that it takes an additional parameter for an alternate phone
  1277.     number to be used in dialing.  This phone number is dialed
  1278.     instead of the number stored in the session Communications
  1279.     dialog box.
  1280.  
  1281. Return Value:
  1282.  
  1283.     Returns 0 if successful.  Otherwise, a standard API error code.
  1284.  
  1285. See Also:
  1286.  
  1287.     haDisconnectSession, haGetConnectionStatus, haOpenSession,
  1288.     haSetSession, haWaitForConnection
  1289.  
  1290. Example:
  1291.  
  1292. /* -------------------------------------------------------------- */
  1293.  
  1294. /* Dial a remote system from within a script.  This program
  1295. segment:  - Displays a message box to ask if user wants to change
  1296. the phone number.  - If yes, it displays another message box to
  1297. get the new phone number.  - Connects and dials using the new
  1298. phone number or uses a standard session connect if the user
  1299. doesn't want to change the phone number.  */
  1300.  
  1301. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Change
  1302. Phone Number?", 0, 0, HA_MB_YN);
  1303. if (ReturnCode == 1) {
  1304.     SubReturnCode = haMessageBox(ScriptHandle, "HAOS2 Query:",
  1305.     "Enter Phone Number:", strlen(PNumber), PNumber, HA_MB_OK);
  1306.     SubReturnCode = haConnectAndDial(ScriptHandle, HA_CNCT_STANDARD,
  1307.     PNumber); }
  1308. else if (ReturnCode == 0)
  1309.     SubReturnCode = haConnectSession(ScriptHandle,
  1310.     HA_CNCT_STANDARD);
  1311.  
  1312. /* -------------------------------------------------------------- */
  1313.  
  1314.  
  1315. haConnectSession
  1316.  
  1317. Starts the connection process within the current session.
  1318.  
  1319. Syntax:
  1320.  
  1321.     INT haConnectSession(ScriptHandle, nMode)
  1322.  
  1323. SCRIPTHANDLE
  1324.  
  1325.     ScriptHandle The program - HyperACCESS link.
  1326.  
  1327. INT nMode
  1328.  
  1329.     Determines how the session is to be connected.
  1330.  
  1331. Arguments:
  1332.  
  1333.     ScriptHandle The script handle returned from haInitialize.
  1334.  
  1335. nMode
  1336.  
  1337.     Determines what type of connection is to be initiated.
  1338.  
  1339. Value                 Meaning
  1340.  
  1341. HA_CNCT_STANDARD      Do a normal connection sequence.
  1342.  
  1343. HA_CNCT_LEARN_LOGIN   Start learning a new login script after
  1344.                       connection.
  1345.  
  1346. HA_CNCT_DO_NOT_DIAL   Open the device but do not dial the associated
  1347.                       phone number.
  1348.  
  1349. HA_CNCT_DO_NOT_LOGIN  Make the connection but do not run any login
  1350.                       script or task associated with this session.
  1351.  
  1352. HA_CNCT_ANSWER_MODE   Connect the session in standard answer mode.
  1353.                       In this mode, the port will be surrended if
  1354.                       another session attempts to connect using the
  1355.                       same port.
  1356.  
  1357. HA_CNCT_ANSWER_HOLD   Connect the session in answer and hold mode.
  1358.                       In this mode, the port will not be surrendered
  1359.                       if another session attempts to connect using
  1360.                       the same port.
  1361.  
  1362. Remarks:
  1363.  
  1364.     This function only starts the connection process.  A connection
  1365.     process may have a number of steps and can take an extended
  1366.     period of time, depending on the process the device requires.
  1367.     You must use haWaitForConnection or haGetConnectionStatus to
  1368.     determine when it is OK to continue.  A session cannot perform
  1369.     communications related functions unless it is connected.
  1370.  
  1371. Return Value:
  1372.  
  1373.     Returns 0 if successful.  Otherwise, a standard API error code.
  1374.  
  1375. See Also:
  1376.  
  1377.     haDisconnectSession, haGetConnectionStatus, haOpenSession,
  1378.     haSetSession, haWaitForConnection
  1379.  
  1380. Example:
  1381.  
  1382. /* -------------------------------------------------------------- */
  1383.  
  1384. /* Connect without dialing and transfer all typed characters to
  1385. the modem.  */
  1386.  
  1387. /* This is often referred to as "Terminal Mode".  */
  1388.  
  1389. /* This program segment:  - Tells HyperACCESS not to call the
  1390. remote system on connection.  The function haSkipConnection is
  1391. required in case the program is run as a preconnection program.
  1392. Otherwise it is ignored.  - Checks the current connection status,
  1393. and if already connected releases resources and returns control
  1394. to HyperACCESS.  - If not connected, request HyperACCESS to
  1395. connect the session (without dialing).  - Don't wait for
  1396. connection because there won't be one until the user types
  1397. commands at keyboard.  - Release resources and return control to
  1398. HyperACCESS.  */
  1399.  
  1400. ReturnCode = haSkipConnection(ScriptHandle);
  1401. if (HA_CONNECTED == haGetConnectionStatus(ScriptHandle))
  1402.     ReturnCode = haTerminate(ScriptHandle, 0);
  1403.  
  1404.     ReturnCode = haConnectSession(ScriptHandle,
  1405.     HA_CNCT_DO_NOT_DIAL);
  1406.     ReturnCode = haTerminate(ScriptHandle, 0);
  1407.  
  1408. /* -------------------------------------------------------------- */
  1409.  
  1410.  
  1411. haCreateNewSession
  1412.  
  1413. Opens a new session and creates a new session file.
  1414.  
  1415. Syntax:
  1416.  
  1417.     haCreateNewSession(ScriptHandle, pszName)
  1418.  
  1419. SCRIPTHANDLE
  1420.     ScriptHandle The program - HA\Win link.
  1421.  
  1422. LPSTR pszName
  1423.  
  1424.     The name used for the session.
  1425.  
  1426. Arguments:
  1427.  
  1428.     ScriptHandle The script handle returned from haInitialize.
  1429.  
  1430.     pszName The name of the new session.  This is the name that
  1431.     shows up in the title bar of the new session, as well as the
  1432.     Phonebook.  It is also used to generate the filename, the first
  1433.     eight characters being used, with non alphanumeric characters
  1434.     being replaced by an underscore.
  1435.  
  1436. Remarks:
  1437.  
  1438.     The session is not connected when it is initially created.  The
  1439.     newly created session becomes the current session for the
  1440.     script.  A script can interact with several sessions
  1441.     simultaneously by storing the session handles in variables and
  1442.     using haSetSession to move among them.
  1443.  
  1444. Return Value:
  1445.  
  1446.     Returns a session handle if successful.  Otherwise a standard
  1447.     API error code.
  1448.  
  1449. See Also:
  1450.  
  1451.     haCloseSession, haConnectSession, haOpenSession
  1452.  
  1453.  
  1454. haDisconnectSession
  1455.  
  1456. This function disconnects a session.
  1457.  
  1458. Syntax:
  1459.  
  1460.     INT haDisconnectSession(ScriptHandle)
  1461.  
  1462. SCRIPTHANDLE
  1463.  
  1464.     ScriptHandle The program - HyperACCESS link.
  1465.  
  1466. Arguments:
  1467.  
  1468.     ScriptHandle The script handle returned from haInitialize.
  1469.  
  1470. Remarks:
  1471.  
  1472.     A session cannot perform communications related operations once
  1473.     it is disconnected.
  1474.  
  1475. Return Value:
  1476.  
  1477.     Returns 0 if successful.  Otherwise, a standard API error code.
  1478.  
  1479. See Also:
  1480.  
  1481.     haConnectSession, haCloseSession, haGetConnectionStatus,
  1482.     haOpenSession
  1483.  
  1484. Example:
  1485.  
  1486. /* -------------------------------------------------------------- */
  1487.  
  1488. /* Disconnecting from a remote system.  */
  1489.  
  1490. ReturnCode = haDisconnectSession(ScriptHandle);
  1491.  
  1492. /* -------------------------------------------------------------- */
  1493.  
  1494.  
  1495. haGetAsciiSettings
  1496.  
  1497. Gets settings that are found in the ASCII Settings dialog box.
  1498.  
  1499. Syntax:
  1500.  
  1501.     INT haGetAsciiSettings(ScriptHandle, nCount, pnData)
  1502.  
  1503. SCRIPTHANDLE
  1504.  
  1505.     ScriptHandle The program - HyperACCESS link.
  1506.  
  1507. INT nCount
  1508.  
  1509.     The number of integers that follow INT FAR *pnData A pointer to
  1510.     an array of integers (16 bit values)
  1511.  
  1512. Arguments:
  1513.  
  1514.     ScriptHandle The script handle returned from haInitialize.
  1515.     nCount The number of integers (16 bit values) in the array
  1516.     pointed to by pnData.  pnData A pointer to an array of integers
  1517.     (16 bit values) that are used to get the ASCII Settings.  Each
  1518.     array element has a value that can be indexed by the following
  1519.     constants:
  1520.  
  1521. Value                 Meaning
  1522.  
  1523. HA_AI_FLAGS           Various individual flags (bits), described
  1524.                       below.
  1525.  
  1526. HA_AI_WFCHAR          Input wait for character.
  1527.  
  1528. HA_AI_OTABS           Output tab expansion value.
  1529.  
  1530. HA_AI_CWAIT           Character delay value.
  1531.  
  1532. HA_AI_LWAIT           Line delay value.
  1533.  
  1534. HA_AI_ITABS           Input tab conversion value.  The following
  1535.                       flags(bits) are used in the.
  1536.  
  1537. HA_AI_FLAGS           word to determine the state of individual
  1538.                       check box items:
  1539.  
  1540. Value                 Meaning
  1541.  
  1542. HA_AFS_LF             Append LF to sent line ends.
  1543.  
  1544. HA_AFS_BLS            Expand blank lines sent to include a space.
  1545.  
  1546. HA_AFS_ECHO           Echo typed characters locally.
  1547.  
  1548. HA_AFS_WAIT           Enable wait for line end character.
  1549.  
  1550. HA_AFS_TABS           Enable tab expansion for sent characters.
  1551.  
  1552. HA_AFR_LF             Append LF to received line ends.
  1553.  
  1554. HA_AFR_7BIT           Force incoming characters to 7 bits.
  1555.  
  1556. HA_AFR_ECHO           Echo received characters to sender.
  1557.  
  1558. HA_AFR_WRAP           Wrap lines that exceed terminal width.
  1559.  
  1560. HA_AFR_HEX            Show hex value of non-printing characters.
  1561.  
  1562. Remarks:
  1563.  
  1564.     The integer HA_AI_FLAGS has individual flags (bits) which are
  1565.     either TRUE (1) or FALSE (0).  Determining the value of
  1566.     individual bits is language dependent.  However, in C, you can
  1567.     test the value of a particular bit by performing a bitwise AND
  1568.     operation of HA_AI_FLAGS with the desired flag name defined
  1569.     above.
  1570.  
  1571. Return Value:
  1572.  
  1573.     Returns 0 if successful.  Otherwise, a standard API error code.
  1574.  
  1575. See Also:
  1576.  
  1577.     haSetAsciiSettings
  1578.  
  1579.  
  1580. haGetBaudRate
  1581.  
  1582. Returns the baud rate of the currently open session if the port
  1583. type in use supports baud rates.
  1584.  
  1585. Syntax:
  1586.  
  1587.     LONG haGetBaudrate(ScriptHandle)
  1588.  
  1589. SCRIPTHANDLE
  1590.  
  1591.     ScriptHandle The program - HyperACCESS link.
  1592.  
  1593. Arguments:
  1594.  
  1595.     ScriptHandle The script handle returned from haInitialize.
  1596.  
  1597. Remarks:
  1598.  
  1599. Return Value:
  1600.  
  1601.     Returns the baud rate if successful.  Otherwise, a standard API
  1602.     error code.
  1603.  
  1604. See Also:
  1605.  
  1606.     haSetBaudRate
  1607.  
  1608.  
  1609. haGetCaptureFileName
  1610.  
  1611. Returns the name of the capture file for the currently active
  1612. session.
  1613.  
  1614. Syntax:
  1615.  
  1616.     INT haGetCaptureFileName(ScriptHandle, nSize, pszBuffer)
  1617.  
  1618. SCRIPTHANDLE
  1619.  
  1620.     ScriptHandle The program - HyperACCESS link.
  1621.  
  1622. INT nSize
  1623.  
  1624.     The size of the following buffer.
  1625.  
  1626. LPSTR pszBuffer
  1627.  
  1628.     A pointer to a buffer
  1629.  
  1630. Arguments:
  1631.  
  1632.     ScriptHandle The script handle returned from haInitialize.
  1633.  
  1634.     nSize The size of the following buffer.
  1635.  
  1636.     pszBuffer A pointer to a buffer that is to contain the filename.
  1637.  
  1638. Remarks:
  1639.  
  1640.     The buffer should be large enough to accomodate a complete path
  1641.     and filename.  If the buffer is too small, only as much of the
  1642.     name as will fit will be copied.
  1643.  
  1644. Return Value:
  1645.  
  1646.     Returns 0 if successful.  Otherwise, a standard API error code.
  1647.  
  1648. See Also:
  1649.  
  1650.     haSetCaptureFileName
  1651.  
  1652. Example:
  1653.  
  1654. /* -------------------------------------------------------------- */
  1655.  
  1656. /* Get the capture filename and let the user change it.  This
  1657. program segment:  - Gets the capture filename.  - Uses a standard
  1658. C function to write formatted data to a string.  - Displays the
  1659. filename in a message box and asks if user wants to change it.  - If
  1660. the user selects the Yes response, another message box request a new
  1661. filename.  - If the user enters a new filename, it's saved as the
  1662. default capture file.  */
  1663.  
  1664. ReturnCode = haGetCaptureFileName(ScriptHandle, strlen(FName),
  1665. FName);
  1666. sprintf(Buffer, "Change Capture Filename:  %s", FName);
  1667. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", Buffer, 0,
  1668. 0, HA_MB_YN);
  1669. if (ReturnCode >= 0)
  1670.     { SubReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
  1671.     "Enter new Capture File:", strlen(FName), FName);
  1672.     SubReturnCode = haSetCaptureFileName(ScriptHandle, FName); }
  1673.  
  1674. /* -------------------------------------------------------------- */
  1675.  
  1676.  
  1677. haGetConnectionStatus
  1678.  
  1679. Returns the connection status of the currently active session.
  1680.  
  1681. Syntax:
  1682.  
  1683.     INT haGetConnectionStatus(ScriptHandle)
  1684.  
  1685. SCRIPTHANDLE
  1686.  
  1687.     ScriptHandle The program - HyperACCESS link.
  1688.  
  1689. Arguments:
  1690.  
  1691.     ScriptHandle The script handle returned from haInitialize.
  1692.  
  1693. Remarks:
  1694.  
  1695. Return Value:
  1696.  
  1697.     Returns one of the following connection status codes if OK.
  1698.     Otherwise, a standard API error code.
  1699.  
  1700. Value                 Meaning
  1701.  
  1702. HA_NOTSTARTED         Connection sequence has not started.
  1703.  
  1704. HA_CONNECTED          Session is connected.
  1705.  
  1706. HA_DISCONNECTED       Session is disconnected.
  1707.  
  1708. HA_CONNECTING         Session is attempting to connect.
  1709.  
  1710. HA_DISCONNECTING      Session is in the process of disconnecting.
  1711.  
  1712. HA_WAITING            Session is in answer mode, waiting for a call.
  1713.  
  1714. HA_SURRENDERED        Session is in answer mode, waiting for a call,
  1715.                       but has surrendered its port to another
  1716.                       session for an outgoing call.
  1717.  
  1718. See Also:
  1719.  
  1720.     haConnectSession, haDisconnectSession
  1721.  
  1722. Example:
  1723.  
  1724. /* -------------------------------------------------------------- */
  1725.  
  1726. /* Check the status of the current connection.  If offline, make
  1727. connection.  This program segment:  - Checks connection status.
  1728. - If disconnected, performs a standard connection sequence.  -
  1729. Wait for connection.  - If connected on entry or connected
  1730. successfully display messge.  - If connection fails for any
  1731. reason, display message.
  1732.  
  1733. ReturnCode = haGetConnectionStatus(ScriptHandle);
  1734. if (ReturnCode== HA_DISCONNECTED) {
  1735.     ReturnCode = haConnectSession(ScriptHandle,
  1736.     HA_CNCT_STANDARD);
  1737.     if (SubReturnCode == 0)
  1738.         ReturnCode = haWaitForConnection(ScriptHandle, HA_CONNECTED,
  1739.         60000L); }
  1740.         if (ReturnCode == HA_CONNECTED)
  1741.             haMessageBox(ScriptHandle, "HyperACCESS", "Online!",
  1742.             0,0,HA_MB_OK);
  1743.         else
  1744.             haMessageBox(ScriptHandle, "HyperACCESS", "Connection
  1745.             Failed!", 0,0,HA_MB_OK);
  1746.  
  1747. /* -------------------------------------------------------------- */
  1748.  
  1749.  
  1750. haGetConnectTime
  1751.  
  1752. Returns the number of seconds that the session has been
  1753. connected.
  1754.  
  1755. Syntax:
  1756.  
  1757.     LONG haGetConnectTime(ScriptHandle)
  1758.  
  1759. SCRIPTHANDLE
  1760.  
  1761.     ScriptHandle The program - HyperACCESS link.
  1762.  
  1763. Arguments:
  1764.  
  1765.     ScriptHandle The script handle returned from haInitialize.
  1766.  
  1767. Remarks:
  1768.  
  1769.     If the session is not connected, zero is returned.
  1770.  
  1771. Return Value:
  1772.  
  1773.     Returns the number of seconds that the session has been
  1774.     connected if successful.  Otherwise, if the return value is a
  1775.     negative number, it is a standard API error code.
  1776.  
  1777. See Also:
  1778.  
  1779.     haConnectSession, haDisconnectSession
  1780.  
  1781.  
  1782. haGetDialingPrefix
  1783.  
  1784. Returns one of the dialing prefixes defined in the program.
  1785.  
  1786. Syntax:
  1787.  
  1788.     INT haGetDialingPrefix(ScriptHandle, nIndex, nSize, pszBuffer)
  1789.  
  1790. SCRIPTHANDLE
  1791.  
  1792. ScriptHandle The program - HyperACCESS link.
  1793.  
  1794. INT nIndex
  1795.  
  1796.     Which prefix string.
  1797.  
  1798. INT nSize
  1799.  
  1800.     The size of the following buffer.
  1801.  
  1802. LPSTR pszBuffer
  1803.  
  1804.     A pointer to a buffer.
  1805.  
  1806. Arguments:
  1807.  
  1808.     ScriptHandle The script handle returned from haInitialize.
  1809.  
  1810.     nIndex This parameter determines which prefix string to return.
  1811.     Valid numbers are 1 thru 10.  nSize The size of the following
  1812.     buffer.
  1813.     pszBuffer A pointer to the buffer that is to receive the prefix
  1814.     string.
  1815.  
  1816. Remarks:
  1817.  
  1818.     There is only one set of ten dialing prefix strings that is
  1819.     shared by all sessions.  The dialing prefix strings, themselves,
  1820.     are stored globally in the .PRF file.  Only the number of the
  1821.     prefix string being used for a session is stored in each session
  1822.     file.
  1823.  
  1824. Return Value:
  1825.  
  1826.     Returns 0 if successful.  Otherwise, a standard API error code.
  1827.  
  1828. See Also:
  1829.  
  1830.     haSetPrefixString
  1831.  
  1832. Example:
  1833.  
  1834. /* -------------------------------------------------------------- */
  1835.  
  1836. /* Let the user change the dialing prefix if necessary.  This
  1837. program segment:  - Gets the first dialing prefix.  - Uses a
  1838. standard C function to write formatted data to a string.  -
  1839. Displays the current prefix in a message box and asks for Yes/No
  1840. response to question.  - If response is Yes, asks user for new
  1841. prefix.  - Sets new prefix (for all phonebook entries).  */
  1842.  
  1843. ReturnCode = haGetDialingPrefix(ScriptHandle, 1, 128, PNumber);
  1844. sprintf(Buffer, "Is this string correct:  %s", PNumber);
  1845. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", Buffer, 0,
  1846. 0, HA_MB_YN);
  1847. if (ReturnCode == 0) {
  1848.     ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter
  1849.     new prefix:", strlen(PNumber), PNumber);
  1850.     ReturnCode = haSetDialingPrefix(ScriptHandle, 1, PNumber); }
  1851.  
  1852. /* -------------------------------------------------------------- */
  1853.  
  1854.  
  1855. haGetDisplay
  1856.  
  1857. Returns a value indicating the type of view currently being
  1858. displayed by the current phonebook.
  1859.  
  1860. Syntax:
  1861.  
  1862.     INT haGetDisplay(ScriptHandle)
  1863.  
  1864. SCRIPTHANDLE
  1865.  
  1866.     ScriptHandle The program - HyperACCESS link.
  1867.  
  1868. Arguments:
  1869.  
  1870.     ScriptHandle The script handle returned from haInitialize.
  1871.  
  1872. Remarks:
  1873.  
  1874. Return Value:
  1875.  
  1876.     Returns one of the following codes if successful. Otherwise, a
  1877.     standard API error code.
  1878.  
  1879. Value                 Meaning
  1880.  
  1881. HA_ICONIC             The Phonebook is being displayed as icons.
  1882.  
  1883. HA_STATS              The Statistics view is being displayed in the
  1884.                       Phonebook.
  1885.  
  1886. HA_DETAILS            The Details view is being displayed in the
  1887.                       Phonebook.
  1888.  
  1889. HA_NAMES              The Phonebook is being displayed as system
  1890.                       names.
  1891.  
  1892. HA_FILES              The Phonebook is being displayed as filenames.
  1893.  
  1894. See Also:
  1895.  
  1896.     haSetDisplay
  1897.  
  1898.  
  1899. haGetEmulator
  1900.  
  1901. Returns the name of the terminal emulator for the currently
  1902. active session.
  1903.  
  1904. Syntax:
  1905.  
  1906.     INT haGetEmulator(ScriptHandle, nSize, pszBuffer)
  1907.  
  1908. SCRIPTHANDLE
  1909.  
  1910.     ScriptHandle The program - HyperACCESS link.
  1911.  
  1912. INT nSize
  1913.  
  1914.     The size of the following buffer
  1915.  
  1916. LPSTR pszBuffer
  1917.  
  1918.     A pointer to a buffer
  1919.  
  1920. Arguments:
  1921.  
  1922.     ScriptHandle The script handle returned from haInitialize.
  1923.  
  1924.     nSize The size of the following buffer.
  1925.  
  1926.     pszBuffer A pointer to a buffer that is to receive the
  1927.     emulator name.
  1928.  
  1929. Remarks:
  1930.  
  1931. Return Value:
  1932.  
  1933.     Returns 0 if successful.  Otherwise, a standard API error code.
  1934.  
  1935. See Also:
  1936.  
  1937.     haSetEmulator
  1938.  
  1939. Example:
  1940.  
  1941. /* -------------------------------------------------------------- */
  1942.  
  1943. /* Change the screen color regardless of terminal emulator in
  1944. use.  This program segment:  - Gets the current terminal
  1945. emulator.  - Change the terminal emulator to ANSI so that local
  1946. commands can change screen color.  - Type local text to change
  1947. screen color to blue letters on white background (see DOS help
  1948. for ANSI.SYS).  - Sets the terminal emulator back to its original
  1949. type.  */
  1950.  
  1951. ReturnCode = haGetEmulator(ScriptHandle, strlen(Emulator),
  1952. Emulator); ReturnCode = haSetEmulator(ScriptHandle, "ANSI");
  1953. ReturnCode = haTypeLocalText(ScriptHandle, "\x1b[37;44;1m");
  1954. ReturnCode = haSetEmulator(ScriptHandle, Emulator);
  1955.  
  1956. /* -------------------------------------------------------------- */
  1957.  
  1958.  
  1959. haGetHWND
  1960.  
  1961. Returns the window handle created by haInitialize to synchronize
  1962. message traffic between the external program and HyperACCESS.
  1963.  
  1964. Syntax:
  1965.  
  1966.     HWND haGetHWND(ScriptHandle)
  1967.  
  1968. SCRIPTHANDLE
  1969.  
  1970.     ScriptHandle The link between HyperACCESS and the operating
  1971.     system.
  1972.  
  1973. Arguments:
  1974.  
  1975.     ScriptHandle The ScriptHandle returned from haInitialize for
  1976.     connection to the HyperACCESS window.
  1977.  
  1978. Remarks:
  1979.  
  1980.     The window handle is used for message passing to and from
  1981.     HyperACCESS.  These messages are sychronized automatically by
  1982.     API functions.  Use this window handle with caution.
  1983.  
  1984. Return Value:
  1985.  
  1986.   Returns a window handle if successful.  Otherwise, zero.
  1987.  
  1988.  
  1989. haGetInput
  1990.  
  1991. Gets data received from the remote system.
  1992.  
  1993. Syntax:
  1994.  
  1995.     INT haGetInput(ScriptHandle, nMode, nCount, lStartTimeout,
  1996.     lCharTimeout, pszBuffer)
  1997.  
  1998. SCRIPTHANDLE
  1999.  
  2000.     ScriptHandle The program - HyperACCESS link.
  2001.  
  2002. INT nMode
  2003.  
  2004.     Additional processing options
  2005.  
  2006. INT nCount
  2007.  
  2008.     The number of characters to wait for.
  2009.  
  2010. LONG lStartTimeout
  2011.  
  2012.     The timeout for the first character.
  2013.  
  2014. LONG lCharTimeout
  2015.  
  2016.     The intercharacter timeout.
  2017.  
  2018. LPSTR pszBuffer
  2019.  
  2020.    A pointer to a buffer.
  2021.  
  2022. Arguments:
  2023.  
  2024.     ScriptHandle The script handle returned from haInitialize.
  2025.  
  2026.     nMode Determines what, if any, extra processing of the input is
  2027.     to be performed.
  2028.  
  2029. Value                 Meaning
  2030.  
  2031. HA_GI_BACKSPACE       Process backspaces.
  2032.  
  2033. nCount
  2034.  
  2035.     The count determines the number of characters to wait for.  If
  2036.     the count is (-1), wait for a carriage return.
  2037.  
  2038. lStartTimeout
  2039.  
  2040.     This timeout value, measured in milliseconds, determines how
  2041.     long to wait for the first character before returning to the
  2042.     caller.  If this timeout is exceeded before any new characters
  2043.     are received, the error code HA_ERR_TIMED_OUT is returned.
  2044.  
  2045. lCharTimeout
  2046.  
  2047.     This timeout value, measured in milliseconds, determines how
  2048.     long to wait between characters before returning to the caller.
  2049.     If this timeout is exceeded, after at least one character has
  2050.     been received, but before a new character is received, the
  2051.     function returns the number of characters already received.  If
  2052.     the function returns fewer characters than were requested, it is
  2053.     because an intercharacter timeout occurred.
  2054.  
  2055. pszBuffer
  2056.  
  2057.     A pointer to a buffer to hold the acquired characters.
  2058.  
  2059. Remarks:
  2060.  
  2061.     If nMode is 0, backspace characters are stored in the buffer.
  2062.     If nMode is HA_GI_BACKSPACE, backspace characters are processed
  2063.     before the buffer is returned.  Return Value:  Returns the
  2064.     number of characters received if successful.  Otherwise, a
  2065.     standard API error code.
  2066.  
  2067. See Also:
  2068.  
  2069.     haWaitForPrompt, haWaitForString
  2070.  
  2071. Example:
  2072.  
  2073. /* -------------------------------------------------------------- */
  2074.  
  2075. /* Prompt remote user for data, and respond.  This program
  2076. segment:  - Sends text to remote system requesting input from
  2077. remote user.  - Gets input from communications port, but lets
  2078. HyperACCESS process any backspace characters.  Waits 100 sec.
  2079. for first character.  Waits 30 sec.  between characters.  - If
  2080. remote user responds, formats response and types message to
  2081. remote user.  */
  2082.  
  2083. ReturnCode = haTypeText(ScriptHandle, 0, "Enter First Name:  ");
  2084. ReturnCode = haGetInput(ScriptHandle, HA_GI_BACKSPACE, -1,
  2085. 100000L, 30000L, FName); if (ReturnCode >= 0) { sprintf(Buffer,
  2086. "Welcome to the system, %s", FName); ReturnCode =
  2087. haTypeText(ScriptHandle, 0, Buffer); }
  2088.  
  2089. /* -------------------------------------------------------------- */
  2090.  
  2091.  
  2092. haGetLearnFileName
  2093.  
  2094. Returns the name of the learn file (script) for the currently
  2095. active session.
  2096.  
  2097. Syntax:
  2098.  
  2099.     INT haGetLearnFileName(ScriptHandle, nSize, pszBuffer)
  2100.  
  2101. SCRIPTHANDLE
  2102.  
  2103.     ScriptHandle The program - HyperACCESS link.
  2104.  
  2105. INT nSize
  2106.  
  2107.     The size of the following buffer.
  2108.  
  2109. LPSTR pszBuffer
  2110.  
  2111.     A pointer to a buffer.
  2112.  
  2113. Arguements:
  2114.  
  2115.     ScriptHandle The script handle returned from haInitialize.
  2116.  
  2117.     nSize The size of the following buffer.
  2118.  
  2119.     pszBuffer A pointer to a buffer that is to contain the filename.
  2120.  
  2121. Remarks:
  2122.  
  2123.     The buffer should be large enough to accomodate a complete path
  2124.     and filename.  If the buffer is too small, only as much of the
  2125.     name as will fit will be copied.
  2126.  
  2127. Return Value:
  2128.  
  2129.     Returns 0 if successful.  Otherwise, a standard API error code.
  2130.  
  2131. See Also:
  2132.  
  2133.     haSetLearnFileName, haGetCaptureFileName
  2134.  
  2135.  
  2136. haGetLogFileName
  2137.  
  2138. Returns the name of the current log file.
  2139.  
  2140. Syntax:
  2141.  
  2142.     INT haGetLogFileName(ScriptHandle, nSize, pszBuffer)
  2143.  
  2144. SCRIPTHANDLE
  2145.  
  2146.     ScriptHandle The program - HyperACCESS link.
  2147.  
  2148. INT nSize
  2149.  
  2150.   The size of the following buffer.
  2151.  
  2152. LPSTR pszBuffer.
  2153.  
  2154.     A pointer to a buffer.
  2155.  
  2156. Arguments:
  2157.  
  2158.     ScriptHandle The script handle returned from haInitialize.
  2159.  
  2160.     nSize The size of the following buffer.
  2161.  
  2162.     pszBuffer A pointer to the buffer that is to receive the log
  2163.     filename.
  2164.  
  2165. Remarks:
  2166.  
  2167.     The buffer should be large enough to accomodate a complete path
  2168.     and filename.
  2169.  
  2170. Return Value:
  2171.  
  2172.     Returns 0 if successful.  Otherwise, a standard API error code.
  2173.  
  2174. See Also:
  2175.  
  2176.     haSetLogFileName
  2177.  
  2178. Example:
  2179.  
  2180. /* -------------------------------------------------------------- */
  2181.  
  2182. /* Get the log filename and let the user change files if desired.
  2183. This program segment:  - Gets the log filename for the current
  2184. session.  - Uses a standard C function to write formatted data to
  2185. a string.  - Displays log filename in a message box and asks for
  2186. Yes/No response to question.  - If response is Yes, asks user for
  2187. new filename and sets new file.  */
  2188.  
  2189. ReturnCode = haGetLogFileName(ScriptHandle, 128, LogName);
  2190. sprintf(Buffer, "Change Log Filename:  %s", LogName);
  2191. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", Buffer, 0, 0,
  2192. HA_MB_YN);
  2193. if (ReturnCode == 0)
  2194.     {
  2195.     ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter
  2196.     new Log File:", strlen(LogName), LogName);
  2197.     ReturnCode = haSetLogFileName(ScriptHandle, LogName);
  2198.     }
  2199.  
  2200. /* -------------------------------------------------------------- */
  2201.  
  2202.  
  2203. haGetNameString
  2204.  
  2205. Returns the identification strings entered by the user during
  2206. program installation.
  2207.  
  2208. Syntax:
  2209.  
  2210.     INT haGetNameString(ScriptHandle, nSize, pszBuffer)
  2211.  
  2212. SCRIPTHANDLE
  2213.  
  2214.     ScriptHandle The program - HyperACCESS link.
  2215.  
  2216. INT nSize
  2217.  
  2218.     The size of the following buffer.
  2219.  
  2220. LPSTR pszBuffer
  2221.  
  2222.     A pointer to a buffer.
  2223.  
  2224. Arguments:
  2225.  
  2226.     ScriptHandle The script handle returned from haInitialize.
  2227.  
  2228.     nSize The size of the following buffer.
  2229.  
  2230.     pszBuffer A pointer to the buffer that will receive the strings.
  2231.  
  2232. Remarks:
  2233.  
  2234.     The user name data string gets set during program installation.
  2235.     This string consists of six lines in HA/Win and seven lines in
  2236.     HA/OS2 and HA/Win95.  Each line is terminated with a carriage
  2237.     return, linefeed pair.  Any of the strings may be blank, with
  2238.     only the terminating pair.  The strings are name, company,
  2239.     street address, city, state, zip code, and country.  HA/Win
  2240.     doesn't support country.
  2241.  
  2242. Return Value:
  2243.  
  2244.     Returns 0 if successful.  Otherwise, a standard API error code.
  2245.  
  2246. See Also:
  2247.  
  2248.     haSetNameString
  2249.  
  2250.  
  2251. haGetOpenSession
  2252.  
  2253. Returns a session handle from the list of open sessions.
  2254.  
  2255. Syntax:
  2256.  
  2257.     HSESS haGetOpenSession(ScriptHandle, nIndex)
  2258.  
  2259. SCRIPTHANDLE
  2260.  
  2261.     ScriptHandle The program - HyperACCESS link.
  2262.  
  2263. INT nIndex
  2264.  
  2265.     Which session handle to return.
  2266.  
  2267. Arguments:
  2268.  
  2269.     ScriptHandle The script handle returned from haInitialize.
  2270.  
  2271.     nIndex An index indicating which session handle from the list to
  2272.     return.  This index can range from 0 to n-1 where n is the
  2273.     number of open sessions.
  2274.  
  2275. Remarks:
  2276.  
  2277.     As sessions are opened, they are added to a list of open
  2278.     sessions within HyperACCESS.  This function returns session
  2279.     handles from that list.  In HA/OS2 and HA/Win95, there is only
  2280.     one open session, so nIndex must be 0. Any other value is an
  2281.     error.
  2282.  
  2283. Return Value:
  2284.  
  2285.     Returns a session handle if successful.  Otherwise, zero.
  2286.  
  2287. See Also:
  2288.  
  2289.     haGetPhonebookEntry, haGetSession, haOpenSession, haSetSession
  2290.  
  2291.  
  2292. haGetPhonebookEntry
  2293.  
  2294. Returns the filename for an entry in the current phonebook.
  2295. Syntax:
  2296.  
  2297.     INT haGetPhonebookEntry(ScriptHandle, nIndex, nSize, pszBuffer)
  2298.  
  2299. SCRIPTHANDLE
  2300.  
  2301.     ScriptHandle The program - HyperACCESS link.
  2302.  
  2303. INT nIndex
  2304.  
  2305.     Which entry in the phonebook.
  2306.  
  2307. INT nSize
  2308.  
  2309.     The size of the following buffer.
  2310.  
  2311. LPSTR pszBuffer
  2312.  
  2313.     A pointer to a buffer.
  2314.  
  2315. Arguments:
  2316.  
  2317.     ScriptHandle The script handle returned from haInitialize.
  2318.  
  2319.     nIndex The index into Phonebook that selects the session
  2320.     filename desired.
  2321.  
  2322.     nSize The size of the following buffer.
  2323.  
  2324.     pszBuffer A pointer to a buffer that is to receive the filename.
  2325.  
  2326. Remarks:
  2327.  
  2328.     The buffer should be large enough to accomodate a complete path
  2329.     and filename.  Remember that the order of sessions in Phonebook
  2330.     can change depending on sorting type selected.  An entry that
  2331.     was previously at one index may not be there at a later time.
  2332.  
  2333. Return Value:
  2334.  
  2335.     Returns 0 if successful.  Otherwise, a standard API error code.
  2336.  
  2337. See Also:
  2338.  
  2339.     haGetOpenSession, haGetSelectedPhonebookEntry
  2340.  
  2341. Example:
  2342.  
  2343. /* -------------------------------------------------------------- */
  2344.  
  2345. /* Open the first phonebook entry in the phonebook and connect to
  2346. it.  This program segment:
  2347. - Gets the filename of the first phonebook entry.
  2348. - Requests HyperACCESS to open and connect to
  2349.   it.  (Don't wait for connection to complete.)  */
  2350.  
  2351. ReturnCode = haGetPhonebookEntry(ScriptHandle, 1, strlen(FName),
  2352. FName);
  2353. ReternCode = haOpenSession(ScriptHandle, FName);
  2354. ReturnCode = haConnectSession(ScriptHandle, HA_CNCT_STANDARD);
  2355.  
  2356. /* -------------------------------------------------------------- */
  2357.  
  2358.  
  2359. haGetPortMode
  2360.  
  2361. Returns the current settings for the number of bits per
  2362. character, the number of stop bits, and the parity type.
  2363.  
  2364. Syntax:
  2365.  
  2366.     INT haGetPortMode(ScriptHandle)
  2367.  
  2368. SCRIPTHANDLE
  2369.  
  2370.     ScriptHandle The program - HyperACCESS link.
  2371.  
  2372. Arguments:
  2373.  
  2374.     ScriptHandle The script handle returned from haInitialize.
  2375.  
  2376. Remarks:
  2377.  
  2378.     The integer value returned has flags (bits) which are either
  2379.     TRUE (1) or FALSE (0).  Determining the value of individual bits
  2380.     is language dependent.  However, in C, you can test the value of
  2381.     a particular bit by performing a bitwise AND operation of the
  2382.     returned value with the desired flag name defined below.
  2383.  
  2384. Return Value:
  2385.  
  2386.     Returns a value that may be one or more of the following values
  2387.     ORed together if successful.  Otherwise, a standard API error
  2388.     code.
  2389.  
  2390. Value                 Meaning
  2391.  
  2392. HA_M_AUTO             Auto-detect is set.
  2393.  
  2394. HA_M_7_BITS           Characters contain 7 bits.
  2395.  
  2396. HA_M_8_BITS           Characters contain 8 bits.
  2397.  
  2398. HA_M_E_PRTY           Characters have even parity.
  2399.  
  2400. HA_M_O_PRTY           Characters have odd parity.
  2401.  
  2402. HA_M_N_PRTY           Characters have no parity.
  2403.  
  2404. HA_M_M_PRTY           Characters have mark parity.
  2405.  
  2406. HA_M_S_PRTY           Characters have space parity.
  2407.  
  2408. Value                 Meaning
  2409.  
  2410. HA_M_1_STOP           Characters have one stop bit.
  2411.  
  2412. HA_M_1_5_STOP         Characters have 1.5 stop bits.
  2413.  
  2414. HA_M_2_STOP           Characters have two stop bits.
  2415.  
  2416. See Also:
  2417.  
  2418.     haSetPortMode
  2419.  
  2420. Example:
  2421.  
  2422. /* -------------------------------------------------------------- */
  2423. /* Get and display all port mode settings.  This program
  2424. segment:
  2425. - Gets the port mode.
  2426. - Uses HyperACCESS bit masks to determine settings and translate bit
  2427.   settings to understandable character strings.
  2428. - Uses standard C functions to convert the baud rate to a string and
  2429.   write formatted data to a string.
  2430. - Displays the resulting string in a message box.  */
  2431.  
  2432. ReturnCode = haGetPortMode(ScriptHandle);
  2433. if (ReturnCode & HA_M_8_BIT) strcpy(DataBits, "8");
  2434. if (ReturnCode & HA_M_7_BIT) strcpy(DataBits, "7");
  2435. if (ReturnCode & HA_M_N_PRTY) strcpy(Parity, "None");
  2436. if (ReturnCode & HA_M_O_PRTY) strcpy(Parity, "Odd");
  2437. if (ReturnCode & HA_M_E_PRTY) strcpy(Parity, "Even");
  2438. if (ReturnCode & HA_M_M_PRTY) strcpy(Parity, "Mark");
  2439. if (ReturnCode & HA_M_S_PRTY) strcpy(Parity, "Space");
  2440. if (ReturnCode & HA_M_1_STOP) strcpy(StopBits, "1");
  2441. if (ReturnCode & HA_M_2_STOP) strcpy(StopBits, "2");
  2442. sprintf(Buffer, "Port Mode:  %s,%s,%s",
  2443. Parity,DataBits,StopBits);
  2444. ReturnCode = haMessageBox(ScriptHandle, "Communications", Buffer,
  2445. 0, 0, HA_MB_OK);
  2446.  
  2447. /* ------------------------------------------ */
  2448.  
  2449.  
  2450. haGetPortName
  2451.  
  2452. Returns the name of the port for the currently active session.
  2453.  
  2454. Syntax:
  2455.  
  2456.    INT haGetPortName(ScriptHandle, nSize, pszBuffer)
  2457.  
  2458. SCRIPTHANDLE
  2459.  
  2460.    ScriptHandle                  The program - HyperACCESS link
  2461.  
  2462.    INT nSize                     The size of the following buffer
  2463.  
  2464.    LPSTR pszBuffer               A pointer to a buffer
  2465.  
  2466. Arguments:
  2467.  
  2468.    ScriptHandle
  2469.  
  2470.       The script handle returned from haInitialize.
  2471.  
  2472.    nSize
  2473.  
  2474.       The size of the following buffer.
  2475.  
  2476.    pszBuffer
  2477.  
  2478.       A pointer to the buffer that will receive the port name.
  2479.  
  2480. Remarks:
  2481.  
  2482.     A port is identified by a port type and a port name.  The format
  2483.     and range of values of the port name depend on the port type
  2484.     selected.  For example, if the port type is Standard Com Port,
  2485.     the port name will be COM1, COM2, etc.  If the port type
  2486.     specifies a network connection, the port name might be a
  2487.     server name or a named network resource.
  2488.  
  2489. Return Value:
  2490.  
  2491.     Returns 0 if successful.  Otherwise, a standard API error code.
  2492.  
  2493. Example:
  2494.  
  2495.    ReturnCode = haGetPortName(ScriptHandle, strlen(PortName),
  2496.    PortName);
  2497.  
  2498.  
  2499. haGetPortPrefs
  2500.  
  2501. Returns strings identifying the type and name of the port being
  2502. used for communications.  It also returns the name of the
  2503. connection device (modem).
  2504.  
  2505. Syntax:
  2506.  
  2507.    INT haGetPortPrefs(ScriptHandle, nSizeType, pszType, nSizeName,
  2508.    pszName, nSizeDevice, pszDevice)
  2509.  
  2510. SCRIPTHANDLE ScriptHandle            The program - HyperACCESS link.
  2511.  
  2512. INT nSizeType                        The size of the type buffer.
  2513.  
  2514. LPSTR pszType                        A pointer to the type buffer.
  2515.  
  2516. INT nSizeName                        The size of the name buffer.
  2517.  
  2518. LPSTR pszName                        A pointer to the name buffer.
  2519.  
  2520. INT nSizeDevice                      The size of the device buffer.
  2521.  
  2522. LPSTR pszDevice                      A pointer to the device buffer.
  2523.  
  2524. Arguments:
  2525.  
  2526.    ScriptHandle
  2527.  
  2528.       The script handle returned from haInitialize.
  2529.  
  2530.    nSizeType
  2531.  
  2532.       The size of the type buffer.
  2533.  
  2534.    pszType
  2535.  
  2536.       A pointer to a buffer that will receive the communications
  2537.       port type.
  2538.  
  2539.    nSizeName
  2540.  
  2541.       The size of the name buffer.
  2542.  
  2543.    pszName
  2544.  
  2545.       A pointer to a buffer that will receive the communications
  2546.       port name.
  2547.  
  2548.    nSizeDevice
  2549.  
  2550.       The size of the device buffer.
  2551.  
  2552.    pszDevice
  2553.  
  2554.       A pointer to a buffer that will receive the communications
  2555.       port device.
  2556.  
  2557. Remarks:
  2558.  
  2559.    The port type and port name values are stored per session in the
  2560.    session settings file.  The name of the connection device
  2561.    (commonly a modem name) associated with each port is stored
  2562.    globally in the .PRF file and applies to all sessions using that
  2563.    port.
  2564.  
  2565. Return Value:
  2566.  
  2567.    Returns 0 if successful.  Otherwise, a standard API error code.
  2568.  
  2569. See Also:
  2570.  
  2571.    haGetPortName, haGetPortType, haSetPortPrefs
  2572.  
  2573. Example:
  2574.  
  2575. /* -------------------------------------------------------------- */
  2576.  
  2577. /* Gather and display port information.
  2578.    This program segment:
  2579. - Gets the port type, name, and device name.
  2580. - Displays theresulting string in a message box.  */
  2581.  
  2582. ReturnCode = haGetPortPrefs(ScriptHandle, strlen(PType), PType,
  2583.                strlen(PortName), PortName, strlen(DName), DName);
  2584. sprintf(Buffer, "Port Info:  %s:%s, %s", Ptype, PortName, DName);
  2585. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", Buffer, 0, 0,
  2586.                HA_MB_OK);
  2587.  
  2588. /* The function "haGetPortType" also gets port type, but none of
  2589. the other information:  */
  2590.    ReturnCode = haGetPortType(ScriptHandle, strlen(PType), PType);
  2591.  
  2592. /* -------------------------------------------------------------- */
  2593.  
  2594.  
  2595. haGetPortType
  2596.  
  2597.    Returns the type of communications port associated with the
  2598.    currently active session.
  2599.  
  2600. Syntax:
  2601.  
  2602.    INT haGetPortType(ScriptHandle, nSize, pszBuffer)
  2603.  
  2604.       SCRIPTHANDLE ScriptHandle     The program - HyperACCESS link.
  2605.  
  2606.       INT nSize                     The size of the following buffer
  2607.  
  2608.       LPSTR pszBuffer               A pointer to a buffer
  2609.  
  2610. Arguments:
  2611.  
  2612.    ScriptHandle
  2613.  
  2614.       The script handle returned from haInitialize.
  2615.  
  2616.    nSIze
  2617.  
  2618.       The size of the following buffer.
  2619.  
  2620.    pszBuffer
  2621.  
  2622.       A pointer to a buffer that will receive the communications
  2623.       port type.
  2624.  
  2625. Remarks:
  2626.  
  2627.    A port type and name identify a port.  For each port type
  2628.    supported, there is a driver file implemented as a DLL
  2629.    module with a name of the form HAC*.DLL.  Adding driver modules
  2630.    adds port types.  Removing driver modules removes the associated
  2631.    port type from the list of those available.
  2632.  
  2633. Return Value:
  2634.  
  2635.    Returns 0 if successful.  Otherwise, a standard API error code.
  2636.  
  2637. See Also:
  2638.  
  2639.    haGetPortName, haGetPortPrefs
  2640.  
  2641. Example:
  2642.  
  2643. /* -------------------------------------------------------------- */
  2644. /* Get and display port type.
  2645.    This program segment:
  2646.    - Gets the port type and displays it in a message box.  */
  2647.  
  2648. ReturnCode = haGetPortType(ScriptHandle, strlen(PType), PType)
  2649. ReturnCode = haMessageBox(ScriptHandle,
  2650. /* -------------------------------------------------------------- */
  2651.  
  2652. haGetRingsForAnswer
  2653.  
  2654. Returns the current number of times an incoming call rings before
  2655. the call is answered.
  2656.  
  2657. Syntax:
  2658.  
  2659.    INT haGetRingsForAnswer(ScriptHandle)
  2660.  
  2661.        SCRIPTHANDLE ScriptHandle      The program - HyperACCESS link
  2662.  
  2663. Arguments:
  2664.  
  2665.    ScriptHandle
  2666.  
  2667.       The script handle returned from haInitialize.
  2668.  
  2669. Remarks:
  2670.  
  2671.    This function returns the value set by an earlier call to
  2672.    haSetRingsForAnswer or the default value for the device being
  2673.    used if haSetRingsForAnswer has not been called.
  2674.  
  2675. Return Value:
  2676.  
  2677.    Returns the number of rings to wait if successful.  Otherwise, a
  2678.    standard API error code.
  2679.  
  2680. See Also:
  2681.  
  2682.    haSetRingsForAnswer
  2683.  
  2684.  
  2685. haGetRuntimeValue
  2686.  
  2687. Returns one of the runtime strings stored with each session.
  2688.  
  2689. Syntax:
  2690.  
  2691.    INT haGetRuntimeValue(ScriptHandle, nValue, nPrompt,
  2692.    nSize, pszBuffer)
  2693.  
  2694.       SCRIPTHANDLE ScriptHandle       The program - HyperACCESS link
  2695.  
  2696.       INT nValue                      Which runtime string to return
  2697.  
  2698.       INT nPrompt                     To prompt or not to prompt
  2699.  
  2700.       INT nSize                       The size of the following
  2701.                                       buffer
  2702.  
  2703.       LPSTR pszBuffer                 A pointer to a buffer
  2704.  
  2705. Arguments:
  2706.  
  2707.    ScriptHandle
  2708.  
  2709.       The script handle returned from haInitialize.
  2710.  
  2711.    nValue
  2712.  
  2713.       Which runtime string to return:
  2714.  
  2715.       Value                         Meaning
  2716.  
  2717.       HA_RV_USERNAME                The currently defined user name.
  2718.  
  2719.       HA_RV_USERID                  The currently defined user ID.
  2720.  
  2721.       HA_RV_PASSWORD                The currently defined password.
  2722.  
  2723.    nPrompt
  2724.  
  2725.       If TRUE (non-zero), HyperACCESS prompts the user for a value
  2726.       if none has been stored in the session.
  2727.  
  2728.    nSize
  2729.  
  2730.       The size of the following buffer.
  2731.  
  2732.    pszBuffer
  2733.  
  2734.       A pointer to a buffer that will receive the runtime string.
  2735.  
  2736. Remarks:
  2737.  
  2738.    If the string is not currently set, the function call can
  2739.    instruct HyperACCESS to prompt for the string by setting nPrompt
  2740.    to TRUE.  The dialog that is used to prompt the user has a
  2741.    checkbox in it that allows the user to specify that they want the
  2742.    value they enter to be stored for future use.  The user can view
  2743.    and change values they store by using the Runtime Values dialog
  2744.    selected from the Properties menu.  If the session has a stored
  2745.    value, it is returned without input from the user regardless of
  2746.    the setting of nPrompt.
  2747.  
  2748. Return Value:
  2749.  
  2750.    Returns 0 if successful.  Otherwise, a standard API error code.
  2751.  
  2752. Example:
  2753.  
  2754. /* -------------------------------------------------------------- */
  2755.  
  2756. /* Get runtime values for NAME, USERID, and PASSWORD.  Then use
  2757. those values.
  2758.    This program segment:
  2759.   - Gets runtime values if they exist.  The TRUE parameter indicates
  2760.     that HyperACCESS should automatically prompt for a value if one
  2761.     isn't already stored.
  2762.   - Use the UserId and password as part of a login sequence with a
  2763.     remote system.*/
  2764.  
  2765. ReturnCode = haGetRuntimeValue(ScriptHandle, HA_RV_USERNAME, TRUE,
  2766.                strlen(UName), UName);
  2767. ReturnCode = haGetRuntimeValue(ScriptHandle, HA_RV_USERID, TRUE,
  2768.                strlen(UID), UID);
  2769. ReturnCode = haGetRuntimeValue(ScriptHandle, HA_RV_PASSWORD, TRUE,
  2770.                strlen(PWord), PWord);
  2771.  
  2772. /* Assume a connection has been made for this example to talk to. */
  2773.    ReturnCode = haWaitForPrompt(ScriptHandle, 1, "LOGON ID:",1000L,
  2774.                 60000L);
  2775.    ReturnCode = haTypeText(ScriptHandle, 0, UID);
  2776.    ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Password:", 1000L,
  2777.                 60000L);
  2778.    ReturnCode = haTypeText(ScriptHandle, 0, PWord);
  2779.  
  2780. /* -------------------------------------------------------------- */
  2781.  
  2782.  
  2783. haGetSelectedPhonebookEntry
  2784.  
  2785. Returns the filename for a selected (highlighted) entry in the
  2786. Phonebook.
  2787.  
  2788. Syntax:
  2789.  
  2790.    INT haGetSelectedPhonebookEntry(ScriptHandle, nIndex, nSize,
  2791.        pszBuffer)
  2792.  
  2793.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  2794.  
  2795.    INT nIndex                       Which entry to return
  2796.  
  2797.    INT nSize                        The size of the folloing buffer
  2798.  
  2799.    LPSTR pszBuffer                  A pointer to a buffer
  2800.  
  2801. Arguments:
  2802.  
  2803.    ScriptHandle
  2804.  
  2805.       The script handle returned from haInitialize.
  2806.  
  2807.    nIndex
  2808.  
  2809.       The index of the filename to return from the list of
  2810.       selected entries.  nSize The size of the following buffer.
  2811.  
  2812.    pszBuffer
  2813.  
  2814.       A pointer to a buffer that is to receive the filename
  2815.       of the selected entry from the Phonebook.
  2816.  
  2817. Remarks:
  2818.  
  2819.    The entry returned can change depending upon the sorting type
  2820.    selected for Phonebook.  It can also change if an entry becomes
  2821.    selected or deselected.
  2822.  
  2823. Return Value:
  2824.  
  2825.    Returns 0 if successful.  Otherwise, a standard API error code.
  2826.  
  2827. See Also:
  2828.  
  2829.    haGetPhonebookEntry, haGetOpenSession
  2830.  
  2831. Example:
  2832.  
  2833. /* -------------------------------------------------------------- */
  2834.  
  2835. /* Get the filename of the currently selected phonebook entry.
  2836. If more than one selected, gets the first session filename */
  2837.  
  2838. ReturnCode = haGetSelectedPhonebookEntry(ScriptHandle, 1,
  2839.                strlen(FName), FName);
  2840.  
  2841. /* -------------------------------------------------------------- */
  2842.  
  2843.  
  2844. haGetSelectedText
  2845.  
  2846. Get the selected (highlighted) text from the associated session
  2847. window.
  2848.  
  2849. Syntax:
  2850.  
  2851.    INT haGetSelectedText(ScriptHandle, nSize, pszBuffer)
  2852.  
  2853.    SCRIPTHANDLE ScriptHandle          The program - HyperACCESS link
  2854.  
  2855.    INT nSize                          The size of the following
  2856.                                       buffer
  2857.  
  2858. LPSTR pszBuffer                       A pointer to a buffer
  2859.  
  2860. Arguments:
  2861.  
  2862.    ScriptHandle
  2863.  
  2864.       The script handle returned from haInitialize.
  2865.  
  2866.    nSize
  2867.  
  2868.       The size of the following buffer.
  2869.  
  2870.    pszBuffer
  2871.  
  2872.       A pointer to a buffer that is to receive the selected text.
  2873.  
  2874. Remarks:
  2875.  
  2876.    Since there is no way to predict how much text the user is going
  2877.    to select, make the buffer as big as is possible and still be
  2878.    reasonable.  Remember, it still won't be large enough every time.
  2879.  
  2880. Return Value:
  2881.  
  2882.    Returns 0 if successful.  Otherwise a standard API error code.
  2883.  
  2884. See Also:
  2885.  
  2886.    haGetTextFromScreen
  2887.  
  2888.  
  2889. haGetSerNumString
  2890.  
  2891. Returns the serial number string from HyperACCESS.
  2892.  
  2893. Syntax:
  2894.  
  2895.    INT haGetSerNumString(ScriptHandle, nSize, pszBuffer)
  2896.  
  2897.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  2898.  
  2899.    INT nSize                        The size of the following buffer
  2900.  
  2901.    LPSTR pszBuffer                  A pointer to a buffer
  2902.  
  2903. Arguments:
  2904.  
  2905.    ScriptHandle
  2906.  
  2907.       The script handle returned from haInitialize.
  2908.  
  2909.    nSize
  2910.  
  2911.       The size of the following buffer.
  2912.  
  2913.    pszBuffer
  2914.  
  2915.       A pointer to a buffer to receive the serial number string.
  2916.  
  2917. Remarks:
  2918.  
  2919.    The serial number is initially set by the installation
  2920.    procedure and is visible in the program's Help About HyperACCESS
  2921.    dialog box.  This function returns the serial number as a string.
  2922.  
  2923. Return Value:
  2924.  
  2925.    Returns 0 if successful.  Otherwise, a standard API error code.
  2926.  
  2927.  
  2928.  
  2929. haGetSession
  2930.  
  2931. Returns the session handle currently associated with the program
  2932. - HyperACCESS link.
  2933.  
  2934. Syntax:
  2935.  
  2936.    HSESS haGetSession(ScriptHandle)
  2937.  
  2938.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  2939.  
  2940. Arguments:
  2941.  
  2942.    ScriptHandle
  2943.  
  2944.       The script handle returned from haInitialize.
  2945.  
  2946. Remarks:
  2947.  
  2948.    Each open session in HyperACCESS is uniquely identified by a
  2949.    session handle.  Several other API functions operate on the
  2950.    current session handle.
  2951.  
  2952. Return Value:
  2953.  
  2954.    This function returns a session handle associated with the
  2955.    script, or zero if no session is currently associated with the
  2956.    script.
  2957.  
  2958. See Also:
  2959.  
  2960.    haCloseSession, haOpenSession, haSetSession
  2961.  
  2962.  
  2963. haGetSessionName
  2964.  
  2965. Returns the name of the current session.
  2966.  
  2967. Syntax:
  2968.  
  2969.    INT haGetSessionName(ScriptHandle, nSize, pszBuffer)
  2970.  
  2971. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  2972.  
  2973. INT nSize                           The size of the following buffer
  2974.  
  2975. LPSTR pszBuffer                     A pointer to a buffer
  2976.  
  2977. Arguments:
  2978.  
  2979.    ScriptHandle
  2980.  
  2981.       The script handle returned from haInitialize.
  2982.  
  2983.    nSize
  2984.  
  2985.       The size of the following buffer.
  2986.  
  2987.    pszBuffer
  2988.  
  2989.       A pointer to a buffer that is to recieve the string.
  2990.  
  2991. Remarks:
  2992.  
  2993.    The session name is the string that is displayed in the title bar
  2994.    of an open session.  It is also displayed in some of the
  2995.    Phonebook views.
  2996.  
  2997. Return Value:
  2998.  
  2999.    Returns 0 if successful. Otherwise, a standard API error code.
  3000.  
  3001. See Also:
  3002.  
  3003.    haGetSessionDataString
  3004.  
  3005.  
  3006. haGetSessionDataString
  3007.  
  3008. Returns one of the 20 internal data strings associated the
  3009. session.
  3010.  
  3011. Syntax:
  3012.  
  3013.    INT haGetSessionDataString(ScriptHandle, nIndex, nSize,
  3014.        pszBuffer)
  3015.  
  3016. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3017.  
  3018. INT nIndex                          Indicates which string to return
  3019.  
  3020. INT nSize                           The size of the following buffer
  3021.  
  3022. LPSTR pszBuffer                     A pointer to a buffer
  3023.  
  3024. Arguments:
  3025.  
  3026.    ScriptHandle
  3027.  
  3028.       The script handle returned from haInitialize.
  3029.  
  3030.    nIndex
  3031.  
  3032.       An index (0 - 19) indicating which string is to be returned.
  3033.  
  3034. nSize
  3035.  
  3036.       The size of the following buffer.
  3037.  
  3038.    pszBuffer
  3039.  
  3040.       A pointer to a buffer that is to receive the data string.
  3041.  
  3042. Remarks:
  3043.  
  3044.    Each session has 20 internal data strings associated with it.
  3045.    The first ten strings are always blank when a session is opened.
  3046.    They can be used in situations where new data must be received
  3047.    before being used.  The second ten strings are stored in the
  3048.    session file when a session is closed and restored when the
  3049.    session is reopened.  You can use these strings in a program for
  3050.    storing user settings, file locations, etc.
  3051.  
  3052. Return Value:
  3053.  
  3054.    Returns 0 if successful.  Otherwise, a standard API error code.
  3055.  
  3056. See Also:
  3057.  
  3058.    haSetSessionDataString
  3059.  
  3060.  
  3061. haGetTextFromScreen
  3062.  
  3063. Returns text from the emulator screen.
  3064.  
  3065. Syntax:
  3066.  
  3067.    INT haGetTextFromScreen(ScriptHandle, nRow, nCol, nCount,
  3068.        pszBuffer)
  3069.  
  3070. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3071.  
  3072. INT nRow                            The row number
  3073.  
  3074. INT nCol                            The column number
  3075.  
  3076. INT nCount                          The number of bytes to return
  3077.  
  3078. LPSTR pszBuffer                     A pointer to a buffer
  3079.  
  3080. Arguments:
  3081.  
  3082.    ScriptHandle
  3083.  
  3084.       The script handle returned from haInitialize.
  3085.  
  3086.    nRow
  3087.  
  3088.       The row number used to address the screen. Addresses start at
  3089.       zero and are limited by the emulator in use.
  3090.  
  3091.    nCol
  3092.  
  3093.       The column number used to address the screen.  Addresses start
  3094.       at zero and are limited by the emulator in use.
  3095.  
  3096.    nCount
  3097.  
  3098.       The number of characters of text to return.
  3099.  
  3100.    pszBuffer
  3101.  
  3102.       A pointer to a buffer large enough to hold the specified
  3103.       number of characters.
  3104.  
  3105. Remarks:
  3106.  
  3107.    Row and column addresses start at zero and are limited by the
  3108.    emulator.  You can retrieve text from only one row at a time.
  3109.  
  3110. Return Value:
  3111.  
  3112.    Returns 0 if successful.  Otherwise, a standard API error code.
  3113.  
  3114. See Also:
  3115.  
  3116.    haGetInput, haTypeText
  3117.  
  3118. Example:
  3119.  
  3120. /* -------------------------------------------------------------- */
  3121.  
  3122. /* Get text from specific screen positions.
  3123.    This program segment:
  3124.   - Requests 10 characters starting at screen position 0,35 where 0
  3125.     is vertical position (from top), 35 is horizontal position (from
  3126.     left).  */
  3127.  
  3128. ReturnCode = haGetTextFromScreen(ScriptHandle, 0, 35, 10, Buffer);
  3129.  
  3130. /* -------------------------------------------------------------- */
  3131.  
  3132.  
  3133. haGetVersion
  3134.  
  3135. Returns a string indicating the version of HyperACCESS.
  3136.  
  3137. Syntax:
  3138.  
  3139.    INT haGetVersion(ScriptHandle, nSize, pszBuffer)
  3140.  
  3141. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3142.  
  3143. INT nSize                           The size of the following buffer
  3144.  
  3145. LPSTR pszBuffer                     A pointer to a buffer
  3146.  
  3147. Arguments:
  3148.  
  3149.    ScriptHandle
  3150.  
  3151.       The script handle returned from haInitialize.
  3152.  
  3153.    nSize
  3154.  
  3155.      The size of the following buffer.
  3156.  
  3157.    pszBuffer
  3158.  
  3159.        A pointer to a buffer that is to receive the version number
  3160.        string.  Remarks:  The version number is returned formatted
  3161.        as a string.
  3162.  
  3163. Return Value:
  3164.  
  3165.    Returns 0 if successful.  Otherwise, a standard API error code.
  3166.  
  3167. Example:
  3168.  
  3169. /* -------------------------------------------------------------- */
  3170.  
  3171. /* Gets HyperACCESS version number, and display it.
  3172.    This program segment:
  3173.   - Gets HyperACCESS version number
  3174.   - Uses a standard C function to write formatted data to a string
  3175.   - Displays the version number in a message box that only accept on
  3176.     OK response. */
  3177.  
  3178. ReturnCode = haGetVersion(ScriptHandle, strlen(Vers), Vers);
  3179. sprintf(Buffer, "Version:  %s", Vers);
  3180. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", Buffer, 0, 0,
  3181.                HA_MB_OK);
  3182. /* -------------------------------------------------------------- */
  3183.  
  3184.  
  3185. haGetWindowStateBits
  3186.  
  3187. Returns a group of flags (bits) that describe the visibility and
  3188. state of HyperACCESS.
  3189.  
  3190. Syntax:
  3191.  
  3192.    INT haGetWindowStateBits(ScriptHandle)
  3193.  
  3194. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3195.  
  3196. Arguments:
  3197.  
  3198.    ScriptHandle
  3199.  
  3200.       The script handle returned from haInitialize.
  3201.  
  3202. Remarks:
  3203.  
  3204.    The integer value returned has flags (bits) which are either TRUE
  3205.    (1) or FALSE (0).  Determining the value of individual bits is
  3206.    language dependent.  However, in C, you can test the value of a
  3207.    particular bit by performing a bitwise AND operation of the
  3208.    returned value with the desired flag name defined below.
  3209.  
  3210. Return Value:
  3211.  
  3212.    Any of the following flags may be ORed together and returned if
  3213.    the call is successful.  Otherwise, a standard API error code is
  3214.    returned.
  3215.  
  3216.    Value                            Meaning
  3217.  
  3218.    HA_FRAME_IS_ACTIVE               The frame is active.
  3219.  
  3220.    HA_FRAME_IS_ICONIC               The frame is iconic.
  3221.  
  3222.    HA_SESSION_IS_ACTIVE             The session is active.
  3223.  
  3224.    HA_SESSION_IS_ICONIC             The session is iconic.
  3225.  
  3226. See Also:  haGetSession, haSetSession
  3227.  
  3228.  
  3229. haGetXferDirectory
  3230.  
  3231. Returns the default transfer directory for the current session.
  3232.  
  3233. Syntax:
  3234.  
  3235.    INT haGetXferDirectory(ScriptHandle, nDirection, nSize,
  3236.        pszBuffer)
  3237.  
  3238. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3239.  
  3240. INT nDirection                      Select which directory
  3241.  
  3242. INT nSize                           The size of the following buffer
  3243.  
  3244. LPSTR pszBuffer                     A pointer to a buffer
  3245.  
  3246. Arguments:
  3247.  
  3248.    ScriptHandle
  3249.  
  3250.       The script handle returned from haInitialize.
  3251.  
  3252.    nDirection
  3253.  
  3254.       Selects sending or receiving.
  3255.  
  3256.    Value                            Meaning
  3257.  
  3258.    HA_XFER_SEND                     Selects the sending directory.
  3259.  
  3260.    HA_XFER_RECV                     Selects the receiving directory.
  3261.  
  3262.    nSize
  3263.  
  3264.       The size of the following buffer.
  3265.  
  3266.    pszBuffer
  3267.  
  3268.       A pointer to a buffer to receive the name of the transfer
  3269.       directory.
  3270.  
  3271. Remarks:
  3272.  
  3273.    The buffer should be large enough to accomodate a complete path.
  3274.  
  3275. Return Value:
  3276.  
  3277.    Returns 0 if successful.  Otherwise, a standard API error code.
  3278.  
  3279. See Also:
  3280.  
  3281.    haSetXferDirectory
  3282.  
  3283. Example:
  3284.  
  3285. /* -------------------------------------------------------------- */
  3286.  
  3287. /* Get (and set) directory path to receive files.  This program
  3288.    segment:
  3289.   - Gets default receive directory path.
  3290.   - Use a message box to ask if the user wants to change the default
  3291.     path.
  3292.   - If the user responds Yes, request a new directory path using a
  3293.     message box.
  3294.   - Sets the new directory as the default.  */
  3295.  
  3296. ReturnCode = haGetXferDirectory(ScriptHandle, HA_XFER_RECV,
  3297.                strlen(DName), DName);
  3298. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS:",
  3299.            "Change Receive Directory Path?", 0, 0, HA_MB_YN);
  3300. if (ReturnCode == 1)
  3301.    {
  3302.    SubReturnCode = haMessageBox(ScriptHandle, "HyperACCESS:",
  3303.            "Enter Receive Directory:", strlen(DName), DName,
  3304.             HA_MB_OK);
  3305.    SubReturnCode = haSetXferDirectory(ScriptHandle, HA_XFER_RECV,
  3306.             DName);
  3307.    }
  3308.  
  3309. /* -------------------------------------------------------------- */
  3310.  
  3311.  
  3312. haGetXferDropList
  3313.  
  3314. Returns a path and filename from an internal list of files
  3315. dropped on the session.
  3316.  
  3317. Syntax:
  3318.  
  3319.    INT haGetXferDropList(ScriptHandle, nIndex, nSize, pszBuffer)
  3320.  
  3321. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3322.  
  3323. INT nIndex                          Which item to return
  3324.  
  3325. INT nSize                           The size of the following buffer
  3326.  
  3327. LPSTR pszBuffer                     A pointer to a buffer
  3328.  
  3329. Arguments:
  3330.  
  3331.    ScriptHandle
  3332.  
  3333.       The script handle returned from haInitialize.
  3334.  
  3335.    nIndex
  3336.  
  3337.       Selects which item in the list of dropped files is to be
  3338.       returned.  Selections start at zero.
  3339.  
  3340.    nSize
  3341.  
  3342.       The size of the following buffer.
  3343.  
  3344.    pszBuffer
  3345.  
  3346.       A pointer to a buffer that is to receive the filename from the
  3347.       list of dropped files.
  3348.  
  3349. Remarks:
  3350.  
  3351.    HyperACCESS supports drag and drop operations on open sessions as
  3352.    well as selected dialog boxes.  When files are dropped on an open
  3353.    session, an external task is run to handle the dropped files.
  3354.    Use this function to get the path and filename of dropped files
  3355.   from the list, one at a time.
  3356.  
  3357. Return Value:
  3358.  
  3359.    Returns 0 if successful.  Otherwise, a standard API error code.
  3360.  
  3361. See Also:
  3362.  
  3363. haClearXferDropList, haGetXferSendList, haXferDropSend
  3364.  
  3365.  
  3366. haGetXferFinalStatus
  3367.  
  3368. Returns the final status of the most recent file transfer.
  3369.  
  3370. Syntax:
  3371.  
  3372.    INT haGetXferFinalStatus(ScriptHandle)
  3373.  
  3374. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3375.  
  3376. Arguments:
  3377.  
  3378.    ScriptHandle
  3379.  
  3380.       The script handle returned from haInitialize.
  3381.  
  3382. Remarks:
  3383.  
  3384.    A file transfer started with nFlag TRUE completes before the
  3385.    function call returns (see haXferReceive, haXferSend,
  3386.    haXferDropSend).  In that case, call haGetXferFinalStatus upon
  3387.    return from function that initiated transfer to get the final
  3388.    status.  If nFlag is FALSE, the function call that starts the
  3389.    transfer returns while transfer continues.  In that case,
  3390.    haGetXferStatus can monitor progress of the transfer.  When
  3391.    haGetXferStatus or haWaitForXfer indicates that transfer has
  3392.    completed, use haGetXferFinalStatus to determine whether the
  3393.    transfer completed successfully.
  3394.  
  3395. Return Value:
  3396.  
  3397.    Returns one of the following values if successful.  Otherwise, a
  3398.    standard API error code.
  3399.  
  3400.    Value                            Meaning
  3401.  
  3402.    HA_XFS_OK                        Transfer completed successfully.
  3403.  
  3404.    HA_XFS_RMT_CANNED                Transfer cancelled at other end.
  3405.  
  3406.    HA_XFS_USER_CANNED               Transfer cancelled locally (by
  3407.                                     the user).
  3408.  
  3409.    HA_XFS_LOST_CARRIER              Carrier lost during transfer.
  3410.  
  3411.    HA_XFS_ERROR_LIMIT               The protocol-defined error limit
  3412.                                     exceeded.
  3413.  
  3414.    HA_XFS_NO_RESPONSE               The remote end of the transfer
  3415.                                     stopped responding.
  3416.  
  3417.    HA_XFS_OUT_OF_SEQ                A protocol packet was received
  3418.                                     out-of- sequence and recovery
  3419.                                     was not possible.
  3420.  
  3421.    HA_XFS_BAD_FORMAT                A protocol packet was received
  3422.                                     with a correct checksum but with
  3423.                                     an illegal format.
  3424.  
  3425.    HA_XFS_TOO_MANY                  The remote sender tried to send
  3426.                                     multiple files but the receiver
  3427.                                     could accept only one.
  3428.  
  3429.    HA_XFS_DISK_FULL                 The disk filled up before
  3430.                                     transfer completed
  3431.  
  3432.    HA_XFS_CANT_OPEN                 A file could not be opened to
  3433.                                     store a received file.
  3434.  
  3435.    HA_XFS_DISK_ERROR                A disk error occurred during
  3436.                                     transfer.
  3437.  
  3438.    HA_XFS_NO_MEM                    The program could not allocate
  3439.                                     sufficient memory to complete
  3440.                                     transfer.
  3441.  
  3442.    HA_XFS_FILE_EXISTS               A file was received with the
  3443.                                     same name as an existing file
  3444.                                     and no option to rename the file
  3445.                                     was specified.
  3446.  
  3447.    HA_XFS_COMPLETE                  The transfer completed
  3448.                                     successfully.
  3449.  
  3450.    HA_XFS_CANT_START                The protocol could not
  3451.                                     successfully negotiate start of
  3452.                                     a transfer.
  3453.  
  3454.    HA_XFS_OLDER_FILE                An option to accept only newer
  3455.                                     files was specified, and the
  3456.                                     received file is older than the
  3457.                                     existing file.
  3458.  
  3459.    HA_XFS_NO_FILETIME               An option to accept only newer
  3460.                                     files was specified, and the
  3461.                                     sender did not include the date
  3462.                                     and time of the file being sent.
  3463.  
  3464.    HA_XFS_WONT_CANCEL               An attempt was made to negotiate
  3465.                                     a graceful cancel of the
  3466.                                     transfer with the remote system,
  3467.                                     but it did not respond to the
  3468.                                     request.
  3469.  
  3470. HA_XFS_GEN_FAILURE                  Any error not explicitly covered
  3471.                                     in the other return codes.
  3472.  
  3473. HA_XFS_USER_SKIP                    The user used the skip button.
  3474.  
  3475. HA_XFS_REFUSE                       The remote system refused to
  3476.                                     accept a file that we attempted
  3477.                                     to send.
  3478.  
  3479. See Also:
  3480.  
  3481.    haGetXferStatus, haWaitForXfer, haXferSend, haXferReceive
  3482.  
  3483.  
  3484. haGetXferParameters
  3485.  
  3486. Returns an integer value composed of flags (bits) that determine
  3487. how a transfer operation is carried out.
  3488.  
  3489. Syntax:
  3490.  
  3491.    INT haGetXferParameters(ScriptHandle)
  3492.  
  3493.       SCRIPTHANDLE ScriptHandle     The program - HyperACCESS link
  3494.  
  3495. Arguments:
  3496.  
  3497.    ScriptHandle
  3498.  
  3499.       The script handle returned from haInitialize.
  3500.  
  3501. Remarks:
  3502.  
  3503.    The integer value returned has flags (bits) which are either TRUE
  3504.    (1) or FALSE (0).  Determining the value of individual bits is
  3505.    language dependent.  However, in C, you can test the value of a
  3506.    particular bit by performing a bitwise AND operation of the
  3507.    returned value with the desired flag name defined below.  Keep in
  3508.    mind that some file transfer protocols, such as Xmodem, have no
  3509.    provision for sending filenames, file sizes, or modification
  3510.    times with files.
  3511.  
  3512. Return Value:
  3513.  
  3514.    Returns one or more of the following flags, if successful.
  3515.    Otherwise, a standard API error code.
  3516.  
  3517.    Value                            Meaning
  3518.  
  3519.    XF_DN_MASK                       A mask for the next 6 flags.
  3520.                                     These flags are used if the
  3521.                                     selected filename is already
  3522.                                     being used.
  3523.  
  3524.    XF_DN_APPEND                     Append if filename is already
  3525.                                     used.  XF_DN_OVERWRT Overwrite
  3526.                                     if filename is already used.
  3527.  
  3528.    XF_DN_REFUSE                     Refuse the transfer if filename
  3529.                                     is already used.  Value Meaning
  3530.  
  3531.    XF_DN_NEWER                      Overwrite if the received file
  3532.                                     is newer than the current file.
  3533.  
  3534.    XF_DN_DATE                       Generate a new filename based on
  3535.                                     the old name and the current
  3536.                                     date.
  3537.  
  3538.    XF_DN_SEQ                        Generate a new filename based on
  3539.                                     the old name and a sequence
  3540.                                     number.
  3541.  
  3542.    XF_CHECK_VIRUS                   Enable virus detection.
  3543.  
  3544.    XF_USE_FILENAME                  Use received filename, if any,
  3545.                                     in naming file.
  3546.  
  3547.    XF_USE_DIRECTORY                 Use received directory, if any,
  3548.                                     in naming file.
  3549.  
  3550.    XF_SAVE_PARTIAL                  Save partial file if transfer is
  3551.                                     interrupted.
  3552.  
  3553.    XF_USE_DATETIME                  Use received file date and time,
  3554.                                     if any.
  3555.  
  3556. See  Also:
  3557.  
  3558.    haSetXferParameters, haXferReceive, haXferSend
  3559.  
  3560. Example:
  3561.  
  3562. /* -------------------------------------------------------------- */
  3563.  
  3564. /* Check a current transfer parameter, and changes its value.
  3565.    This program segment:
  3566.   - Gets a current transfer parameter (checks save partial received
  3567.     files).
  3568.   - Sets transfer parameter (to save).  */
  3569.  
  3570. ReturnCode = haGetXferParameters(ScriptHandle);
  3571. if ( !(ReturnCode & XF_SAVE_PARTIAL) )
  3572.    {
  3573.    ReturnCode |= XF_SAVE_PARTIAL ; // Add save partial
  3574.    haSetXferParameters(ScriptHandle, ReturnCode);
  3575.    }
  3576. /* -------------------------------------------------------------- */
  3577.  
  3578.  
  3579. haGetXferProtocol
  3580.  
  3581. Returns the current default transfer protocol.
  3582.  
  3583. Syntax:
  3584.  
  3585.    INT haGetXferProtocol(ScriptHandle, nDirection)
  3586.  
  3587. SCRIPTHANDLE ScriptHandle           The program - HyperACCESS link
  3588.  
  3589. INT nDirection                      Selects send or receive
  3590.  
  3591. Arguments:
  3592.  
  3593.    ScriptHandle
  3594.  
  3595.       The script handle returned from haInitialize.
  3596.  
  3597.    nDirection
  3598.  
  3599.       Selects sending or receiving.
  3600.  
  3601.    Value                            Meaning
  3602.  
  3603.    HA_XFER_SEND                     Gets the sending method.
  3604.  
  3605.    HA_XFER_RECV                     Gets the receiving method.
  3606.  
  3607. Remarks:
  3608.  
  3609. Return Value:
  3610.  
  3611.    Returns one of the following values if successful.  Otherwise, a
  3612.    standard API error code.
  3613.  
  3614.    Value                            Meaning
  3615.  
  3616.    HA_HYPERP                        Hilgraeve's HyperProtocol.
  3617.  
  3618.    HA_COMPUSERV_B                   CompuServe B+.
  3619.  
  3620.    HA_KERMIT                        Kermit.
  3621.  
  3622.    HA_XMODEM                        XMODEM.
  3623.  
  3624.    HA_XMODEM_1K                     1K XMODEM.
  3625.  
  3626.    HA_YMODEM                        YMODEM.
  3627.  
  3628.    HA_YMODEM_G                      YMODEM-G.
  3629.  
  3630.    HA_ZMODEM                        ZMODEM.
  3631.  
  3632. See Also:
  3633.  
  3634.    haSetXferProtocol, haXferReceive, haXferSend
  3635.  
  3636.  
  3637. haGetXferSendList
  3638.  
  3639. Returns a path and filename from the internal file send list.
  3640.  
  3641. Syntax:
  3642.  
  3643.    INT haGetXferSendList(ScriptHandle, nIndex, nSize,
  3644.        pszBuffer)
  3645.  
  3646.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3647.  
  3648.    INT nIndex                       Which item to return
  3649.  
  3650.    INT nSize                        The size of the following buffer
  3651.  
  3652.    LPSTR pszBuffer                  A pointer to a buffer
  3653.  
  3654. Arguments:
  3655.  
  3656.    ScriptHandle
  3657.  
  3658.       The script handle returned from haInitialize.
  3659.  
  3660.    nIndex
  3661.  
  3662.       Selects which item in the list of files is to be returned.
  3663.       Selections start at zero.
  3664.  
  3665.    nSize
  3666.  
  3667.       The size of the following buffer.  The buffer should be large
  3668.       enough to accomodate a complete path and filename.
  3669.  
  3670.    pszBuffer
  3671.  
  3672.       A pointer to a buffer that is to receive the path and filename
  3673.       from the list of files.
  3674.  
  3675. Remarks:
  3676.  
  3677.     You can build a list of files that HyperACCESS maintains
  3678.     internally and then send all files in the list by using
  3679.     haXferSendFromList.  Files are normally added to the list by
  3680.     haXferAddToSendList.  You can examine the list using this
  3681.     function.
  3682.  
  3683. Return Value:
  3684.  
  3685.    Returns 0 if successful.  Otherwise, a standard API error code.
  3686.  
  3687. See Also:
  3688.  
  3689.    haClearXferSendList, haXferAddToList, haGetXferDropList,
  3690.    haXferSendFromList
  3691.  
  3692.  
  3693. haGetXferStatus
  3694.  
  3695. Returns a percentage value that indicates how much of a transfer
  3696. has completed.
  3697.  
  3698. Syntax:
  3699.  
  3700.   INT haGetXferStatus(ScriptHandle)
  3701.  
  3702.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3703.  
  3704. Arguments:
  3705.  
  3706.    ScriptHandle
  3707.  
  3708.       The script handle returned from haInitialize.
  3709.  
  3710. Remarks:
  3711.  
  3712.    The number returned is between 0 and 99. This function is only
  3713.    useful if a transfer is started with the nFlag argument set
  3714.    FALSE.  See the remarks under haXferSendFromList for an
  3715.    explanation.
  3716.  
  3717. Return Value:
  3718.  
  3719.    Returns 0 thru 99 if successful.  Otherwise, a standard API error
  3720.    code.
  3721.  
  3722. See Also:
  3723.  
  3724.    haWaitForXfer, haXferReceivehaXferSend, haXferSendBatch,
  3725.    haXferSendFromList, haXferSendList
  3726.  
  3727.  
  3728. haHideInput
  3729.  
  3730. Disables (or enables) emulator display operation.
  3731.  
  3732. Syntax:
  3733.  
  3734.    INT haHideInput(ScriptHandle, nFlag)
  3735.  
  3736.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3737.  
  3738.    INT nFlag                         Enable or disable display of
  3739.                                      input characters.
  3740.  
  3741. Arguments:
  3742.  
  3743.    ScriptHandle The script handle returned from haInitialize.
  3744.    Argument If TRUE, disable display of characters via the emulator.
  3745.    If FALSE, enable display of characters via the emulator.
  3746.  
  3747. Remarks:
  3748.  
  3749.    Normally, received characters are passed to the emulator to be
  3750.    displayed.  This function disables (or enables) passing
  3751.    characters.  When emulator display is disabled, received
  3752.    characters are still processed normally in other respects:  they
  3753.    can be captured, matched, printed, etc.
  3754.  
  3755. Return Value:
  3756.  
  3757.    Returns 0 if successful.  Otherwise, a standard API error code.
  3758.  
  3759. Example:
  3760.  
  3761. /* -------------------------------------------------------------- */
  3762.  
  3763. /* Hide received characters.
  3764.    This program segment:
  3765.   - Hides received characters.
  3766.   - Waits for a carriage return (or 30 seconds).
  3767.   - Enables display of received characters after one line */
  3768.  
  3769. ReturnCode = haHideInput(ScriptHandle, TRUE);
  3770. ReturnCode = haWaitForLines(ScriptHandle, 1, 30000L);
  3771. ReturnCode = haHideInput(ScriptHandle, FALSE);
  3772.  
  3773. /* -------------------------------------------------------------- */
  3774.  
  3775.  
  3776. haInitialize
  3777.  
  3778. This required function must be called before any other API
  3779. functions.  The arguments for haInitialize are operating system
  3780. dependent, so a program that runs on multiple platforms will
  3781. require conditional compilation to account for the different
  3782. calling sequences.
  3783.  
  3784. HA/OS2 Syntax:
  3785.  
  3786.    SCRIPTHANDLE haInitialize(argc, argv)
  3787.  
  3788.    INT argc                         Number of arguments in the
  3789.                                     command line
  3790.  
  3791.    PSZ* argv                        Array of pointers to strings of
  3792.                                     command line arguments
  3793.  
  3794. HA/Win95 Syntax:
  3795.  
  3796.    SCRIPTHANDLE haInitialize(lpCmdLine)
  3797.  
  3798.    LPSTR lpCmdLine                  The command line
  3799.  
  3800. HA/Win Syntax:
  3801.  
  3802.    SCRIPTHANDLE haInitialize(hParentHwnd, hInst, hPrevInst,
  3803.                              lpCmdLine)
  3804.  
  3805.    HWND hParentHwnd                 The parent window handle
  3806.  
  3807.    HANDLE hInst                     The current instance handle
  3808.  
  3809.    HANDLE hPrevInst                 The previous instance handle
  3810.  
  3811.    LPSTR lpCmdLine                  The command line
  3812.  
  3813. Arguments:
  3814.  
  3815.    argc
  3816.  
  3817.       A count of the number of arguments in the command line.  This
  3818.       value is returned by OS/2.
  3819.  
  3820.    argv
  3821.  
  3822.       An array of pointers to strings of command line arguments.
  3823.       This array is provided by OS/2.
  3824.  
  3825.    hParentHwnd
  3826.  
  3827.       A window handle that the external API is to be a child of.
  3828.  
  3829.    hInst
  3830.  
  3831.       The current instance of the task.
  3832.  
  3833.    hPrevInst
  3834.  
  3835.       The previous instance of the task, if any.
  3836.  
  3837.    lpCmdLine
  3838.  
  3839.       The command line that started the task.
  3840.  
  3841. Remarks:
  3842.  
  3843.    This function performs necessary initialization so that an
  3844.    external API task can communicate with HyperACCESS.  It must be
  3845.    called before any other external API function is called.  All of
  3846.    the parameters are those generally passed in to a C program by
  3847.    the operating system. Programmers using C or a similar Software
  3848.    Development Kit (SDK) should pass the parameters to haInitialize
  3849.    without modification.  For Visual Basic there is no WinMain entry
  3850.    point available to the user.  Visual Basic users need to use the
  3851.    Command$ function to retrieve the command line.  The C
  3852.    interpreter used by HyperACCESS is a special case.  The function
  3853.    must be called, but the parameters may be NULL, because WinMain
  3854.    is handled internally.  Users of other SDKs are encouraged to
  3855.    search appropriate documentation to find the necessary functions.
  3856.    A single external program may call haInitialize more than once to
  3857.    create multiple simultaneous control scripts.  Doing so allows
  3858.    the program to execute multiple tasks in HyperACCESS
  3859.    simultaneously or to control more than one HyperACCESS session at
  3860.    the same time.  Each call to haInitialize must be matched with a
  3861.    call to haTerminate when the program is done.
  3862.  
  3863. Return Value:
  3864.  
  3865.    Returns an external API script handle if successful.  Otherwise,
  3866.    zero.
  3867.  
  3868. See Also: haTerminate
  3869.  
  3870.  
  3871. haLearnControl
  3872.  
  3873. Turns learning(recording) on or off for the currently active
  3874. session.
  3875.  
  3876. Syntax:
  3877.  
  3878.    INT haLearnControl(ScriptHandle, nCmd)
  3879.  
  3880.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3881.  
  3882.    INT nCmd                         The control command
  3883.  
  3884. Arguements:
  3885.  
  3886.    ScriptHandle
  3887.  
  3888.       The script handle returned from haInitialize.
  3889.  
  3890.    nCmd
  3891.  
  3892.       This is a constant value that represents the command to be
  3893.       applied to the HyperACCESS learning(recording) system.
  3894.  
  3895.    Value                            Meaning
  3896.  
  3897.    HA_L_START                       Start learning(recording).
  3898.  
  3899.    HA_L_STOP                        Stop learning(recording) and
  3900.                                     save the learned script in the
  3901.                                     default file.
  3902.  
  3903.    HA_L_ABORT                       Stop learning(recording) but do
  3904.                                     not save the learned script.
  3905.  
  3906. Remarks:
  3907.  
  3908. Return Value:
  3909.  
  3910.    Returns 0 if successful.  Otherwise, a standard API error code.
  3911.  
  3912. See Also:
  3913.  
  3914.    haSetLearnFileName, haCaptureControl
  3915.  
  3916.  
  3917. haMenuString
  3918.  
  3919. Performs HyperACCESS menu actions as if mnemonic keystrokes were
  3920. used.
  3921.  
  3922. Syntax:
  3923.  
  3924.    INT haMenuString(ScriptHandle, pszString)
  3925.  
  3926.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3927.  
  3928.    LPSTR pszString                  A pointer to a string of
  3929.                                     characters terminated by a
  3930.                                     null
  3931. Arguments:
  3932.  
  3933.    ScriptHandle
  3934.  
  3935.       The script handle returned from haInitialize.
  3936.  
  3937.    pszString
  3938.  
  3939.       A pointer to a string of characters representing menu actions.
  3940.       For example, "FX" would represent the menu selections File and
  3941.       Exit.  Remarks:  This function lets a programmer perform
  3942.       actions in HyperACCESS by specifying the menu mnemonic
  3943.       keystrokes that would perform the operation.  This function
  3944.       can be said to follow the menus to perform the requested
  3945.       function.  For example, to exit HyperACCESS the string "FX"
  3946.       for File and Exit would be used.
  3947.  
  3948. Return Value:
  3949.  
  3950.    Returns 0 if successful.  Otherwise, a standard API error code.
  3951.  
  3952. Example:
  3953.  
  3954. /* -------------------------------------------------------------- */
  3955.  
  3956. /* Let the user set default transfer protocols.
  3957.    This program segment:
  3958.   - Uses the Properties/Transfer Protocols...  menu item
  3959.     to display the File Transfer properties sheet (Transfer
  3960.     Protocols dialog in HA/Win) so the user can select new
  3961.     protocols.  */
  3962.  
  3963. ReturnCode = haMenuString(ScriptHandle, "PT");
  3964.  
  3965. /* -------------------------------------------------------------- */
  3966.  
  3967.  
  3968. haMessageBox
  3969.  
  3970. Displays a dialog box and accepts keyboard or mouse input from
  3971. the user.
  3972.  
  3973. Syntax:
  3974.  
  3975.    INT haMessageBox(ScriptHandle, pszTitle, pszMessage, nSize,
  3976.        pszBuffer, nButtons)
  3977.  
  3978.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  3979.  
  3980.    LPSTR pszTitle                   The title of the message box
  3981.  
  3982.    LPSTR pszMessage                 The message to be displayed
  3983.  
  3984.    INT nSize                        The size of the following buffer
  3985.  
  3986.    LPSTR pszBuffer                  A pointer to a buffer
  3987.  
  3988.    INT nButtons                     What buttons to display
  3989.  
  3990. Arguments:
  3991.  
  3992.    ScriptHandle
  3993.  
  3994.       The script handle returned from haInitialize.
  3995.  
  3996.    pszTitle
  3997.  
  3998.       The title of the message box.  No commas or NULLs are allowed.
  3999.  
  4000.    pszMessage
  4001.  
  4002.       The message in the message box.  No commas or NULLs are
  4003.       allowed.
  4004.  
  4005.    nSize
  4006.  
  4007.       The size of the following buffer.  If the message box does not
  4008.       need an input field, this must be set to zero.
  4009.  
  4010.    pszBuffer
  4011.  
  4012.       A pointer to a buffer to receive user keyboard input.  If the
  4013.       message box does not need an input field, this pointer must be
  4014.       set to NULL.
  4015.  
  4016.    nButtons
  4017.  
  4018.       The following button groups are available:
  4019.  
  4020.    Value                            Meaning
  4021.  
  4022.    HA_MB_OK                         Use a single OK button
  4023.  
  4024.    HA_MB_OKC                        Use OK and Cancel buttons.
  4025.  
  4026.    HA_MB_YN                         Use Yes and No buttons.
  4027.  
  4028. Remarks:
  4029.  
  4030.    This function brings up a dialog box similar to a HyperACCESS
  4031.    display box.  It allows the external API task to display messages
  4032.    on the local desktop and get local input.  The external task is
  4033.    not required to use this function to create a message box.  It
  4034.    can use standard operating system function calls instead.  This
  4035.    function is made available as a helpful alternative.
  4036.  
  4037. Return Value:
  4038.  
  4039.    Returns 0 if Cancel or No is selected, 1 if OK or Yes is
  4040.    selected.  Otherwise, a standard API error code.
  4041.  
  4042.  
  4043. haNotifyOnTerminate
  4044.  
  4045. Posts a message to a specified Window when the session closes.
  4046.  
  4047. Syntax:
  4048.  
  4049.    INT haNotifyOnTerminate(ScriptHandle, hWnd, nMsg)
  4050.  
  4051.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4052.  
  4053. HWND hWnd                           A window handle to post to
  4054.  
  4055. INT nMsg                            The message to be posted
  4056.  
  4057. Arguments:
  4058.  
  4059.    ScriptHandle
  4060.  
  4061.       The script handle returned from haInitialize.
  4062.  
  4063.    hWnd
  4064.  
  4065.      The handle of the window that the following message is to be
  4066.      posted to.
  4067.  
  4068.    nMsg
  4069.  
  4070.       The message that is to be posted to the previous window
  4071.       handle.
  4072.  
  4073. Remarks:
  4074.  
  4075.    Posting messages across tasks is not a standard method in a
  4076.    Windows program.  However, it can sometimes be useful.  In this
  4077.    case, the message is posted if the script handle is still valid
  4078.    and the window handle is still valid.  There is no type of
  4079.    checking done on the message.  It is up to the user to correctly
  4080.    deal with it.
  4081.  
  4082. Return Value:
  4083.  
  4084.    Returns 0 if successful.  Otherwise, a standard API error code.
  4085.  
  4086. See Also:
  4087.  
  4088.    haGetHWND
  4089.  
  4090.  
  4091. haOpenSession
  4092.  
  4093. Opens an existing phonebook entry.  In HA/OS2 and HA/Win95,
  4094. displays the Terminal panel.  In HA/Win, opens a new session
  4095. window.
  4096.  
  4097. Syntax:
  4098.  
  4099.    HSESS haOpenSession(ScriptHandle, pszName)
  4100.  
  4101.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4102.  
  4103.    LPSTR pszName                    Name of a session file
  4104.  
  4105. Arguments:
  4106.  
  4107.    ScriptHandle
  4108.  
  4109.       The script handle returned from haInitialize.
  4110.  
  4111.    pszName
  4112.  
  4113.        The path and filename of the session file to use.
  4114.  
  4115. Remarks:
  4116.  
  4117.    The session is not connected when it is initially opened.
  4118.    The newly opened session becomes the current session for the
  4119.    script.  In HA/Win, a script can interact with several sessions
  4120.    simultaneously by storing the session handles in variables and
  4121.    using haSetSession to move among them.  In HA/OS2 and HA/Win95,
  4122.    there is only one session for each instance of HyperACCESS, so
  4123.    you must call haInitialize for each instance and use the correct
  4124.    script handle.
  4125.  
  4126. Return Value:
  4127.  
  4128.    Returns a session handle if successful. Otherwise, a standard API
  4129.    error code.
  4130.  
  4131. See Also:
  4132.  
  4133.    haCloseSession, haConnectSession, haGetPhonebookEntry,
  4134.    haGetSession, haInitialize, haSetSession
  4135.  
  4136.  
  4137. haPause
  4138.  
  4139. Causes the API interface to enter the HyperACCESS server idle
  4140. loop for a specified period of time.
  4141.  
  4142. Syntax:
  4143.  
  4144.    haPause (ScriptHandle, lTime)
  4145.  
  4146.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4147.  
  4148.    LONG lTime                       How long to pause
  4149.  
  4150. Arguments:
  4151.  
  4152.    ScriptHandle
  4153.  
  4154.       The script handle returned from haInitialize.
  4155.  
  4156.    lTime
  4157.  
  4158.        The amount of time to pause, measured in milliseconds.
  4159.  
  4160. Remarks:
  4161.  
  4162.    Similar to haSleep.  While an application pauses, the session
  4163.    neither sends nor receives characters.  During this time,
  4164.    however, system messages continue to be dispatched to prevent the
  4165.    Windows environment from becoming inactive.
  4166.  
  4167. Return Value:
  4168.  
  4169.    Returns 0 if successful.  Otherwise, a standard API error code.
  4170.  
  4171. See Also:
  4172.  
  4173.    haSleep
  4174.  
  4175.  
  4176. haReleaseRemoteInput
  4177.  
  4178. Decrements the counter used to determine how and when a session
  4179. processes characters.
  4180.  
  4181. Syntax:
  4182.  
  4183.    INT haReleaseRemoteInput(ScriptHandle)
  4184.  
  4185.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4186.  
  4187. Arguments:
  4188.  
  4189.    ScriptHandle
  4190.  
  4191.       The script handle returned from haInitialize.
  4192.  
  4193. Remarks:
  4194.  
  4195.    When the counter is greater than zero, a session does not process
  4196.    characters.  When the counter is zero, a session processes
  4197.    characters.  When a session is opened, the count is set to zero.
  4198.    If a script is run from within a session, the counter is
  4199.    incremented.  If the script exits from within a session, the
  4200.    counter is decremented.  If you create a script that doesn't
  4201.    process received characters using functions such as haGetInput or
  4202.    haWaitForPrompt, and you want the current session to continue to
  4203.    process received data normally,  you must call
  4204.    haReleaseRemoteInput for the session.  If you create scripts that
  4205.    change control among sever all sessions using haSetSession, you
  4206.    can use haBlockRemoteInput and haReleaseRemoteInput to control
  4207.    when the sessions process received data.  This ensures that your
  4208.    script doesn't miss any characters.
  4209.  
  4210. Return Value:
  4211.  
  4212.    Returns 0 if successful.  Otherwise, a standard API error code.
  4213.  
  4214. See Also:
  4215.  
  4216.    haBlockRemoteInput
  4217.  
  4218.  
  4219. haReloadPhonebook
  4220.  
  4221. Causes HyperACCESS to rescan for Phonebook files.
  4222.  
  4223. Syntax:
  4224.  
  4225.    INT haReloadPhonebook(ScriptHandle)
  4226.  
  4227.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4228.  
  4229. Arguments:
  4230.  
  4231.    ScriptHandle
  4232.  
  4233.       The script handle returned from haInitialize.
  4234.  
  4235. Remarks:
  4236.  
  4237.    This function is useful to notify HyperACCESS that something in
  4238.    Phonebook has changed.  If you add or remove session files from
  4239.    the phonebook directory or modify session files directly, you can
  4240.    use this function to force HyperACCESS to redisplay the phonebook
  4241.    with the changes.
  4242.  
  4243. Return Value:
  4244.  
  4245.    Returns 0 if successful.  Otherwise, a standard API error code.
  4246.  
  4247. See Also:
  4248.  
  4249.    haGetPhonebookEntry
  4250.  
  4251.  
  4252. haRestrictMenus
  4253.  
  4254. This function causes HyperACCESS to offer the user a very
  4255. restricted set of menus.
  4256.  
  4257. Syntax:
  4258.  
  4259.    INT haRestrictMenus(ScriptHandle, nMode)
  4260.  
  4261.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4262.  
  4263.    INT nMode                        Menu restriction mode
  4264.  
  4265. Arguements:
  4266.  
  4267.    ScriptHandle
  4268.  
  4269.       The script handle returned from haInitialize.
  4270.  
  4271.    nMode
  4272.  
  4273.       When the mode is set to TRUE, restricted menu access is
  4274.       activated.  When the mode is set to FALSE, restricted menus
  4275.       access is deactivated.
  4276.  
  4277. Remarks:
  4278.  
  4279. Return Value:
  4280.  
  4281.    Returns 0 if successful.  Otherwise, a standard API error code.
  4282.  
  4283.  
  4284. haSavePhonebook
  4285.  
  4286. Writes the HyperACCESS preferences file to disk.
  4287.  
  4288. Syntax:
  4289.  
  4290.    INT haSavePhonebook(ScriptHandle)
  4291.  
  4292.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4293.  
  4294. Arguments:
  4295.  
  4296.    ScriptHandle
  4297.  
  4298.       The script handle returned from haInitialize.
  4299.  
  4300. Remarks:
  4301.  
  4302.    HyperACCESS stores program-wide settings in its preferences file,
  4303.    .PRF.  It keeps this information in memory while it is running,
  4304.     and writes these settings to the disk file as it exits.  This
  4305.     function writes these settings to .PRF immediately.
  4306.  
  4307. Return Value:
  4308.  
  4309.    Returns 0 if successful.  Otherwise, a standard API error code.
  4310.  
  4311. See Also:
  4312.  
  4313.    haReloadPhonebook
  4314.  
  4315.  
  4316. haSelectDialingPrefix
  4317.  
  4318. Specifies the dialing prefix that is to be used by the current
  4319. session.
  4320.  
  4321. Syntax:
  4322.  
  4323.    INT haSelectDialingPrefix(ScriptHandle, nIndex)
  4324.  
  4325.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4326.    INT nIndex                       Which prefix to use
  4327.  
  4328. Arguments:
  4329.  
  4330.    ScriptHandle
  4331.  
  4332.       The script handle returned from haInitialize.  nIndex
  4333.       Specifies which prefix to use.  A value of zero means no
  4334.       prefix is used.  Valid choices are 1 - 9.
  4335.  
  4336. Remarks:
  4337.  
  4338.    HyperACCESS uses the dialing prefix as part of the phone number
  4339.    when it attempts to establish a connection.
  4340.  
  4341. Return Value:
  4342.  
  4343.    Returns 0 if successful.  Otherwise, a standard API error code.
  4344.  
  4345. See Also:
  4346.  
  4347.    haGetDialingPrefix, haSetDialingPrefix
  4348.  
  4349. Example:
  4350.  
  4351. /* -------------------------------------------------------------- */
  4352.  
  4353. /* Select dialing prefix.
  4354.    This program segment:
  4355.   - Selects the first dialing prefix as the one to use for this
  4356.     session */
  4357.  
  4358. ReturnCode = haSelectDialingPrefix(ScriptHandle, 1);
  4359.  
  4360. /* -------------------------------------------------------------- */
  4361.  
  4362.  
  4363. haSetAdlOverride
  4364.  
  4365. Changes the automatic download override setting.
  4366.  
  4367. Syntax:
  4368.  
  4369.    INT haSetAdlOverride(ScriptHandle, nFlag)
  4370.  
  4371.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4372.  
  4373.    INT nFlag                        The new setting of the automatic
  4374.                                     download override switch
  4375.  
  4376. Arguments:
  4377.  
  4378.    ScriptHandle
  4379.  
  4380.       The script handle returned from haInitialize.  nFlag
  4381.       If TRUE (non-zero), the automatic download feature for
  4382.       Hyperprotocol, and ZModem transfers is disabled.  If FALSE
  4383.      (zero), the automatic download capability is controlled by user
  4384.      settings available in the interface.
  4385.  
  4386. Remarks:
  4387.  
  4388.    This override of the setting in the HyperProtocol Settings and
  4389.    Zmodem Settings dialog boxes is not available from the user
  4390.    interface.  This override is available only when controlling
  4391.    HyperACCESS from an external program.  It allows you to disable
  4392.    the automatic downloading capabilities built into HyperACCESS to
  4393.    avoid situations where an automatic download might compromise
  4394.    security restrictions built into a program.
  4395.  
  4396. Return Value:
  4397.  
  4398.    Returns 0 if successful.  Otherwise, a standard API error code.
  4399.  
  4400. Example:
  4401.  
  4402. /* ------------------------------------------------------------- */
  4403.  
  4404. /* Turn off automatic download feature of Zmodem and
  4405.    HyperProtocol.  */
  4406.  
  4407. ReturnCode = haSetAdlOverride(ScriptHandle, TRUE);
  4408.  
  4409. /* -------------------------------------------------------------- */
  4410.  
  4411.  
  4412. haSetAsciiSettings
  4413.  
  4414. Change settings that are found in the ASCII Settings dialog box.
  4415.  
  4416. Syntax:
  4417.  
  4418.    INT haSetAsciiSettings(ScriptHandle, nCount, pnData)
  4419.  
  4420.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4421.  
  4422.    INT nCount                       The number of integers that
  4423.                                     follow
  4424.  
  4425.    INT FAR *pnData                  A pointer to an array of
  4426.                                     integers
  4427.  
  4428. Arguments:
  4429.  
  4430.    ScriptHandle
  4431.  
  4432.       The script handle returned from haInitialize.
  4433.  
  4434.    nCount
  4435.  
  4436.       The number of integers (16 bit values) that are in the pnData
  4437.       array.
  4438.  
  4439.    pnData
  4440.  
  4441.       A pointer to an array of integers (16 bit values) that are
  4442.       used to set ASCII settings values.  Each array element sets a
  4443.       different value and can be indexed by the following constants:
  4444.  
  4445.    Value                            Meaning
  4446.  
  4447.    HA_AI_FLAGS                      Various individual flags(bits),
  4448.                                     described below.
  4449.  
  4450.    HA_AI_WFCHAR                     Input wait for character.
  4451.  
  4452.    HA_AI_OTABS                      Output tab expansion value.
  4453.  
  4454.    HA_AI_CWAIT                      Character delay value.
  4455.  
  4456.    HA_AI_LWAIT                      Line delay value.
  4457.  
  4458.    HA_AI_ITABS                      Input tab conversion value.
  4459.  
  4460.    The  following flags(bits) are used in the HA_AI_FLAGS word to
  4461.    set the state of individual check box items:
  4462.  
  4463.    Value                            Meaning
  4464.  
  4465.    HA_AFS_LF                        Append LF to sent line ends.
  4466.  
  4467.    HA_AFS_BLS                       Expand blank lines sent to
  4468.                                     include a space.
  4469.  
  4470.    HA_AFS_ECHO                      Echo typed characters locally.
  4471.  
  4472.    HA_AFS_WAIT                      Enable wait for line end
  4473.                                     character.
  4474.    HA_AFS_TABS                      Enable tab expansion for sent
  4475.                                     characters.
  4476.  
  4477.    HA_AFR_LF                        Append LF to received line ends.
  4478.  
  4479.    HA_AFR_7BIT                      Force incoming characters to 7
  4480.                                     bits.
  4481.  
  4482.    HA_AFR_ECHO                      Echo received characters to
  4483.                                     sender.
  4484.  
  4485.    HA_AFR_WRAP                      Wrap lines that exceed terminal
  4486.                                     width.
  4487.  
  4488.    HA_AFR_HEX                       Show hex value of non-printing
  4489.                                     characters.
  4490.  
  4491. Remarks:
  4492.  
  4493.    The integer at index HA_AI_FLAGS has individual flags (bits)
  4494.    which are either TRUE (1) or FALSE (0).  Setting the value of
  4495.    individual bits is language dependent.  However, in C, you can
  4496.    set the value of a particular bit by performing a bitwise OR
  4497.    operation.  You can also add all the flagnames that you want set
  4498.    (TRUE) and assign the result to the array location identified by
  4499.    HA_AI_FLAGS.
  4500.  
  4501. Return Value:
  4502.  
  4503.    Returns 0 if successful.  Otherwise, a standard API error code.
  4504.  
  4505. See Also:
  4506.  
  4507.    haGetAsciiSettings
  4508.  
  4509. Example:
  4510.  
  4511. /* -------------------------------------------------------------- */
  4512.  
  4513. /* Set ASCII Settings for a communications session.
  4514.    This program segment sets HyperACCESS to:
  4515.   - Append LF to sent lines.
  4516.   - Expand blank lines to include a space.
  4517.   - Append LF to received line ends.  */
  4518.  
  4519. nSettings = HA_AFS_LF | HA_AFS_BLS | HA_AFR_LF;
  4520. haSetAsciiSettings(hScriptHandle, 3, &nSettings);
  4521.  
  4522. /* ------------------------------------------------------------- */
  4523.  
  4524.  
  4525. haSetBaudRate
  4526.  
  4527. Changes the speed, generally referred to as the baud rate, of the
  4528. communications device associated with the current session.  The
  4529. port type of the communications device determines the range of
  4530. acceptable values.
  4531.  
  4532. Syntax:
  4533.  
  4534.    INT haSetBaudRate(ScriptHandle, lSpeed)
  4535.  
  4536.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4537.  
  4538.    LONG lSpeed                      The new speed for the device
  4539.  
  4540. Arguments:
  4541.  
  4542.    ScriptHandle
  4543.  
  4544.       The script handle returned from haInitialize.
  4545.  
  4546.    lSpeed
  4547.  
  4548.       The new speed for the device.
  4549.  
  4550. Remarks:
  4551.  
  4552.    Some device types do not need a baud rate setting.  For those
  4553.    that don't, this setting is ignored.
  4554.  
  4555. Return Value:
  4556.  
  4557.    Returns 0 if successful.  Otherwise, a standard API error code.
  4558.  
  4559. See Also:
  4560.  
  4561.    haGetBaudRate
  4562.  
  4563. Example:
  4564.  
  4565. /* ------------------------------------------------------------- */
  4566.  
  4567. /* Change the baud rate of the current session.
  4568.   - This program segment sets the baud rate to 19,200.*/
  4569.  
  4570. ReturnCode = haSetBaudRate(ScriptHandle, 19200L);
  4571.  
  4572. /* -------------------------------------------------------------- */
  4573.  
  4574.  
  4575. haSetCaptureFileName
  4576.  
  4577. Changes the default name of the capture file for the currently
  4578. active session.
  4579.  
  4580. Syntax:
  4581.  
  4582.    INT haSetCaptureFileName(ScriptHandle, pszPtr)
  4583.  
  4584.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4585.  
  4586.    LPSTR pszPtr                     A pointer to a path and filename
  4587.  
  4588. Arguments:
  4589.  
  4590.    ScriptHandle
  4591.  
  4592.       The script handle returned from haInitialize.
  4593.  
  4594.    pszPtr
  4595.  
  4596.       A pointer to a string containing the new capture path and
  4597.       filename.
  4598.  
  4599. Remarks:
  4600.  
  4601. Return Value:
  4602.  
  4603.    Returns 0 if successful.  Otherwise, a standard API error code.
  4604.  
  4605. See Also:
  4606.  
  4607.    haCaptureBegin, haCaptureControl, haGetCaptureFileName
  4608.  
  4609. Example:
  4610.  
  4611. /* -------------------------------------------------------------- */
  4612.  
  4613. /* Set capture filename.
  4614.    This program segment:
  4615.   - Sets a string to a program defined path and filename.
  4616.   - Calls haSetCaptureFileName to set the name.  */
  4617.  
  4618. strcpy(szFilename, "C:\\HAOS2\\HAOS2.CAP");
  4619. ReturnCode = haSetCaptureFileName(hScriptHandle, szFilename);
  4620.  
  4621. /* -------------------------------------------------------------- */
  4622.  
  4623.  
  4624. haSetDialingPrefix
  4625.  
  4626. Sets one of the dialing prefix strings stored by HyperACCESS.
  4627.  
  4628. Syntax:
  4629.  
  4630.    INT haSetDialingPrefix(ScriptHandle, nIndex, pszPtr)
  4631.  
  4632.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4633.  
  4634.    INT nIndex                       Which string to change
  4635.  
  4636.    LPSTR pszPtr                     A pointer to the new string
  4637.  
  4638. Arguments:
  4639.  
  4640.    ScriptHandle
  4641.  
  4642.       The script handle returned from haInitialize.
  4643.  
  4644.    nIndex
  4645.  
  4646.       Which string to change.  Valid choices are 1 thru 9.
  4647.  
  4648.    pszPtr
  4649.  
  4650.       A pointer to a string containing the new prefix string.
  4651.  
  4652. Remarks:
  4653.  
  4654.    Dialing prefix strings are stored globally in the preferences
  4655.    file, and all sessions use the same set of strings.  If, for
  4656.    example, string 1 is changed from within a particular session,
  4657.    all sessions that use dialing prefix string 1 will be affected.
  4658.  
  4659. Return Value:
  4660.  
  4661.    Returns 0 if successful. Otherwise, a standard API error code.
  4662.  
  4663. See Also:
  4664.  
  4665.    haGetDialingPrefix, haSelectDialingPrefix
  4666.  
  4667. Example:
  4668.  
  4669. /* -------------------------------------------------------------- */
  4670.  
  4671. /* Changes a dialing prefix to a new value.
  4672.    This program segment:
  4673.   - Changes the first dialing prefix (for all sessions) to "1-313"
  4674. */
  4675.  
  4676. ReturnCode = haSetDialingPrefix(ScriptHandle, 1, "1-313");
  4677.  
  4678. /* -------------------------------------------------------------- */
  4679.  
  4680.  
  4681. haSetDisplay
  4682.  
  4683. Changes display mode of the Phonebook.
  4684.  
  4685. Syntax:
  4686.  
  4687.    INT haSetDisplay(ScriptHandle, nMode)
  4688.  
  4689.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4690.  
  4691.    INT nMode                        The mode to change to
  4692.  
  4693. Arguments:
  4694.  
  4695.    ScriptHandle
  4696.  
  4697.       The script handle returned from haInitialize.
  4698.  
  4699.    nMode
  4700.  
  4701.       The valid display modes are:
  4702.  
  4703.    Value                            Meaning
  4704.  
  4705.    HA_ICONIC                        The Phonebook will be displayed
  4706.                                     as icons.
  4707.  
  4708.    HA_STATS                         The Statistics view will be
  4709.                                     displayed in the Phonebook.
  4710.  
  4711.    HA_DETAILS                       The Details view will be
  4712.                                     displayed in the Phonebook.
  4713.    HA_NAMES                         The Phonebook will be displayed
  4714.                                     as system names.
  4715.  
  4716.    HA_FILES                         The Phonebook will be displayed
  4717.                                     as filenames.
  4718.  
  4719. Remarks:
  4720.  
  4721.    Changing the display mode of the phonebook causes the phonebook
  4722.    window to redisplay with the proper format.
  4723.  
  4724. Return Value:
  4725.  
  4726.    Returns 0 if successful.  Otherwise, a standard API error code.
  4727.  
  4728. See Also:
  4729.  
  4730.    haGetDisplay
  4731.  
  4732.  
  4733. haSetEcho
  4734.  
  4735. Enables and disables echo of received characters.
  4736.  
  4737. Syntax:
  4738.  
  4739.    INT haSetEcho(ScriptHandle, nEcho)
  4740.  
  4741.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4742.  
  4743.    INT nEcho                        To echo or not to echo
  4744.  
  4745. Arguments:
  4746.  
  4747.    ScriptHandle
  4748.  
  4749.       The script handle returned from haInitialize.
  4750.  
  4751.    nEcho
  4752.  
  4753.       If the value is TRUE, echoing is enabled.  If it is FALSE,
  4754.       echoing is disabled.
  4755.  
  4756. Remarks:
  4757.  
  4758.    When this setting is TRUE, every character received from a remote
  4759.    system is transmitted back to the remote system for display. This
  4760.    setting is normally set to TRUE only when HyperACCESS is serving
  4761.    as a host system.
  4762.  
  4763. Return Value:
  4764.  
  4765.    Returns 0 if successful.  Otherwise, a standard API error code.
  4766.  
  4767. See Also:
  4768.  
  4769.    haSetLocalEcho
  4770.  
  4771. Example:
  4772.  
  4773. /* -------------------------------------------------------------- */
  4774.  
  4775. /* Set character echo for half duplex operation.
  4776.    This program segment:
  4777.   - Disables echo of characters received.
  4778.   - Enables echo of characters sent so they display locally.  */
  4779.  
  4780. ReturnCode = haSetEcho(ScriptHandle, FALSE);
  4781. ReturnCode = haSetLocalEcho(ScriptHandle, TRUE);
  4782.  
  4783. /* -------------------------------------------------------------- */
  4784.  
  4785.  
  4786. haSetEmulator
  4787.  
  4788. Changes the emulator that is used by the currently active
  4789. session.
  4790.  
  4791. Syntax:
  4792.  
  4793.    INT haSetEmulator(ScriptHandle, pszPtr)
  4794.  
  4795.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4796.  
  4797.    LPSTR pszPtr                     A pointer to the new emulator
  4798.  
  4799. Arguments:
  4800.  
  4801.    ScriptHandle
  4802.  
  4803.       The script handle returned from haInitialize.
  4804.  
  4805.     pszPtr
  4806.  
  4807.       A pointer to a string containing the name of the new emulator.
  4808.  
  4809. Remarks:
  4810.  
  4811.    Only valid emulator names are accepted.  The type of emulator
  4812.    loaded determines how HyperACCESS decodes received control
  4813.    sequences.
  4814.  
  4815.  
  4816. Return Value:
  4817.  
  4818.    Returns 0 if successful.  Otherwise, a standard API error code.
  4819.  
  4820. See Also:
  4821.  
  4822.    haGetEmulator
  4823.  
  4824.  
  4825. haSetLearnFileName
  4826.  
  4827. Changes the default name of the learn file(script) for the
  4828. currently active session.
  4829.  
  4830. Syntax:
  4831.  
  4832.    INT haSetLearnFileName(ScriptHandle, pszPtr)
  4833.  
  4834.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4835.  
  4836.    LPSTR pszPtr                     A ponter to a filename
  4837.  
  4838. Arguements:
  4839.  
  4840.    ScriptHandle
  4841.  
  4842.       The script handle returned from haInitialize.
  4843.  
  4844.    pszPtr
  4845.  
  4846.       A pointer to a string containing the new learn filename.
  4847.  
  4848. Remarks:
  4849.  
  4850. Return Value:
  4851.  
  4852.    Returns 0 if successful.  Otherwise a standard API error code.
  4853.  
  4854. See Also:  haGetLearnFileName, haSetCaptureFileName
  4855.  
  4856.  
  4857. haSetLocalDisplay
  4858.  
  4859. Display data on the local emulator.
  4860.  
  4861. Syntax:
  4862.  
  4863.    INT haSetLocalDisplay(ScriptHandle, INT)
  4864.  
  4865.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4866.  
  4867.    INT nFlag                        The local display flag.
  4868.  
  4869. Arguments:
  4870.  
  4871.    ScriptHandle
  4872.  
  4873.       The script handle returned from haInitialize.
  4874.  
  4875.    nFlag
  4876.  
  4877.       If TRUE, displays all characters on the local emulator screen.
  4878.       If FALSE, suppresses display.
  4879.  
  4880. Remarks:
  4881.  
  4882.    If FALSE, will suppress display of both incoming and locally
  4883.    echoed characters.
  4884.  
  4885. Return Value:
  4886.  
  4887.    Returns 0 if successful.  Otherwise, a standard API error code.
  4888.  
  4889. See Also:
  4890.  
  4891.  
  4892. haSetLocalEcho
  4893.  
  4894. Enable or disables local display of transmitted characters.
  4895.  
  4896. Syntax:
  4897.  
  4898.    INT haSetLocalEcho(ScriptHandle, nEcho)
  4899.  
  4900.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4901.  
  4902.    INT nEcho                        To echo or not to echo
  4903.  
  4904. Arguments:
  4905.  
  4906.    ScriptHandle
  4907.  
  4908.       The script handle returned from haInitialize.
  4909.  
  4910.    nEcho
  4911.  
  4912.       If TRUE, transmitted characters are displayed locally.  If
  4913.       FALSE, transmitted characters are not diplayed unless they are
  4914.       echoed back by the remote system.
  4915.  
  4916. Remarks:
  4917.  
  4918. Return Value:
  4919.  
  4920.    Returns 0 if successful.  Otherwise, a standard API error code.
  4921.  
  4922. See Also:
  4923.  
  4924.    haSetEcho
  4925.  
  4926.  
  4927. haSetLogFileName
  4928.  
  4929. Changes the name of the log file for the currently active
  4930. session.
  4931.  
  4932. Syntax:
  4933.  
  4934.    INT haSetLogFileName(ScriptHandle, pszPtr)
  4935.  
  4936.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4937.  
  4938.    LPSTR pszPtr                     A pointer to the new path and
  4939.                                     filename
  4940.  
  4941. Arguments:
  4942.  
  4943.    ScriptHandle
  4944.  
  4945.       The script handle returned from haInitialize.
  4946.  
  4947.    pszPtr
  4948.  
  4949.       A pointer to a string containing the new log file path and
  4950.       filename.
  4951.  
  4952. Remarks:
  4953.  
  4954.    If logging is enabled, all calls and file transfers are recorded
  4955.    in the log file.
  4956.  
  4957. Return Value:
  4958.  
  4959.    Returns 0 if successful.  Otherwise, a standard API error code.
  4960.  
  4961. See Also:
  4962.  
  4963.    haGetLogFileName
  4964.  
  4965.  
  4966. haSetLogonTask
  4967.  
  4968. Sets the task that is run when the currently active session
  4969. successfully completes a connection.
  4970.  
  4971.    Syntax:
  4972.  
  4973.    INT haSetLogonTask(ScriptHandle, pszPtr)
  4974.  
  4975.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  4976.  
  4977.    LPSTR pszPtr                     A pointer to a path and filename
  4978.  
  4979. Arguments:
  4980.  
  4981.    ScriptHandle
  4982.  
  4983.       The script handle returned from haInitialize.
  4984.  
  4985.    pszPtr
  4986.  
  4987.       A pointer to a string containing the new path and filename.
  4988.  
  4989. Remarks:
  4990.  
  4991.    A file with a .c extension is passed to the HyperACCESS C
  4992.    interpreter.  Any other string is passed to the operating system
  4993.    for execution.  Normally, a logon task calls haInitialize and
  4994.    runs as a script, however, any executable file can be run.
  4995.  
  4996. Return Value:
  4997.  
  4998.    Returns 0 if successful.  Otherwise, a standard API error code.
  4999.  
  5000. Example:
  5001.  
  5002. /* -------------------------------------------------------------- */
  5003.  
  5004. /* Set connect program for the current session.  */
  5005.  
  5006. ReturnCode = haSetLogonTask(ScriptHandle, "C:\\MYDIR\\BOB.C");
  5007.  
  5008. /* -------------------------------------------------------------- */
  5009.  
  5010.  
  5011. haSetMessageTimer
  5012.  
  5013. Sets a timer for dismissing message boxes that report errors and
  5014. unusual conditions.
  5015.  
  5016. Syntax:
  5017.  
  5018.    INT haSetMessageTimer(ScriptHandle,nSeconds)
  5019.  
  5020.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5021.  
  5022.    INT nSeconds                     The number of seconds before
  5023.                                     timeout
  5024.  
  5025. Arguments:
  5026.  
  5027.    ScriptHandle
  5028.  
  5029.       The script handle returned from haInitialize.
  5030.  
  5031.    nSeconds
  5032.  
  5033.       The number of seconds before timeout.  A value of zero (0)
  5034.       means that the message box is not displayed at all.  A value
  5035.       of minus one (-1) means no timeout is to be used and the
  5036.       message box will be displayed until the user responds to it.
  5037.       Minus one (-1) is the initial session default.
  5038.  
  5039. Remarks:
  5040.  
  5041.    An external task can perform most of the operations that a user
  5042.    can perform.  One of the few exceptions is dismissing message
  5043.    boxes that report errors and unusual conditions.  This function
  5044.    changes the way standard HyperACCESS message boxes function by
  5045.    setting a timeout value.  If no user interaction dismisses the
  5046.    message box within the timeout value, the box times out and
  5047.    dismisses itself.  Each message box attempts to perform an
  5048.    appropriate action upon timeout.  The timeout effects only the
  5049.    current session and is valid for as long as the session lasts,
  5050.    even if the script terminates before the session is closed.
  5051.  
  5052. Return Value:
  5053.  
  5054.    Returns 0 if successful.  Otherwise, a standard API error code.
  5055.  
  5056. Example:
  5057.  
  5058. /* -------------------------------------------------------------- */
  5059.  
  5060. /* Dismiss message boxes after fixed period of time.  This lets a
  5061. user respond, or continues with default actions if no user
  5062. response received in fixed time interval (10 seconds, in example).*/
  5063.  
  5064. ReturnCode = haSetMessageTimer(ScriptHandle, 10);
  5065. /* -------------------------------------------------------------- */
  5066.  
  5067.  
  5068. haSetNameString
  5069.  
  5070. Sets the internal HyperACCESS user name and address field.
  5071.  
  5072. Syntax:
  5073.  
  5074.    INT haSetNameString(ScriptHandle, pszPtr)
  5075.  
  5076.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5077.  
  5078.    LPSTR pszPtr                     A pointerto the new string
  5079.  
  5080. Arguments:
  5081.  
  5082.    ScriptHandle
  5083.  
  5084.       The script handle returned from haInitialize.
  5085.  
  5086.    pszPtr
  5087.  
  5088.       A pointer to a string.  This string is six lines in HA/Win and
  5089.       seven lines in HA/OS2 and HA/Win95.  Each line is terminated
  5090.       by a carriage return - line feed pair.  The first line is the
  5091.       name line.  The second line is the company line.  The third
  5092.       line is the street address.  The fourth line is the city.  The
  5093.       fifth line is the state.  The sixth line is the zip code.  The
  5094.       seventh line is country.
  5095.  
  5096. Remarks:
  5097.  
  5098.    These values are normally established by the setup program at
  5099.    installation.
  5100.  
  5101. Return Value:
  5102.  
  5103.    Returns 0 if successful.  Otherwise, a standard API error code.
  5104.  
  5105. See Also:
  5106.  
  5107.    haGetNameString
  5108.  
  5109. Example:
  5110.  
  5111. /* -------------------------------------------------------------- */
  5112.  
  5113. /* Set the User name and address information.
  5114.    This program segment:
  5115.   - Defines a character string variable.
  5116.   - Sets the variable to the name and address desired.
  5117.   - Sets the internal HyperACCESS user name and address field.
  5118.   - This example assumes the HA/OS2 definition that includes a
  5119.     country field.  */
  5120.  
  5121. char szNameString[128];          / Variable to store the name string
  5122.  
  5123. strcpy(szNameString, "Mr. Joel Pendergast\r\n"
  5124.                      "Pendergast Consulting\r\n"
  5125.                      "123 Main St.\r\n"
  5126.                      "Anywhere\r\n"
  5127.                      "MI\r\n"
  5128.                      "48999\r\n"
  5129.                      "USA\r\n");
  5130. ReturnCode = haSetNameString(hScriptHandle, szNameString);
  5131.  
  5132. /* -------------------------------------------------------------- */
  5133.  
  5134.  
  5135. haSetPortMode
  5136.  
  5137. Changes current settings for number of bits per character, number
  5138. of parity bits, and parity type.
  5139.  
  5140. Syntax:
  5141.  
  5142.    INT haSetPortMode(ScriptHandle, nMode)
  5143.  
  5144.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5145.  
  5146.    INT nMode                        Flags for the new settings
  5147.  
  5148.  
  5149. Arguments:
  5150.  
  5151.    ScriptHandle
  5152.  
  5153.       The script handle returned from haInitialize.
  5154.  
  5155.    nMode
  5156.  
  5157.       The mode is set by ORing selected flags together:
  5158.  
  5159.    Value                            Meaning
  5160.  
  5161.    HA_M_AUTO                        Auto-detect is set.
  5162.  
  5163.    HA_M_7_BITS                      Characters contain 7 bits.
  5164.  
  5165.    HA_M_8_BITS                      Characters contain 8 bits.
  5166.  
  5167.    HA_M_E_PRTY                      Characters have even parity.
  5168.  
  5169.    HA_M_O_PRTY                      Characters have odd parity.
  5170.  
  5171.    HA_M_N_PRTY                      Characters have no parity.
  5172.  
  5173.    HA_M_M_PRTY                      Characters have mark parity.
  5174.  
  5175.    HA_M_S_PRTY                      Characters have space parity.
  5176.  
  5177.    HA_M_1_STOP                      Characters have one stop bit.
  5178.  
  5179.    HA_M_1_5_STOP                    Characters have 1.5 stop bits.
  5180.  
  5181.    HA_M_2_STOP                      Characters have two stop bits.
  5182.  
  5183. Remarks:
  5184.  
  5185.    The integer nMode has individual flags (bits) which are either
  5186.    TRUE (1) or FALSE (0).  Setting the value of individual bits is
  5187.    language dependent.  However, in C, you can set the value of a
  5188.    particular bit by performing a bitwise OR operation of nMode with
  5189.    the desired flag name defined above.  You can also add all the
  5190.    flagnames that you want set (TRUE) and assign the result to
  5191.    nMode.
  5192.    For example:
  5193.    haSetPortMode(ScriptHandle, HA_M_8BITS + HA_M_N_PRTY +
  5194.                   HA_M_1_STOP);
  5195.  
  5196. Return Value:
  5197.  
  5198.    Returns 0 if successful.  Otherwise, a standard API error code.
  5199.  
  5200. See Also:
  5201.  
  5202.    haGetPortMode
  5203.  
  5204. Example:
  5205.  
  5206. /* -------------------------------------------------------------- */
  5207.  
  5208. /* Change communications parameters.
  5209.    This program segment:
  5210.   - Sets the port mode to 8 bit, no parity, 1 stop bit.
  5211.   - Sets the port name to "COM1".
  5212.   - Sets the port type to "Standard COM Port".  */
  5213.  
  5214. ReturnCode = haSetPortMode(ScriptHandle, HA_M_8_BITS +
  5215.                HA_M_N_PRTY + HA_M_1_STOP);
  5216. ReturnCode = haSetPortName(ScriptHandle, "COM1");
  5217. ReturnCode = haSetPortType(ScriptHandle, "STANDARD COM PORT");
  5218.  
  5219. /* -------------------------------------------------------------- */
  5220.  
  5221.  
  5222. haSetPortName
  5223.  
  5224. Changes the device name that is associated with the currently
  5225. active session.
  5226.  
  5227. Syntax:
  5228.  
  5229.    INT haSetPortName(ScriptHandle, pszPtr)
  5230.  
  5231.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5232.  
  5233.     LPSTR pszPtr                    A pointer to the new name
  5234.  
  5235. Arguments:
  5236.  
  5237.     ScriptHandle
  5238.  
  5239.       The script handle returned from haInitialize.
  5240.  
  5241.    pszPtr
  5242.  
  5243.       A pointer to a string containing the new name.
  5244.  
  5245. Remarks:
  5246.  
  5247.    The setting for port type determines which values are acceptable
  5248.    as port names.  For example, the port type Standard Com Port can
  5249.    have values such as COM1 and COM2.  Other port types accept
  5250.    different names as appropriate.  In general, HyperACCESS doesn't
  5251.    attempt to prescreen names.  Instead, they are passed to the
  5252.    communications driver for verification.
  5253.  
  5254. Return Value:
  5255.  
  5256.    Returns 0 if successful. Otherwise, a standard API error code.
  5257.  
  5258. See Also:
  5259.  
  5260.   haGetPortName, haSetPortPrefs, haSetPortType
  5261.  
  5262.  
  5263. haSetPortPrefs
  5264.  
  5265. Changes the connection device associated with a communications
  5266. port.
  5267.  
  5268. Syntax:
  5269.  
  5270.    INT haSetPortPrefs(ScriptHandle, pszType, pszName, pszDevice)
  5271.  
  5272.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5273.  
  5274.    LPSTR pszType                     A pointer to the port type
  5275.  
  5276.    LPSTR pszName                     A pointer to the port name
  5277.  
  5278.    LPSTR pszDevice                   A pointer to the commumications
  5279.                                      device
  5280.  
  5281. Arguments:
  5282.  
  5283.    ScriptHandle
  5284.  
  5285.       The script handle returned from haInitialize.
  5286.  
  5287.    pszType
  5288.  
  5289.       A pointer to a string containing the device type.
  5290.  
  5291.    pszName
  5292.  
  5293.       A pointer to a string containing the port name.
  5294.  
  5295.    pszDevice
  5296.  
  5297.       A pointer to a string containing the connection device name.
  5298.  
  5299. Remarks:
  5300.  
  5301.    This function lets you set the three values that, together,
  5302.    define a connection path.  The device type and port name can also
  5303.    be set by haSetPortType and haSetPortName, respectively.  This
  5304.    function also lets you set the connection device (modem).
  5305.    Acceptable values for port name and connection device depend on
  5306.    the port type in use.  Each session has an assigned port type and
  5307.    port name.  The connection device name, however, is defined
  5308.    globally for each port type - port name combination.  The user
  5309.    defines these combinations, and HyperACCESS stores them in the
  5310.   .PRF file along with the connection devices associated with them.
  5311.    As a result, changing a connection device in one session impacts
  5312.    all sessions that use the same port type - port name combination.
  5313.    For example, if in the session MCI Mail, you specify that an XYZ
  5314.    SuperModem is attached to Standard Com Port, COM1, then any
  5315.    session that is set up to use Standard Com Port, COM1, will now
  5316.    also expect to use an XYZ SuperModem.
  5317.  
  5318. Return Value:
  5319.  
  5320.     Returns 0 if successful.  Otherwise, a standard API error code.
  5321.  
  5322. See Also:
  5323.  
  5324. haGetPortPrefs, haSetPortName, haSetPortType
  5325.  
  5326. Example:
  5327.  
  5328. /* -------------------------------------------------------------- */
  5329.  
  5330. /* Change communications parameters and modem.
  5331.    This program segement:
  5332.   - Uses one function call to set port name, port type, and modem */
  5333.  
  5334. ReturnCode = haSetPortPrefs(ScriptHandle, "STANDARD COM PORT",
  5335.                "COM1", "Amstrad Quad");
  5336.  
  5337. /* -------------------------------------------------------------- */
  5338.  
  5339.  
  5340. haSetPortType
  5341.  
  5342. Changes the device type associated with the currently active
  5343. session.
  5344.  
  5345. Syntax:
  5346.  
  5347.    INT haSetPortType(ScriptHandle, pszPtr)
  5348.  
  5349.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5350.  
  5351.     LPSTR pszPtr                    A pointer to the device type
  5352.  
  5353. Arguments:
  5354.  
  5355.    ScriptHandle
  5356.  
  5357.       The context handle returned from haInitialize.
  5358.  
  5359.    pszPtr
  5360.  
  5361.       A pointer to a string containing the device type.
  5362.  
  5363. Remarks:
  5364.  
  5365.    HyperACCESS supports many types of communications devices.  Each
  5366.    device type may consist of one or more actual ports.  For
  5367.    example, if the port type is Standard Com Port, you may have COM1
  5368.    and COM2 available as port names.  Each port type is implemented
  5369.    as a driver module in a *.DLL file on the disk.  Changing th port
  5370.    type changes the values acceptable as port name and connection
  5371.    device name (modem).
  5372.  
  5373. Return Value:
  5374.  
  5375.    Returns 0 if successful. Otherwise, a standard API error code.
  5376.  
  5377. See Also:
  5378.  
  5379.   haGetPortType
  5380.  
  5381.  
  5382. haSetPulseTone
  5383.  
  5384. Sets the device dialing method to pulse or tone.
  5385.  
  5386. Syntax:
  5387.  
  5388.    INT haSetPulseTone(ScriptHandle, nMode)
  5389.  
  5390.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5391.  
  5392.    INT nMode                        Select pulse or tone
  5393.  
  5394. Arguments:
  5395.  
  5396.    ScriptHandle
  5397.  
  5398.       The script handle returned from haInitialize.
  5399.  
  5400.    nMode
  5401.  
  5402.       Valid values are:
  5403.  
  5404.    Value                            Meaning
  5405.  
  5406.    HA_PT_PULSE                      Set to pulse mode dialing.
  5407.  
  5408.    HA_PT_TONE                       Set to tone mode dialing.
  5409.  
  5410. Remarks:
  5411.  
  5412.    This setting will be used only by connection devices that place
  5413.    calls over dial-up phone lines.
  5414.  
  5415. Return Value:
  5416.  
  5417.    Returns 0 if successful.  Otherwise, a standard API error code.
  5418.  
  5419. Example:
  5420.  
  5421. /* -------------------------------------------------------------- */
  5422.  
  5423. /* Change dialing type to PULSE */
  5424.  
  5425. ReturnCode = haSetPulseTone(ScriptHandle, HA_PT_PULSE);
  5426.  
  5427. /* -------------------------------------------------------------- */
  5428.  
  5429.  
  5430. haSetRingsForAnswer
  5431.  
  5432. Changes the number of rings that the modem should wait before
  5433. answering a call.
  5434.  
  5435. Syntax:
  5436.  
  5437.    INT haSetRingsForAnswer(ScriptHandle, nCount)
  5438.  
  5439.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5440.  
  5441.    INT nCount                       The number of rings to wait
  5442.  
  5443. Arguments:
  5444.  
  5445.    ScriptHandle
  5446.  
  5447.       The script handle returned from haInitialize.
  5448.  
  5449.    nCount
  5450.  
  5451.       The number of rings that the modem is instructed to wait for
  5452.       before answering.
  5453.  
  5454. Remarks:
  5455.  
  5456. Return Value:
  5457.  
  5458.    Returns 0 if successful.  Otherwise, a standard API error code.
  5459.  
  5460. See Also:
  5461.  
  5462.     haConnectSession, haGetRingsForAnswer
  5463.  
  5464. Example:
  5465.  
  5466. /* -------------------------------------------------------------- */
  5467.  
  5468. /* Set the number of rings to answer the phone, and put modem in
  5469.    answer mode.
  5470.    This program segment:
  5471.   - Sets the number of rings before answer to 3.
  5472.   - Connects the session to its port in answer mode.  */
  5473.  
  5474. ReturnCode = haSetRingsForAnswer(ScriptHandle, 3);
  5475. ReturnCode = haConnectSession(ScriptHandle, HA_CNCT_ANSWER_MODE);
  5476.  
  5477. /* -------------------------------------------------------------- */
  5478.  
  5479.  
  5480. haSetSession
  5481.  
  5482. Changes the session handle that is accociated with the current
  5483. program - HyperACCESS link.
  5484.  
  5485. Syntax:
  5486.  
  5487.    INT haSetSession(ScriptHandle, hSession)
  5488.  
  5489.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5490.  
  5491.    HSESS hSession                   A session handle
  5492.  
  5493. Arguments:
  5494.  
  5495.    ScriptHandle
  5496.  
  5497.       The script handle returned from haInitialize.
  5498.  
  5499.    hSession
  5500.  
  5501.       A session handle returned by haGetSession or haOpenSession.
  5502.  
  5503. Remarks:
  5504.  
  5505.    The session handle identifies which session an external task is
  5506.    associated with.  This is necessary because HA/Win allows
  5507.    multiple concurrent communications sessions within the same task.
  5508.    In HA/OS2 and HA/Win95, there is only one session for each
  5509.    instance of HyperACCESS.  haSetSession doesn't save the session
  5510.    handle that was previously associated with the program -
  5511.    HyperACCESS link, but a program can save the previous session
  5512.    handle in a variable and restore it later using haSetSession.  If
  5513.    you write a program that attempts to control more than one
  5514.    session, you should read the remarks for functions
  5515.    haBlockRemoteInput and haReleaseRemoteInput.
  5516.  
  5517. Return Value:
  5518.    Returns 0 if successful.  Otherwise, a standard API error code.
  5519.  
  5520. See Also:
  5521.  
  5522.    haBlockRemoteInput, haCloseSession, haGetSession, haOpenSession,
  5523.    haReleaseRemoteInput
  5524.  
  5525.  
  5526. haSetSessionDataString
  5527.  
  5528. Sets one of the data strings stored with each session.
  5529.  
  5530. Syntax:
  5531.  
  5532.    INT haSetSessionDataString(ScriptHandle, nIndex, pszPtr)
  5533.  
  5534.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5535.  
  5536.    INT nIndex                       Which string to set
  5537.  
  5538.    LPSTR pszPtr                     A pointer to a string
  5539.  
  5540. Arguments:
  5541.  
  5542.    ScriptHandle
  5543.  
  5544.       The script handle returned from haInitialize.
  5545.  
  5546.    nIndex
  5547.  
  5548.       The index of the string to be set.  Valid numbers are 0 thru
  5549.       19.
  5550.  
  5551.    pszPtr
  5552.  
  5553.       A pointer to the new string.
  5554.  
  5555. Remarks:
  5556.  
  5557.    The first ten session data strings (0 - 9) are normally used with
  5558.    the HyperACCESS DDE interface.  They are not stored in the
  5559.    session file and will be blank when a session is opened.  The
  5560.    second ten (10 - 19) are available for general script use and are
  5561.    saved with the session.  They can be used to store any values
  5562.    that should be maintained unchanged from one execution to the
  5563.    next.
  5564.  
  5565. Return Value:
  5566.  
  5567.    Returns 0 if successful.  Otherwise, a standard API error code.
  5568.  
  5569. See Also:
  5570.  
  5571.    haGetSessionDataString
  5572.  
  5573.  
  5574. haSetStripTo7Bits
  5575.  
  5576. Enables and disables stripping of received chatacters to 7 bits.
  5577.  
  5578. Syntax:
  5579.  
  5580.    INT haSetStripTo7Bits(ScriptHandle, nStrip)
  5581.  
  5582.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5583.  
  5584.    INT nStrip                       Enable or disable stripping
  5585.  
  5586. Arguments:
  5587.  
  5588.    ScriptHandle
  5589.  
  5590.       The script handle returned from haInitialize.
  5591.  
  5592.    nStrip
  5593.  
  5594.       If TRUE, stripping is enabled.  If FALSE, stripping is
  5595.       disabled.
  5596.  
  5597. Remarks:
  5598.  
  5599.    When this setting is TRUE, the high order bit of each received
  5600.    character is forced to zero prior to display.  This is done
  5601.    regardless of the parity or data bits settings for the
  5602.    communications channel.
  5603.  
  5604. Return Value:
  5605.  
  5606.    Returns 0 if successful.  Otherwise, a standard API error code.
  5607.  
  5608. See Also:
  5609.  
  5610.    haSetAsciiSettings (HA_AI_FLAGS value HA_AFT_7BIT)
  5611.  
  5612.  
  5613. haSetXferDirectory
  5614.  
  5615. Changes one of the default transfer directories for the currently
  5616. active session.
  5617.  
  5618. Syntax:
  5619.    INT haSetXferDirectory(ScriptHandle, nDirection, pszPtr)
  5620.  
  5621.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5622.  
  5623.    INT nDirection                   Which directory to change
  5624.  
  5625.    LPSTR pszPtr                     A pointer to a string containing
  5626.                                     the directory path
  5627.  
  5628. Arguments:
  5629.  
  5630.    ScriptHandle
  5631.  
  5632.       The script handle returned from haInitialize.
  5633.  
  5634.    nDirection
  5635.  
  5636.       Describes which directory to change:
  5637.  
  5638.    Value                            Meaning
  5639.  
  5640.    HA_XFER_SEND                     Selects the sending directory.
  5641.  
  5642.    HA_XFER_RECV                     Selects the receiving directory.
  5643.  
  5644.    pszPtr
  5645.  
  5646.       A pointer to a string containing the new directory path.
  5647.  
  5648. Remarks:
  5649.  
  5650. Return Value:
  5651.  
  5652.    Returns 0 if successful.  Otherwise, a standard API error code.
  5653.  
  5654. See Also:
  5655.  
  5656.   haGetXferDirectory
  5657.  
  5658.  
  5659. haSetXferParameters
  5660.  
  5661. Provides an integer value composed of flags (bits) that determine
  5662. how a transfer operation is carried out.
  5663.  
  5664. Syntax:
  5665.  
  5666.    INT haSetXferParameters(ScriptHandle, lParams)
  5667.  
  5668.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5669.  
  5670.    LONG lParams                     The new parameters
  5671.  
  5672. Arguments:
  5673.  
  5674.    ScriptHandle
  5675.  
  5676.       The script handle returned from haInitialize.
  5677.  
  5678.    lParams
  5679.  
  5680.       The transfer parameters are describe by the following flags
  5681.       which may be used to modify the current parameters:
  5682.  
  5683.    Value                            Meaning
  5684.  
  5685.    XF_DN_MASK                       A mask for the next 6 flags.
  5686.                                     These flags are used if the
  5687.                                     selected filename is already
  5688.                                     being used.
  5689.  
  5690.    XF_DN_APPEND                     Append if filename is already
  5691.                                     used.
  5692.  
  5693.    XF_DN_OVERWRT                    Overwrite if filename is already
  5694.                                     used.
  5695.  
  5696.    XF_DN_REFUSE                     Refuse the transfer if filename
  5697.                                     is already used.
  5698.  
  5699.    XF_DN_NEWER                      Overwrite if the received file
  5700.                                     is newer than the current file.
  5701.  
  5702.    XF_DN_DATE                       Generate a new filename based on
  5703.                                     the old name and the current
  5704.                                     date.
  5705.    XF_DN_SEQ                        Generate a new filename based on
  5706.                                     the old name and a sequence
  5707.                                     number.
  5708.    XF_CHECK_VIRUS                   Enable virus detection.
  5709.  
  5710.    XF_USE_FILENAME                  Use received filename in
  5711.                                     naming file.
  5712.    XF_USE_DIRECTORY                 Use received directory in naming
  5713.                                     file.
  5714.  
  5715.    XF_SAVE_PARTIAL                  Save partial file from
  5716.                                     interrupted transfer.
  5717.  
  5718.    XF_USE_DATETIME                  Use received file date and
  5719.                                     time.
  5720.  
  5721. Remarks:
  5722.  
  5723.    The integer lParams has individual flags (bits) which are either
  5724.    TRUE (1) or FALSE (0).  Setting the value of individual bits is
  5725.    language dependent.  However, in C, you can set the value of a
  5726.    particular bit by performing a bitwise OR operation of lParams
  5727.    with the desired flag name defined above. You can also add all
  5728.    the flag names that you want set (TRUE) and assign the result to
  5729.    lParams.
  5730.  
  5731. Return Value:
  5732.  
  5733.    Returns 0 if successful.  Otherwise, a standard API error code.
  5734.  
  5735. See Also:
  5736.  
  5737. haGetXferParameters
  5738.  
  5739. Example:
  5740.  
  5741. /* -------------------------------------------------------------- */
  5742.  
  5743. /* Check a current transfer parameter, and changes its value.
  5744.    This program segment:
  5745.   - Gets a current transfer parameter (checks append mask).
  5746.   - Sets transfer parameter (to overwrite). */
  5747.  
  5748. ReturnCode = haGetXferParameters(ScriptHandle);
  5749. if (ReturnCode == XF_DN_APPEND)
  5750.    ReturnCode = haSetXferParameters(ScriptHandle, XF_DN_OVERWRT);
  5751.  
  5752. /* -------------------------------------------------------------- */
  5753.  
  5754.  
  5755. haSetXferProtocol
  5756.  
  5757. Changes one of the default transfer protocols for the currently
  5758. active session.
  5759.  
  5760. Syntax:
  5761.  
  5762.    INT haSetXferProtocol(ScriptHandle, nDirection, nProtocol)
  5763.  
  5764.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5765.  
  5766.    INT nDirection                   Selects the direction
  5767.  
  5768.    INT nProtocol                    Selects the protocol
  5769.  
  5770. Arguments:
  5771.  
  5772.   ScriptHandle
  5773.  
  5774.       The script handle returned from haInitialize.
  5775.  
  5776.    nDirection
  5777.  
  5778.       Describes which direction to change:
  5779.  
  5780.    Value                            Meaning
  5781.  
  5782.    HA_XFER_SEND                     Sets the sending method.
  5783.  
  5784.    HA_XFER_RECV                     Sets the receiving method.
  5785.  
  5786.    nProtocol
  5787.  
  5788.       Select the new protocol
  5789.  
  5790.    Value                            Meaning
  5791.  
  5792.    HA_HYPERP                        Hilgraeves HyperProtocol.
  5793.  
  5794.    HA_COMPUSERV_B                   CompuServ B+.
  5795.  
  5796.    HA_KERMIT                        Kermit.
  5797.  
  5798.    HA_XMODEM                        XMODEM.
  5799.  
  5800.    HA_XMODEM_1K                     1K XMODEM.
  5801.  
  5802.    HA_YMODEM                        YMODEM.
  5803.  
  5804.    HA_YMODEM_G                      YMODEM-G.
  5805.  
  5806.    HA_ZMODEM                        ZMODEM.
  5807.  
  5808. Remarks:
  5809.  
  5810. Return Value:
  5811.  
  5812.    Returns 0 if successful.  Otherwise, a standard API error code.
  5813.  
  5814. See Also:
  5815.  
  5816.    haGetXferProtocol, haXferDropSend, haXferReceive, haXferSend,
  5817.     haXferSendBatch, haXferSendFromList, haXferSendList
  5818.  
  5819. Example:
  5820.  
  5821. /* -------------------------------------------------------------- */
  5822.  
  5823. /* Set the default receive protocol
  5824.    This program segment:
  5825.   - Sets the default receive protocol to HyperProtocol.  */
  5826.  
  5827. ReturnCode = haSetXferProtocol(ScriptHandle, HA_XFER_RECV,
  5828.                HA_HYPERP);
  5829.  
  5830. /* -------------------------------------------------------------- */
  5831.  
  5832.  
  5833. haSizeHyperACCESS
  5834.  
  5835. Changes the size and visibility of the HyperACCESS application
  5836. window.
  5837.  
  5838. Syntax:
  5839.  
  5840.    INT haSizeHyperACCESS(ScriptHandle, nMode)
  5841.  
  5842.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5843.  
  5844.    INT nMode                        What to do to the program
  5845.  
  5846. Arguments:
  5847.  
  5848.    ScriptHandle
  5849.  
  5850.       The script handle returned from haInitialize.
  5851.  
  5852.    nMode
  5853.  
  5854.       The following GUI operations can be performed by HyperACCESS:
  5855.  
  5856.    Value                            Meaning
  5857.  
  5858.    HA_S_MAX                         Maximize HyperACCESS.
  5859.  
  5860.    HA_S_MIN                         Minimize HyperACCESS.
  5861.  
  5862.    HA_S_RSTR                        Restore HyperACCESS.
  5863.  
  5864.    HA_S_HIDE                        Hide HyperACCESS.
  5865.  
  5866. Remarks:
  5867.  
  5868. Return Value:
  5869.  
  5870.    Returns 0 if successful.  Otherwise, a standard API error code.
  5871.  
  5872. See Also:
  5873.  
  5874.    haSizePhonebook, haSizeSession
  5875.  
  5876. Example:
  5877.  
  5878. /* -------------------------------------------------------------- */
  5879.  
  5880. /* Set HyperACCESS window sizes.
  5881.    This program segment:
  5882.   - Maximizes the HyperACCESS application window.*/
  5883.  
  5884. ReturnCode = haSizeHyperACCESS(ScriptHandle, HA_S_MAX);
  5885.  
  5886. /* -------------------------------------------------------------- */
  5887.  
  5888.  
  5889. haSizePhonebook
  5890.  
  5891. Changes the size of the Phonebook window within HyperACCESS.
  5892.  
  5893. Syntax:
  5894.  
  5895.    INT haSizePhonebook(ScriptHandle, nMode)
  5896.  
  5897.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5898.  
  5899.   INT nMode                          How to change the Phonebook
  5900.  
  5901. Arguments:
  5902.  
  5903.    ScriptHandle
  5904.  
  5905.       The script handle returned from haInitialize.
  5906.  
  5907.    nMode
  5908.  
  5909.       The following Windows operations can be performed on the
  5910.       Phonebook:
  5911.  
  5912.    Value                            Meaning
  5913.  
  5914.    HA_S_MAX                         Maximize the Phonebook.
  5915.  
  5916.    HA_S_MIN                         Minimize the Phonebook.
  5917.  
  5918.    HA_S_RSTR                        Restore the Phonebook.
  5919.  
  5920. Remarks:
  5921.  
  5922.    Used in HA/Win.  Ignored in HA/OS2 and HA/Win95 (always gives a
  5923.    successful return).
  5924.  
  5925. Return Value:
  5926.  
  5927.    Returns 0 if successful.  Otherwise, a standard API error code.
  5928.  
  5929. See Also:
  5930.  
  5931.    haSizeHyperACCESS, haSizeSession
  5932.  
  5933.  
  5934. haSizeSession
  5935.  
  5936. Changes the size of the currently active session window.
  5937.  
  5938. Syntax:
  5939.  
  5940.    INT haSizeSession(ScriptHandle, nMode)
  5941.  
  5942.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  5943.  
  5944.    INT nMode                        How to change the session
  5945.  
  5946. Arguments:
  5947.  
  5948.    ScriptHandle
  5949.  
  5950.       The script handle returned from haInitialize.
  5951.  
  5952.    nMode
  5953.  
  5954.       The following Windows operations can be performed on the
  5955.       session:
  5956.  
  5957.    Value                            Meaning
  5958.  
  5959.    HA_S_MAX                          Maximize the session.
  5960.  
  5961.    HA_S_MIN                          Minimize the session.
  5962.  
  5963. HA_S_RSTR                            Restore the session.
  5964.  
  5965. Remarks:
  5966.  
  5967.    Used in HA/Win.  Ignored in HA/OS2 and HA/Win95 (always gives a
  5968.    successful return).
  5969.  
  5970. Return Value:
  5971.  
  5972.    Returns 0 if successful.  Otherwise, a standard API error code.
  5973.  
  5974. See Also:
  5975.  
  5976.     haSizeHyperACCESS, haSizePhonebook
  5977.  
  5978.  
  5979. haSkipConnection
  5980.  
  5981. Clears the perform connection flag.
  5982.  
  5983. Syntax:
  5984.  
  5985.    INT haSkipConnection(ScriptHandle)
  5986.  
  5987.     SCRIPTHANDLE ScriptHandle       The program - HyperACCESS link
  5988.  
  5989. Arguments:
  5990.  
  5991.      ScriptHandle
  5992.  
  5993.       The script handle returned from haInitialize.
  5994.  
  5995. Remarks:
  5996.  
  5997.    In HyperACCESS, you can define a program that runs before a
  5998.    connection is attempted and one that runs (as a logon) after a
  5999.    connection has been completed.  Normally, HyperACCESS runs the
  6000.    preconnection program, attempts to connect to the remote system,
  6001.    and then, if the connection is successful, runs the logon
  6002.    program.  If you write a preconnection program that does some
  6003.    advance processing and then determines that the connection should
  6004.    not proceed, or you want to make the connection from within the
  6005.    preconnection program, you can disable the automatic connection
  6006.    that is normally attempted when the preconnect program ends.  If
  6007.    haSkipConnection is called during the preconnect program,
  6008.    HyperACCESS doesn't attempt to automatically connect the session
  6009.    when it terminates and won't run the logon program.
  6010.  
  6011. Return Value:
  6012.  
  6013.    Returns 0 if successful.  Otherwise, a standard API error code.
  6014.  
  6015. See Also:
  6016.  
  6017.    haOpenSession, haConnectSession
  6018.  
  6019.  
  6020. haSleep
  6021.  
  6022. Causes the API interface to enter the HyperACCESS server idle
  6023. loop for a specified period of time.
  6024.  
  6025. Syntax:
  6026.  
  6027.    INT haSleep(ScriptHandle, lTime)
  6028.  
  6029.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6030.  
  6031.    LONG lTime                        How long to sleep
  6032.  
  6033. Arguments:
  6034.  
  6035.    ScriptHandle
  6036.  
  6037.       The script handle returned from haInitialize.
  6038.  
  6039.    lTime
  6040.  
  6041.      The amount of time to sleep, measured in milliseconds.
  6042.  
  6043. Remarks:
  6044.  
  6045.    While an application sleeps, the session neither sends nor
  6046.    receives characters.  During this time, however, windows messages
  6047.    continue to be dispatched to prevent the Windows environment from
  6048.    becoming inactive.
  6049.  
  6050. Return Value:
  6051.  
  6052.    Returns 0 if successful.  Otherwise, a standard API error code.
  6053.  
  6054. See Also:
  6055.  
  6056.    haPause
  6057.  
  6058. Example:
  6059.  
  6060. /* -------------------------------------------------------------- */
  6061.  
  6062. /* Pause execution of the API program.  haSleep doesn't block
  6063. other tasks from getting CPU time, and lets HyperACCESS continue
  6064. to send and receive data.
  6065.  
  6066.    This program segment:
  6067.   - Pauses for 10 seconds.  */
  6068.  
  6069. ReturnCode = haSleep(ScriptHandle, 10000L);
  6070.  
  6071. /* -------------------------------------------------------------- */
  6072.  
  6073.  
  6074. haSpawn
  6075.  
  6076. Starts up another external task (or script).
  6077.  
  6078. Syntax:
  6079.  
  6080.    INT haSpawn(ScriptHandle, pszName)
  6081.  
  6082.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6083.  
  6084.    LPSTR pszName                     The name of the external task
  6085.  
  6086. Arguments:
  6087.  
  6088.    ScriptHandle
  6089.  
  6090.       The script handle returned from haInitialize.
  6091.  
  6092.    pszName
  6093.  
  6094.       A buffer containing the file name of the external task that is
  6095.       to be run.
  6096.  
  6097. Remarks:
  6098.  
  6099. Return Value:
  6100.  
  6101.    Returns 0 if successful.  Otherwise, a standard API error code.
  6102.  
  6103.  
  6104. haTerminate
  6105.  
  6106. Releases any resources that are allocated to the external API
  6107. task interface.
  6108.  
  6109. Syntax:
  6110.  
  6111.    INT haTerminate(ScriptHandle, hWndParent)
  6112.  
  6113.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6114.  
  6115.     HWND hWndParent                 A window handle
  6116.  
  6117. Arguments:
  6118.  
  6119.    ScriptHandle
  6120.  
  6121.       The script handle returned from haInitialize.
  6122.  
  6123.    hWndParent
  6124.  
  6125.       The same window handle that was passed to haInitialize.
  6126.  
  6127. Remarks:
  6128.  
  6129.    You call this function after all external API operations have
  6130.    been performed.  It releases any resources that are allocated to
  6131.    the external API task interface.  Any later use of the program -
  6132.    HyperACCESS link results in an error.  This function makes an
  6133.    implicit call to haReleaseRemoteInput for its current session.
  6134.  
  6135. Return Value:
  6136.  
  6137.    Returns 0 if successful.  Otherwise, a standard API error code.
  6138.  
  6139. See Also:
  6140.  
  6141.    haInitialize, haReleaseRemoteInput
  6142.  
  6143.  
  6144. haTextSend
  6145.  
  6146. Queues a text file for transmission through the port of a
  6147. connected session.
  6148.  
  6149. Syntax:
  6150.  
  6151.    INT haTextSend(ScriptHandle, pszFilename)
  6152.  
  6153.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6154.  
  6155.    LPSTR pszFilename                The name of the path and
  6156.                                     filename to be sent
  6157.  
  6158. Arguments:
  6159.  
  6160.    ScriptHandle
  6161.  
  6162.       The script handle returned from haInitialize.
  6163.  
  6164.    pszFilename
  6165.  
  6166.       A pointer to a null terminated string containing the path and
  6167.       filename of the file to be sent.
  6168.  
  6169.  
  6170. Remarks:
  6171.  
  6172.    The file is sent out the port as though it were being typed
  6173.    rapidly by the user.  If any other data is waiting to be
  6174.    transmitted, it will be sent first.
  6175.  
  6176. Return Value:
  6177.  
  6178.    Returns 0 if successful.  Otherwise, a standard API error code.
  6179.  
  6180. See Also:
  6181.  
  6182.    haTypeText, haWaitForOutputDone
  6183.  
  6184. Example:
  6185.  
  6186. /* -------------------------------------------------------------- */
  6187.  
  6188. /* Send a text file as if it were typed.
  6189.    This program segment:
  6190.   - Sends a text file as typed data.  */
  6191.  
  6192. ReturnCode = haTextSend(ScriptHandle, "C:\\MYDIR\\LETTER.TXT");
  6193.  
  6194. /* -------------------------------------------------------------- */
  6195.  
  6196.  
  6197. haTypeLocalText
  6198.  
  6199. Displays text on screen using the current emulator.
  6200.  
  6201. Syntax:
  6202.  
  6203.    INT haTypeLocalText(ScriptHandle, nSize, pszPtr)
  6204.  
  6205.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6206.  
  6207.    INT nSize                        The number of characters
  6208.  
  6209.    LPSTR pszPtr                     A pointer to a string
  6210.  
  6211. Arguments:
  6212.  
  6213.    ScriptHandle
  6214.  
  6215.       The script handle returned from haInitialize.
  6216.  
  6217.    nSize
  6218.  
  6219.       The number of characters in the string to follow.  If the
  6220.       following string is a zero terminated string, this value can
  6221.       be 0. If the string has embedded zero characters, then this
  6222.       value is the number of characters in the string, including the
  6223.       zero characters.
  6224.  
  6225.    pszPtr
  6226.  
  6227.       A pointer to a string of characters.
  6228.  
  6229. Remarks:
  6230.  
  6231.    The text is treated as though it had been received from the
  6232.    remote system.  It is displayed on screen, captured as
  6233.    appropriate, passed into the backscroll buffer, etc.
  6234.  
  6235. Return Value:
  6236.  
  6237.    Returns 0 if successful.  Otherwise, a standard API error code.
  6238.  
  6239. See Also:
  6240.  
  6241.    haTypeText, haWaitForPrompt, haWaitForString
  6242.  
  6243.  
  6244. haTypeText
  6245.  
  6246. Transmits a string of characters through the port of a connected
  6247. session.
  6248.  
  6249. Syntax:  INT haTypeText(ScriptHandle, nSize, pszPtr)
  6250.  
  6251.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6252.  
  6253.    INT nSize                        The number of characters
  6254.  
  6255.    LPSTR pszPtr                     A pointer to a string
  6256.  
  6257. Arguments:
  6258.  
  6259.    ScriptHandle
  6260.  
  6261.       The script handle returned from haInitialize.
  6262.  
  6263.    nSize
  6264.  
  6265.       The number of characters in the string to follow.  If the
  6266.       following string is a NULL terminated string, this value can
  6267.       be 0. If the string has embedded NULLs, then this value is the
  6268.       number of characters in the string, including the embedded
  6269.       NULLs.
  6270.  
  6271.    pszPtr
  6272.  
  6273.       A pointer to a string of characters.
  6274.  
  6275. Remarks:
  6276.  
  6277.    The characters are buffered as necessary.
  6278.  
  6279. Return Value:
  6280.  
  6281.    Returns 0 if successful.  Otherwise, a standard API error code.
  6282.  
  6283. See Also:
  6284.  
  6285.     haTypeLocalText, haWaitForPrompt, haWaitForString
  6286.  
  6287.  
  6288. haWaitForActivity
  6289.  
  6290. Waits for any character to be received from the remote system.
  6291.  
  6292. Syntax:
  6293.  
  6294.    INT haWaitForActivity(ScriptHandle, lTimeout)
  6295.  
  6296.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6297.  
  6298.    LONG lTimeout                    How long to wait
  6299.  
  6300. Arguments:
  6301.  
  6302.    ScriptHandle
  6303.  
  6304.       The script handle returned from haInitialize.
  6305.  
  6306.    lTimeout
  6307.  
  6308.       How long to wait for a character, measured in milliseconds.
  6309.  
  6310. Remarks:
  6311.  
  6312.    If no character is received before the timer expires, an error is
  6313.    returned.  This function is most often used to wait for the
  6314.    remote system to complete an operation that doesn't generate
  6315.    output.
  6316.  
  6317. Return Value:
  6318.  
  6319.    Returns 0 if successful.  Otherwise, a standard API error code.
  6320.  
  6321. See Also:
  6322.  
  6323.    haGetInput, haWaitForLines, haWaitForLull
  6324.  
  6325.  
  6326. haWaitForConnection
  6327.  
  6328. Waits for the connection status to match the supplied parameter.
  6329.  
  6330. Syntax:
  6331.  
  6332.    INT haWaitForConnection(ScriptHandle, nStatus, lTimeout)
  6333.  
  6334.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6335.  
  6336.    INT nStatus                      The status to wait for
  6337.  
  6338.    LONG lTimeout                    How long to wait
  6339.  
  6340. Arguments:
  6341.  
  6342.    ScriptHandle
  6343.  
  6344.       The script handle returned from haInitialize.
  6345.  
  6346.    nStatus
  6347.  
  6348.       The function waits for one of the following:
  6349.  
  6350.    Value                            Meaning
  6351.  
  6352.    HA_CONNECTED                     The session is currently
  6353.                                     connected.
  6354.    HA_DISCONNECTED                  The session is currently
  6355.                                     disconnected.
  6356.    HA_CONNECTING                    The session is currently in the
  6357.                                     process of attempting a
  6358.                                     connection.
  6359.  
  6360.    lTimeout
  6361.  
  6362.       How long to wait for the connection state before timing out,
  6363.       measured in milliseconds.
  6364.  
  6365. Remarks:
  6366.  
  6367.    This function should be used to wait for a connection to complete
  6368.    rather than calling haGetConnectionStatus repeatedly.  In an
  6369.    event driven environment like Windows, it is important to make
  6370.    sure that a program doesn't hog the system while waiting for an
  6371.    external event.
  6372.  
  6373. Return Value:
  6374.  
  6375.    Returns 0 if successful.  Otherwise, a standard API error code.
  6376.  
  6377. See Also:
  6378.  
  6379.    haConnectSession, haDisconnectSession, haGetConnectionStatus
  6380.  
  6381.  
  6382. haWaitForLines
  6383.  
  6384. Waits for a specified number of lines to be received.
  6385.  
  6386. Syntax:
  6387.  
  6388.    INT haWaitForLines(ScriptHandle, nLines, lTimeout)
  6389.  
  6390.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6391.  
  6392.    INT nLines                        Number of lines to wait for
  6393.  
  6394.    LONG lTimeout                     How long to wait
  6395.  
  6396. Arguments:
  6397.  
  6398.    ScriptHandle
  6399.  
  6400.       The script handle returned from haInitialize.
  6401.  
  6402.    nLines
  6403.  
  6404.       The number of lines to wait for.
  6405.  
  6406.   lTimeout
  6407.  
  6408.       Argument How long to wait before returning an error, measured
  6409.       in milliseconds.
  6410.  
  6411. Remarks:
  6412.  
  6413.    A line is considered to be received when a carriage return
  6414.    character is received.  If the function does not receive the
  6415.    specified number of lines within the time limit, an error is
  6416.    returned.
  6417.  
  6418. Return Value:
  6419.  
  6420.    Returns 0 if successful.  Otherwise, a standard API error code.
  6421.  
  6422. See Also:
  6423.  
  6424.     haWaitForActivity, haWaitForLull
  6425.  
  6426.  
  6427. haWaitForLull
  6428.  
  6429. Waits for a pause or a gap in the input data stream of a
  6430. specified minimum size.
  6431.  
  6432. Syntax:
  6433.  
  6434.    INT haWaitForLull(ScriptHandle, lPause, lTimeout)
  6435.  
  6436.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6437.  
  6438.    LONG lPause                      The size of the pause
  6439.  
  6440.    LONG lTimeout                    The timeout limit
  6441.  
  6442. Arguments:
  6443.  
  6444.    ScriptHandle
  6445.  
  6446.       The script handle returned from haInitialize.
  6447.  
  6448.    lPause
  6449.  
  6450.       The size of the pause or gap to wait for, measured in
  6451.       milliseconds.
  6452.  
  6453.    lTimeout
  6454.  
  6455.       How long to wait for the pause or gap, measured in
  6456.       milliseconds.
  6457.  
  6458. Remarks:
  6459.  
  6460.    If a pause or gap is not found within the specified timeout
  6461.    interval, an error is returned.
  6462.  
  6463. Return Value:
  6464.  
  6465.    Returns 0 if successful.  Otherwise, a standard API error code.
  6466.  
  6467. See Also:
  6468.  
  6469.    haWaitForActivity, haWaitForLines, haWaitForPrompt
  6470.  
  6471. Example:
  6472.  
  6473. /* -------------------------------------------------------------- */
  6474.  
  6475. /* Wait for activity from remote system.
  6476.    This program segment:
  6477.   - Waits up to 100 seconds for HyperACCESS to receive a character
  6478.     from the remote system.  */
  6479.  
  6480. ReturnCode = haWaitForActivity(ScriptHandle, 100000L);
  6481.  
  6482. /* Wait for no activity from remote system.
  6483.    This program segment:
  6484.   - Waits up to 100 seconds for HyperACCESS to stop receiving
  6485.     characters from the remote system.  It defines a lull as 5
  6486.     seconds without activity.  */
  6487.  
  6488. ReturnCode = haWaitForLull(ScriptHandle, 5000L, 100000L);
  6489.  
  6490.  
  6491. /* -------------------------------------------------------------- */
  6492.  
  6493.  
  6494. haWaitForOutputDone
  6495.  
  6496. Waits for a session to finish sending any text that may be in the
  6497. buffer and hasn't been transmitted.
  6498.  
  6499. Syntax:
  6500.  
  6501.    INT haWaitForOutputDone(ScriptHandle, lTimeout)
  6502.  
  6503.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6504.  
  6505.    LONG lTimeout                    How long to wait before
  6506.                                     returning
  6507.  
  6508. Arguments:
  6509.  
  6510.    ScriptHandle
  6511.  
  6512.       The script handle returned from haInitialize.
  6513.  
  6514.    lTimeout
  6515.  
  6516.       The number of milliseconds to wait for the output to finish
  6517.       before returning an error.
  6518.  
  6519. Remarks:
  6520.  
  6521.    Because different types of communication devices buffer outgoing
  6522.    data differently, this function can't always determine when all
  6523.    data has actually been transmitted.  It will return after
  6524.    HyperACCESS has passed all outgoing data from its internal
  6525.    buffers to the communications device.
  6526.  
  6527. Return Value:
  6528.  
  6529.    Returns 0 if successful.  Otherwise, a standard API error code.
  6530.  
  6531. See Also:
  6532.  
  6533.    haTextSend, haTypeText
  6534.  
  6535.  
  6536. haWaitForPrompt
  6537.  
  6538. Checks characters read from the connected device to see if they
  6539. match any of a number of specified character strings.
  6540.  
  6541. Syntax:
  6542.  
  6543.    INT haWaitForPrompt(ScriptHandle, nCount, pszText, lPause,
  6544.            lTimeout)
  6545.  
  6546.     SCRIPTHANDLE ScriptHandle       The program - HyperACCESS link
  6547.  
  6548.    INT nCount                       The number of strings to follow
  6549.  
  6550.    LPSTR pszText                    A pointer to a string sequence
  6551.  
  6552.    LONG lPause                      How long a pause to require
  6553.  
  6554.    LONG lTimeout                    How long to wait before timeout
  6555.  
  6556. Arguments:
  6557.  
  6558.    ScriptHandle
  6559.  
  6560.       The script handle returned from haInitialize.
  6561.  
  6562.    nCount
  6563.  
  6564.       This variable determines the number of strings that are to
  6565.       be searched for.
  6566.  
  6567.    pszText
  6568.  
  6569.       A pointer to the first of a series of strings to search for.
  6570.       The strings follow one another in memory and are separated by
  6571.       a single NULL ('\0') character.  The last string is also
  6572.       terminated by an additional NULL ('\0') character.
  6573.  
  6574.    lPause
  6575.  
  6576.       This value, measured in milliseconds, is how long a pause
  6577.       must be seen after one of the strings is seen before a
  6578.       positive return is generated.
  6579.  
  6580.    lTimeout
  6581.  
  6582.       This value, measured in milliseconds, is how long to wait for
  6583.       one of the strings to arrive before returning an error.
  6584.  
  6585. Remarks:
  6586.  
  6587.    Once a match is made, the function checks for a pause or gap in
  6588.    the input stream of a specified period.  If no characters are
  6589.    received during this period, the index of the string that was
  6590.    matched is returned.  Otherwise, the search continues until the
  6591.    timeout value is exceeded.  If the timeout is exceeded, an error
  6592.    is returned.  When responding to prompts from a remote system,
  6593.    this function is often more reliable than haWaitForString.  If,
  6594.    for example, you needed to wait for a prompt such as "Enter
  6595.    password ", a call to haWaitForString(..., "password", ...)
  6596.    could match the word "password" prematurely as it was displayed
  6597.    in a paragraph of instructions.  Alternatively, if you use
  6598.    haWaitForPrompt(...,"password", 500L, ...), you would skip the
  6599.    descriptive paragraph because additional text would immediately
  6600.    follow "password"and the prompt delay wouldn't be satisfied.
  6601.  
  6602. Return Value:
  6603.  
  6604.    Returns the index of the string that matched, if successful.
  6605.  
  6606.    Otherwise, a standard API error code.
  6607.  
  6608. See Also:
  6609.  
  6610.    haGetInput, haWaitForString
  6611.  
  6612.  
  6613. haWaitForString
  6614.  
  6615. Checks characters read from the connected device to see if they
  6616. match any number of specified character strings.
  6617.  
  6618. Syntax:
  6619.  
  6620.    INT haWaitForString(ScriptHandle, nCount, pszText, lTimeout)
  6621.  
  6622.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6623.  
  6624.    INT nCount                       The number of strings to follow
  6625.  
  6626.    LPSTR pszText                    A pointer to a string sequence
  6627.  
  6628.    LONG lTimeout                    How long to wait before timeout
  6629.  
  6630.  
  6631. Arguments:
  6632.  
  6633.    ScriptHandle
  6634.  
  6635.       The script handle returned from haInitialize.
  6636.  
  6637.    nCount
  6638.  
  6639.     This variable determines the number of strings that are to be
  6640.     searched for.
  6641.  
  6642.    pszText
  6643.  
  6644.       A pointer to the first of a series of strings to search for.
  6645.       The strings follow one another in memory and are separated by
  6646.       a single NULL ('\0') character.  The last string is also
  6647.       terminated by a NULL ('\0') character.  lTimeout This value,
  6648.       measured in milliseconds, is how long to wait for one of the
  6649.       strings to arrive before returning an error.
  6650.  
  6651. Remarks:
  6652.  
  6653.    Unlike haWaitForPrompt, this function doesn't require a pause
  6654.    after a string match.
  6655.  
  6656. Return Value:
  6657.  
  6658.    Returns the index of the string that matched, if successful.
  6659.    Otherwise, a standard API error code.
  6660.  
  6661. See Also:
  6662.  
  6663.    haGetInput, haWaitForPrompt
  6664.  
  6665.  
  6666. haWaitForXfer
  6667.  
  6668. Waits for a transfer to complete.
  6669.  
  6670. Syntax:
  6671.  
  6672.    INT haWaitForXfer(ScriptHandle, lTimeout)
  6673.  
  6674.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6675.  
  6676.    LONG lTimeout                    How long to wait
  6677.  
  6678. Arguments:
  6679.  
  6680.    ScriptHandle
  6681.  
  6682.       The script handle returned from haInitialize.
  6683.  
  6684.    lTimeout
  6685.  
  6686.       The number of milliseconds to wait for the transfer to end
  6687.       before returning an error.
  6688.  
  6689. Remarks:
  6690.  
  6691.    This function can be called any time after the transfer is
  6692.    started.  It returns when the transfer is complete.  It is only
  6693.    needed if the call that started the transfer did not specify the
  6694.    wait flag itself.
  6695.  
  6696. Return Value:
  6697.  
  6698.    Returns 0 if successful.  Otherwise, a standard API error code.
  6699.  
  6700. See Also:
  6701.  
  6702.    haXferDropSend, haXferReceive, haXferSend, haGetXferStatus
  6703.  
  6704.  
  6705. haWriteLogEntry
  6706.  
  6707. Appends a time and date stamped entry to the log file for the
  6708. currently active session.
  6709.  
  6710. Syntax:
  6711.  
  6712.    INT haWriteLogEntry(ScriptHandle, pszPtr)
  6713.  
  6714.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6715.  
  6716.    LPSTR pszPtr                     A pointer to a string
  6717.  
  6718. Arguments:
  6719.  
  6720.    ScriptHandle
  6721.  
  6722.       The script handle returned from haInitialize.
  6723.  
  6724.    pszPtr
  6725.  
  6726.       A pointer to the string that is to be appended to the log
  6727.       file.
  6728.  
  6729. Remarks:
  6730.  
  6731.    Several events are automatically entered into the log file by
  6732.    HyperACCESS.  This function lets you add your own entries.
  6733.  
  6734. Return Value:
  6735.  
  6736.    Returns 0 if successful.  Otherwise, a standard API error code.
  6737.  
  6738. See Also:
  6739.  
  6740. haGetLogFileName, haSetLogFileName
  6741.  
  6742.  
  6743. haXferAddToSendList
  6744.  
  6745. Adds a path and filename to the internal list of files queued for
  6746. sending.
  6747.  
  6748. Syntax:
  6749.  
  6750.    INT haXferAddToSendList(ScriptHandle, pszName)
  6751.  
  6752.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6753.  
  6754.    LPSTR pszName                    A pointer to a path and filename
  6755.  
  6756. Arguments:
  6757.  
  6758.    ScriptHandle
  6759.  
  6760.      The script handle returned from haInitialize.
  6761.  
  6762.    pszName
  6763.  
  6764.       A pointer to an array or string containing the null terminated
  6765.       path and filenames.  Remarks:  HyperACCESS maintains in
  6766.       internal list of files that can be sent to a remote system
  6767.       using one of the supported file transfer protocols.  The list
  6768.       is empty when a session is opened.  You can insert any number
  6769.       of files into this list using haXferAddToSendList.  When
  6770.       you've completed adding files to the list, you would normally
  6771.       use haXferSendFromList to send them to the remote system using
  6772.       the current transfer protocol.  The list can be examined using
  6773.       haGetXferSendList or explicitly cleared using
  6774.       haClearXferSendList.  The list is also cleared after all files
  6775.       are sent.  Several other functions send files from the send
  6776.       list although they are not normally used for that purpose.
  6777.       haXferSend, haXferSendBatch, and haXferSendList. are self-
  6778.       contained send functions, but they also send files from
  6779.       the list if any are present.  No checking for duplicate files
  6780.       or actual existance of files is performed.  Placing duplicate
  6781.       names in the list results in multiple copies of the file being
  6782.       sent.  Placing invalid filenames or the names of non-existant
  6783.       files in the list will usually cause an error during the
  6784.       transfer.
  6785.  
  6786. Return Value:
  6787.  
  6788.    Returns 0 if successful.  Otherwise, a standard API error code.
  6789.  
  6790. See Also:
  6791.  
  6792.    haClearXferSendList, haGetXferSendList, haXferSendFromList
  6793.  
  6794. Example:
  6795.  
  6796. /* -------------------------------------------------------------- */
  6797.  
  6798. /* Send multiple files specified by the user.
  6799.    This program segment:
  6800.   - Uses a message box to ask if the user has file(s) to
  6801.     send.
  6802.   - Loops until user finished adding.
  6803.   - Sends list of files.  */
  6804.  
  6805. ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
  6806.                   "Do you want to send files" , 0 , 0, HA_MB_YN);
  6807. if (ReturnCode == 1)
  6808. {
  6809.    while (ReturnCode == 1)
  6810.    { ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",
  6811.          "Enter a file to send:"  , strlen(FName), FName, HA_MB_OK);
  6812.      ReturnCode = haXferAddToSendList(ScriptHandle, FName);
  6813.     }
  6814.     ReturnCode = haXferSendFromList(ScriptHandle, TRUE);
  6815. }
  6816.  
  6817. /* -------------------------------------------------------------- */
  6818.  
  6819.  
  6820. haXferDropSend
  6821.  
  6822. This function sends files that have been placed on the internal
  6823. dropped-files list using the current default protocol.
  6824.  
  6825. Syntax:
  6826.  
  6827.    INT haXferDropSend(ScriptHandle, nFlag)
  6828.  
  6829.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6830.  
  6831.    INT nFlag                        The wait flag
  6832.  
  6833. Arguments:
  6834.  
  6835.    ScriptHandle
  6836.  
  6837.       The script handle returned from haInitialize.
  6838.  
  6839.    nFlag
  6840.  
  6841.       If TRUE, the function waits until the transfer has completed
  6842.       before returning.  If FALSE, the function returns as soon as
  6843.       the transfer is started.
  6844.  
  6845. Remarks:
  6846.  
  6847.    If the user drags files and drops them on an open HyperACCESS
  6848.    session window, HyperACCESS builds an internal list of dropped
  6849.    filenames. If the File Usage dialog contains the name of a
  6850.    program to run when files are dropped, that program is executed.
  6851.    It can either examine the list of dropped files using
  6852.    haGetXferDropList, or send them to the remote system using this
  6853.    function.  The list is cleared after all files are sent.
  6854.    Normally, nFlag should be TRUE.  This causes file transfer to
  6855.    proceed to completion before the function call returns.  If nFlag
  6856.    is FALSE, however, the function starts the transfer and returns
  6857.    immediately.  Your program can then use haGetXferStatus and
  6858.    haWaitForXfer to monitor the transfer.
  6859.  
  6860. Return Value:
  6861.  
  6862.    Returns 0  if successful.  Otherwise, a standard API error code.
  6863.  
  6864. See Also:
  6865.  
  6866. haClearXferDropList, haGetXferDropList, haGetXferStatus,
  6867. haWaitForXfer, haXferSend, haXferSendBatch, haXferSendFromList,
  6868. haXferSendList
  6869.  
  6870.  
  6871. haXferReceive
  6872.  
  6873. Starts to receive a file or group of files sent by the remote
  6874. system.
  6875.  
  6876. Syntax:
  6877.  
  6878.    INT haXferReceive(ScriptHandle, pszName, nFlag)
  6879.  
  6880.  
  6881.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6882.  
  6883.    LPSTR pszName                     A pointer to a string
  6884.  
  6885.    INT nFlag                         The wait flag
  6886.  
  6887. Arguments:
  6888.  
  6889.    ScriptHandle
  6890.  
  6891.       The script handle returned from haInitialize.
  6892.  
  6893.    pszName
  6894.  
  6895.       This parameter points to the filename or directory to receive
  6896.       into, depending on requirements of the protocol.
  6897.  
  6898.    nFlag
  6899.  
  6900.       If TRUE, the function waits until the transfer has completed
  6901.       before returning.  If FALSE, the function returns as soon as
  6902.       the transfer is started.
  6903.  
  6904. Remarks:
  6905.  
  6906.    You should call haSetXferProtocol, haSetXferDirectory, and
  6907.    haSetXferParameters, if necessary, prior to calling
  6908.    haXferReceive.  If the filename doesn't include a directory path,
  6909.    the default directory path is used.  Normally, nFlag should be
  6910.    TRUE.  This causes file transfer to proceed to completion before
  6911.    the function call returns.  If nFlag is FALSE, however, the
  6912.    function starts the transfer and returns immediately.  Your
  6913.    program can then use haGetXferStatus and haWaitForXfer to monitor
  6914.    the transfer.
  6915.  
  6916. Return Value:
  6917.  
  6918.    Returns 0 if successful.  Otherwise, a standard API error code.
  6919.  
  6920. See Also:
  6921.  
  6922.    haGetXferStatus, haSetXferDirectory, haSetXferParameters,
  6923.    haSetXferProtocol, haXferSend
  6924.  
  6925. Example:
  6926.  
  6927. /* -------------------------------------------------------------- */
  6928.  
  6929. /* Receive a specific file.
  6930.    This program segment:
  6931.   - Uses the default receive protocol and directory.
  6932.   - Starts to receive a particular file assuming the protocol
  6933.     supports filename transfers.  The TRUE parameter indicates that
  6934.     HyperACCESS shouldn't return to the function until the transfer
  6935.     is complete. */
  6936.  
  6937. ReturnCode = haXferReceive(ScriptHandle, "MYFILE.TXT", TRUE);
  6938.  
  6939. /* -------------------------------------------------------------- */
  6940.  
  6941.  
  6942. haXferSend
  6943.  
  6944. Adds a single file to the internal list of files to be
  6945. transferred and starts to send the contents of the list to the
  6946. remote using the current default protocol.
  6947.  
  6948. Syntax:
  6949.  
  6950.    INT haXferSend(ScriptHandle, pszName, nFlag)
  6951.  
  6952.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  6953.  
  6954.    LPSTR pszName                     A pointer to a string
  6955.  
  6956.    INT nFlag                         The wait flag
  6957.  
  6958. Arguments:
  6959.  
  6960.    ScriptHandle
  6961.  
  6962.       The script handle returned from haInitialize.
  6963.  
  6964.    pszName
  6965.  
  6966.       This parameter points to a string containing the path and
  6967.       filename of the file that is to be sent.  
  6968.  
  6969.    nFlag 
  6970.  
  6971.       If TRUE, the function waits until the transfer has 
  6972.       completed before returning.  If FALSE, the function
  6973.       returns as soon as the transfer is started.  Remarks:  If
  6974.       the filename doesn't include directory information, the
  6975.       default transfer directory is used.  By default, the list 
  6976.       of queued files is empty, resulting in one file being
  6977.       transferred.  Calling this function clears the internal 
  6978.       file list.  Normally, nFlag should be TRUE.  This causes
  6979.       file transfer to proceed to completion before the function
  6980.       call returns.  If nFlag is FALSE, however, the function
  6981.       starts the transfer and returns immediately.  Your program
  6982.       can then use haGetXferStatus and haWaitForXfer to monitor
  6983.       the transfer.
  6984.  
  6985. Return Value:
  6986.  
  6987.    Returns 0 if successful.  Otherwise, a standard API error code.
  6988.  
  6989. See Also:
  6990.  
  6991.    haGetXferStatus, haSetXferDirectory, haSetXferProtocol,
  6992.    haWaitForXfer, haXferReceive, haXferSendFromList
  6993.  
  6994. Example:
  6995.  
  6996. /* ------------------------------------------------------------- */
  6997.  
  6998. /* Send a specifice file.
  6999.    This program segment:
  7000.   - Sends a particular file using an absolute path.  Note double
  7001.     slash (\\). Required because single slash is C escape character.
  7002.   - The FALSE parameter indicates that HyperACCESS should return to
  7003.     the function as soon as the transfer starts.
  7004.   - Minimizes the HyperACCESS application window.
  7005.   - Allow up to 1 hour for transfer to complete.
  7006.   - If timeout, display an error message. */
  7007.  
  7008. ReturnCode = haXferSend(ScriptHandle, "C:\\MYDIR\\DOOM.ZIP", FALSE);
  7009. ReturnCode = haSizeHyperACCESS(ScriptHandle, HA_S_MIN);
  7010. if (haWaitForXfer(ScriptHandle, 3600000L) == HA_ERR_TIMED_OUT)
  7011.    ReturnCode = haMessageBox(ScriptHandle, "Transfer Error",
  7012.              "Transfer timed out.", 0, 0, HA_MB_OK);
  7013.  
  7014. /* -------------------------------------------------------------- */
  7015.  
  7016.  
  7017. haXferSendBatch
  7018.  
  7019. Adds a batch of files to the internal list of files queued to be
  7020. transferred and sends the files on the list to the remote system
  7021. using the default protocol.
  7022.  
  7023. Syntax:
  7024.  
  7025.    INT haXferSendBatch(ScriptHandle, pszName, nFlag)
  7026.  
  7027.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  7028.  
  7029.    LPSTR pszName                    A pointer to a string
  7030.  
  7031.    INT nFlag                        The wait flag
  7032.  
  7033. Arguments:
  7034.  
  7035.    ScriptHandle
  7036.  
  7037.       The script handle returned from haInitialize.
  7038.  
  7039.    pszName
  7040.  
  7041.       A pointer to a string that contains the name of the batch
  7042.      file.  The file is an ASCII text file that contains the names
  7043.      of the files to be transferred.  The file contains one file
  7044.      description per line.
  7045.  
  7046.    nFlag
  7047.  
  7048.       If TRUE, the function waits until the transfer has completed
  7049.       before returning.  If FALSE, the function returns as soon as
  7050.       the transfer is started.
  7051.  
  7052. Remarks:
  7053.  
  7054.    A batch file is a list of paths and filenames in a file.  A batch
  7055.    file can be created in the Send dialog box of HyperACCESS or can
  7056.    be created by any standard text editor.  By default the internal
  7057.    list of files to be sent is empty.  Calling this function clears
  7058.    the internal file list.  Normally, nFlag should be TRUE.  This
  7059.    causes file transfer to proceed to completion before the function
  7060.    call returns.  If nFlag is FALSE, however, the function starts
  7061.    the transfer and returns immediately.  Your program can then use
  7062.    haGetXferStatus and haWaitForXfer to monitor the transfer.
  7063.  
  7064. Return Value:
  7065.  
  7066.    Returns 0 if successful.  Otherwise, a standard API error code.
  7067.  
  7068. See Also:
  7069.  
  7070.    haGetXferStatus, haSetXferDirectory, haSetXferParameters,
  7071.    haSetXferProtocol, haWaitForXfer, haXferSend, haXferSendFromList
  7072.  
  7073.  
  7074. haXferSendFromList
  7075.  
  7076. Sends files that are on the internal list of files queued to be
  7077. transferred using the current default protocol.
  7078.  
  7079. Syntax:
  7080.  
  7081.    INT haXferSendFromList(ScriptHandle, nWait)
  7082.  
  7083.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  7084.    INT nWait                        The wait flag
  7085.  
  7086. Arguments:
  7087.  
  7088.    ScriptHandle
  7089.  
  7090.       The script handle returned from haInitialize.
  7091.  
  7092.    nWait
  7093.  
  7094.       If TRUE, the function waits until the transfer has completed
  7095.       before returning.  If FALSE, the function returns as soon as
  7096.       the transfer is started.
  7097.  
  7098. Remarks:
  7099.    By default, the list of queued file is empty and filenames must
  7100.    be explicitly added to the list via API calls.  See the remarks
  7101.    in the description of haXferAddToSendList for information on how
  7102.    to prepare the list.  The internal list of files is cleared after
  7103.    this operation.  Normally, nFlag should be TRUE.  This causes
  7104.    file transfer to proceed to completion before the function call
  7105.    returns.  If nFlag is FALSE, however, the function starts the
  7106.    transfer and returns immediately.  Your program can then use
  7107.    haGetXferStatus and haWaitForXfer to monitor the transfer.
  7108.  
  7109. Return Value:
  7110.  
  7111.    Returns 0 if successful.  Otherwise, a standard API error code.
  7112.  
  7113. See Also:
  7114.  
  7115.    haClearXferSendList, haGetXferSendList, haGetXferStatus,
  7116.    haSetXferDirectory, haSetXferParameters, haSetXferProtocol,
  7117.    haXferAddToSendList, haXferReceive, haXferSend, haWaitForXfer
  7118.  
  7119.  
  7120. haXferSendList
  7121.  
  7122. Adds a list or array of filenames to the the internal list of
  7123. files queued to be transferred.  It sends the files in the list
  7124. to the remote system using the current default protocol.
  7125.  
  7126. Syntax:
  7127.  
  7128.    INT haXferSendList(ScriptHandle, pszPtr, nFlag)
  7129.  
  7130.    SCRIPTHANDLE ScriptHandle        The program - HyperACCESS link
  7131.  
  7132.    LPSTR pszPtr                     A pointer to a string
  7133.  
  7134.    INT nFlag                        The wait flag
  7135.  
  7136. Arguments:
  7137.  
  7138.    ScriptHandle
  7139.  
  7140.       The script handle returned from haInitialize.
  7141.  
  7142.    pszPtr
  7143.  
  7144.       A pointer to an array of string pointers.  Each entry in the
  7145.       array is a far pointer to a string containing a filename.  The
  7146.       last entry in the array must be 0. 
  7147.  
  7148.    nFlag 
  7149.  
  7150.       If TRUE, the function waits until the transfer has
  7151.       completed before returning.  If FALSE, the function returns
  7152.       as soon as the transfer is started.  Remarks:  This 
  7153.       function provides an alternative to adding files
  7154.       individually to the internal file list and then using
  7155.       haXferSendFromList to send them.  You can specify all
  7156.       the files to send and start the transfer with one call.  By
  7157.       default, the internal list of files to be transferred is
  7158.       empty.  If there are files already on the list, however, they
  7159.       will be sent along with the files specified in the array.
  7160.       Sending the files clears the internal file list.  Normally,
  7161.       nFlag should be TRUE.  This causes the file transfer to
  7162.       proceed to completion before the function call returns.  If
  7163.       nFlag is FALSE, however, the function starts the transfer and
  7164.       returns immediately.  Your program can then use
  7165.       haGetXferStatus and haWaitForXfer to monitor the transfer.
  7166.  
  7167. Return Value:
  7168.  
  7169.    Returns 0 if successful.  Otherwise, a standard API error code.
  7170.  
  7171. See Also:
  7172.  
  7173.    haGetXferStatus, haSetXferDirectory, haSetXferParameters,
  7174.    haSetXferProtocol, haWaitForXfer, haXferSend
  7175.  
  7176. Example:
  7177.  
  7178. /* -------------------------------------------------------------- */
  7179.  
  7180. /* Check the first file in the list.
  7181.    This program segment:
  7182.   - Gets the first file in the send list (index starts at 0)
  7183.   - Uses a message box to display the filename and ask if OK.  */
  7184.  
  7185.  
  7186. ReturnCode = haGetXferSendList(ScriptHandle, 0, strlen(FName),
  7187. FName); ReturnCode = haMessageBox(ScriptHandle, "First file to
  7188.        send:", FName, 0, 0, HA_MB_OK);
  7189.  
  7190. /* -------------------------------------------------------------- */
  7191.