Methods

<<<<

^^^^^

>>>>

Introduction

In this section, information is arranged into:

The following methods are supported by this control:

AboutBox displays an about dialogue;
CalculateMF calculates the molecular formula of the chemical displayed in the control;
CalculateMWeight calculates the molecular weight of the chemical displayed in the control;
CanCopy checks whether the contents of the control can be copied onto the clipboard;
CanCut checks whether the contents of the control can be cut to the clipboard;
CanPaste informs whether the control can paste the content of the clipboard;
Clear empties the control;
ClearEntryNumber deletes the structure server's entry number for the chemical;
ClearHeader deletes all server header properties;
Connect attempts to connect to the structure server;
Copy copies the control's content to the clipboard;
Cut cuts the control's content to the clipboard;
DDEAddTopic adds a topic to a list of those supported by the control's DDE server;
DDEConversationCommand issues a command in a DDE conversation;
DDEConversationEnd ends a conversation with a DDE server;
DDEConversationStart starts a conversation with a DDE server;
DDEDeleteTopic removes a topic from the list of those previously added by the control's DDE server;
DDEGetTopic returns the name of a topic supported by the control's DDE server;
DDEInUse checks whether DDE has been initialised;
DDEXeq connects to a DDE server, issues a command, then disconnects from that server;
Disconnect terminates a connection to the structure server;
Display shows a chemical downloaded from the server;
DoProperties displays the control's properties dialogue;
ExecutableClose sends a close message to an executable;
ExecutableGetLastError returns the last system error associated with an executable;
ExecutableHide attempts to hide an executable's window;
ExecutableIsRunning checks to see if a previously launched executable is still running;
ExecutableLaunch attempts to run a program;
ExecutablePostMessage posts an Application message to the previous launched executable;
ExecutablePostWndMessage posts a message to the previous launched executable's main window;
ExecutablePredujiceTerminate kills a reluctant executable;
ExecutableReuse indicates that an executable's slot can be reused;
ExecutableShow attempts to show a previously hidden executable's window;
GetAtomData returns information about an atom;
GetAtomPosition returns an atom's coördinates;
GetAtomString returns string information about an atom;
GetBondData returns information about a bond;
GetCount returns information about a molecule;
GetEntryNumber gets the chemical's server entry number;
GetQuantitySearchResults returns the number of hits from the last server search;
GetRange download chemicals from the last search;
GetRevision gets the chemical's audit revision number;
GetRGroupData returns information about a reaction group;
GetRGroupString returns string information about a reaction group;
GetSGroupData returns information about a superatom;
GetSGroupString returns string information about a superatom;
HasChanged checks to see whether the content has been changed;
IsConnected checks to see whether the control is connected to the structure server;
IsLoggedOn checks to see whether the control is connected to the structure server;
LoadEnhMetaFile loads an enhanced metafile;
LoadMolFile loads and interprets a .MOL file;
LoadRxnFile loads and interprets an .RXN file;
LoadTGFFile loads, but does not interpret, a .TGF file;
Login logs into the structure server;
Logout logs out of the structure server;
Paste copies data from the clipboard;
Refresh redraws the control's content;
SaveEnhMetaFile saves the current enhanced metafile;
SaveMolFile saves the current content of the control as a .MOL file;
SaveRxnFile saves the current content of the control as a .RXN file;
SaveTGFFile saves TGF information obtained from the server as a .TGF file;
SearchKey has the structure server search for a particular key;
SearchSimilar has the structure server search for a similar chemical;
SearchStruct has the structure server search for a chemical structure;
SubmitStruct submits a chemical to the server;

See Events, Properties, return to Developer's Reference, or the top of this document.

Error Codes

Methods (and properties) can return any of the following error codes:

OCXERR_WINDOWS: an unspecified Windows error occurred.
OCXERR_RESOURCE: a resource is missing from the control; set it up again.
OCXERR_BADPARAM: a bad parameter value was given to an control method or property.
OCXERR_LOCKMEM: the control cannot lock memory.
OCXERR_TEXTOUT: a windows error occurred when attempting to draw text.
OCXERR_BADMOLFILE: the .MOL file is in a duff format.
OCXERR_ALLOCMEM: the control cannot allocate memory.
OCXERR_OPENFILE: the file cannot be opened.
OCXERR_READ: a read error occurred when processing a file.
OCXERR_BADFONT: Windows does not recognise a font name.
OCXERR_MOLFILETOOBIG: the .MOL file is too big.
OCXERR_CREATEFILE: the control cannot create the file.
OCXERR_CLIPBOARD: an unspecified clipboard error occurred.
OCXERR_WRITE: an error occurred when writing to a file.
OCXERR_TYPE: the control cannot process the data on the clipboard; its the wrong type.
OCXERR_DDE: an unspecified DDE error occurred.
OCXERR_TOOMANYXEQ: too many executables running.
OCXERR_LAUNCH: could not launch executable.
OCXERR_READONLY: attempt to change read-only data.
OCXERR_METAFILE: error processing a metafile.
OCXERR_UNKNOWN: an unknown or undocumented Windows error.
OCXERR_ARCHIVE: a Windows archive error.
OCXERR_EOF: unexpected end-of-file.
OCXERR_FORMAT: an OLE format error.
OCXERR_INTERNAL: the control has a serious problem.
OCXERR_BADRXNFILE: the .RXN file is faulty.
OCXERR_NOTENUFBITS: an internal problem has occurred.
OCXERR_VERSION: attempt to read data saved by a more recent version of the control.
OCXERR_CLOSE: unable to flush log file.
OCXERR_MOLBADKEYWORD: unrecognised keyword in .MOL (or .CTAB) file.
OCXERR_RTFCREATE: systems resources are low.

These codes are currently defined as follows:



#define OCX_ERROR                -1000



#define OCXERR_WINDOWS                (OCX_ERROR - 0)

#define OCXERR_RESOURCE                (OCX_ERROR - 1)

#define OCXERR_BADPARAM                (OCX_ERROR - 2)

#define OCXERR_NODLL                (OCX_ERROR - 3)

#define OCXERR_LOCKMEM                (OCX_ERROR - 4)

#define OCXERR_TEXTOUT                (OCX_ERROR - 5)

#define OCXERR_BADMOLFILE        (OCX_ERROR - 6)

#define OCXERR_ALLOCMEM                (OCX_ERROR - 7)

#define OCXERR_OPENFILE                (OCX_ERROR - 8)

#define OCXERR_READ                (OCX_ERROR - 9)

#define OCXERR_BADFONT                (OCX_ERROR -10)

#define OCXERR_NODATA                (OCX_ERROR -11)

#define OCXERR_NOSUCHRESULT        (OCX_ERROR -12)

#define OCXERR_TESTVERSION        (OCX_ERROR -13)

#define OCXERR_MOLFILETOOBIG        (OCX_ERROR -14)

#define OCXERR_CREATEFILE        (OCX_ERROR -15)

#define OCXERR_CLIPBOARD        (OCX_ERROR -16)

#define OCXERR_SIZEMEM                (OCX_ERROR -17)

#define OCXERR_WRITE                (OCX_ERROR -18)

#define OCXERR_TYPE                (OCX_ERROR -19)

#define OCXERR_DDE                (OCX_ERROR -20)

#define OCXERR_TOOMANYXEQ        (OCX_ERROR -21)

#define OCXERR_LAUNCH                (OCX_ERROR -22)

#define OCXERR_READONLY                (OCX_ERROR -23)

#define OCXERR_METAFILE                (OCX_ERROR -24)

#define OCXERR_UNKNOWN                (OCX_ERROR -25)

#define OCXERR_ARCHIVE                (OCX_ERROR -26)

#define OCXERR_EOF                (OCX_ERROR -27)

#define OCXERR_FORMAT                (OCX_ERROR -28)

#define OCXERR_INTERNAL                (OCX_ERROR -29)

#define OCXERR_BADRXNFILE        (OCX_ERROR -30)

#define OCXERR_NOTENUFBITS        (OCX_ERROR -31)

#define OCXERR_VERSION                (OCX_ERROR -32)

#define OCXERR_CLOSE                (OCX_ERROR -33)

#define OCXERR_MOLBADKEYWORD        (OCX_ERROR -34)

#define OCXERR_RTFCREATE        (OCX_ERROR -35)

Chemical Methods

The methods discussed in this section are grouped together by a common theme of chemistry.

CalculateMF Method

The CalculateMF method calculates and returns the molecular formula of the current content of the control.



BSTR CalculateMF ();

To set the molecular formula passed to the server, use the MF property.

See the CalculateWeight method, MF and Weight properties, return to Methods, Developer's Reference, or the top of this document.

CalculateWeight Method

The CalculateWeight method calculates and returns the molecular weight of the current content of the control.



double CalculateWeight ();

To set the molecular weight passed to the server, use the Weight property.

See the CalculateMF method, MF and Weight properties, return to Methods, Developer's Reference, or the top of this document.

GetAtomData Method

The GetAtomData returns some information about a particular atom.



short GetAtomData (short nItem, short nAtom);

nItem identifies exactly which piece of data to obtain, and nAtom identifies the atom to examine (from the range of zero to one less than the atom count returned by GetCount). Any one of the following values, which correspond to value describing the atom in the file, may be supplied for nItem:



#define ATOM_MASSDIFF                1

#define ATOM_CHARGE                2

#define ATOM_STEREO                3

#define ATOM_HYDROGEN                4

#define ATOM_VALENCE                5

#define ATOM_HO                        6

#define ATOM_ELEMENT                7

#define ATOM_INDEX                8

#define ATOM_REACTION_TYPE        9

#define ATOM_REACTION_NUMBER        10

#define ATOM_MAPPING                11

#define ATOM_INVERSION                12

#define ATOM_ISSTEREO                13

#define ATOM_ISFIXED                14

#define ATOM_RADICAL                15

#define ATOM_ATOMLIST                16

#define ATOM_RINGBONDCOUNT        17

#define ATOM_SUBSTITUTION        18

#define ATOM_LINKREPEAT                19

#define ATOM_LINKNOT1                20

#define ATOM_LINKNOT2                21

#define ATOM_ATTACHMENTPOINT    22

#define ATOM_RGROUP                23

#define ATOM_SGROUP                24

#define ATOM_SGROUPPARENT        25

#define ATOM_REPEATINGUNIT        26

#define ATOM_ISISOTOPE                27

#define ATOM_ISUNSATURATED        28

See the GetAtomPosition, GetAtomString, and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetAtomPosition Method

The GetAtomPosition returns the atom's coördinates, as specified in the original file, not as currently drawn on the screen.



void GetAtomPosition (short nAtom, double* pdbX, double* pdbY, double* pdbZ);

nAtom is the atom number, which must be between zero and one less than the atom count returned by GetCount. This number is one less than the number stored in .MOL, .RXN or .TGF files. Each of the remaining variables point to a double, which is used to receive the corresponding coördinate value.

See the GetAtomData, GetStringData, and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetAtomString Method

The GetAtomString returns string information about a particular atom.



BSTR GetAtomString (short nItem, short nAtom);



#define ATOM_SYMBOL                64

#define ATOM_ALIAS                65

#define ATOM_LIST                66

See the GetAtomData, GetAtomPosition, and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetBondData Method

The GetBondData method returns information about a particular bond.



short GetBondData (short nItem, short nBond);

nItem identifies exactly which piece of data to obtain, and nBond identifies the bond to examine (from the range of zero to one less than the bond count returned by GetCount). Any one of the following values, which correspond to value describing the atom in the file, may be supplied for nItem:



#define BOND_FROM                1

#define BOND_TO                        2

#define BOND_TYPE                3

#define BOND_STEREO                4

#define BOND_TOPOLOGY                5

#define BOND_SIDE                6

#define BOND_REACTION                7

#define BOND_SGROUP                8

See the GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetCount Method

The GetCount returns the number of a particular type in the file.



BSTR GetCount ();

nItem identifies exactly which count of data to obtain. Any one of the following values, which correspond to a count found in the file, may be supplied for nItem:



#define COUNT_ATOM                1

#define COUNT_BOND                2

#define COUNT_LIST                3

#define COUNT_CHIRAL                4

#define COUNT_STEXT                5

#define COUNT_COMPONENT                6

#define COUNT_REACTANT                7

#define COUNT_PRODUCT                8

#define COUNT_INTERMEDIATE        9

#define COUNT_LINE                10

#define COUNT_SGROUP                11

#define COUNT_RGROUP                12

#define COUNT_RICHTEXT                13

You will need to use this method to obtain the atom (COUNT_ATOM) or bond (COUNT_BOND) counts before using GetAtomData, GetAtomPosition, GetAtomStrng, GetBondData. GetRGroupData, GetRGroupStrng, GetSGroupData or GetSGroupStrng,

See the GetAtomData, GetAtomPosition, GetAtomStrng, GetBondData. GetRGroupData, GetRGroupStrng, GetSGroupData and GetSGroupStrng methods, return to Methods, Developer's Reference, or the top of this document.

GetRevision Method

The GetRevision returns the chemical's audit revision number.



int GetRevision ();

Each chemical on the server can have an audit number, reflecting the current revision of the data on the server for that chemical. A chemical that has not been submitted has revision number 0.

Return to Methods, Developer's Reference, or the top of this document.

GetRGroupData Method

The GetRGroupData method returns information about a particular reaction group.



short GetRGroupData (short nItem, short nRGroup);

nItem identifies exactly which piece of data to obtain, and nRGroup identifies the reaction to examine (from the range of zero to one less than the reaction count returned by GetCount). Any one of the following values, which correspond to value describing the atom in the file, may be supplied for nItem:



#define RGROUP_SATISFY        1

#define RGROUP_RESTH        2

See the GetRGroupString and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetRGroupString Method

The GetRGroupString method returns string information about a particular reaction group.



BSTR GetRGroupString (short nItem, short nRGroup);



#define RGROUP_LOGIC        64

See the GetRGroupData and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetSGroupData Method

The GetSGroupData method returns information about a particular bond.



short GetSGroupData (short nItem, short nBond);

nItem identifies exactly which piece of data to obtain, and nSGroup identifies the superatom to examine (from the range of zero to one less than the bond count returned by GetCount). Any one of the following values, which correspond to value describing the atom in the file, may be supplied for nItem:



#define SGROUP_TYPE                        1

#define SGROUP_SUBTYPE                2

#define SGROUP_CONNECTIVITY        3

#define SGROUP_RESIDUE                4

#define SGROUP_EXPANDED                5

#define SGROUP_PARENT                6

See the GetSGroupString and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

GetSGroupString Method

The GetSGroupString method returns string information about a particular bond.



BSTR GetSGroupString (short nItem, short nBond);



#define SGROUP_TEXT                64

#define SGROUP_UPPERBRACKET        65

#define SGROUP_LOWERBRACKET        66

See the GetSGroupData and GetCount methods, return to Methods, Developer's Reference, or the top of this document.

LoadEnhMetaFile Method

The LoadEnhMetaFile method loads a metafile.



short LoadEnhMetaFile (BSTR lpszFile);

lpszFile is the full path name of the enhanced metafile to load. The function returns an error code.

This function is designed to make it simpler to store reactions on the system. The metafile will be displayed if there is nothing else to display.

See the SaveEnhMetaFile method, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

LoadMolFile Method

The LoadMolFile method loads and interprets a .MOL file.



short LoadMolFile (BSTR lpszFile);

lpszFile is the full path name of the .MOL file to load. The function returns an error code.

See the SaveMolFile method, MolFile property, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

LoadRxnFile Method

The LoadRxnFile method loads and interprets an .RXN file.



short LoadRxnFile (BSTR lpszFile);

lpszFile is the full path name of the .RXN file to load. The function returns an error code.

See the SaveRxnFile method, RxnFile property, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

LoadTGFFile Method

The LoadTGFFile method loads and interprets a .TGF file.



short LoadTGFFile (BSTR lpszFile);

lpszFile is the full path name of the .TGF file to load. The function returns an error code.

See the SaveTGFFile method, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

SaveEnhMetaFile Method

The SaveEnhMetaFile writes an Enhanced Metafile file.



short SaveEnhMetaFile (BSTR lpszTGFFile);

lpszFileName is the full path name of the enhanced metafile file to be written. The function returns an error code.

Note this function simple writes out the enhanced metafile it previously loaded, pasted, or obtained from the server.

See the LoadEnhMetaFile and Pastemethods, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

SaveMolFile Method

The SaveMolFile writes a .MOL file.



short SaveMolFile (BSTR lpszMolFile, boolean bCreate);

lpszMolFile is the full path name of the .MOL file to create. If bCreate is false, then the file must already exist. The function returns an error code.

Note this function simple writes out the .MOL files it previously loaded, pasted, or obtained from the server.

See the LoadMolFile and Pastemethods, the MolFile property, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

SaveRxnFile Method

The SaveRxnFile writes a .RXN file.



short SaveRxnFile (BSTR lpszRxnFile, boolean bCreate);

lpszRxnFile is the full path name of the .RXN file to create. If bCreate is false, then the file must already exist. The function returns an error code.

Note this function simple writes out the .RXN file it previously loaded, pasted, or obtained from the server.

See the LoadRxnFile and the RxnFile property, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

SaveTGFFile Method

The SaveTGFFile writes a TGF file.



short SaveTGFFile (BSTR lpszTGFFile, boolean bCreate);

lpszTGFFile is the full path name of the .TGF file to create. If bCreate is false, then the file must already exist. The function returns an error code.

Note this function simple writes out the .TGF file it previously loaded, or obtained from the server.

See the LoadTGFFile and Pastemethods, check the control's error codes, return to Methods, Developer's Reference, or the top of this document.

Server Methods

All Server methods require a TCP/IP link with the Structure Server in order to operate correctly. Information shared with the server includes the data file itself (.MOL, .RXN or .TGF), and some header fields.

To communicate with the server, an application could do the following:

Connect using Connect, check VersionStrings, and Login;
Search for some records using SearchKey, SearchSimilar or SearchStruct;
Download some of the results using GetRange;
Display one of the just-got structures;
Potentially, make changes to it using other mechanisms;
Use SubmitStructure to send a modified structure back to the server (call ClearEntryNumber first to submit a new structure);
continue ad infinitum until the application calls Logout and Disconnect.

There methods may return server error codes, as well as the control's error codes. Server error codes are negative; server information may be positive - see the structure server documentation for further details.

ClearEntryNumber Method

The ClearEntryNumber method clears the database entry number in a structure. This should be done before submitted a modified structure as something new to the server.



void ClearEntryNumber ();

See the GetEntryNumber and SubmitStructure methods, return to Methods, Developer's Reference, or the top of this document.

ClearHeader Method

The ClearHeader method clears all fields in the header (e.g. all Server Properties).



void ClearHeader ();

See the Server Properties, return to Methods, Developer's Reference, or the top of this document.

Connect Method

The Connect method attempts to establish a connection with the server. It should be called before any other Server Methods.



short Connect (BSTR lpszIPAddress, BSTR lpszService);

The first parameter, lpszIPAddress, is a string containing the server's IP Address in one of the normal formats (such as 10.20.30.40:50 or abc.def.com:123), or the name of an entry in the system standard services file. When the services file is used, the second parameter identifies the service.

The function returns an error code, or zero if successful.

See the Disconnect method, return to Methods, Developer's Reference, or the top of this document.

Disconnect Method

The Disconnect method terminates a previously connected session. It should be the last Server Method call made.



short Disonnect ();

The function returns an error code, or zero if successful.

See the Connect method, return to Methods, Developer's Reference, or the top of this document.

Display Method

The Display method displays a chemical previously obtained using GetRange.



short Display (short nResult);

The single parameter, nResult, is a number between zero and the number of chemicals obtained using GetRange.

The function returns an error code, or zero if successful.

See the GetRange method, return to Methods, Developer's Reference, or the top of this document.

GetEntryNumber Method

The GetEntryNumber returns the currently displayed chemical's structure server entry number. Such a number is unique to a particular chemical, and can be used to rapidly locate it on the server.



long GetEntryNumber ();

The function returns an error code, or the (positive) entry number if successful.

See the ClearEntryNumber and GetRange method, return to Methods, Developer's Reference, or the top of this document.

GetQuantitySearchResults Method

The GetQuantitySearchResults returns the number of hits following a search.



long GetQuantitySearchResults ();

The function returns an error code, or the (positive) number of hits if successful (or zero if the search failed). It returns invalid information after a call to the SubmitStruct method.

See the SearchKey, SearchSimilar, SearchStruct or SubmitStruct methods, return to Methods, Developer's Reference, or the top of this document.

GetRange Method

The GetRange method is used after a successful search to download chemical information from the server.



short GetRange (short nFrom, short nTo);

The two parameters are the range of results to obtain, between 1 and the number of hits from a search (obtained by calling GetQuantitySearchResults).

The function returns an error code, or the (positive) number of chemicals downloaded if successful. The more chemicals downloaded, the longer the function takes.

See the Display, GetQuantitySearchResults, SearchKey, SearchSimilar or SearchStruct method, return to Methods, Developer's Reference, or the top of this document.

HasChanged Method

The HasChanged method returns true if a structure has changed since it was downloaded from the server.



bool HasChanged ();

Return to Methods, Developer's Reference, or the top of this document.

IsConnected Method

The IsConnected method returns true if the control is currently connected to the server (after a successful call to Connect method).



bool IsConnected ();

See the Connect method, return to Methods, Developer's Reference, or the top of this document.

IsLoggedOn Method

The IsLoggedOn method returns true if the control is currently logged on to the server (after a successful call to Login method).



bool IsLoggedOn ();

See the Login method, return to Methods, Developer's Reference, or the top of this document.

Login Method

The Login method logs the given user into the server.



short Login (BSTR lpszUser, BSTR lpszPassword);

The supplier lpszUser and lpszPassword must have been registered on the server (using server utilities) for this function to succeed. No server methods, apart from Connect and Disonnect can succeed unless this method has been used successfully.

The function returns zero if successful, or a negative error number.

See the Connect, Disonnect and Logout methods, return to Methods, Developer's Reference, or the top of this document.

Logout Method

The Logout method logs the user off the server.



short Logout ();

The method should only be called if the user successfully logged on to the server using Login, before Disconnecting.

The function returns zero if successful, or a negative error number.

See the Disonnect and Login methods, return to Methods, Developer's Reference, or the top of this document.

SearchKey Method

The SearchKey method instructs the structure server to search the database for the given key.



short SearchKey (short nSearch, BSTR lpszKey);

nSearch identifies the search to be carried out, and lpszKey is the key to be used in the search. nSearch can be one of the following values:

SEARCH_AUDIT conducts an audit search (identifies all modifications);
SEARCH_ENTRYNO searches using a database entry number;
SEARCH_EXP_NAME searches for experiment names including the key;
SEARCH_KEY searches on the structure server's compound number;
SEARCH_MF searches using a Molecular Formula;
SEARCH_SQL treats lppszKey as a SQL statement, and passes it to the server for interpretation.

These constants are current defined as:



#define SEARCH_KEY                1

#define SEARCH_MF                2

#define SEARCH_ENTRYNO                3

#define SEARCH_AUDIT                4

#define SEARCH_SQL                8

#define SEARCH_EXP_NAME                9

The function returns the number of hits if successful, or a negative error number.

See the SearchSimilar, SearchStruct methods, return to Methods, Developer's Reference, or the top of this document.

SearchSimilar Method

The SearchSimilar method instructs the structure server to search the database for a structure which is similar to the one in the control.



short SearchSimilar(short nSearch, short nPercent);

nSearch identifies the search to be carried out, and nPercent identifies the degree of similarity required (100% implies identical, and 0% implies the entire database - not a good idea!). nSearch can be one of the following values:

SEARCH_SIMILAR conducts a similarity search.

These constants are current defined as:



#define SEARCH_SIMILAR                7

The function returns the number of hits if successful, or a negative error number.

See the SearchKey, SearchStruct methods, return to Methods, Developer's Reference, or the top of this document.

SearchStruct Method

The SearchStruct method instructs the structure server to search the database for the structure currently shown in the control.



short SearchStruct (short nSearch);

nSearch identifies the search to be carried out. It can be one of the following values:

SEARCH_FULLSTRUCT searches for all occurrences of the structure in the database;
SEARCH_SUBSTRUCT searches for all chemicals containing the given structure in the database.

These constants are current defined as:



#define SEARCH_FULLSTRUCT        5

#define SEARCH_SUBSTRUCT        6

The function returns the number of hits if successful, or a negative error number.

See the SearchKey, SearchSimilar methods, return to Methods, Developer's Reference, or the top of this document.

SubmitStruct Method

The SubmitStruct method sends the structure contained in the control to the server.



short SubmitStruct (BSTR lpszKey);

lpszKey should be empty if the structure is completely new. It should be an existing key if data in the control is of modification to an existing structure. The server takes this information on advice.

The function returns zero if successful, or a negative error number. You should not call GetQuantitySearchResults after this method before another search, since this method invalidates that information.

See the GetQuantitySearchResults method, return to Methods, Developer's Reference, or the top of this document.

Standard Methods

The control includes a number of methods which support standard Windows activities.

AboutBox Method

The AboutBox method displays a copyright dialogue.



HRESULT AboutBox ();

Return to Methods, Developer's Reference, or the top of this document.

CanCopy Method

The CanCopy method indicates whether the control can copy it's current content to the clipboard.



boolean CanCopy ();

The function returns true if a copy is possible.

See the CanCut, CanPaste, Copy, Cut, and Paste methods, return to Methods, Developer's Reference, or the top of this document.

CanCut Method

The CanCut method indicates whether the control can cut it's current content to the clipboard.



boolean CanCut ();

The function returns true if a cut is possible. The only difference between this and the CanCopy is that this method will return false if the control is set to read only, whereas that method would return true.

See the CanCopy, CanPaste, Copy, Cut, and Paste methods, return to Methods, Developer's Reference, or the top of this document.

CanPaste Method

The CanPaste method indicates whether the control can paste its current content of the clipboard.



boolean CanPaste();

The function returns true if a copy is possible. Note that the control will happily paste a metafile, a bitmap, or its own Chemical control data. It cannot (yet) paste a Sketch file.

See the CanCopy, CanCut, Copy, Cut, and Paste methods, return to Methods, Developer's Reference, or the top of this document.

Clear Method

The Clear method empties the control.



void Clear ();

Return to Methods, Developer's Reference, or the top of this document.

Copy Method

The Copy method copies its content to the clipboard.



boolean Copy();

The control puts its content on the clipboard as a bitmap, and in its own Chemical control format. It returns true if successful.

See the CanCopy, CanCut, CanPaste, Cut, and Paste methods, return to Methods, Developer's Reference, or the top of this document.

Cut Method

The Cut method cuts its content to the clipboard.



boolean Cut();

The control puts its content on the clipboard as a bitmap, and in its own Chemical control format. It returns true if successful.

See the CanCopy, CanCut, CanPaste, Copy, and Paste methods, return to Methods, Developer's Reference, or the top of this document.

DoProperties Method

The DoProperties method displays the control's Property sheet.



void DoProperties ();

Return to Methods, Developer's Reference, or the top of this document.

Paste Method

The Paste pastes the content of the clipboard into the control.



boolean Paste ();

The appropriate data type is selected from the clipboard in the following order:

The control's own format, which should have put on the clipboard by using the Copy or and Cut methods;
A metafile, which is drawn into the control;
A bitmap and palette, which is drawn into the control.

The plain drawing options for paste are provided to enable the developer to display sophisticated chemical information, such as reactions, which have been prepared in an application such as ISIS/Draw, and which need to be displayed elsewhere. Any attempt to use any of the chemical methods after pasting a metafile or bitmap into the control will yield undefined results.

The control returns true if successful.

See the CanCopy, CanCut, CanPaste, Copy, and Cut methods, return to Methods, Developer's Reference, or the top of this document.

Refresh Method

The Refresh method redraws the control's content.



void Refresh();

Return to Methods, Developer's Reference, or the top of this document.

DDE Methods

The control includes DDE functionality to permit communication with non-OLE compliant chemical editing applications. These functions, and the executable methods, enable a developer to simulate OLE by supporting double-clicking on a chemical to run up an editor - although this may require some editor macro programming.

Future version of this control may drop these functions - see the DDE Wrap controls.

The DDEService property must be set before any of these methods are used.

DDEAddTopic Method

The DDEAddTopic method adds the specified topic to the list of those accepted by the control's DDE server.



short DDEAddTopic (BSTR lpszTopic);

lpszTopic is the name of the topic to add to the server. The method returns a handle to the topic if successful, or -1 on failure.

The DDE server must have previously been successfully initialised by assigning a value to the DDEService property. Once a topic has been added, a DDECommand event may occur when an external application uses that topic to communicate with the control.

See DDECommand, DDEDeleteTopic, DDEGetTopic, or DDEService, return to Methods, the Developer's Reference, or the top of this document.

DDEConversationCommand Method

The DDEConversationCommand method issues a command to a DDE server.



long DDEConversationCommand (BSTR lpszCommand);

lpszCommand is command to issue to the server. The method returns a value from the server.

The DDE conversation must have been successfully initialised by an earlier call to DDEConversationStart.

See DDEConversationEnd, DDEConversationStart, DDEInUse, DDEService, or DDEXeq, return to Methods, the Developer's Reference, or the top of this document.

DDEConversationEnd Method

The DDEConversationEnd method ends a conversation with a DDE server.



short DDEConversationEnd ();

The DDE conversation must have been successfully initialised by an earlier call to DDEConversationStart.

See DDEConversationCommand, DDEConversationStart, DDEInUse, DDEService, or DDEXeq, return to Methods, the Developer's Reference, or the top of this document.

DDEConversationStart Method

The DDEConversationStart method starts a conversation with a DDE server.



short DDEConversationStart(BSTR lpszService, BSTR lpszTopic);

lpszService identifies the service with which the conversation is desired, and lpszTopic identifies the topic of discussion. The method returns -1 if DDE has not been initialise, 0 if conversation cannot be started for some reason, and 1 if the conversation is successfully started.

DDE can only be initialised by assigning a value to the DDEService property.

See DDEConversationCommand, DDEConversationStart, DDEInUse, DDEService, or DDEXeq, return to Methods, the Developer's Reference, or the top of this document.

DDEDeleteTopic Method

The DDEDeleteTopic method removes the specified topic to the list of those accepted by the control's DDE server.



short DDEDeleteTopic(short nTopic);

nTopic is the value identifying the topic, previously returned by DDEAddTopic. The method returns 0 if successful, and -1 if something went dreadfully wrong.

See DDECommand, DDEAddTopic, or DDEGetTopic, return to Methods, the Developer's Reference, or the top of this document.

DDEGetTopic Method

The DDEGetTopic method returns the name of the specified topic.



BSTR DDEGetTopic(short nTopic);

nTopic is the value identifying the topic, previously returned by DDEAddTopic. The method returns NULL if unsuccessful, or the name of the topic otherwise.

See DDECommand, DDEAddTopic, or DDEDeleteTopic, return to Methods, the Developer's Reference, or the top of this document.

DDEInUse Method

The DDEInUse method confirms whether or not the DDE server has been initialised.



boolean DDEInUse ();

The DDE server can be initialised by assigning a value to the DDEService property.

See DDEService, return to Methods, the Developer's Reference, or the top of this document.

DDEXeq

The DDEXeq method connects to a service, issues a command, and then disconnects from that service.



long DDEXeq(BSTR lpszService, BSTR lpszTopic, BSTR lpszCommand);

lpszService is the DDE server with which you wish to communicate, lpszTopic is the topic of the conversation, and lpszCommand is the single command you wish to issue.

This method is equivalent to calling DDEConversationStart, DDEConversationCommand and DDEConversationEnd in sequence. The method returns -1 if it cannot successfully communicate with the server, and the return value of the command otherwise.

The DDE server can be initialised by assigning a value to the DDEService property.

See DDEConversationCommand, DDEConversationEnd, DDEConversationStart, DDEInUse, DDEService, or DDEXeq, return to Methods, the Developer's Reference, or the top of this document.

Executable Methods

The control includes DDE functionality to permit communication with non-OLE compliant chemical editing applications. These functions, and the DDE methods, enable a developer to simulate OLE by supporting double-clicking on a chemical to run up the editor and let the user edit a .MOL file - although this may require some macro programming in the editor.

ExecutableClose

The ExecutableClose method sends a close message to an executable.



short ExecutableClose (short nExecutable);

nExecutable is the executable identifier returned by ExecutableLaunch.

If the executable has a number of windows, you should identify the key window using the ExecutableWindow property before you use this method.

Not all executable take any notice of instructions telling them to go away. You can check whether this is the case having used this method by having your program do the following:

waiting an appropriate period of time;
using the ExecutableIsRunning method to see if the application has politely shut down;
if it hasn't, you can squash it by using the ExecutablePredujiceTerminate method as a last resort.

See the ExecutableIsRunning, ExecutableLaunch, and ExecutablePredujiceTerminate methods, the ExecutableWindow property, return to Methods, the Developer's Reference, or the top of this document.

ExecutableGetLastError

The ExecutableGetLastError method returns the last system error which occurred as a consequence of using these methods.



long ExectuableGetLastError ();

You should use this function to determine the exact reason why at attempt to use the ExecutableLaunch method failed.

See the ExecutableLaunch method, return to Methods, the Developer's Reference, or the top of this document.

ExecutableHide

The ExecutableHide attempts to hide an executable's window;



void ExecutableHide(short nExecutable);

nExecutable is the executable identifier returned by ExecutableLaunch.

If the executable has a number of windows, you should identify the key window using the ExecutableWindow property before you use this method.

See the ExecutableLaunch, and ExecutableShow methods, the ExecutableWindow property, return to Methods, the Developer's Reference, or the top of this document.

ExecutableIsRunning

The ExecutableIsRunning checks to see if a previously launched executable is still running.



boolean ExecutableIsRunning (short nExecutable);

nExecutable is the executable identifier returned by ExecutableLaunch. The method returns true if the executable is still running.

See the ExecutableLaunch method, the ExecutableWindow property, return to Methods, the Developer's Reference, or the top of this document.

ExecutableLaunch

The ExecutableLaunch method attempts to run a program.



short ExecutableLaunch (BSTR lpszAppName, BSTR lpszCmdLine, BSTR lpszWindowTitle, short nShowWindow);

lpszAppName is a string containing the applications name. If the application is not on the path, you will may need to provide the full path. The method will enclose this parameter in quotes.

lpszCmdLine is a string containing the command line parameters to feed to the program.

lpszWindowTitle is a string containing the program's main window title. This is used by the control to identify which window is to be targeted by other methods, including ExecutableClose, ExecutableHide and ExecutableShow. If this string is omitted, or the program does not launch with a window with this title, then control will attempt to identify an appropriate window. You can also provide this information using the ExecutableWindow property.

nShowWindow is a standard windows parameter identifying how the new applications window is to appear upon launch. This value corresponds to that fed to the standard windows API call ShowWindow - see that call's documentation for further information.

If successful, the method returns zero or a positive number as an executable identifier, which is used by other Executable methods and properties. If the function fails, it returns one of the following error codes:

OCXERR_TOOMANYXEQ indicated that the control is being used to control a large number of executables and cannot control any more - perhaps you should call ExecutableReuse;
OCXERR_LAUNCH indicates that the windows system call to launch the executable failed - use the ExecutableGetLastError to obtain further details.

See the ExecutableClose, ExecutableGetLastError, ExecutableHide, ExecutableIsRunning, ExecutablePredujiceTerminate, ExecutableReuse, and ExecutableShow methods, the ExecutableWindow property, error codes, return to Methods, the Developer's Reference, or the top of this document.

ExecutablePredujiceTerminate

The ExecutablePredujiceTerminate kills a previously launched application.



short ExecutablePrejudiceTerminate(short nExecutable);

nExecutable is the executable identifier returned by ExecutableLaunch.

For a discussion on when to use this method, see the ExecutableClose.

Be warned: killing an application is dangerous and should only be done in the last resort. If you do this, there is a danger that work in progress will not be saved, and it is quite possible for the applications files to become corrupt. Do not use this function unless you have to.

See the ExecutableClose, ExecutableIsRunning, and ExecutableLaunch methods, the ExecutableWindow property, return to Methods, the Developer's Reference, or the top of this document.

ExecutablePostMessage

The ExecutablePostMessage posts an application message to the executable.



short ExecutablePostMessage (short nExecutable, short nMessage, long wParam, long lParam);

nExecutable is the executable identifier returned by ExecutableLaunch. The remaining three paramaters are standard parameters - see your Windows documentation on PostAppMessage. If you want to post a message to the executable's window, use ExecutablePostWndMessage.

See the ExecutablePostWndMessage method, return to Methods, the Developer's Reference, or the top of this document.

ExecutablePostWndMessage

The ExecutablePostWndMessage posts a message to an application's main window.



short ExecutablePostWndMessage (short nExecutable, short nMessage, long wParam, long lParam, boolean bAll);

nExecutable is the executable identifier returned by ExecutableLaunch. The next three parameters are the usual message parameters - see your Windows documentation on PostMessage. The final parameter indicates whether the message is sent to all windows associated with the application, or simply the main one (see ExecutableLaunch and ExecutableWindowTitle). If you want to post a message to the executable's application queue, use ExecutablePostMessage.

See the ExecutableLaunch and ExecutablePostMessage methods, return to Methods, the Developer's Reference, or the top of this document.

ExecutableReuse

The ExecutableReuse indicates that an executable's slot can be reused.



void ExecutableReuse (short nExecutable);

nExecutable is the executable identifier returned by ExecutableLaunch.

Once an application is launched, its identifier remains reserved for that application until this method is called to free it.

See the ExecutableLaunch methods, return to Methods, the Developer's Reference, or the top of this document.

ExecutableShow

The ExecutableShow method attempts to show a previously hidden executable's window;



void ExecutableShow (short nExecutable, boolean bMaximize);

nExecutable is the executable identifier returned by ExecutableLaunch. If bMaximixe is true, the window is shown maximised, otherwise it is shown normalised.

If the executable has a number of windows, you should identify the key window using the ExecutableWindow property before you use this method.

See the ExecutableHide, and ExecutableLaunch methods, the ExecutableWindow property, return to Methods, the Developer's Reference, or the top of this document.

Version 2.1.15, 1st May 2001