This page describes the TCL interface to BioCoRE. For general information about programming with BioCoRE, please go to our Programming With BioCoRE page.

Files. These are the latest released versions of the API:

  • The actual API
  • Testing File. Most of the examples below are from this file
  • Package file allows TCL to easily find the file it needs
  • Helper procedures that don't directly talk to the BioCoRE server, but use the BioCoRE api calls. These include things like Tk window frontends to some of the API calls.
  • TCL Version of the Control Panel Alpha version of a Control Panel written in TCL. This isn't very robust at this point, and it requires you to have valid session information in your .biocoreSession file (normally you populate this file by logging in via the Java Control Panel) But, the concepts are covered and can be used to implement more robust solutions.

    Quick Jump. I want to:

    The API is provided as a BioCoRE package and is available for download. The package requires http, and if you have tls it will use https for communication. We recommend the installation of the tls package.

    First, the user of your program must register with a BioCoRE server. This is done via the standard BioCoRE web interface, or, a guest account can be created with the API.

    Connecting to BioCoRE

    There are multiple ways to get your TCL code talking to the BioCoRE server as a BioCoRE user.
    • If the user logs in via the Web Start version of the Control Panel, it is pretty easy. You can just call the initDefault procedure. Check out the biolog code example.
         package require biocore 1.15
      
         puts "Testing biocore_initDefault"
      
         set anyErrors [::biocore::initDefault ]
         if { [string length $anyErrors] > 0} {
            puts stderr $anyErrors
         } else {
            # user values have been set.  It would be wise to call
            # verify here to make sure.
         }
      
    • There is a login TCL procedure. For versions of the API before 1.17 you MUST have TLS installed to use the procedure. (The server won't allow nonsecure connections for login, so you MUST have TLS to allow the secure connections) Starting with API version 1.17, encryption is used to send the password to the server, so it can be safely used to log into the BioCoRE server.

      The login procedure returns the user ID of the user, although that isn't being used for anything right now.

      If the user has not logged in, the following code will get the user logged in. Note, if you have the biocoreHush variable set, and do NOT have TLS, this procedure call will fail with an error of Invalid User. The login method requires version 1.15 of the biocore package.

         package require biocore 1.15
         ::biocore::UserInfo ui
      
         puts "Testing biocore_login"
      
         # get the user name
         puts "User Name?"
         gets stdin strUserName
      
         # get the password
         puts "Password (will show plaintext in terminal window)?"
         gets stdin strPassword
      
         if [catch {eval ::biocore::ui configure [::biocore::login $strUserName \
                                                $strPassword ]} errmsg] {
            # if we make it in here, we had an error thrown
            puts "Error: $errmsg"
         } else {
            # we got a response.  We need to print it out
            puts "Login successful."
            puts "Session: '$::biocore::Session'"
            puts "User Id: '[::biocore::ui cget Id]'"
      
         }
      
      The login procedure will cause a session file to be written to the user's home directory. Specifically, a directory called .biocore is written in the user's home directory, and a file called .biocoreSession is written to that directory that contains information about the user's current session. On Unix and derivatives, the home directory concept should be easy to understand. On Windows, TCL seems to typically use the user's Documents & Settings folder or something similar. You might have to look around to discover the exact location.

    • If the user logs in via the web without the Web Start version of the Control Panel... By clicking on the Utilities link in the bottom left hand corner of the screen they will be presented with the Utilities menu.

      An option near the end of that menu is API Connection Information. Clicking on this will present a table that looks something like:

      URL:            https://biocore-s.ks.uiuc.edu/biocore/
      Session ID:     3EFC480542F5781751C1453EB999AE98
      Project list. Choose the ID associated with the project that 
      you are working on:
      
      All User Test Project     1
      Project X                 2
      Project Y                27
      Project Z                93 
      
      The URL, Session ID, and project ID are all values that you will need.

      For the purposes of the following code, we will assume that the TCL variable strUrl has been set to the URL value given above, the TCL variable strSession has been set to the session id given above (except for documentation about the login procedure), and the TCL variable strProject has been set to the number corresponding to the user's desired project given above.

      In the program you are writing you might be able to save some of the above values for the user IF they only ever login to one BioCoRE server. If they use multiple BioCoRE servers they will need to enter this information everytime. The URL and the project IDs are unlikely to change. The session id, however, will change each time they log in.

      The following code will initialize the BioCoRE API with the information that it needs to connect to the BioCoRE server assuming the user has already logged in.

      package require biocore 1.15
      
      # set the URL
      set ::biocore::URL $strUrl
      
      # Are you behind a proxy?  If so, uncomment the following line
      #   ::biocore::setProxy $strProxyHost $iProxyPort
      
      # set the Session
      set ::biocore::Session $strSession
      
      # set the Project
      set ::biocore::Project $strProject
      

    When the biocore TCL package is accessed for the first time it will print out a line to STDOUT giving the version number and the URL for BioCoRE. Additionally, if the user doesn't have TLS in their version of TCL it will print a warning line stating this.

    We have provided to way to turn this printing off, but we suggest leaving the printing enabled. If you wish to turn it off, give the variable biocoreHush a value before using the package and it won't print these two lines to STDOUT.

    Determining if a user has a valid BioCoRE Session

    If you want to determine whether or not the BioCoRE server thinks that a user has a valid session id and project id, you can do:

       package require biocore 1.15
    
       puts "Testing biocore_verify"
    
       if [catch {set i [::biocore::verify ]} errmsg] {
          # if we make it in here, we had an error thrown
          puts "Error: $errmsg"
       } else {
          # we got a response.  We need to print it out
          puts "User is valid $i"
       }
        
    

    Reset A User's BioCoRE Password

    A user's password can be reset to a random password. This is used in cases where a user has forgotten their password.

       package require biocore 1.20
       puts "Testing biocore_resetPassword"
    
       # get the user name
       puts "User Name?"
       gets stdin strUserName
    
       if {[catch {::biocore::resetPassword $strUserName } errmsg]} {
          # if we make it in here, we had an error thrown
          global errorInfo errorCode
          puts "Error in resetPassword: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          # everything worked
          puts "Password Reset Successful.  Check Your Email."
       }
        
    

    Change A User's BioCoRE Password

    A user's password can be changed to a new password. This is used when a user knows their password, but wants to change it to something new. As you can see from the sample code below, the changePassword procedure takes an old and a new password. It is suggested that the programmer verify that the new password is correct (typically by having the user enter it twice).

       package require biocore 1.20
       puts "Testing biocore_changePassword"
    
       # get the old password
       puts "Old Password? (will show plaintext in terminal window)"
       gets stdin strOld
    
       puts "New Password?"
       gets stdin strNew1
    
       puts "New Password (confirm)?"
       gets stdin strNew2
    
       if { [string compare $strNew1 $strNew2] == 0 } {
          if {[catch {::biocore::changePassword $strOld $strNew1 } errmsg]} {
             # if we make it in here, we had an error thrown
             global errorInfo errorCode
             puts "Error in changePassword: <$errmsg> <$errorInfo> <$errorCode>"
          } else {
             # Looks like things went ok
             puts "Password Changed successful."
          }
       } else {
          puts "Two new passwords don't match."
       }
       
    
    

    Getting a list of BioCoRE projects in which a user is enrolled

    You can retrieve a list of project names along with their associated BioCoRE project ids.

       package require biocore 1.15
    
       puts "Testing biocore_getProjectList"
    
        # get the list
        if [catch { set projectList [::biocore::getProjectList] } errmsg] {
          # if we make it in here, we had an error thrown
          puts "Error: $errmsg"
       } else {
          # we got a response.  We need to print it out
          puts " Id   Project"
          puts "----  -------"
          foreach { name id } $projectList {
             puts "[format %3i $id]   $name"
          }
       }                
    

    Get a list of projects that a user is eligible to join

    getEligibleProjects will return a list of projects that a user is eligible to join. These can then be displayed in lists/windows/etc. Presumably, this would be followed by a call to joinProject.
       package require biocore 1.16
       puts "Testing biocore_getEligibleProjects"
    
        # get the list
        if {[catch { set projectList [::biocore::getEligibleProjects] } errmsg]} {
          # if we make it in here, we had an error thrown
          global errorInfo errorCode
          puts "getEligibleProjects Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          # we got a response.  We need to print it out
          puts $projectList
          puts "Time          id  [format %18s title] [format %40s description] isPublic userInvited creatorid altproject publicareas defaulttab"
          puts "----  -------"
          foreach { ti p t d i in ci ap pa dt } $projectList {
             puts "$ti [format %3i $p] [format %18s $t] [format %40s $d] $i $in $ci
    $ap $pa $dt"
          }
      }
    
    

    Join a project that a user is eligible to join

    Given a project id, add this user to the project. The project must either be a public project, or the user must have been invited to the project.
       package require biocore 1.16
       puts "Project id to join?"
       gets stdin iId
        if {[catch {::biocore::joinProject $iId } errmsg]} {       
          # if we make it in here, we had an error thrown
          global errorInfo errorCode
          puts "joinProject Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          puts "Joined project $iId"
       } ; # end the else on not having an error in the API request
    
    
    

    Getting a list of BioCoRE Notebook entries

    Using the API you can retrieve an index of entries that have been posted to the BioCoRE notebook. The following code will demonstrate how to do this. BioCoRE Notebook entries are stored according to "type". The regular user message list (what you normally see when you choose the Message Board in BioCoRE) is type 0. The list of saved VMD states is type 2. The list of BioLog messages is 4. So, if you wish to retrieve the list of regular user message board messages, iType would be 0. The code also prints out each entry.

       package require biocore 1.15
    
       ::biocore::NotebookEntryInfo nei
       puts "Testing biocore_getNotebookEntryList"
    
       puts "Message type (0 for normal notebook msg; 4 for biolog messages)?"
       gets stdin iType
    
       if [catch {set neiList [::biocore::getNotebookEntryList $iType 0 \
                                                                0 ]} errmsg] {
          # if we make it in here, we had an error thrown
          puts "Error: $errmsg"
       } else {
          # we got a response.  We need to print it out
          set iNumEntries [llength $neiList]
          puts "Number of Notebook Entries: '$iNumEntries'"
    
          # now we loop over the entries
          for {set iCount 0} {$iCount < $iNumEntries} {incr iCount} {
             eval ::biocore::nei configure [lindex $neiList $iCount]
    
             if { [::biocore::nei cget Id] == -1 } {
                puts "This entry has been deleted"
             } else {
                puts "Id: [::biocore::nei cget Id], Time: '[::biocore::nei cget Time]', "
                puts "User: '[::biocore::nei cget User]', Title: '[::biocore::nei cget Title]', "
                puts "Desc: '[::biocore::nei cget Description]'"
             }
          }
       }
    

    Getting a single Notebook entry

    The above procedure will return a list of IDs of individual messages. The id of a desired message can be used to retrieve the message itself.
       package require biocore 1.15
    
       ::biocore::NotebookEntry ne
    
       puts "Message id?"
       gets stdin iMsgId
    
       if [catch {eval ::biocore::ne configure [::biocore::getNotebookEntry \
                                                           $iMsgId ]} errmsg] {
          # if we make it in here, we had an error thrown
          puts "Error: $errmsg"
       } else {
          # we got a response.  We need to print it out
          ::biocore::ne print
       }
    

    Saving a BioCoRE Notebook entry

    You can save a new entry to the Notebook also. If you want, you can upload an image or something else along with the notebook message. If you have an image called plot.jpg you can reference this file in your notebook entry text by saying: <IMG SRC="<<<notebookAttach plot.jpg>>>">
       package require biocore 1.22
    
       ::biocore::NotebookEntry ne
    
       puts "title?"
       gets stdin strTitle
       ::biocore::ne configure Title $strTitle
    
       # NOTE:  Description isn't yet supported on the server side.  This
       # requires us to change a database table to add a new column, etc
       # and this hasn't been done yet
       puts "description?"
       gets stdin strDesc
       ::biocore::ne configure Description $strDesc
    
       puts "Message type (0 for normal notebook msg; 4 for BioLog msg)?"
       gets stdin iType
       ::biocore::ne configure Type $iType
    
       puts "Are you going to upload a file with this entry? (1 for yes, 0 for no)"
       gets stdin iUpload
    
       if { $iUpload == 1} {
          puts "Local filename that you are going to upload"
          gets stdin strLocalName
          ::biocore::ne configure FileUploadName $strLocalName
          set ind [string last "/" $strLocalName]
          incr ind
          set XXXX [string range $strLocalName $ind end]
          puts "Put <<<notebookAttach $XXXX>>> anywhere you want the file URL to be"
       }
    
       puts "Number of lines in body (purely for ease of testing)?"
       gets stdin iNum
    
       set count 0
       set strMsg ""
    
       puts "Enter the message"
       for {set iCount 0} {$iCount < $iNum} {incr iCount} {
          gets stdin strLine
          append strMsg  "$strLine\n"
       }
       ::biocore::ne configure Text $strMsg
    
       # print out the message to be sent, just for verification
       puts "\n---\nTitle: '[::biocore::ne cget Title]'"
       puts "Description: '[::biocore::ne cget Description]'"
       puts "Type: '[::biocore::ne cget Type]'"
       puts "FileUpload: '[::biocore::ne cget FileUploadName]'"
    
       puts "Text: '[::biocore::ne cget Text]'"
    
       if {[catch {set iRetVal [::biocore::saveNotebookEntry ::biocore::ne ]} \
                                                                      errmsg]} {
          global errorInfo errorCode
          puts "saveNotebookEntry Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          puts "iRetVal was $iRetVal"
       }
    

    Deleting a BioCoRE Notebook entry

    You can delete a BioCoRE Notebook entry, given its ID. The server will not allow this if the user doesn't have permission to do so.
       package require biocore 1.15
    
       puts "Testing biocore_deleteNotebookEntry"
    
       puts "Notebook entry id to delete?"
       gets stdin iId
    
       if [catch [::biocore::deleteNotebookEntry $iId ] errmsg] {
          # if we make it in here, we had an error thrown
          puts "deleteNotebookEntry Error: $errmsg"
       } else {
          puts "Notebook entry deleted"
    
       } ; # end the else on not having an error in the API request
    

    Getting the content of a BioCoRE BioFS directory

    You can get information about a directory in the BioFS. Directories are identified by an id number. Directory ID 0 is the top level directory for a user. It has, as children, all of the directories that a user can access. Directory ID -1 is the user's special private directory that no one else can access.
       package require biocore 1.15
    
       ::biocore::BiofsDirectory biofsDir
    
       puts "Directory id to retrieve?"
       gets stdin iId
    
       if [catch {eval ::biocore::biofsDir configure \
                                 [::biocore::getBiofsDirectory $iId 0]} errmsg] {
          # if we make it in here, we had an error thrown
          puts "getBiofsDirectory Error: $errmsg"
       } else {
          # we got a response.  We need to print it out
          puts "Directory name: '[::biocore::biofsDir cget Name]'"
    
          set deList [::biocore::biofsDir cget Entries]
          set iNumEntries [llength $deList]
          puts "Number of Dir Entries: '$iNumEntries'"
    
          # now we loop over the entries
          for {set iCount 0} {$iCount < $iNumEntries} {incr iCount} {
             ::biocore::BiofsDirectoryEntry bioDE
             eval ::biocore::bioDE configure [lindex $deList $iCount]
    
             # do we have a directory, or a file?
             if { [::biocore::bioDE cget Type] == 0 } {
                ::biocore::bioDE printDir
             } else {
                ::biocore::bioDE printFile
             } ; # end the else
          } ; # end the for loop over the directory entries
       } ; # end the else on not having an error in the API request
    

    Getting a particular BioCoRE BioFS file

    Once you have the ID for a BioFS file that you want, you can use the API to save the file to a filename on your local filesystem.
       package require biocore 1.15
    
       puts "Testing biocore_getBiofsFile"
    
       puts "File id to retrieve"
       gets stdin iId
    
       puts "Local filename to save to"
       gets stdin strLocalName
    
       if [catch [::biocore::getBiofsFile $iId $strLocalName] errmsg] {
          # if we make it in here, we had an error thrown
          puts "getBiofsFile Error: $errmsg"
       } else {
          puts "File downloaded to $strLocalName"
    
       } ; # end the else on not having an error in the API request
    

    Uploading a file to the BioCoRE BioFS

    Once you have the directory ID for the BioFS directory where you want to upload a file,you can use the putBiofsFile procedure in the API to upload a file on your local filesystem to the BioFS. This procedure requires http package 2.2+ to be successful.
       package require biocore 1.15
    
       puts "Testing biocore_putBiofsFile"
     
       puts "Directory id to place file in?"
       gets stdin iDirId
    
       puts "Local filename to send?"
       gets stdin strLocalName
    
       puts "Name file will be given in BioFS?"
       gets stdin strRemoteName
    
       if [catch [::biocore::putBiofsFile $iDirId $strLocalName \
                                                        $strRemoteName] errmsg] {
          # if we make it in here, we had an error thrown
          puts "putBiofsFile Error: $errmsg"
       } else {
          puts "File $strLocalName uploaded to $strRemoteName"
       } ; # end the else on not having an error in the API request
    

    Deleting a file from the BioCoRE BioFS

    Files can be deleted from the BioFS.
       package require biocore 1.15
    
       puts "Testing biocore_delBiofsFile"
    
       puts "File id to delete?"
       gets stdin iId
    
       if [catch [::biocore::delBiofsFile $iId ] errmsg] {
          # if we make it in here, we had an error thrown
          puts "delBiofsFile Error: $errmsg"
       } else {
          puts "File deleted"
    
       } ; # end the else on not having an error in the API request
    

    Deleting a directory from the BioCoRE BioFS

    Directories can be deleted from the BioFS. They must be empty to be deleted. So, if you need to, you will need to use other API methods to retrieve current contents and delete contents before the entire directory can be removed.
       package require biocore 1.15
    
       puts "Testing biocore_delBiofsDirectory"
    
       puts "Directory id to delete? (must already be empty)"
       gets stdin iId
    
       if [catch [::biocore::delBiofsDirectory $iId ] errmsg] {
          # if we make it in here, we had an error thrown
          puts "delBiofsDirectory Error: $errmsg"
       } else {
          puts "Directory deleted"
    
       } ; # end the else on not having an error in the API request
                                    
    

    Creating a new directory in the BioCoRE BioFS

    To create a new directory in the BioFS you need to know the ID of the directory in which you wish to place the new directory.
       package require biocore 1.15
    
       puts "Testing biocore_createBiofsDirectory"
    
       puts "Directory id where the new directory should go?"
       gets stdin iId
    
       puts "New Directory Name?"
       gets stdin strNewName
    
       if [catch [::biocore::createBiofsDirectory $iId $strNewName] errmsg] {
          # if we make it in here, we had an error thrown
          puts "createBiofsDirectory Error: $errmsg"
       } else {
          puts "New directory created"
    
       } ; # end the else on not having an error in the API request
    

    Getting the list of jobs that the BioCoRE server can run

    BioCoRE job types are identified by a short name. Each job type may use the job parameters in particular ways, or ignore some values. This call returns a list of job type names. These are currently NAMD and Generic
      package require biocore 1.15
      
      puts "Testing biocore_getJobTypes"
      
      if [catch {set jobTypeList [::biocore::getJobTypes ]} errmsg] {
          # if we make it in here, we had an error thrown
          # This shouldn't ever happen
          global errorInfo
          global errorCode
          puts "getJobTypes Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          puts "-------------"
          set i 0
          foreach { name } $jobTypeList {
             set i [ expr $i + 1 ]
             puts "$i:$name"
          }
          puts "-------------"
       }
    

    Get the accounts the user has defined which can run this type of job

    This method will return a list of two-item lists. Each item contains the account id and user-defined name for one of the user's accounts which is able to run a job of the specified job type.
      package require biocore 1.15
      
      puts "Testing biocore_getAccountsForJob"
       
      if [catch {set jobTypeList [::biocore::getAccountsForJob $jobType ]} errmsg] {
         # if we make it in here, we had an error thrown
         # This shouldn't ever happen
         global errorInfo
         global errorCode
         puts "getAccountsForJob Error: <$errmsg> <$errorInfo> <$errorCode>"
      } else {
         puts " Id   Name"
         puts "----  -------"
         foreach { name } $jobTypeList {
            puts "[format %3i [lindex $name 0]]   [lindex $name 1]"
         }
         puts "-------------"
      }
    
    

    Get the available queues for a particular account id

    The getQueuesForAccount method returns the list of account names and descriptions for a particular account id.
       package require biocore 1.15
    
       puts "Testing getQueuesForAccount $account"
       if {[catch {set queueList [::biocore::getQueuesForAccount \
                                                        $account ]} errmsg]} {
          # if we make it in here, we had an error thrown
          # This shouldn't ever happen
          global errorInfo errorCode
          puts "getQueuesForAccount Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
          puts " Name   Desc"
          puts "-----  -------"
          foreach { name } $queueList {
             puts "[lindex $name 0]   [lindex $name 1]"
          }
          puts "-------------"
       }
    }
    

    Run a job

    The BioCoRE server will submit a job specified by the parameters that get passed in.
       package require biocore 1.15
      
       puts "Testing biocore_submitJob"
       
       set jobType "Generic"
       set accountId 12
       set projectId 3
       set jobName "MyJob"
       set jobDesc "The description"
       set workDir "sim1/run1"
       set cmd "~/bin/my_sim"
       set cmdParams "infile1 infile2 outfile1 outfile2"
       set stdoutFile ""
       set stderrFile ""
       set queueName ""
       set projToCharge ""
       set numProcs ""
       set cpuTime ""
       set memory ""
       set inputFileList { "/myproj/file1" "/myproj/file2" }
       set outputFileList { "outfile1" "outfile2" }
    
       if [catch {set result [::biocore::runJob \
                                "$jobType" \
                                "$accountId" \
                                "$projectId" \
                                "$jobName" \
                                "$jobDesc" \
                                "$workDir" \
                                "$cmd" \
                                "$cmdParams" \
                                "$stdoutFile" \
                                "$stderrFile" \
                                "$queueName" \
                                "$projToCharge" \
                                "$numProcs" \
                                "$cpuTime" \
                                "$memory" \
                                "$inputFileList" \
                                "$outputFileList" ] } errmsg] {
          # if we make it in here, we had an error thrown
          global errorInfo
          global errorCode
          puts "submitJob Error: <$errmsg> <$errorInfo> <$errorCode>"
       } else {
         puts "Job id is $result"
       }
    
       
    

    Get the status of a BioCoRE job

    The getJobStatus method returns the status of a job running in BioCoRE
       package require biocore 1.15
    
       # check the job status 10 times, then return. The return codes are
       # listed in the java code in collab.jobManagement.Job.java, but
       # the important ones are SUBMITTED=2, RUNNING=3, RETRIEVING=10
       # COMPLETE=4, KILLED=5
       set done 0
       for {set i 0} { $i<10 && $done==0 } {incr i} {
          if {[catch {set status [::biocore::getJobStatus $jobid] } errmsg ]} {
             # if we make it in here, we had an error thrown
             global errorInfo errorCode
             puts "submitJob Error: <$errmsg> <$errorInfo> <$errorCode>"
             break
          } 
          puts "Job status is $status"
          after 5000
       }
    

    Logging a user out of BioCoRE

    The biocore logout method can be used to log a user out of BioCoRE. Note that this will completely log a user out. If the user has other Control Panels, etc., running they will be closed.
       package require biocore 1.15
    
       puts "Testing biocore_logout"
    
       if [catch {set i [::biocore::logout ]} errmsg] {
          # if we make it in here, we had an error thrown
          # This shouldn't ever happen
          puts "Error: $errmsg"
       } else {
          puts "User logged out."
       }
    

    Feedback

    The BioCoRE team welcomes any comments, questions, or suggestions that you might have concerning our software! Please email us or fill out our feedback form.