pcANYWHERE IV Programmer's Interface The pcANYWHERE IV Application Programmer's Interface (API) makes it possible for a user's program to interact with and possibly modify the operation of pcANYWHERE IV. The programmer's interface is intended for use by programmers with experience in IBM PC assembly language. pcANYWHERE IV API functions are invoked from assembly language by issuing a far call to the pcANYWHERE IV API entry point with a function number in the AX register and other parameters in various registers. The status of the function is returned in the AX register. Before a program may call the pcANYWHERE IV API, it must first determine the entry point. This is accomplished by issuing a DOS INT 21H "Set Date" function to set a specific invalid date (as described below). If pcANYWHERE IV is not resident, DOS will simply return an invalid function error code. If pcANYWHERE IV is resident, it will intercept the function and return the value 'OK' or 'ok' in the AX register and the API entry point in CX:DX. The following is a sample program that determines if pcANYWHERE IV is resident and if so, displays its current status: dseg segment para public 'DATA' AW4_Address dd 0 ;Place to store pcANYWHERE IV API entry point NoAW4 db 13,10,'pcANYWHERE IV is not resident.',13,10,'$' AW4Active db 13,10,'pcANYWHERE IV is active.',13,10,'$' AW4Ready db 13,10,'pcANYWHERE IV is ready for a connection.',13,10,'$' AW4Idle db 13,10,'pcANYWHERE IV is inactive.',13,10,'$' dseg ends stack segment para stack 'STACK' dw 200H dup (0) stack ends cseg segment para public 'CODE' assume cs:cseg, ds:dseg, ss:stack main proc far push ds ;Put return to DOS on stack xor ax,ax push ax mov ax,dseg ;Set DS to our data segment mov ds,ax call near ptr Find_AW4 ;See if pcANYWHERE IV is resident jz AW4_Resident ;Continue if so mov dx,Offset NoAW4 ;If not, point to not resident message jmp Display_Status ;Go display status and exit AW4_Resident: mov word ptr AW4_Address,dx ;Save pcANYWHERE IV API entry point mov word ptr AW4_Address+2,cx mov ax,2 ;Function number to get pcAW4 status call AW4_Address ;On return, AH=operating mode, AL=status mov dx,Offset AW4Active ;Point to pcANYWHERE IV is active message test al,1 ;If bit 0 of AL is set, session is active jnz Display_Status ;Jump if so mov dx,Offset AW4Ready ;Point to pcANYWHERE IV is ready message cmp ah,2 ;Check for mode=2, "allow incoming calls" je Display_Status ; Jump if so mov dx,Offset AW4Idle ;Must be in "hot key activates" mode Display_Status: mov ah,9 ;DOS function to display a string int 21H ;Display the status message ret ;Return to DOS main endp ; ; This routine determines if pcANYWHERE IV is resident ; and returns with the Z flag set if so, or clear if not. ; ; We will check for pcANYWHERE IV by issuing a DOS INT 21H function ; to set the date to a specific invalid date. If pcANYWHERE IV is not ; resident, DOS will return with an invalid date error code. ; If pcANYWHERE IV is present, it will intercept the call and return ; with the value 'OK' in the AX register, and its entry point in CX:DX. ; (Note: If the small version of the pcANYWHERE IV/LAN host is resident, ; it will return with AX set to 'ok' in lowercase.) ; Find_AW4 proc near mov ah,2BH ;DOS INT 21H set date function number. mov al,'D' ;Load registers with pcANYWHERE IV signature. mov bx,'MA' ; The values loaded into the registers mov cx,'pc' ; are not a valid date and DOS will return mov dx,'AW' ; with AL = 0FFH if pcANYWHERE IV is not int 21H ; resident. cmp ax,'OK' ;Is pcANYWHERE IV resident ? je FIND_AW4_EXIT ; If so, return, Z flag is set cmp ax,'ok' ;Set Z flag if a "small" host is resident Find_AW4_Exit: ret ;If pcANYWHERE IV is resident, Z flag is set ; and CX:DX has its entry point. Find_AW4 endp cseg ends end main The pcANYWHERE IV API functions are divided into two groups: 1) general functions and 2) communications functions. All functions are passed a function number and return status in the AX register. For general functions, additional parameters, if required, are passed to the function in a buffer pointed to by DS:SI and additional return information is placed in a buffer pointed to by DS:DI. All registers are preserved. For communications functions, additional parameters are passed in BX and CX. DS, ES, DI, SI and BP are preserved. The functions supported by the pcANYWHERE IV API are as follows: General functions Function number Description --------------- -------------------------------------------- 0000H Get pcANYWHERE IV version 0001H Initialize pcANYWHERE IV operation 0002H Get pcANYWHERE IV status 0003H Suspend remote screen updates 0004H Resume remote screen updates 0005H End current remote access session 0006H Remove pcANYWHERE IV from memory Communications functions Function number Description --------------- -------------------------------------------- 8000H Read data from communication channel 8001H Write data over communication channel 8002H Get connection status Note: The communications functions (8000H-8002H) should only be used after function 0003H has been called to suspend pcANYWHERE IV. Function descriptions: ============================================================================ Function 0000H - Get pcANYWHERE IV version Calling parameters: AX = 0000H DS:DI = Pointer to a 1 byte reply buffer where the host type code is to be placed. Returns: AH = Version number AL = Revision number DS:DI = Pointer to host type code 0 - host is a full featured host 1 - host is a limited feature LAN host Description: This function returns pcANYWHERE IV's version and revision number as well as a host type code. This function should be used to determine if the resident host can support the pcANYWHERE IV functions that your program will be using. IMPORTANT NOTE! If the byte returned at DS:DI is not a 0 or a 1, your program should refrain from making additional API calls. Values greater than 1 are reserved for custom versions of pcANYWHERE IV which may NOT fully support the programmer's interface. Issuing the API call's described here when the host type code is not a 0 or a 1 could result in the host PC hanging. ============================================================================ Function 0001H - Initialize pcANYWHERE IV operation Calling parameters: AX = 0001H DS:SI = Pointer to request structure formatted as follows: BYTE Operating mode 0 = Wait for a call 1 = Hot key activates 2 = Incoming call activates 3 = Initiate a call BYTE[3] User ID to append to config file names WORD DS relative pointer to path for config files WORD DS relative pointer to path for program files Returns: AX = Status of function 0000H - Function completed successfully FFFDH - The specified operating mode is invalid FFFCH - A remote access session is active FFFAH - The configuration file could not be found FFF9H - The configuration file is invalid FFF7H - The communications driver type specified in the configuration file is different than the one loaded when pcANYWHERE IV was initially started. Once the pcANYWHERE IV host has been loaded, the driver type may not be changed. If a different driver needs to be loaded, pcANYWHERE IV must first be removed from memory. FFF6H - The host operator aborted the function FFF5H - The communications device could not be initialized The reason for initialization failure depends on the type of device. If the device is a software driver (IPX, NetBIOS, etc), then the required interface software is probably not installed (IPX, NetBIOS, etc.). If the device is a local serial port, then the COM port did not respond to a standard hardware test. If the device is NASI or NCSI, either the NASI/NCSI driver is not installed or the specified port could not be found. FFF4H - Modem initialization failed (no modem response) FFF3H - Modem configuration is invalid (corrupt config) FFF2H - Unable to establish a connection when operating mode is "Initiate a call" Description: This function causes pcANYWHERE IV to load a new configuration and set its operating mode according to the mode specified. If the operating mode specified is 0 (Wait for a call), this function will not return until the host operator cancels the function by pressing or until a valid connection is established. If the function is not successful, the operating mode will be changed to 1 (Hot key activates). ============================================================================ Function 0002H - Get pcANYWHERE IV status Calling parameters: AX = 0002H Returns: AH = Current operating mode 0 = Wait for a call 1 = Hot key activates 2 = Incoming call activates AL = Current connection status, where: Bit 0 = 1 A physical connection is active Bit 1 = 1 Remote screen updating is active Bit 2 = 1 Connection checking is active Bit 3 = 1 Hot key detection is active Bit 4 = 1 Background file transfer is active Notes: The following table lists the possible bit combinations in the connection status byte: Value pcANYWHERE IV status ----- ---------------------------------------- 08H No connection, hot key activates 0CH No connection, hot key or call activates 01H Connection active, remote user is logging in or pcANYWHERE IV has been suspended via API function 3 03H Connection active, screen updates active 11H Connection active, background transfer active pcANYWHERE IV will set the connection status to 00H while it is initializing, removing itself from memory or when it is in "Wait for a call" mode. If initialization or cancelling fails, the connection status will be changed to 08H and the operating mode will be set to 1 (Hot key activates). The only time a connection status of 00H could be returned by this function is if the function is called from an interrupt service routine while pcANYWHERE IV is performing one of the above mentioned tasks. ============================================================================ Function 0003H - Suspend remote screen updates Calling parameters: AX = 0003H Returns: AX = 0000H - Function completed successfully FFFBH - A session is not active or has already been suspended Description: This function suspends pcANYWHERE IV's remote screen updating, allowing a user's application to perform I/O through the communications device that pcANYWHERE IV is using. The file transfer program, AWSEND, uses this function to suspend pcANYWHERE IV while it is transfering files with the remote computer. While pcANYWHERE IV is in a suspended state, it will not peform any communications I/O and it will not check for loss of connection. It is the responsibility of your application program to check for loss of connection (see API function 8002H) when pcANYWHERE IV has been suspended. If the connection is lost, your application should resume pcANYWHERE IV. Once resumed, pcANYWHERE IV will detect the connection loss and prepare for another connection. ============================================================================ Function 0004H - Resume remote screen updates Calling parameters: AX = 0004H Returns: AX = 0000H - Function completed successfully FFFBH - A session is not active Description: This function causes pcANYWHERE IV to resume remote screen updating after it has been suspended by API function 3. Since suspending pcANYWHERE IV can cause the host and remote screens to be out of sync, this function will automatically refresh the remote screen. ============================================================================ Function 0005H - End current remote access session Calling parameters: AX = 0005H DS:SI = Pointer to request structure formatted as follows: BYTE Operating mode 00H = Wait for a call 01H = Hot key activates 02H = Incoming call activates 80H = Use current mode FFH = Remove from memory Returns: AX = Status of function 0000H - Function completed successfully FFFBH - A session is not active FFF6H - The host operator aborted the function FFF4H - Modem initialization failed (no modem response) Description: This function terminates the current remote access session and re-initializes pcANYWHERE IV to the specified operating mode. (See function 6 for notes on removing pcANYWHERE IV from memory.) If the specified operating mode is invalid, the current operating mode will be used. ============================================================================ Function 0006H - Cancel pcANYWHERE IV and remove it from memory Calling parameters: AX = 0006H Returns: AX = Status of function 0000H - Function completed successfully FFD2H - Unable to release allocated memory FFD1H - Unable to release trapped interrupt vectors Description: This function terminates the current remote access session (if one is active) and removes pcANYWHERE IV from memory if possible. In order for pcANYWHERE IV to remove itself from memory, it must be able to restore all of the interrupt vectors it has trapped to their original values and the memory block in which it resides must be a valid DOS memory block. If pcANYWHERE IV reports that it could not release its memory, either the DOS memory allocation tables have been corrupted or pcANYWHERE IV was not loaded into memory by DOS. If one or more of the interrupt vectors that pcANYWHERE IV has trapped is not currently pointing to pcANYWHERE IV's service routine for that interrupt, pcANYWHERE IV will not restore any of the vectors and will not remove itself from memory. This situation could occur if other TSR's are loaded after pcANYWHERE IV or if this function is called from an application that has trapped interrupt vectors. ============================================================================ Function 8000H - Read data from communication channel Calling parameters: AX = 8000H DS:BX = Pointer to buffer for received data CX = Buffer size or 0 to get count of characters available Returns: AX = Number of characters read or avaiable 0 - No data available >0 - Character count <0 - Error Description: This function reads data from pcANYWHERE IV's communication channel and places it in the buffer at DS:BX. As many characters as are available up to the buffer size will be copied to the destination buffer. If the buffer size passed to this function in the CX register is 0, the number of bytes available for reading will be returned without copying any data. For example, if your application expects exactly 10 characters to be received, it may call this function repeatedly with CX=0 until a value of 10 or greater is returned. Once it is known that at least 10 characters are available, it may then issue a call to this function with CX=10 to read the required 10 bytes. Using this method simplifies the task of reading a specific number of characters by eliminating the need for the application to maintain its own buffer count and pointer. Under normal operation, error codes should not be returned. If an error code is returned (high bit of AX=1), a serious problem exists in the communications driver and your program should assume that the connection has been lost. ============================================================================ Function 8001H - Write data over communication channel Calling parameters: AX = 8001H DS:BX = Pointer to buffer containing data to write CX = Number of characters in buffer Returns: AX = Number of characters written 0 - No characters written >0 - Character count <0 - Error Description: This function causes the data in the specified buffer to be placed in the communications driver's transmit buffer. If the driver cannot accept all of the data, it will take as much as it can and return the number of characters accepted (0 if its buffer is completely full). As with the read data function, this function should never return an error. If it does, your application should assume that the connection has been lost and should resume pcANYWHERE IV so that it may attempt to prepare for a new connection. ============================================================================ Function 8002H - Get connection status Calling parameters: AX = 8002H Returns: AX = Connection status >0 - Connection active 0 - Connection lost <0 - Error Description: This function returns the state of the logical connection between the host and remote. The type of device in use and the "Connection ended by" selection specified in the configuration determine how loss of connection is detected. For network devices, this function returns the true state of the logical connection. For serial devices, this function returns the state of the signal selected in the "Connection ended by" selection. If "Always connected" is selected, this function will always return a non-zero value in AX. ============================================================================