We begin this article by asking the question, why would you want to add caller ID to your PowerBuilder applications anyway? I can think of about a handful of applications for it, mostly revolving around picking a phone number and querying a database. For example, "Good morning, Chance, will you be ordering the cheese and sausage pizza again?" Or perhaps a database of people, some whom you might not like, just to have your modem hang up on them. The possibilities are endless.

First some introductions. How does caller ID information get relayed from Ma Bell to your phone or modem anyway? Modems use a technique called Frequency Shift Keying to transmit information over a phone line. One tone represents a binary 1, while a nother represents a binary zero. A modem changes frequencies depending on whether it wants to send a 1 or a 0. To send caller ID information to your home it simply sends ASCII data to the caller ID box between the first and second rings. The modem then decodes the bits and makes the data available for your viewing pleasure. Incidentally, there's a more advanced system that contains the caller's name and the date and time of call but its technique is identical.

In this demonstration we'll simply pick off the incoming phone number (but you could use a similar technique to get the caller's name if you want). However, before we begin you'll need a few things:

• A telephone account with the caller ID feature enabled
• A modem capable of reading caller ID information
• PowerBuilder
• Some time to learn

For starters, we'll need a way to communicate with the modem. In general, modems are serial devices so we'll need a way to "talk to" the comm port. We'll need to use the Win32 API rather than the native PowerBuilder file I/O functions. Why? Because PowerBuilder buffers data on top of that already being done by the operating system. That can be problematic for serial devices. With that, here are the external function prototypes that you'll need for your project.

Function Long CreateFile(ref string lpszName, long fdwAccess, long &
fdwShareMode, long lpsa, long fdwCreate, long fdwAttrsAndFlags, long &
hTemplateFile) Library "Kernel32.dll" ALIAS FOR "CreateFileA;Ansi"

Function Long ReadFile(Long hFile, ref string lpBuffer, long nBytesToRead, &
ref Long nBytesRead, Long lNull) Library "Kernel32.dll" alias for "ReadFile;Ansi"

Function Long WriteFile(Long hFile, ref string lpBuffer, long nBytesToWrite, &
ref Long nBytesWritten, LONG lNull) Library &
"Kernel32.dll" alias for "WriteFile;Ansi"

Function Long CloseHandle(Long hObject) Library "Kernel32.dll"

For demonstrations purposes, we'll have to create a GUI capable of displaying the incoming information. You might use something like this: (Figure 1)

With that in place, we can go about coding our main algorithm in a "pre-open" event. It looks like this:

If wf_open_modem() Then
wf_write_data()
    wf_read_data()
End If

The first function tries to open the comm port the modem is located on. It looks like this. (Note: I've hard-coded the port number in. In an actual implementation you'd probably want this to be a user-defined setting.)

//poll device until we get a hit
Integer li_sub = 1
Boolean lb_connected = FALSE
UnsignedLong ll_tmp = 3221225472

    is_CommPort = "COM3:"

    //modem already detected
    If il_hCon > 0 Then
      Return True
    End If

    //try to connect
    Do While li_sub <= 10 And Not lb_connected
      il_hCon = CreateFile(is_CommPort, ll_tmp, 3, 0, 3, 0, 0);
      If il_hCon < 0 Then
        MessageBox(This.Title, "Modem NOT detected " + String(il_hCon))
      Else
        MessageBox(This.Title, "Modem detected " + String(il_hCon))
        lb_connected = TRUE
      End If
      li_sub ++
    Loop

    If Not lb_connected Then
        MessageBox(This.Title, "Modem not detected ")
    End If

    Return lb_Connected

A little explanation may be in order with the call to CreateFile. You may be wondering where the value 3221225472 comes from and what it represents. If we look at the prototype for the function, we'll see that this is the access mode to the commport that can be read, write, or both. In our case, we are interested in the hexadecimal constants GENERIC_READ and GENERIC_WRITE or more precisely these two values or'd together. For example, in hex, 0x80000000 | 0x40000000 = 0xC0000000. Convert that to a decimal and we have our constant 3221225472.