QuickVerse for Windows
Dynamic Data Exchange Specification
July, 1994

*********************************************************************
                        INTRODUCTION
*********************************************************************

This document specifies the Dynamic Data Exchange (DDE) support 
provided by QuickVerse for Windows (QV/Win).  DDE is a method whereby 
two applications can communicate with one another using a standardized 
format.  The two applications can share data as well as send and 
respond to commands that specific actions be performed. 

In every DDE conversation, one application is called the "client 
application" and the other is called the "server application."  The 
client is the application that begins the conversation, requests data 
from the other application, and sends commands to the other 
application.  The server application is the application that provides 
data to the client or that performs actions requested by the client.  
QuickVerse for Windows is capable of being both a DDE client and a DDE 
server.  For example, when QuickVerse requests that PC Bible Atlas for 
Windows (PCBA/Win) show a map containing a city, then QuickVerse is 
acting as a DDE client.  When another program requests that QuickVerse 
perform a Quick Paste operation, QuickVerse acts as a DDE server.  
This document provides specifications for both server and client DDE 
capability supported by QuickVerse. 

IMPORTANT NOTE:  Due to substantial improvements in dynamic data 
exchange processing included with QuickVerse for Windows version 1.0i, 
we recommend that this version be the minimum program version used 
when using DDE with QuickVerse.  You can determine your version of 
QuickVerse for Windows by referring to the "About Box" (select About 
QuickVerse from the Help menu).

For specific information on using DDE with QuickVerse and another 
application, refer to this document and the other application's 
documentation.  For specific information on how to write your own 
program that uses DDE, refer to chapter 15 of the Windows Software 
Developer Kit (SDK) volume 2 and chapter 17 of "Programming Windows 
2nd edition" by Charles Petzold.


*********************************************************************
                        SERVER SPECIFICATION
*********************************************************************

GENERAL METHODOLOGY
-------------------

QuickVerse supports "cold" DDE links.  Cold links allow information to 
be passed from one application to another without any additional 
updating being required or requested.  Warm links and hot links are 
not required and are not supported. 

QuickVerse responds to the application name "QVWIN" and the topic name 
of "Verses."  The primary DDE interface supported by QuickVerse is the 
WM_DDE_EXECUTE message.  The QuickVerse server will respond to a 
variety of instructions (also called commands) passed with the 
WM_DDE_EXECUTE command.  The QuickVerse server is also capable of 
responding to a WM_DDE_REQUEST message; however, the preferred 
interface is through the WM_DDE_EXECUTE message. 

QuickVerse responds to all WM_DDE_EXECUTE messages with a WM_DDE_ACK 
acknowledgement.  A negative acknowledgement is sent if the command 
could not be completed; a positive acknowledgement indicates that the 
command was completed.  

SPECIFICATION FOR WM_DDE_EXECUTE
--------------------------------

The WM_DDE_EXECUTE message is used to pass commands to QV/Win.  These 
commands can cause QV to perform a specific action (such as a search) 
or to provide information back to the caller (such as a version 
number).  In all cases, the item string contains the command string.
The command string is one or more execute commands and any of their 
associated parameters.  

The following execute commands are supported.  The Syntax Version 
column specifies the syntax version of each command, and the Program 
Version column indicates which version of QuickVerse first supported 
the command.  Detailed descriptions of these command are provided in a 
later section.

                                    Syntax          Program
    Execute Command                 Version         Version
    --------------------------------------------------------
    NULL                               0              1.0c
    [QvPaste]                          1              1.0f
    [GoTo("John 3:16")]                1              1.0f
    [Translation("KJV")]               1              1.0f
    [Minimize]                         1              1.0f
    [Activate]                         1              1.0f
    [QuickSearch("phrase")]            1              1.0g
    [RefSearch("ref")]                 1              1.0i
    [LoadProgVersion(hmem)]            1              1.0i
    [LoadSyntaxVersion(hmem)]          1              1.0i
    [LoadCurrentTranslation(hmem)]     1              1.0i
    [LoadTranslations(hmem)]           1              1.0i
    [LoadVerseText(parameters)]        1              1.0i

Beginning with version 1.0i of QuickVerse, QuickVerse can return the 
syntax level that it supports.  A client application can determine 
which syntax level is supported to determine if QuickVerse will 
support a specific command.  For instance, if a client application 
wants to send a "level 2 syntax" command to QuickVerse, it may first 
determine if QuickVerse supports that level of syntax.  All levels are 
"backwards" compatible, so a program capable of support level 2 syntax 
also supports all level 0 and level 1 commands.

Each command must be enclosed by brackets [ ] and each command may be 
separated by a space.  Spaces within each command are not allowed, 
except in quoted strings.  Parenthesis ( ) are used to begin and end 
the parameter list.  All parameters are passed as strings and decoded 
depending upon the execute command.  String parameters are expected to 
be enclosed by double-quotes, so the string parameter may not contain 
a double quote character.  Parenthesis within quoted parameters are 
allowed. 

Multiple commands may be passed in one command string.  For instance, 
to display John 3:16 in the King James Version, the following command 
string would be used. 

    [Translation("KJV")][GoTo("John 3:16")]

However, this is not recommended.  By passing each command in a 
different WM_DDE_EXECUTE message, the return value may be examined to 
determine which command, if any, failed.  The one exception to this 
recommendation is the [Activate] command, which is typically sent with 
some messages.

If multiple commands are contained in one item, the commands will be 
processed from left to right.  The process will abort and return a 
negative acknowledgement immediately upon encountering an error.  That 
is, if the command string is

    [Translation("KJV")][GoTo("John 3:16")]

and the KJV translation is unavailable, then the GoTo command will not 
be attempted. 

Additional details about each command are provided below.

    Application:    QVWIN
    Topic:          Verses
    Item:           NULL
    Example:        none
    Syntax Level:   0

        A null item causes QuickVerse to perform a QuickVerse paste.  
        The preferred method of performing this is to use the 
        [QvPaste] item (see below).  Also note that all versions of 
        QV/Win prior to version 1.0f will respond to _all_ 
        WM_DDE_EXECUTE messages by performing this action.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [QvPaste] 
    Example:        [QvPaste]
    Syntax Level:   1 

        This command is used to perform a QuickVerse Paste operation.  
        It causes a dialog box to be displayed.  The user can select a 
        reference and a translation.  The reference is copied to the 
        clipboard from the specified translation using current 
        clipboard setup settings. 

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [GoTo("ref")]
    Example:        [GoTo("John 3:16")]
    Syntax Level:   1

        This command causes QuickVerse to go to the specified 
        reference in the currently active window.  The reference is 
        passed as a string, so it must be enclosed in double-quotes.  
        The reference string must conform to standard QuickVerse 
        references and is limited to 128 characters.  An error occurs 
        if there is not an active window.  A multiple verse reference 
        may be passed; in this case, the first verse in the reference 
        string will be used.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [Translation("abbr")]
    Example:        [Translation("KJV")]        
    Syntax Level:   1

        This command is used to activate the specified translation.  
        Since some commands require a Bible window to be open, this
        command may be used to make sure that at least one Bible 
        window is available before sending another command.

        The translation is passed as a string, so it must be enclosed 
        in double-quotes.  The translation is the standard 
        abbreviation used by QuickVerse, and is limited to 4 
        characters.  (Use the LoadTranslations command to obtain a 
        list of installed translations.)  If the translation is 
        already the active translation then nothing happens.  If a 
        window with the translation is open but not active, it is 
        activated.  If the translation is not open in any window, then 
        a new window is opened to contain the translation.  During the 
        processing of this command, QV/Win may be temporarily 
        activated.  However, it returns activation to the previously 
        active application when through. 

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [Minimize]
    Example:        [Minimize]        
    Syntax Level:   1

        This command causes the whole QuickVerse application to be 
        minimized (i.e. made into an icon), but does not activate it. 

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [Activate]
    Example:        [Activate]        
    Syntax Level:   1

        This command causes QuickVerse to be activated.  If it is 
        minimized, it is also restored to normal size.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [QuickSearch("phrase")]
    Example:        [Activate][QuickSearch("Kingdom of God")]        
    Syntax Level:   1

        This command is used to perform a QuickSearch on the given 
        phrase.  The phrase is passed as a string, so it must be 
        enclosed by double-quotes.  The phrase is limited to 128 
        characters and 10 words.  It may be any phrase supported by 
        QuickVerse and may include Boolean operators and punctuation.  
        QuickVerse may or may not be activated following this command; 
        therefore, it is typical to use the activate command in 
        conjunction with this command.  An error occurs if there is 
        not an active window.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [RefSearch("ref")]
    Example:        [RefSearch("John 3:16; Eph 2:8-9")]        
    Syntax Level:   1

        This command instructs QuickVerse to perform a search for the 
        specified references.  The reference is passed as a string and 
        therefore must be enclosed in double-quotes.  The reference 
        string may be up to 128 characters long and contain up to 10 
        different references.  QuickVerse may or may not be activated 
        following this command; therefore, it is typical to use the 
        activate command in conjunction with this command.  An error 
        occurs if there is not an active window. 

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [LoadProgVersion(hmem)]
    Example:        [LoadProgVersion(1234)]        
    Syntax Level:   1

        This command causes QuickVerse to load the string identified 
        by the memory handle "hmem" with the version of QuickVerse.  
        hmem is converted from a string value into an unsigned integer 
        (memory handle) with little error checking provided.  An error 
        occurs if hmem is not a valid memory handle, or if the memory 
        it references is not large enough to contain the version 
        string.  The version string is something like "1.0i" where 1.0 
        is the major version number and the last letter is the minor 
        revision letter.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [LoadSyntaxVersion(hmem)]
    Example:        [LoadSyntaxVersion(1234)]        
    Syntax Level:   1

        This command causes QuickVerse to load the syntax version that 
        it supports into the memory identified by "hmem."  hmem is 
        converted from a string value into an unsigned integer (memory 
        handle) with little error checking provided.  An error occurs 
        if hmem is not a valid memory handle.  The memory identified 
        is loaded with an integer value (i.e. not a string 
        representation of an integer) such as 1, 2, etc.

        It is recommended that client applications use this command to 
        determine if QuickVerse supports the commands that the client 
        supports.  Versions of QuickVerse prior to version 1.0i, 
        however, do not support this command.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [LoadCurrentTranslation(hmem)]
    Example:        [LoadTranslations(1234)]
    Syntax Level:   1

        This command causes QuickVerse to load the string identified
        by the memory handle hmem with the abbreviation of the
        translation being used by the active window.  hmem is
        converted from a string value into an unsigned integer
        (memory handle) with little error checking provided.  An
        error occurs if hmem is not a valid memory handle, or if
        the memory it references is not large enough to contain
        the translation abbreviation.

        The string contains only the abbreviation of the current
        translation.  For example, if the King James Version is
        active, the string would contain "KJV".

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [LoadTranslations(hmem)]
    Example:        [LoadTranslations(1234)]
    Syntax Level:   1

        This command causes QuickVerse to load a string containing a 
        list of the installed translations into the memory identified 
        by the memory handle hmem.  hmem is converted from a string 
        value into an unsigned integer (memory handle) with little 
        error checking provided.  An error occurs if hmem is not a 
        valid memory handle, or if the memory it references is not 
        large enough to contain the string of translations.  The 
        loaded string contains the abbreviations of the translations 
        that are installed, with a space separating each entry.  
        "KJV NIV RSV" is an example returned string.

    Application:    QVWIN 
    Topic:          Verses 
    Item:           [LoadVerseText(hmem, flags, "ref")]
    Example:        [LoadVerseText(1234,0,"John 3:16-18")]
    Syntax Level:   1

        This command is used to request that QuickVerse load the
        specified memory handle (hmem) with verse text from the
        active translation.  An error occurs if there is not an
        active window.  Also note that there may not be any spaces
        included in the list of parameters (the example above is 
        correct).

        The "flags" parameter is a 2-byte bit field.  The individual
        bits in this flag can be used to specify the format of the
        text that is loaded.  You may specify a flag value of 0 to 
        use default settings.  In the following table, the bit
        position is from least significant to most significant (that 
        is, Bit 0 is the least significant (right-most) bit).

          Bit(s)   Value    Definition
        -----------------------------------------------------------
            0       0       use plain text format
                    1       use rich text format (rtf)
            1       0       don't use a cancel dialog box
                    1       use a cancel dialog box
            2       0       when using rtf, don't use bold codes
                    1       when using rtf, use bold codes
            3       0       when using rtf, don't use italics codes
                    1       when using rtf, use italics codes
            4       0       when using rtf, don't use red codes
                    1       when using rtf, use red codes
            5       0       don't includes quotes around verses
                    1       include quotes around verses
            6       0       use full book names
                    1       use abbreviated book names
            7       0       don't include verse and word notes
                    1       include verse and word notes
            8       0       don't include book notes
                    1       include book notes
            9       0       don't include chapter notes
                    1       include chapter notes
            10      0       don't include translation with reference 
                    1       include translation with reference
         11-13      0       reference followed by verse format
                    1       verse followed by reference format
                    2       verse only format (no reference)
                    3       reference above verse format
                    4       reference only format (no verse)
                    5       paragraph format
         14-15      0       use Strong's numbers only
                    1       use transliterated HG word only
                    2       use both word and Strong's number

        Bits 14 and 15 are valid only when the Hebrew and Greek 
        Transliterated Bible is being exported.

As previously noted, QuickVerse will respond to the WM_DDE_EXECUTE 
messages with a WM_DDE_ACK message.  A positive acknowledgement is 
sent when the command was successful; a negative acknowledgement is 
sent otherwise.  Information about the WM_DDE_ACK message and error 
handling is provided in a following section. 

Additional commands may be added in later editions of QuickVerse.  If 
so, these commands will be identified with a new syntax version.  This 
allows a client application to determine which commands are available 
before trying to use one.

SPECIFICATION FOR WM_DDE_REQUEST
--------------------------------

The WM_DDE_REQUEST message is used to request QV/Win to place the text 
for a specified passage in DDE shared memory that can then be used by 
the client application.  The preferred method of performing this 
activity is with the LoadVerseText execute command discussed above.

The DDE conversation must be initiated with an application name of 
"QVWIN" and a topics name of "Verses."  wParam of the WM_DDE_REQUEST 
message is the handle to the DDE client window.  The low word of 
lParam is the requested clipboard format.  CF_TEXT and rich text 
format are supported.  To obtain the rich text format specifier, use 
the RegisterClipboardFormat("Rich Text Format") API.  The high word of 
lParam is an atom containing the requested verse reference or 
references. 

In response to this message, QuickVerse will allocate DDE shared 
memory and transfer the text into this memory.  QuickVerse will then 
post a WM_DDE_DATA message.  The low word of lParam contains the 
handle to the DDEDATA memory block.  The values stored in this memory 
block are shown below. 

    Field       Value   Explanation
    -------------------------------------------------------------
    fResponse   TRUE    The client application is expected to
                        free the  memory object.
    fRelease    TRUE    This data is offered in response to a
                        WM_DDE_REQUEST message.
    reserved    FALSE   Reserved by Windows.
    fAckReq     TRUE    The client application is expected to
                        send a WM_DDE_ACK message after the
                        WM_DDE_DATA message has been
                        processed.
    cfFormat   CF_TEXT  Format of the data in the value
                        field.
    Value       hMem    Handle to the memory block
                        containing the verse text.

The client window is expected to send a WM_DDE_ACK message to 
QuickVerse after the WM_DDE_DATA message has been processed.  If the 
client window does not respond within a specified time period, 
QuickVerse will free the memory blocks it allocated for the 
WM_DDE_DATA message. 

If the requested data can not be provided, QuickVerse will respond by 
sending a WM_DDE_ACK message with a negative acknowledgement) instead
of the WM_DDE_DATA message.  See the following section on error 
handling for more details.

ERROR HANDLING
--------------

The client application can generally rely upon QuickVerse to display 
an error message that describes the error condition.  

In addition, QuickVerse responds to all WM_DDE_EXECUTE messages and 
failure conditions for WM_DDE_REQUEST with a WM_DDE_ACK message.  A 
DDEACK structure accompanies the acknowledge message.  This structure 
contains 3 fields of interest:  fAck, fBusy, and bAppReturnCode.  The 
fAck flag contains the acknowledgement.  A positive acknowledgement is 
sent if the command string was completely executed; otherwise a 
negative acknowledgement is sent.  The remaining two fields contain 
information about the failure, since there may be many reasons that 
the commands were not completed. 

The client application should not assume that the command was 
unrecognized if a negative acknowledgement was received.  If a 
negative acknowledgement is received, the client application should 
first examine the fBusy flag.  If this flag is set, then QuickVerse 
did not execute the commands because it was busy.  Additionally, the 
bAppReturnCode field may contain additional information about why a 
negative acknowledgement was received.  Since QuickVerse will 
generally display a message to the user when a bona-fide error occurs, 
the client application does not need to examine the application error 
code.  However, it is provided for convenience. 

The following application return codes are provided.

    bAppReturnCode  Description
    ----------------------------------------------------------------
        0           Additional information about the error source
                    is not provided.

        1           Busy.  QuickVerse did not respond because it
                    was busy.  QuickVerse is "busy" when a modal 
                    dialog box is displayed, or when an error message 
                    is displayed, or when QuickVerse is still
                    processing a previous DDE message.
                    Note that the client application should not rely 
                    on this value, but should instead check the fBusy 
                    field to determine if the command failed because 
                    QuickVerse was busy.

        2           The DDE message is not supported by QuickVerse.  
                    The WM_DDE_ADVISE is an example of this.

        3           An unrecognized execute command was received.

        4           The command contained a syntax error or an invalid 
                    parameter.  This code is also returned when the
                    command does not provide a valid memory handle.

        5           The operation failed.  This can occur when an
                    active window is required, but not available, or
                    when memory was not available.

        6           A system error occurred.  These are rather severe
                    and occur only when a system level activity (such 
                    as atom string retrieval or posting a message)
                    fail.


*********************************************************************
                        CLIENT SPECIFICATION
*********************************************************************

GENERAL METHODOLOGY
-------------------

QuickVerse can serve as a DDE client application and pass instructions 
to other applications with the WM_DDE_EXECUTE command.

NOTES FOR ALL SERVER APPLICATIONS
---------------------------------

One important note is that QuickVerse expects a WM_DDE_ACK message to 
be received within a specified period after sending the execute 
command.  If the message is not received, QuickVerse will prompt the 
user about whether or not to continue waiting.  The server program
should, therefore, send an acknowledge message promptly.

QuickVerse checks the returned acknowledgement for a positive or 
negative acknowledgement, as well as the busy flag as appropriate.  It 
does not check the bAppReturnCode flag.

SPECIFICATION FOR THE INTERFACE TO A BIBLE ATLAS
------------------------------------------------

A QuickVerse user can choose the Bible Atlas program that QuickVerse 
interacts with.  While QuickVerse is designed to be used with PC Bible 
Atlas for Windows, any Bible Atlas program that supports the 
following WM_DDE_EXECUTE commands may be used.

    Application:    User defined
    Topic name:     Commands

                                Syntax          Program Version
    Item                        Level           Used In
    ------------------------------------------------------------
    [Show("item")]              1               1.0i
    [Activate]                  1               1.0i
    [LoadSyntaxVersion(hmem)]   1               1.0i

Refer to the DDE Specification for PC Bible Atlas for Windows for more 
detail regarding these specific commands.

SPECIFICATION FOR THE INTERFACE TO A BIBLE DICTIONARY
-----------------------------------------------------

A QuickVerse user can choose the dictionary program that QuickVerse 
interacts with.  While QuickVerse is designed to be used with the
Holman Bible Dictionary, and dictionary that supports the following
WM_DDE_EXECUTE commands may be used.

    Application:    User defined
    Topic name:     Commands

                                Syntax          Program Version
    Item                        Level           Used In
    ------------------------------------------------------------
    [Show("item")]              1               1.0j
    [ShowVerseRefs("ref")]      1               1.0j
    [Activate]                  1               1.0j
    [LoadSyntaxVersion(hmem)]   1               1.0j

Refer to the DDE Specification for the Holman Bible Dictionary
for more detail regarding these specific commands.

SPECIFICATION FOR THE INTERFACE TO BIBLE ILLUSTRATOR
----------------------------------------------------

QuickVerse is designed to be used with Bible Illustrator for
Windows, but may be used with any illustration program that
supports the correct syntax.  The following WM_DDE_EXECUTE
commands may be used.

    Application:    User defined
    Topic name:     Commands

                                Syntax          Program Version
    Item                        Level           Used In
    ------------------------------------------------------------
    [Show("item")]              1               3.0c
    [ShowVerseRefs("ref")]      1               3.0c
    [Activate]                  1               3.0c
    [LoadSyntaxVersion(hmem)]   1               3.0c

Refer to the DDE Specification for Bible Illustrator for more 
detail regarding these specific commands.


