Vely logo Empower C
install  tutorials  examples
documentation  license  about

12.1.0 released on Sep 19, 2022

tutorial-utility



DESCRIPTION:



What you'll learn


You'll learn how to:

Temperature-measuring device


In this example, a temperature measuring device will periodically insert temperatures into a SQLite 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.

Prerequisites


To run the example, you need to install SQLite database.

Next, install Vely - it's simple by using standard packaging tools such as apt, dnf, pacman, zypper.

It is a good idea to create a separate source code directory for each application (and you can name it whatever you like):
mkdir util
cd util


Create the application


To create the application named 'util':
sudo vf -i -u $(whoami) util

This will create the application home directory at

/var/lib/vv/util/app

and that's where we will create the SQLite database.

Setup SQLite database


The SQLite database will be in the application home directory above, and will be named "util.db". Create it:
sqlite3 /var/lib/vv/util/app/util.db

and then create the table used in this tutorial:
create table temps (temp integer, timest text primary key);

Press Ctrl-D to leave the sqlite3 shell. In this case, there is a "temp" column (temperature reading) and "timest" (time stamp of the reading). Table name is "temps" (temperatures).

In order for Vely application to use this database, a database_config_file must be created. The name of this file will be used in Vely code, and here its name will be "utl":
vi utl

For SQLite, this file holds the above file location of the database, so copy this and save:

/var/lib/vv/util/app/util.db

Given database configuration file name is "utl", its usage in run-query statement would be like this:
run-query @utl = ...

Note "@utl", meaning this particular query will take place in the database specified with the file "utl".

Write the code


First off, to get syntax_highlighting for Vely code (if you are using vim):
vv -m

Create file temphist.v:
vi temphist.v

and copy and paste this:
#include "vely.h"

void temphist() {
    out-header default

    input-param action

    if (!strcmp (action, "record")) {
        input-param temp
        run-query @utl = "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 @utl = "select temp, timest from temps order by timest" output temp, timest
            @Date: <<query-result  timest>>
            @Temperature: <<query-result  temp>>
        end-query
    }
}


Make the application


To make the application:
vv -q --db=sqlite:utl util

"-q" means to make the application, and "--db" option denotes that file "utl" is a configuration file for a SQLite database. The name of the application is "util".

Run it


You can run any Vely application both from the command-line and web browser (see other tutorials for that), but here it's all about a command line interface (CLI).

To add a record to the database, for example to record a temperature reading of 91F, run this from command line:
VV_SILENT_HEADER=yes REQUEST_METHOD=GET QUERY_STRING="req=temphist&action=record&temp=91" /var/lib/vv/bld/util/util

That results in:

Vely

To view the current database in chronological order:
VV_SILENT_HEADER=yes REQUEST_METHOD=GET QUERY_STRING="req=temphist&action=list" /var/lib/vv/bld/util/util

That results in:

Vely


Discussion


This application will record temperatures, as well as list them. The source code in "temphist.v" 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 historical order.

Notice use of run-query to insert or select data from tables. Another statement commonly used is the input-param:
input-param action

It means this: if there is an input parameter named "action", simply put its value into variable "action"; if there isn't one, then the variable will hold an empty string. In Vely, input parameters and the variables that hold them always have the same name; this makes following code easier.

How would this input parameter be provided in the command line? Your program's input parameters are given on the command line by specifying the URL query. This is nice, because then you can use the exact same URL to call your program from the web! It makes testing a breeze.

Note "action=record" in the URL that records temperature, with "temp=91" specifying the actual value in degrees:
VV_SILENT_HEADER=yes REQUEST_METHOD=GET QUERY_STRING="req=temphist&action=record&temp=91" /var/lib/vv/bld/util/util

So what is in this command line? Here is the breakdown.

The URL is passed to the utility via environment variables. The actual program invoked is:

/var/lib/vv/bld/util/util

and the environment variables are:
VV_SILENT_HEADER=yes REQUEST_METHOD=GET QUERY_STRING="req=temphist&action=record&temp=91"

Here, three such variables are set.

That's it! You can have any number of input parameters. Note that the values must be suitable for a URL, and that means URL encoding when necessary. In this example, that wasn't necessary, but here's how you can do it:
VV_SILENT_HEADER=yes REQUEST_METHOD=GET QUERY_STRING="req=temphist&action=record&temp=$($(vv -l)/v1 -urlencode '91')"

Note this code:
$(vv -l)/v1 -urlencode '91'

The output of $(vv -l) is the location of Vely's library directory. In it, there is v1 program, which is Vely's internal core tool - it's main purpose is to process Vely code and generate C from it. It can also convert data to URL-encoded and web-encoded string (use -webencode for that).

Here, it will convert string "91", which in this case is also "91". You'd need to URL-encode when your input data has characters like space, "&" or "=" for instance.

SEE ALSO:


Tutorials ( tutorial-file_manager   tutorial-hello_world   tutorial-multitenant_cloud   tutorials   tutorial-stock_app   tutorial-utility  )  SEE ALL (documentation)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Icons copyright PaweĊ‚ Kuna licensed under MIT. This web page is licensed under CC-BY-SA-4.0.