2. Starting the Web Service and Help Screen

On starting the Web service with the hammerdbws command HammerDB will return a hammerws prompt and also listen on the specified port for HTTP requests. Navigating to the prompt returns the home page.

Figure 10.1. Web Service Home Page

Web Service Home Page


The help command at the CLI prompt shows the available commands.

HammerDB Web Service v4.3
Copyright (C) 2003-2021 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
Initialized new SQLite on-disk database C:/Users/Steve/AppData/Local/Temp/hammer.DB
Starting HammerDB Web Service on port 8080
Listening for HTTP requests on TCP port 8080
hammerws>help
HammerDB v4.3 WS Help Index

Type "help command" for more details on specific commands below

        buildschema
        clearscript
        customscript
        datagenrun
        dbset
        dgset
        diset
        jobs
        librarycheck
        loadscript
        print
        quit
        runtimer
        tcset
        tcstart
        tcstatus
        tcstop
        vucomplete
        vucreate
        vudestroy
        vurun
        vuset
        vustatus
        waittocomplete

hammerws>

hammerws supports all commands supported by the CLI except for the remote modes commands of switchmode and steprun at release v4.3. Clicking on the Web Service API link returns the underlying interface. The Web Service can be interacted with either through the CLI commands or directly over HTTP. As noted when using the CLI it will automatically translate the command and call the local HTTP interface for you with the API as shown.

HammerDB Web Service
HammerDB API
GET db: Show the configured database.
get http://localhost:8080/print?db / get http://localhost:8080/db

GET bm: Show the configured benchmark.
get http://localhost:8080/print?bm / get http://localhost:8080/bm
{"benchmark": "TPC-C"}

GET dict: Show the dictionary for the current database ie all active variables.
get http://localhost:8080/print?dict /  http://localhost:8080/dict

GET script: Show the loaded script.
get http://localhost:8080/print?script / http://localhost:8080/script

GET vuconf: Show the virtual user configuration.
get http://localhost:8080/print?vuconf / http://localhost:8080/vuconf

GET vucreate: Create the virtual users. Equivalent to the Virtual User Create option in the graphical interface. Use vucreated to see the number created, vustatus to see the status and vucomplete to see whether all active virtual users have finished the workload. A script must be loaded before virtual users can be created.
get http://localhost:8080/vucreate
 
GET vucreated: Show the number of virtual users created.
get http://localhost:8080/print?vucreated / get http://localhost:8080/vucreated

GET vustatus: Show the status of virtual users, status will be "WAIT IDLE" for virtual users that are created but not running a workload,"RUNNING" for virtual users that are running a workload, "FINISH SUCCESS" for virtual users that completed successfully or "FINISH FAILED" for virtual users that encountered an error.
get http://localhost:8080/print?vustatus / get http://localhost:8080/vustatus

GET datagen: Show the datagen configuration
get http://localhost:8080/print?datagen /  get http://localhost:8080/datagen

GET vucomplete: Show if virtual users have completed. returns "true" or "false" depending on whether all virtual users that started a workload have completed regardless of whether the status was "FINISH SUCCESS" or "FINISH FAILED".
get http://localhost:8080/vucomplete

GET vudestroy: Destroy the virtual users. Equivalent to the Destroy Virtual Users button in the graphical interface that replaces the Create Virtual Users button after virtual user creation.
get http://localhost:8080/vudestroy

GET loadscript: Load the script for the database and benchmark set with dbset and the dictionary variables set with diset. Use print?script to see the script that is loaded. Equivalent to loading a Driver Script in the Script Editor window in the graphical interface. Driver script must be set to timed for the script to be loaded. Test scripts should be run in the GUI environment.  
get http://localhost:8080/loadscript

GET clearscript: Clears the script. Equivalent to the "Clear the Screen" button in the graphical interface.
get http://localhost:8080/clearscript

GET vurun: Send the loaded script to the created virtual users for execution. Equivalent to the Run command in the graphical interface. Creates a job id associated with all output. 
get http://localhost:8080/vurun

GET buildschema: Runs the schema build for the database and benchmark selected with dbset and variables selected with diset. Equivalent to the Build command in the graphical interface. Creates a job id associated with all output. 
get http://localhost:8080/buildschema

GET jobs: Show the job ids, configuration, output, status, results and timings of jobs created by buildschema and vurun. Job output is equivalent to the output viewed in the graphical interface or command line.
get http://localhost:8080/jobs
get http://localhost:8080/jobs?jobid=TEXT
get http://localhost:8080/jobs?jobid=TEXT&bm
get http://localhost:8080/jobs?jobid=TEXT&db
get http://localhost:8080/jobs?jobid=TEXT&delete
get http://localhost:8080/jobs?jobid=TEXT&dict
get http://localhost:8080/jobs?jobid=TEXT&result
get http://localhost:8080/jobs?jobid=TEXT&status
get http://localhost:8080/jobs?jobid=TEXT&tcount
get http://localhost:8080/jobs?jobid=TEXT&timestamp
get http://localhost:8080/jobs?jobid=TEXT&timing
get http://localhost:8080/jobs?jobid=TEXT&timing&vuid=INTEGER
get http://localhost:8080/jobs?jobid=TEXT&vu=INTEGER

GET librarycheck: Attempts to load the vendor provided 3rd party library for all databases and reports whether the attempt was successful.
get http://localhost:8080/librarycheck

GET tcstart: Starts the Transaction Counter. 
get http://localhost:8080/tcstart

GET tcstop: Stops the Transaction Counter. 
get http://localhost:8080/tcstop

GET tcstatus: Checks the status of the Transaction Counter. 
get http://localhost:8080/tcstatus

GET quit: Terminates the webservice and reports message to the console.
get http://localhost:8080/quit

POST dbset: Usage: dbset [db|bm] value. Sets the database (db) or benchmark (bm). Equivalent to the Benchmark Menu in the graphical interface. Database value is set by the database prefix in the XML configuration.
post http://localhost:8080/dbset { "db": "ora" }

POST diset: Usage: diset dict key value. Set the dictionary variables for the current database. Equivalent to the Schema Build and Driver Options windows in the graphical interface. Use print?dict to see what these variables are and diset to change.
post http://localhost:8080/diset { "dict": "tpcc", "key": "duration", "value": "1" }

POST vuset: Usage: vuset [vu|delay|repeat|iterations|showoutput|logtotemp|unique|nobuff|timestamps]. Configure the virtual user options. Equivalent to the Virtual User Options window in the graphical interface.
post http://localhost:8080/vuset { "vu": "4" }

POST tcset: Usage: tcset [refreshrate] 
post http://localhost:8080/tcset { "refreshrate": "20" }

POST dgset: Usage: dgset [vu|ware|directory]. Set the Datagen options. Equivalent to the Datagen Options dialog in the graphical interface.
post http://localhost:8080/dgset { "directory": "/home/oracle" }

POST customscript: Load an external script. Equivalent to the "Open Existing File" button in the graphical interface. Script must be converted to JSON format before post.
post http://localhost:8080/customscript { "script": "customscript"}