Mar-28-96

This archive contains the source for COBCOM.DLL and a compiled version
of the DLL.

CobCom is a utility to be used from within Codewright to enhance support
for COBOL.  It inserts a specified string at a specified column
for each line that has been changed or added during the editing
session.  The insertion occurs when the file is written.

To install the package, copy CobCom.DLL into your CWRIGHT directory, then do the following:

1 Go to Tools | Customize 'Libraries' folder.
2 Click Add.
3 Browse for CobCom.DLL and double click. This will load the DLL.

This adds a line to the [LibPreload] section of your CWRIGHT.INI file similar to:

	LibPreLoad="c:\cw32\cobcom.dll"
    
CWRIGHT.INI is located in the CodeWright home directory.

To activate the DLL, add the following line to the [Editor] section of CWRIGHT.INI:

    CobComBegin="c:\cwright\cobcom.dat",73
    
and create the file "cobcom.dat" containing the template you
wish to insert at column 73 of inserted and modified lines.

NEW: Existing text at column 73 will be deleted the first time
a line is modified.

If you want the option of modifying the insertion string when CodeWright is launched, then
add this line _before_ the CobComBegin line:

	CobComPromptMe=TRUE
	
This will cause Codewright to ask you, when it starts up, to
confirm or change the insertion string.


When installed, a number of new API calls become available that can
be used from the API command line in Codewright or bound to keystrokes:

    int    CobComHandler(LONG eventID, LONG data)
    int    CobComBufSaveHandler(LONG eventID, LONG data)
    int    CobComInitHandler(long event, long data)

    int    CobComBegin(LPSTR dataFileName, DWORD column)
    int    CobComEnd(void)
    DWORD  CobComReset(void)

    int    CobComQStatus(void)
    LPSTR  CobComQString(void)
    DWORD  CobComQChanged(void)

    LPSTR  CobComSetString(LPSTR)
    void   CobComSetStringPrompt(voi)
    BOOL   CobComPromptMe(BOOL)


Following is a description of each call.  To use the package, you
only need CobComBegin.


CobComBegin
    
    Installs the line-changed and save-buffer handlers,
    and returns a bitmap of the handlers installed.

    The first argument sets the file containing the string to insert.
    Whatever's at the beginning of the file will be used.
    There is no checking for length or valid characters.  The whole
    string is inserted in any case.

    The string is global within the CobCom module.  It is
    allocated here and is to be freed by CobComEnd.

    The string may contain Codewright macros.  Its only
    use is that it is passed to ExtExpandTemplate; so
    any legal argument for that function may be used here.

    The second argument is the column at which to insert
    the string.  It defaults to 73.
    
    The string is inserted when the file is written, not when
    a line is added or modified.

    
CobComEnd

    Turn off all installed handlers.  This call removes any effect of
    the DLL.  A bitmap of the successfully deinstalled handlers is
    returned.


CobComReset

    This function is not called automatically.  You may call it
    from an API Command prompt, or by binding a keystroke to it.

    It clears the changed status of each line in the file.  After
    you call this, only lines changed after the call will get tagged.

    Return value is the number of lines that had been targeted for
    tagging.


CobComQString

    Diagnostic tool: returns the string that is to be inserted
    into the comment field.  String must not be deallocated by
    the caller.
    

CobComQChanged

    This function returns the number of lines that have been
    targeted for tagging.  It is primarily a diagnostic tool.

    
CobComQStatus

	Diagnostic tool: tells which handlers are installed
	(handler 0 is the self-deinstalling init handler).
	Returns a bitmap of the handlers installed, along with
	bits to indicate the state of DLL-global variables.

    
CobComSetString

	Sets the insertion string to the string given as an
	argument.

    
CobComSetStringPrompt

	Prompts the user for a string, then sets the insertion
	string to that string.


CobComPromptMe

	If the argument given is TRUE, then the user will be prompted
	for the insertion string when the package first starts up.
	If a string has already been supplied (for example, if it was
	given in the call to CobComBegin), that will be used as a 
	default.
	

CobComInitHandler

	This handler is triggered on EVENT_BUFFER_CURRENT.  It de-installs
	itself the first time it's called, after performing any needed
	interaction with the user.  This setup ensures that the startup
	process is complete before the user gets prompted.

    
CobComHandler

    Handler for line-changed events (lines changed or added.
    First argument is the event that triggered this call.
    Second argument is a pointer to a long int containing
    the line number for which the event was generated.
    Return value is 0, to indicate that processing should
    continue normally.

    
CobComBufSavedHandler

    The handler called when a buffer is saved (before the buffer
    is written to disk).
    First argument is the event ID.
    Second argument is NULL unless the buffer is being saved
    under a name different from that of the original file.
    Return value is 0 to indicate that the buffer should be
    saved normally.

    Looks at every line in the file; any that have been changed
    are truncated at column 73, and the template in the data file
    is appended to the line at that column.

               
               


Submitted by Starbase Corporation, Jan-12-94.
Updated by Starbase Corporation, Mar-13-95.
Updated by Starbase Corporation, Feb-13-01.