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 Zap SPL program attempts to pass the molecule information to the Zap 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 Zap problems arise from path, environment, and protection difficulties and inconsistencies. Each time the actual Zap executable is run from within SYBYL, it is a new shell being spawned, with the user's own .cshrc, etc. being executed. If Zap is not defined in the .cshrc, e.g., if the user defines Zap by sourcing its definition file directly, then the important Zap environmental variables may not be properly defined and Zap 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 Zap 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 Zap.) Zap attempts to reuse the same filenames to reduce disk space, and if Zap can't write to one of its scratch files, it will fail.

3. Most Zap errors are currently reported only in the SYBYL text window. Thus the SPL part of the program does not know that the Zap executable had a problem, and may report results in dialog boxes that are artifacts from previous Zap sessions. We will continue to supplement the Zap 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 Zap user interface becomes. The obvious workaround is to monitor the SYBYL text window for error messages from the Zap executable.

4. SYBYL issues a steady stream of comments about files failing to open in R mode. Most of these arise because in the Zap 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.

5. When using the ZapCoMFA command, SYBYL fills the ZAPCOMFA 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 ZAPCOMFA 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.

6. Some parts of Zap, especially having to do with the Spreadsheet, may not work with X-terminal emulators on PCs and Macintoshes and occasionally on SGIs. Sometimes, and it does not seem to be particularly reproducible, the ZAPCOMFA item is missing from the Molecular Spreadsheet Autofill 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 Zap-specific macros that may have been overwritten by SYBYL.

7. Some statistical functions operating on Field columns in the MSS give irreproducible results when there is Zap field present. This may be related to the problem described next. There apparently is a memory instability in Sybyl associated with externally generated fields. The workaround is to save the table (MSS) and exit Sybyl after filling the field columns and then re-start Sybyl and resume.

8. When you try and "customize" a Zap field in CoMFA for some comparative studies, you get the same result as you get with the original Zap field. This would also occur if you are using other software packages such as HINT and/or Molconn-Z in the same Sybyl session. This error 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 "external" column you wish to add to your spreadsheet.

9. It is difficult to graph the results of a PLS study that involves a Zap 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 ZapQSAR dialog under ZapQSAR on the main menubar should help here, but will only take you part of the way.

10. You cannot "Pick" points on QSAR graphs from PLS studies that include a Zap 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.

11. You cannot Predict Properties from PLS Models that include the Zap Field. This is apparently an error in the graphical MSS interface: From the molecular spreadsheet the menubar command
    
    QSAR >> Predict Property ...
    
    does not work correctly if external fields like a Zap field are used in the CoMFA/PLS calculation! To check: simply predict the activities of the training set. They are different from the fitted predictions of the PLS analysis.
    Workaround: Use the command mode command in the text window:
    
    QSAR >> Analysis >> Predict >> Row expression(*)
    
    The simplest way to perform an external prediction is to include the compounds to be predicted into the molecular spreadsheet, to omit them from the CoMFA analysis, and finally use this command for prediction. (This error and workaround was prepared by Michael Wiese of Martin Luther Universität.)

Zap 1.05S Installation Instructions

Zap is released as a UNIX tar set via FTP or 4mm-DAT tape format. The release consists of an executable image "zap", executable images for several small utility programs, and extensive SPL (SYBYL Programming Language) script that creates menus, dialog boxes, and macros to execute the Zap programs. The installation (cshell) script places the Zap files in appropriate subdirectories under a new eduSoft directory tree and makes a few very minor (and easily reversible) changes to the SYBYL directory tree. A new cshrc file is created that, when "sourced", causes SYBYL to come up with Zap installed in its menu system. The Zap installation creates a parallel directory structure which in no way affects the performance and integrity of the previously installed Tripos tree.

The Zap 1.05S installation consists of three components: 1) installing the Zap software, 2) making a few minor changes to the Sybyl environment to enable Zap, and 3) setting up user accounts to give them access to Zap. Although it is not strictly necessary, the installation of Zap 1.05S is best performed as the "superuser" Special cases for: 1) Installing Zap "on top of" HINT or Molconn-Z and 2) Installing Zap, HINT and/or 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 Zap 1.05S tape (or FTP tar-set) into this directory:
   • cd /usr/eduSoft
   • tar xov (tar xovf zap105s 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 Zap installation makes the following changes to the Sybyl environment. Verify that there are not local modifications to these files that will be lost when Zap is installed.
   • The NetBatch application list, $TA_ROOT/batch/admin/APPLICATION, is modified to include the new Zap applications so that they can be run through Sybyl NetBatch. Note that if you have local additions to the APPLICATION list, you should manually add the new Zap applications.
   • The Zap NetBatch shell programs are copied into the appropriate Sybyl directory $TA_ROOT/batch/cmd.
   • Files are copied into the $TA_ROOT/sybylbase/tables/ta_coltype directory to define the Zap column types. (This directory has been created by Tripos for this purpose.)

5. Execute the appropriate Zap 1.05S installation script (if you are comfortable with the changes to the Sybyl environment described). 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_zap100s or
   • sh install_zapHV105s

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 SGI processor you are using and the eduSoft products you are installing (see the table below). (All other Zap environment variables are defined relative to $EDUSOFT_ROOT.) If you are on a mixed network of processors, you may have to add some shell logic here to call the correct definition files.
   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)	Platform	cshrc (in ta_site.csh)	profile (in ta_site.sh)
      Zap 1.05S	r4000+	cshrc_zap	profile_zap
      HASL 4.10S & Zap 1.05S	r4000+	cshrc_hasl+zap	profile_hasl+zap
      Hint 2.35S & Zap 1.05S	r4000+	cshrc_hint+zap	profile_hint+zap
      Molconn-Z 3.50S & Zap 1.05S	r4000+	cshrc_mconn+zap	profile_mconn+zap
      HASL 4.10S, Hint 2.35S & Zap 1.05S	r4000+	cshrc_hasl+hint+zap	profile_hasl+hint+zap
      HASL 4.10S, Molconn-Z 3.50S & Zap 1.05S	r4000+	cshrc_hasl+mconn+zap	profile_hasl+mconn+zap
      Hint 2.35S, Molconn-Z 3.50S & Zap 1.05S	r4000+	cshrc_hint+mconn+zap	profile_hint+mconn+zap
      HASL 4.10S, Hint 2.35S, Molconn-Z 3.50S & Zap 1.05S	r4000+	cshrc_hasl+hint++mconn+zap	profile_hasl+hint+mconn+zap
      ZapHV 1.05S	r4000+	cshrc_zapHV	profile_zapHV
      HASL 4.10S & ZapHV 1.05S	r4000+	cshrc_hasl+zapHV	profile_hasl+zapHV
      Hint 2.35S & ZapHV 1.05S	r4000+	cshrc_hint+zapHV	profile_hint+zapHV
      Molconn-Z 3.50S & ZapHV 1.05S	r4000+	cshrc_mconn+zapHV	profile_mconn+zapHV
      HASL 4.10S, Hint 2.35S & ZapHV 1.05S	r4000+	cshrc_hasl+hint+zapHV	profile_hasl+hint+zapHV
      HASL 4.10S, Molconn-Z 3.50S & ZapHV 1.05S	r4000+	cshrc_hasl+mconn+zapHV	profile_hasl+mconn+zapHV
      Hint 2.35S, Molconn-Z 3.50S & ZapHV 1.05S	r4000+	cshrc_hint+mconn+zapHV	profile_hint+mconn+zapHV
      HASL 4.10S, Hint 2.35S, Molconn-Z 3.50S & ZapHV 1.05S	r4000+	cshrc_hasl+hint++mconn+zapHV	profile_hasl+hint+mconn+zapHV

   5. Install your Zap License Keys(s) as described on-line.

   6. Enable Zap 1.05S for users. All users who want to use the Zap 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 Zap to be defined.
      • vi ~user/.sybylrc
      • make appropriate changes (for each user)...
      Note that Zap 1.05S uses each user's dumpster directory as a scratch location for temporary files. Confirm that each Zap user has a ~user/dumpster.

   7. Try it out. Re-login or re-source the .cshrc file and run Sybyl. If Zap 1.05S is set up properly, the messages "Loading eslc menubar descriptions" and "Loading Zap macro definitions and dialogs" will appear (perhaps very briefly) in the graphics screens after the usual Sybyl messages. There should be a new pulldown "eslc" on the Sybyl menubar which includes a "Zap" menu item. Follow all of the Zap 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.

   Adding Zap to a Site that has HINT, Molconn-Z and/or HASL

   1. Unload the Zap 1.05S tape (or FTP tar set) into the current $EDUSOFT_ROOT directory:
      • cd $EDUSOFT_ROOT
      • tar xov (tar xovf zap105s and tar xovf eslctar)

   2. Execute one of the Zap 1.05S installation scripts (if you are comfortable with the changes to the Sybyl environment described in detail in Step 4 above). The installation scripts are quite simple, and the functions they include can be performed manually if you wish to intercept any of the steps.
      • cd eslc
      • sh install_zap100S_after_hasl400S or
      • sh install_zap100S_after_hint235S or
      • sh install_zap100S_after_mconn350S or
      • sh install_zapHV105S_after_hasl400S or
      • sh install_zapHV105S_after_hint235S or
      • sh install_zapHV105S_after_mconn350S

   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 SGI processor you are using and the eduSoft products you are installing (see the table above). (All other Zap environment variables are defined relative to $EDUSOFT_ROOT. If you are on a mixed network of processors, you may have to add some shell logic here to call the correct definition files.

   4. Steps 7, 8 and 9 above.

   Installing Zap and HINT, Molconn-Z and/or HASL Together

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

   2. Unload the Zap 1.05S tape (or FTP tar set), the HINT 2.35S tape (or FTP tar set), the Molconn-Z 3.50S tape (or FTP tar set) and/or the HASL 4.10S tape (or FTP tar set) into this directory:
      • cd /usr/eduSoft
      • tar xov (tar xovf hint235s) and/or
      • tar xov (tar xovf mconn350s) and/or
      • tar xov (tar xovf hasl410s) and/or
      • tar xov (tar xovf zap105s and tar xovf eslctar)

   3. Execute one of the installation scripts (if you are comfortable with the changes to the Sybyl environment described in detail in Step 4 above). The installation scripts are quite simple, and the functions they include can be performed manually if you wish to intercept any of the steps.
      • cd eslc
      • sh install_hint235S_and_mconn350S_and_zap100S or
      • sh install_hint235S_and_mconn350S_and_hasl400S_and_zap100S or
      • sh install_hint235S_and_mconn350S_and_zap100S or
      • sh install_hint235S_and_mconn350S_and_hasl400S_and_zap100S

   4. Step 6 above.

   5. Install the Zap, HINT, Molconn-Z and/or HASL License Keys(s) as described on-line.

   6. Steps 8 and 9 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/Zap SPL files wth other applications, there are two types of environmental variables in the HINT/Molconn-Z/Zap 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 $ZAP_SPL, and $MCONN_SPL; these are reserved for files that are specific to the product (i.e., HINT, Molconn-Z and Zap) functionality. The root of the HINT, Molconn-Z and Zap 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 Zap/HINT/Molconn-Z/HASL installation, please feel free to give us a call.