home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 3 Comm
/
03-Comm.zip
/
haotd1_1.zip
/
APIHELP.TXT
< prev
next >
Wrap
Text File
|
1995-10-12
|
25KB
|
650 lines
------------------------------------------------------------
HyperACCESS for OS/2 API Examples
------------------------------------------------------------
API Examples
This file contains a series of REXX program code segments that
illustrate how to use most API functions. Each segment includes
commentary that explains the purpose and reasoning behind the
function calls.
The program segments, below, don't include calls to haInitialize
or haTerminate unless specifically required for the example. For
simplicity, they also lack most error checking that good
programming technique requires. Please add return code tests and
have your program take appropriate action.
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
/*
* Capture data to disk.
*This program segment:
* - Waits for a prompt string ("Press Enter to begin...")
* from the remote system
* - Begins capturing all incoming data -- one line at a time
* as the carriage return character is received
* - Appends incoming data to the end of the session's
* default capture file if the file already exists
* - Stops capturing data when an end string appears ("End of
* Data") */
ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Press Enter to begin...", 300, 60000)
ReturnCode = haCaptureBegin(ScriptHandle, "HA_C_LINES", "TRUE")
ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data", 100000)
ReturnCode = haCaptureControl(ScriptHandle, "HA_C_END")
/**************************************************************/
/*
* Capture data to printer.
* This program segment:
* - Waits for a prompt string ("Turn printer on and press Enter to begin...")
* from the remote system
* - Begins capturing all incoming data -- one line at a time as the
* cursor moves off the line.
* - Releases each page to the printer as it fills.
* - Stops capturing data when an end string appears ("End of Data")
*/
ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Turn printer on and press Enter to begin...", 300, 60000)
ReturnCode = haCaptureToPrinterBegin(ScriptHandle, "HA_CP_LINES", "HA_CP_PAGE")
ReturnCode = haWaitForString(ScriptHandle, 1, "End of Data", 100000)
ReturnCode = haCaptureToPrinterControl(ScriptHandle, "HA_CP_END")
/**************************************************************/
/*
* Close an open session.
*/
ReturnCode = haCloseSession(ScriptHandle)
/**************************************************************/
/*
* Dial a remote system from within a script.
* This program segment:
* - Displays a message box to ask if user wants to change the phone number.
* - If yes, it displays another message box to get the new phone number.
* - Connects and dials using the new phone number or uses a standard
* session connect if the user doesn't want to change the phone number.
*/
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Change Phone Number?", 0, , "HA_MB_YN")
IF ReturnCode = 1 THEN
DO
SubReturnCode = haMessageBox(ScriptHandle, "HAOS2 Query:", "Enter Phone Number:", 128, "PNumber", "HA_MB_OK")
SubReturnCode = haConnectAndDial(ScriptHandle, "HA_CNCT_STANDARD", PNumber)
END
IF ReturnCode = 0 THEN
SubReturnCode = haConnectSession(ScriptHandle, "HA_CNCT_STANDARD")
/**************************************************************/
/*
* Connect a session without dialing and transfer all typed characters to the
* modem. This is often referred to as "Terminal Mode".
*
* This program segment:
* - Tells HyperACCESS not to call the remote system on connection.
* This function (haSkipConnection) is required in case the program
* is run as a preconnection program. Otherwise it is ignored.
* - Checks the current connection status, and if already connected
* releases resources and returns control to HyperACCESS.
* - If not connected, request HyperACCESS to connect the session
* (without dialing).
* - Don't wait for connection because there won't be one until the
* user types commands at keyboard.
* - Release resources and return control to HyperACCESS.
*/
ReturnCode = haSkipConnection(ScriptHandle)
Status = haGetConnectionStatus(ScriptHandle)
IF haGetConstantString("haGetConnectionStatus", Status) = "HA_CONNECTED" THEN
DO
ReturnCode = haTerminate(ScriptHandle)
END
ReturnCode = haConnectSession(ScriptHandle, "HA_CNCT_DO_NOT_DIAL")
ReturnCode = haTerminate(ScriptHandle)
/**************************************************************/
/*
* Disconnect from a remote system.
*/
ReturnCode = haDisconnectSession(ScriptHandle)
/**************************************************************/
/*
* Gather and display port information.
* This program segment:
* - Gets the port type, name, and device name.
* - Displays the resulting string in a message box.
*/
ReturnCode = haGetPortPrefs(ScriptHandle, 128, "PType", 128, "PName", 128, "DName")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS",PType||PName||DName, 0, , "HA_MB_OK")
/*
* The function "haGetPortType" also gets port type, but none of the other
* information:
*/
ReturnCode = haGetPortType(ScriptHandle, 128, "PType")
/**************************************************************/
/*
* Get the capture filename from the current session and let the user change it.
* This program segment:
* - Gets the capture filename.
* - Displays the filename in a message box and asks if user wants to
* change the capture file.
* - If the user selects the Yes response, another message box request
* a new filename.
* - If the user enters a new filename, it's saved as the session
* capture file.
*/
ReturnCode = haGetCaptureFileName(ScriptHandle, 128, "FName")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Change name to: "FName, 0, , "HA_MB_YN")
IF ReturnCode >= 0 THEN
DO
SubReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter new Capture File:", 128, "FName", "HA_MB_OK")
SubReturnCode = haSetCaptureFileName(ScriptHandle, FName)
END
/**************************************************************/
/*
* Check the status of the current connection. If offline, make connection.
* This program segment:
* - Checks connection status.
* - If disconnected, request HyperACCESS to perform a standard connection
* sequence.
* - Wait for connection.
* - If connected on entry or connected successfully display "Online" messge.
* - If connection fails for any reason, display "Connection Failed" message.
*/
Status = haGetConnectionStatus(ScriptHandle)
IF haGetConstantString('haGetConnectionStatus', Status) = "HA_DISCONNECTED" THEN
DO
ReturnCode = haConnectSession(ScriptHandle, "HA_CNCT_STANDARD")
IF SubReturnCode = 0 THEN
ReturnCode = haWaitForConnection(ScriptHandle, "HA_CONNECTED", 60000)
END
IF ReturnCode = 0 THEN
DO
haMessageBox(ScriptHandle, "HyperACCESS", "Online!", 0, , "HA_MB_OK")
END
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Connection Failed!", 0, , "HA_MB_OK")
/**************************************************************/
/*
* Change the screen color regardless of terminal emulator in use.
* This program segment:
* - Gets the current terminal emulator.
* - Change the terminal emulator to ANSI so that local commands can
* change screen color.
* - Type local text to change screen color to blue letters on white
* background (see DOS help for ANSI.SYS).
* - Sets the terminal emulator back to its original type.
*/
ReturnCode = haGetEmulator(ScriptHandle, 128, "Emulator")
ReturnCode = haSetEmulator(ScriptHandle, "ANSI")
ReturnCode = haTypeLocalText(ScriptHandle, "1B"x||"[37;44;1m")
ReturnCode = haSetEmulator(ScriptHandle, Emulator)
/**************************************************************/
/*
* Let the user change the dialing prefix if necessary.
* This program segment:
* - Gets the first dialing prefix for the current session.
* - Displays the current prefix in a message box and asks for Yes/No
* response to question.
* - If response is Yes, asks user for new prefix.
* - Sets new prefix (for all sessions).
*/
ReturnCode = haGetDialingPrefix(ScriptHandle, 1, 128, "PNumber")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Is this string correct: "PNumber, 0, , "HA_MB_YN")
IF ReturnCode = 0 THEN
DO
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter new prefix:", 128, "PNumber", "HA_MB_OK")
ReturnCode = haSetDialingPrefix(ScriptHandle, 1, PNumber)
END
/**************************************************************/
/*
* Prompt remote user for data, and respond.
* This program segment:
* - Sends text to remote system requesting input from remote user.
* - Gets input from communications port, but lets HyperACCESS process
* any backspace characters. Waits 100 sec. for first character.
* Waits 30 sec. between characters.
* - If remote user responds, formats response and types message to
* remote user.
*/
ReturnCode = haTypeText(ScriptHandle, 0, "Enter First Name: ")
ReturnCode = haGetInput(ScriptHandle, "HA_GI_BACKSPACE", -1, 100000, 30000, "FName")
IF ReturnCode >= 0 THEN
DO
ReturnCode = haTypeText(ScriptHandle, 0, "Welcome to the system," FName)
END
/**************************************************************/
/*
* Get the log filename and let the user change files if desired.
* This program segment:
* - Gets the log filename for the current session.
* - Displays log filename in a message box and asks for Yes/No
* response to question.
* - If response is Yes, asks user for new filename and sets new log file.
*/
ReturnCode = haGetLogFileName(ScriptHandle, 128, "LogName")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Change Log Filename:" LogName, 0, , "HA_MB_YN")
IF ReturnCode = 0 THEN
DO
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter new Log File:", 128, "LogName", "HA_MB_OK")
ReturnCode = haSetLogFileName(ScriptHandle, LogName)
END
/**************************************************************/
/*
* Open the first session in the Phonebook and connect to it
* This program segment:
* - Gets the filename of the first Phonebook entry
* - Requests HyperACCESS to open and connect to the session.
* (It doesn't wait for connection to complete.)
*/
ReturnCode = haGetPhonebookEntry(ScriptHandle, 1, 128, "FName")
ReternCode = haOpenSession(ScriptHandle, FName)
ReturnCode = haConnectSession(ScriptHandle, "HA_CNCT_STANDARD")
/**************************************************************/
/*
* Get runtime values for NAME, USERID, and PASSWORD. Then use those values.
* This program segment:
* - Gets runtime values if they exist. The TRUE parameter indicates
* that HyperACCESS should automatically prompt for a value if one
* isn't already stored.
* - Use the UserId and password as part of a login sequence with a
* remote system.
*/
ReturnCode = haGetRuntimeValue(ScriptHandle, "HA_RV_USERNAME", "TRUE", 128, "UName")
ReturnCode = haGetRuntimeValue(ScriptHandle, "HA_RV_USERID", "TRUE", 128, "UID")
ReturnCode = haGetRuntimeValue(ScriptHandle, "HA_RV_PASSWORD", "TRUE", 128, "PWord")
/* Assume a connection has been made for this example to talk to. */
ReturnCode = haWaitForPrompt(ScriptHandle, 1, "LOGON ID:", 1000, 60000)
ReturnCode = haTypeText(ScriptHandle, 0, UID)
ReturnCode = haWaitForPrompt(ScriptHandle, 1, "Password:", 1000, 60000)
ReturnCode = haTypeText(ScriptHandle, 0, PWord)
/**************************************************************/
/*
* Get the filename of the currently selected session. If more than one is
* selected, gets the first session filename
*/
ReturnCode = haGetSelectedPhonebookEntry(ScriptHandle, 1, 128, "FName")
/**************************************************************/
/*
* Get text from specific screen positions.
* This program segment:
* - Requests 10 characters starting at screen position 0,35
* where 0 is vertical position (from top),
* 35 is horizontal position (from left).
*/
ReturnCode = haGetTextFromScreen(ScriptHandle, 0, 35, 10, "ScrText")
/**************************************************************/
/*
* Gets HyperACCESS version number, and display it.
* This program segment:
* - Gets HyperACCESS version number
* - Displays log filename in a message box that only accepts on OK
* response.
*/
ReturnCode = haGetVersion(ScriptHandle, 128, "Vers")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Version: "Vers, 0, , "HA_MB_OK")
/**************************************************************/
/**************************************************************/
/* The following program segments illustrate how to use API functions to
manage file transfers. They show how to set directories for send and receive,
change transfer protocol, create a list of files to send, and add files to
the list. */
/**************************************************************/
/**************************************************************/
/*
* Get (and set) directory path to receive files.
* This program segment:
* - Gets default receive directory path.
* - Use a message box to ask if the user wants to change the default path.
* - If the user responds Yes, request a new directory path using a message box.
* - Sets the new directory as the default.
*/
ReturnCode = haGetXferDirectory(ScriptHandle, "HA_XFER_RECV", 128, "DName")
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Change Receive Directory Path?", 0, , "HA_MB_YN")
IF ReturnCode = 1 THEN
DO
SubReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter Receive Directory:", 128, "DName", "HA_MB_OK")
SubReturnCode = haSetXferDirectory(ScriptHandle, "HA_XFER_RECV", DName)
END
/**************************************************************/
/*
* Let the user set default transfer protocols.
* This program segment:
* - Switches to the Terminal Panel.
* - Uses the Properties/Transfer Protocols... menu item to display
* the Transfer Protocols dialog so the user can select new protocols.
*/
ReturnCode = haMenuString(ScriptHandle, "W0")
ReturnCode = haMenuString(ScriptHandle, "PT")
/**************************************************************/
/*
* Set the default receive protocol.
* This program segment:
* - Sets the default receive protocol to HyperProtocol.
*/
ReturnCode = haSetXferProtocol(ScriptHandle, "HA_XFER_RECV", "HA_HYPERP")
/**************************************************************/
/*
* Check current general transfer parameters, and change value.
* This program segment:
* - Gets the current transfer parameters.
* - Sets transfer parameter to overwrite an existing file if parameters
* were set previously to append to an existing file.
*/
XParms = haGetXferParameters(ScriptHandle)
IF BITAND(XParms,haDecodeString("XF_DN_APPEND")) <> 0 THEN
DO
XParms = BITXOR(XParms,haGetConstantValue("XF_DN_MASK"))
XParms = BITOR(XParms,haGetConstantValue("XF_DN_OVERWRT"))
ReturnCode = haSetXferParameters(ScriptHandle, XParms)
END
/**************************************************************/
/*
* Receive a specific file.
* This program segment:
* - Uses the default receive protocol and directory.
* - Starts to receive a particular file assuming the protocol supports
* filename transfers. The TRUE parameter indicates that HyperACCESS
* shouldn't return to the function until the transfer is complete.
*/
ReturnCode = haXferReceive(ScriptHandle, "MYFILE.TXT", "TRUE")
/**************************************************************/
/*
* Send a specific file.
* This program segment:
* - Sends a particular file using an absolute path.
* - The FALSE parameter indicates that HyperACCESS
* should return to the function as soon as the transfer starts.
* - Minimizes the HyperACCESS application window.
* - Allow up to 1 hour for transfer to complete.
* - If timeout, display an error message.
*/
ReturnCode = haXferSend(ScriptHandle, "C:\HAOS2\DOOM.ZIP", "FALSE")
ReturnCode = haSizeHyperACCESS(ScriptHandle, "HA_S_MIN")
ReturnCode = haWaitForXfer(ScriptHandle, 3600000)
IF haGetErrorString(ReturnCode) <> "HA_ERR_OK" THEN
DO
ReturnCode = haMessageBox(ScriptHandle, "Transfer Error", "Transfer timed out.", 0, , "HA_MB_OK")
END
/**************************************************************/
/*
* Send a text file as if it were typed.
* This program segment:
* - Sends a text file as typed data.
*/
ReturnCode = haTextSend(ScriptHandle, "C:\HAOS2\LETTER.TXT")
/**************************************************************/
/*
* Send multiple files specified by the user.
* This program segment:
* - Uses a message box to ask if the user has file(s) to send.
* - Loops until user finished adding.
* - Sends list of files.
*/
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Do you want to send files" , 0 , , "HA_MB_YN")
IF ReturnCode = 1 THEN
DO
DO While ReturnCode = 1
ReturnCode = haMessageBox(ScriptHandle, "HyperACCESS", "Enter a file to send:" , 128, "FName", "HA_MB_OK")
ReturnCode = haXferAddToSendList(ScriptHandle, FName)
END
ReturnCode = haXferSendFromList(ScriptHandle, "TRUE")
END
/**************************************************************/
/*
* Check the first file in the list.
* This program segment:
* - Gets the first file in the send list (index starts at 0)
* - Uses a message box to display the filename and ask if OK.
*/
ReturnCode = haGetXferSendList(ScriptHandle, 0, 128, "FName")
ReturnCode = haMessageBox(ScriptHandle, "First file to send:", FName, 0, , "HA_MB_OK")
/**************************************************************/
/*
* Hide received characters.
* This program segment:
* - Hides received characters.
* - Waits for a carriage return (or 30 seconds).
* - Enables display of received characters after one line
*/
ReturnCode = haSetLocalDisplay(ScriptHandle, "FALSE")
ReturnCode = haWaitForLines(ScriptHandle, 1, 30000)
ReturnCode = haSetLocalDisplay(ScriptHandle, "TRUE")
/**************************************************************/
/* Changes a dialing prefix to a new value.
This program segment:
- Changes the first dialing prefix (for all sessions) to "1-313" */
ReturnCode = haSetDialingPrefix(ScriptHandle, 1, "1-313")
/**************************************************************/
/*
* Select dialing prefix.
* This program segment:
* - Selects the first dialing prefix as the one to use
* for this session
*/
ReturnCode = haSelectDialingPrefix(ScriptHandle, 1)
/**************************************************************/
/*
* Turn off automatic download feature of Zmodem and HyperProtocol.
*/
ReturnCode = haSetAdlOverride(ScriptHandle, "TRUE")
/**************************************************************/
/*
* Change the baud rate of the current session.
* - This program segment sets the baud rate to 19,200.
*/
ReturnCode = haSetBaudRate(ScriptHandle, 19200)
/**************************************************************/
/* Set character echo for half duplex operation.
This program segment:
- Disables echo of characters received.
- Enables echo of characters sent so they display locally. */
ReturnCode = haSetEcho(ScriptHandle, "FALSE")
ReturnCode = haSetLocalEcho(ScriptHandle, "TRUE")
/**************************************************************/
/*
* Set connect script for the current session.
*/
ReturnCode = haSetLogonTask(ScriptHandle, "C:\HAOS2\LOGON.CMD")
/**************************************************************/
/*
* Dismiss message boxes after fixed period of time. This lets a user respond
* if present, or continues with default actions if no user response received
* in fixed time interval (10 seconds, in example).
*/
ReturnCode = haSetMessageTimer(ScriptHandle, 10)
/**************************************************************/
/*
* Change communications parameters.
* This program segment:
* - Sets the port mode to 8 bit, no parity, 1 stop bit.
* - Sets the port name to "COM1".
* - Sets the port type to "Standard COM Port".
*/
PMode = 0
PMode = BITOR(PMode, haGetConstantValue("HA_M_8_BITS"))
PMode = BITOR(PMode, haGetConstantValue("HA_M_N_PRTY"))
PMode = BITOR(PMode, haGetConstantValue("HA_M_1_STOP"))
ReturnCode = haSetPortMode(ScriptHandle, PMode)
ReturnCode = haSetPortName(ScriptHandle, "COM1")
ReturnCode = haSetPortType(ScriptHandle, "STANDARD COM PORT")
/**************************************************************/
/*
* Change communications parameters and modem.
* This program segement:
* - Uses one function call to set port name, port type, and modem
*/
ReturnCode = haSetPortPrefs(ScriptHandle, "STANDARD COM PORT", "COM1", "Amstrad Quad")
/**************************************************************/
/*
* Change dialing type to PULSE.
*/
ReturnCode = haSetPulseTone(ScriptHandle, "HA_PT_PULSE")
/**************************************************************/
/*
* Set the number of rings to answer the phone, and put modem in answer mode.
* This program segment:
* - Sets the number of rings before answer to 3.
* - Connects the session to its port in answer mode.
*/
ReturnCode = haSetRingsForAnswer(ScriptHandle, 3)
ReturnCode = haConnectSession(ScriptHandle, "HA_CNCT_ANSWER_MODE")
/**************************************************************/
/*
* Set HyperACCESS window sizes.
* This program segment:
* - Maximizes the HyperACCESS application window.
* - Sets the session window to its previous size.
*/
ReturnCode = haSizeHyperACCESS(ScriptHandle, "HA_S_MAX")
ReturnCode = haSizeSession(ScriptHandle, "HA_S_RSTR")
/**************************************************************/
/*
* Pause execution of the script. haSleep doesn't block other tasks from
* getting CPU time, and lets HyperACCESS continue to send and receive data.
* This program segment:
* - Pauses for 10 seconds.
*/
ReturnCode = haSleep(ScriptHandle, 10000)
/**************************************************************/
/*
* Wait for activity from remote system.
* This program segment:
* - Waits up to 100 seconds for HyperACCESS to receive a character
* from the remote system.
*/
ReturnCode = haWaitForActivity(ScriptHandle, 100000)
/**************************************************************/
/*
* Wait for no activity from remote system.
* This program segment:
* - Waits up to 100 seconds for HyperACCESS to stop receiving
* characters from the remote system. It defines a lull as 5 seconds
* without activity.
*/
ReturnCode = haWaitForLull(ScriptHandle, 5000, 100000)
/**************************************************************/