Example: utility

In this example, a temperature measuring device will periodically insert temperatures into a database table, along with a timestamp. The purpose is to read this history and output the result from time to time, which can then be piped or sent elsewhere.

In a nutshell: 2 source files, 26 lines of code; SQLite; command line; Unix sockets;

Screenshots of application

Adding a record to the database, for example to record a temperature reading of 91F:

To view the current database in chronological order:

Setup prerequisites

Install Vely - you can use standard packaging tools such as apt, dnf, pacman or zypper.

Because they are used in this example, you will need to install Nginx as a web server and SQLite as a database.

After installing Vely, turn on syntax highlighting in vim if you're using it:

vv -m

Get the source code

The source code is a part of Vely installation. It is a good idea to create a separate source code directory for each application (and you can name it whatever you like). In this case, unpacking the source code will do that for you:

tar xvf $(vv -o)/examples/utility.tar.gz
cd utility

Setup application

The very first step is to create an application. The application will be named "utility", but you can name it anything (if you do that, change it everywhere). It's simple to do with vf:

sudo vf -i -u $(whoami) utility

This will create a new application home (which is "/var/lib/vv/utility") and do the application setup for you. Mostly that means create various subdirectories in the home folder, and assign them privileges. In this case only current user (or the result of "whoami" Linux command) will own those directories with 0700 privileges; it means a secure setup.

Setup the database

Before any coding, you need some place to store the information used by the application. First, create SQLite database "db_utility". You can change the database name, but remember to change it everywhere here. And then, create database objects in the database.

Execute the following to create database "utility.db" and also setup the database objects needed for the example:

sqlite3 /var/lib/vv/utility/app/utility.db < setup.sql

The SQLite database will be in the application home directory (see how_vely_works):

/var/lib/vv/utility/app

Connect Vely to a database

In order to let Vely know where your database is and how to log into it, you will create database_config_file named "db_utility". This name doesn't have to be "db_utility", rather it can be anything - this is the name used in actual database statements in source code (like run-query), so if you change it, make sure you change it everywhere. Create it:

echo '/var/lib/vv/utility/app/utility.db' > db_utility

The above in general is a location of SQLite database and is all that's needed to connect to it.

Build application

Use vv utility to make the application:

vv -q --db=sqlite:db_utility

Note usage of --db option to specify SQLite database and the database configuration file name.

Run program from command line

Execute the following to run your application from command line (as a command-line utility):

#Record a temperature to 91F
export REQUEST_METHOD=GET
export SCRIPT_NAME='/utility'
export PATH_INFO='/temphist'
export QUERY_STRING='action=record&temp=91'
/var/lib/vv/bld/utility/utility

#List recorded temperatures
export REQUEST_METHOD=GET
export SCRIPT_NAME='/utility'
export PATH_INFO='/temphist'
export QUERY_STRING='action=list'
/var/lib/vv/bld/utility/utility

Note: to suppress output of HTTP headers, add this before running /var/lib/vv/bld/utility/utility program:

export VV_SILENT_HEADER=yes

Files

You are now done with the example! What follows are the source files in this project so you can examine how it works:

Recording temperature readings in a table (setup.sql)

There is a "temp" column (temperature reading) and "timest" (time stamp of the reading). Table name is "temps" (temperatures).

create table temps (temp integer, timest text primary key);

Utility for recording temperatures (temphist.vely)

This application will record temperatures, as well as list them. The source code in "temphist.vely" file is fairly self-explanatory. If input parameter "action" is "record", store the temperature into table "temps" and check for any errors. If it is "list", just display all the temperature records in a historical order.

// SPDX-License-Identifier: EPL-2.0
// Copyright 2018 DaSoftver LLC.
#include "vely.h"

void temphist() {
    out-header default

    input-param action

    if (!strcmp (action, "record")) {
        input-param temp
        run-query @db_utility = "insert into temps (temp, timest) values ('%s', current_timestamp)" : temp affected-rows define rc error-text define er no-loop
        if (rc != 1) {
            @Could not insert temperature reading, error <<p-out er>>.
        } else {
            @Temperature reading stored.
        }
    }

    else if (!strcmp (action, "list")) {
        run-query @db_utility = "select temp, timest from temps order by timest" output temp, timest
            @Date: <<query-result  timest>>
            @Temperature: <<query-result  temp>>
        end-query
    }
}