
              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
          <Esc> 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.

============================================================================
