Problems, Workarounds, Clarifications (FAQ)

1. Spreadsheet functions fail with cryptic messages implying shell errors. This can sometimes happen if the name of your molecule has spaces or quotes single or double) imbedded. What is happening is that when the HINT SPL program attempts to pass the molecule information to the HINT executable the unix shell interpreter can not parse the information properly. The workaround is to change the name of the molecules in the database.

2. A lot of other serious Molconn-Z problems arise from path, environment, and protection difficulties and inconsistencies. Each time the actual Molconn-Z executable is run from within SYBYL, it is a new shell being spawned, with the user's own .cshrc, etc. being executed. If Molconn-Z is not defined in the .cshrc, e.g., if the user defines Molconn-Z by sourcing its definition file directly, then the important Molconn-Z environmental variables may not be properly defined and Molconn-Z will not function as designed. Often the "ridiculously long path" unix error accompanies this problem. Another related potential source of this type of problem arises when the Molconn-Z scratch files, written to the user's ~/dumpster directory, don't have write privilege. (This may occur, for example, if root privilege was earlier used to run Molconn-Z.) Molconn-Z attempts to reuse the same filenames to reduce disk space, and if Molconn-Z can't write to one of its scratch files, it will fail.

3. Most Molconn-Z errors are currently reported only in the SYBYL text window. Thus the SPL part of the program does not know that the Molconn-Z executable had a problem, and may report results in dialog boxes that are artifacts from previous Molconn-Z sessions. We will continue to supplement the Molconn-Z error reporting with upcoming releases, but there is a significant tradeoff here. The more error checking that is done with the SPL code (and all screen dialogs are generated by SPL), the slower and more unresponsive the Molconn-Z user interface becomes. The obvious workaround is to monitor the SYBYL text window for error messages from the Molconn-Z executable.

4. When you try and delete one column from a MSS that has multiple Molconn-Z indices, all of the indices are deleted. This is a quirk of the SPL column types. Regardless of their actual relationship SYBYL assumes that the SPL column types created for each row in a single pass are related and that they cannot exist independently. There is no simple workaround other than to more carefully choose the column types that you will want before filling the table.

5. SYBYL issues a steady stream of comments about files failing to open in R mode. Most of these arise because in the Molconn-Z SPL code we chose to ask the user to verify if he wants to write over an existing file of the same name. The only way to do this is to first check to see if the file already exists by trying to open it with R(ead) mode, which is the source of the "errors" reported by SYBYL.

6. When using the MConnCoMFA command, SYBYL fills the MCONNCOMFA column with zeroes and also asks you to check field values for each row in the table. Both of these are perfectly normal. SYBYL always tells you to check field values when an externally generated field is imported into the spreadsheet. The 0.00 value placed in the spreadsheet for the MCONNCOMFA column only represents a placeholder for purposes of display, the actual column contains all of the field values for the entire grid. The value visible in the column probably represents the first grid value (one of the corners of the grid cage) which is almost always zero.

7. Some parts of Molconn-Z, especially having to do with the Spreadsheet, may not work with X-terminal emulators on PCs and Macintoshes. There are apparently differences within SYBYL for the XDEV virtual graphics device that influence how certain SPL scripts are interpreted by SYBYL.

8. Sometimes the Molconn-Z CoMFA column does not appear in the AutoFill (Column) Menu. If this happens type "mss!reset_eslc" to the Sybyl> prompt before hitting Autofill. This simple command appears to clear up this problem by re-defining a few of the Molconn-Z-specific macros that may have been overwritten by SYBYL.

9. When you try and "customize" an E-State field in CoMFA for some comparative studies, you get the same result as you get with the original MCONN field. This is caused by a long-standing SYBYL bug that apparently prohibits you from filling more than one CoMFA-type column from an externally-generated field per SYBYL session. The Workaround, which is less than satisfying, is to save your Spreadsheet, exit and restart SYBYL for each MCONN column you wish to add to your spreadsheet.

10. It is difficult to graph the results of a PLS study that involves a MCONN field. As Tripos "improved" their dialog boxes for using the spreadsheet and CoMFA, they made it more difficult to graph fields other than the standard steric and electrostatic ones The View CoMFA dialog under QSAR has no provisions for looking at anything other than the standard two field types (it is quite nice for that, though). The Graph MConnQSAR dialog under MolconnZQSAR should help here.

11. You cannot "Pick" points on QSAR graphs from PLS studies that include a Molconn-Z field. Again this appears to be a bug in SYBYL. The "problem" graph is "ORIGINAL_DATA" -- if that one is active, the SYBYL Pick function always chooses the first row of the Table, regardless of your actual selection. The workaround is to go into the QSAR, Manage QSAR, Select Graphs... dialog and choose COEFFICIENTS, PREDICTED_ACTUAL and/or QQ_PLOT as the graphs to be plotted. Selection of ORIGINAL_DATA or ALL (which includes ORIGINAL_DATA) seems to activate the SYBYL bug.

Molconn-Z 4.03S Installation Instructions

1. Separate Installation Instructions are provided for users of the multiplatform standalone versions of Molconn-Z in Chapter Three.

   The Molconn-Z 4.03S installation consists of three components: 1) installing the Molconn-Z software, 2) making a few minor changes to the Sybyl environment to enable Molconn-Z, and 3) setting up user accounts to give them access to Molconn-Z. Although it is not strictly necessary, the installation of Molconn-Z 4.03S is best performed as the "superuser".

   Special cases for: 1) Installing Molconn-Z "on top of" HINT, 2) Installing HINT and Molconn-Z together are described below.

   1. Make a root directory for the eduSoft products. We recommend /usr/eduSoft, but any location will work. The unix command for this step is: mkdir /usr/eduSoft

   2. Unload the Molconn-Z 4.03S tape (or FTP tar-set) into this directory:
      • cd /usr/eduSoft
      • (gunzip mconn403s.gz and gunzip eslctar.gz)
      • tar xov (tar xovf mconn403s and tar xovf eslctar)

   3. Make sure Sybyl is defined. If you are not sure, check to see if the environment variable TA_ROOT is defined:
      • echo $TA_ROOT
      If $TA_ROOT is not defined, you will have to perform the steps you usually undertake to run Sybyl up to the point where you enter sybyl to the unix prompt.

   4. The Molconn-Z installation makes only the following change to the Sybyl environment:
      • One file is copied into the $TA_ROOT/sybylbase/tables/ta_coltype directory to define the MConnIDX column type. (This directory has been created by Tripos for this purpose.)

   5. Execute the Molconn-Z 4.03S installation script (if you are comfortable with the change to the Sybyl environment described in detail above). The installation script is quite simple, and the functions it includes can be performed manually if you wish to intercept any of the steps.
      • cd eslc
      • sh install_mconn400s

   6. Edit $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh to add the following features: a) define two Tripos variables, TA_MENUBAR_USER_INIT and TA_MSS_USER_INIT, as null; b) define the EDUSOFT_ROOT environmental variable; c) "source" a platform-and product-specific definitions file that defines the a variety of eduSoft environment variables; and d) activate user specific startup information for Sybyl (the .sybylrc file, see below).

      To do this:

      1. append install/ta_site.csh_eslc to $TA_ROOT/lib/ta_site.csh either with the editor or the unix cat command.
      2. append install/ta_site.sh_eslc to $TA_ROOT/lib/ta_site.sh either with the editor or the unix cat command.
      3. edit both $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh so that the proper location of $EDUSOFT_ROOT is set (assumed above to be /usr/eduSoft) and that the proper cshrc and profile files are defined for the eduSoft products you are installing (see the table below). (All other Molconn-Z environment variables are defined relative to $EDUSOFT_ROOT.
      4. also in $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh make sure that the TA_USER_STRT option is turned on and pointing to $HOME/.sybylrc.

         Product(s)	cshrc (in ta_site.csh)	profile (in ta_site.sh)
         mconn 4.03S	cshrc_mconn	profile_mconn
         hint 2.35S & mconn 4.03S	cshrc_hint+mconn_r4	profile_hint+mconn_r4

      5. Install the Molconn-Z License Keys(s) as described: on-line. Note that you are installing a license for Molconn-Z 4.03S, but that license will also activate the Irix "standalone" Molconn-Z program that was alos included on the tape.

      6. Enable Molconn-Z 4.03S for users. All users who want to use the Molconn-Z program through Sybyl must modify (or create) their individual .sybylrc files to include the two lines in the file $EDUSOFT_ROOT/eslc/install/sybylrc. These added lines are two commands that Sybyl must execute on startup in order for Molconn-Z to be defined. Note that Molconn-Z 4.03S uses each user's dumpster directory as a scratch location for temporary files. Confirm that each Molconn-Z user has a ~user/dumpster.

      7. Each user must have a directory (.molconnz) containing a set of personal Molconn-Z preference files: a csh command "MCONN_USER" has been defined as an alias to automatically copy these files. Each user should enter this command before attempting to use Molconn-Z 4.03S for the first time.

      8. Try it out. Re-login or re-source the .cshrc file and run Sybyl. If Molconn-Z 4.03S is set up properly, the messages "Loading eslc menubar descriptions" and "Loading MolconnZ macro definitions and dialogs" will appear in the graphics screens after the usual Sybyl messages. There should be a new pulldown "eslc" on the Sybyl menubar which includes a "MolconnZ" menu item. Follow all of the MolconnZ Tutorials in the manual for a complete introduction to the program, but it is advisable at this point to try at least a portion of Lesson 1 to confirm that the license is properly configured and that the program is operational.

      9. Standalone Molconn-Z is available with the command $MCONN_RUN/molconnz. (See the Standalone Versions portion of the manual, in particular Chapter 4, for operational instructions.)

      Adding Molconn-Z to a Site that has HINT

      1. Unload the Molconn-Z 4.03S tape (or FTP tar set) into the current $EDUSOFT_ROOT directory:
         • cd $EDUSOFT_ROOT
         • (gunzip mconn403s.gz and gunzip eslctar.gz)
         • tar xov (tar xovf mconn403s and tar xovf eslctar)

      2. Execute the Molconn-Z 4.03S installation script (if you are comfortable with the change to the Sybyl environment described in detail in Step 4 above). The installation script is quite simple, and the function it includes can be performed manually if you wish to intercept any of the steps.
         • cd eslc
         • sh install_mconn400s_after_hint230s

      3. As described in Step 6, above, edit both $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh so that the proper location of $EDUSOFT_ROOT is set (assumed above to be /usr/eduSoft) and that the proper cshrc and profile files are defined for the eduSoft products you are installing (see the table above). (All other HINT environment variables are defined relative to $EDUSOFT_ROOT.

      4. Steps 7 - 11 above.

      Installing HINT and Molconn-Z Together

      1. Make a new directory for the eduSoft products, e.g., mkdir /usr/eduSoft.

      2. Unload the HINT 2.35S tape (or FTP tar set) and Molconn-Z 4.03S tape (or FTP tar set) into this directory:
         • cd /usr/eduSoft
         • (gunzip hint235s.gz)
         • tar xov (tar xovf hint235s)
         • (gunzip mconn403s.gz and gunzip eslctar.gz)
         • tar xov (tar xovf mconn403s and tar xovf eslctar)

      3. Execute the installation script (if you are comfortable with the changes to the Sybyl environment described in detail in Step 4 above). The installation script is quite simple, and the functions it includes can be performed manually if you wish to intercept any of the steps.
         • cd eslc
         • sh install_hint230s_and_mconn400s

      4. Steps 6 - 11, above.

      ---

      Special Notes for "Customized" Sybyl Sites

      There can be difficulties with the above procedures if there have already been local modifications made to your Sybyl installation. For example, if the $TA_MENUBAR_USER_INIT or $TA_MSS_USER_INIT variables are already being used at your site to define new functions, the described installation procedure should be modified. To make it easy to merge the HINT/Molconn-Z SPL files wth other applications, there are two types of environmental variables in the HINT/Molconn-Z setup. The first, $ESLC_SPL, points to files (which are named with the eslc_ prefix) that may be moved to another directory or otherwise modified to fit the local requirements. The other type of environmental variable is specific to the product, i.e., $HINT_SPL and $MCONN_SPL; these are reserved for files that are specific to the product (i.e., HINT and Molconn-Z) functionality. The root of the HINT and Molconn-Z additions to Sybyl are in the files: $ESLC_SPL/eslc_sybyl.spl and $ESLC_SPL/eslc_spreadsheet.spl, which are pointed to by $TA_MENUBAR_USER_INIT and $TA_MSS_USER_INIT, respectively.

      If there are questions or difficulties with the HINT/Molconn-Z installation, please feel free to give us a call.