Beginning with CWMS/HEC-RTS 3.4, the CWMSjy scripting API supports both read and write operations, replacing the legacy DBAPI.py.

This guide walks you through updating your script to use CWMSjy.

Scripts run from within HEC-RTS/CAVI or CWMS-Vue can reuse the CWMS Data API (CDA) login you are already using, so you usually do not need to put a CDA URL or office ID in the script. See Step 3 for when those arguments are required.

Step 1: Open Your Script

  1. Identify the script you need to edit and open it in your script editor.

Step 2: Remove Old DBI Connection Lines

  1. Locate the lines where the script connects to the database using cwms.dbi. You'll typically see something like this: 
    cwms.dbi.ConnectUsingUrl=jdbc:oracle:thin:@
    cwms.dbi.OfficeId=
    CODE
  2. Comment out or delete these lines (lines 8-9 in the example below).

    Original Code with DBAPI.py

    #----------------#
    DBI properties #
    #----------------#
    ###
    Database connection specs
    
    ###
    #cwms.dbi.ConnectUsingUrl=jdbc:oracle:thin:@XXX.XX.XXX.XX:XXXX/G6CWMSP1
    #cwms.dbi.OfficeId=NWDM
    from hec.heclib.dss import HecDss, DSSPathname
    from javax.swing import JOptionPane
    from hec.dataTable import HecDataTableToExcel
    from hec.heclib.util import HecTime
    from hec.script import Plot
    #from cwms import cwms
    #from hec.cwms import CWMSjy
    import time, thread, wcds, java, javax, os, operator, hec, traceback, string, RADARAPI, CWMSjy, DBAPI, sys
    
    #######################
    Get Database Connection ##
    
    #######################
    db = DBAPI.open()
    db.setTimeZone('UTC')
    
    ############################################
    CODE

Step 3: Replace the DBAPI.open( ) Call

  1. Look for this line:
    db = DBAPI.open()
    CODE
  2. Comment it out or delete it and replace it with one of these forms, depending on where the script runs:

    Already logged into CDA in HEC-RTS/CAVI or CWMS-Vue

    db = CWMSjy.open()
    CODE

    Not logged in, or running from DSSVue

    db = CWMSjy.open("CWBI TEST OR YOUR OFFICE CDA INSTANCE URL", "YOUR OFFICE")
    CODE
  3. Calling CWMSjy.open() with no arguments reuses the credentials and current login from CWMS-Vue or HEC-RTS, so the CDA URL and office ID are not needed. Supply the URL and office ID only when the script has no existing login to reuse, such as when it runs from DSSVue or before you log in; CWMSjy then prompts you to log in to the CDA instance you named.

    Requires CWMS/HEC-RTS 3.6 or later

    In CWMS/HEC-RTS 3.4 and 3.5 the no-argument form does not connect to the watershed database the CAVI or CWMS-Vue is logged into (CWMS-2399). On those versions, keep using CWMSjy.open(url, office).

  4. Your updated code should look something like this:

    New Code with CWMSJy

    #----------------#
    DBI properties #
    
    #----------------#
    
    ###
    Database connection specs
    
    ###
    #cwms.dbi.ConnectUsingUrl=jdbc:oracle:thin:@XXX.XX.XXX.XX:XXXX/G6CWMSP1
    #cwms.dbi.OfficeId=NWDM
    from hec.heclib.dss import HecDss, DSSPathname
    from javax.swing import JOptionPane
    from hec.dataTable import HecDataTableToExcel
    from hec.heclib.util import HecTime
    from hec.script import Plot
    import time, thread, wcds, java, javax, os, operator, hec, traceback, string, RADARAPI, CWMSjy, DBAPI, sys
    
    #######################
    Get Database Connection ##
    
    #######################
    #db = DBAPI.open()
    # Logged into CDA via CWMS-Vue or HEC-RTS? Reuse that login:
    db = CWMSjy.open()
    # Running from DSSVue or not logged in? Supply the CDA URL and office:
    #db = CWMSjy.open("https://cwms-data-test.cwbi.us/cwms-data/", "MVS")
    db.setTimeZone('UTC')
    
    ############################################
    CODE

Step 4: Save and Run Your Script

After making these changes, save your script and run it to verify successful connection and operation using CWMSjy.