Cloudgizer

Cloudgizer is a free open source tool for building web applications as Apache modules, with emphasis on performance, small-footprint, and more productive and safer programming in C. It combines the ease of scripting with the power of C, improving the resource utilization for cloud applications.

Cloudgizer is licensed under Apache 2 License.

Current stable version is 1.2 (as tagged in git repository).

This site has been last updated on Sun Jul 21 12:22:49 MST 2019.

This is the documentation for the latest Cloudgizer code. If you download older tagged versions from the git repository, each comes with 'docs' directory that contains the documentation matching that version.

Read an article introducing Cloudgizer.

To get started now, read the article on how to install Cloudgizer and build your own application quickly.

---

About Cloudgizer
    Example source code - learn by example
    License
    Source code & issues
    Hello world
Basics
    The big picture
    Basic components
    The architecture
    Structure of an application
    Hello World
Download and Installation
    Install Cloudgizer
    Requirements
    Create a Linux user
    Install Cloudgizer
    Create the Example application
    Install the Example application
    Clone the Example application into your own
    Install your application
    Develop your application
        Your code
        GET/POST handler
        Make
        Test
        Tips
    Distribute your application
    Software dependencies
        MariaDB
        Postfix
        SELinux
        Apache
        Other software
    Large example
    Smoke tests
Getting started
    Configuration, database and debug files
        Configuration file
        Database file
        Debug file
    How to write code
        Markup code block
        Markup usage
        Line continuation and whitespaces
        A typical program
        Errors in your program
    CLD utility
Processing of requests
Constructs
    Comments
    Outputting data
        Whitespaces and empty lines
        Semicolon
        Encoding output
        Ignoring markup
        Outputting preprocessor data to a file
        Outputting HTTP header for a typical web page
        Defining, setting and outputting integers
        Outputting data from a command line program
    Embedded C code
    URL input parameters (GET and POST)
    Cookies, setting and getting
    Database queries
        Basic usage of queries
        Database transactions
        Column Length
        When query has no results
        Force query to produce a single empty row
        Current row in a query result set
        Number of rows and columns in a query result set
        Number of affected rows in DML
        Input parameters to queries
        Column names
        Nesting queries
        Using multiple query texts at run-time (conditional queries)
        Dynamic queries
        Dynamic queries when table structure is unknown
        Result-set data array
        Using query results more than once
        Copying query text in multiple places safely (query shards)
        Re-using query text in multiple places (query fragments)
        Loop control in result set
        Error handling in executing queries
        Getting auto_increment value
        NULL and result column data types
    Executing Cloudgizer program from command line
    Executing external programs
    Sending emails
    Loading URL content (calling a web page) programmatically
    Strings
        Defining and copying strings
        Appending string
        Search and replace string
        Constructing complex strings
    Program flow
        Loops
        Conditional statements (if, else...)
    Files
        File storage
        Permissions and ownership
        Uploading files
        Reading a whole file
        Writing a whole file or appending to a file
        Copying a file
    Web address of server
    Error handling in general
    Include files
    Debugging your code
        Tracing and debugging options
        Finding where program crashed
        Enabling debugging information
        Which shared libraries are loaded?
API
    Memory allocation
        Allocation and garbage collection
        Get size of memory allocated for variable
        Check if allocated memory is valid, overwritten or underwritten
    Configuration parameters
    Tracing and debugging
        Write to trace file
        Which trace file is being written to?
        Using custom tag value for debugging
        Linting your HTML code dynamically
    URL input
        URL input parameters
        Is URL referrer from the same site?
        URL string that is being processed
        URL parameters manipulation
    Cookies
        Data type for storing
        Cookies: get, set, delete, find
    Global data
    Encoding and Decoding, URL encoding, Web encoding, Base64 encoding
    Numbers
        Create string from integer
        Check if string is a positive integer or a number
    Execution of external programs, piping from one program to another
    Output data and HTTP header
        Outputting HTTP header, custom HTTP response headers
        Encoding data for output
        Output text without breaks
        Disable and Enable HTML output, status of enablement
        Send files to the client and output HTTP headers for files
        File not found (404)
        Flush output
    Create new database document and a new associated file
    Strings
        Initialize, Copy, Append strings
        Output data to string
        Change case of strings (upper, lower)
        Substrings
        Trim string
        Break down string into an array of strings based on a delimiter
    Clear Unused variable error
    Error reporting
    Encryption and hashing
        Hashing
        Encrypting data
        Decrypting data
        Generating random string
    Storing and retrieving data in a sequential list (FIFO)
    Executing Cloudgizer program from command line (Batch processing)
        Using batch processing
        Exit code for batch processing
    POST URL (web call)
    Files
        File storage
        Get file size
        Copy files
        Read entire file into a string variable
        Write whole file from a string
        Append to file from a string
        Lock a file
        Get application home directory
        Check if directory
        Temporary files
    Send email
    Queries and Transactions
        SELECT from the database
        Get value from auto-increment column
        Execute any SQL other than SELECT, including DDL statements
        Check for open transaction
    Get miscellaneous
        Get web address for forms and links
        Get Base URL of server
        Get version
        Get current, past or future time, including GMT
        Get current time
        Get application name
        Get environment variable (web or command shell)

About Cloudgizer

Cloudgizer is a free open source tool for building web applications as Apache modules in C programming language, licensed under Apache 2 License..

Example source code - learn by example

• The Example Application (also used as a smoke test for Cloudgizer) contains good amount of code used to test basic Cloudgizer functionality - these are small snippets of code demonstrating usage.
  
  Install the Example application.
  
  The Example application is also a starting point for your own applications.
  
  
• As a large-scale example, Rentomy is a business application written entirely with Cloudgizer (about 32,000 lines of code).
  
  Rentomy is a Free Open Source cloud software for Rental Property Managers - check out the documentation.
  
  Install Rentomy now.
  

Browse the source code for both Example application and Rentomy to learn by example, get a feel for developing with Cloudgizer and to understand better the usage patterns of markups and API.

License

Cloudgizer is licensed under Apache License, Version 2.0.

Source code & issues

Source code is available at Cloudgizer git repository.

Older Cloudgizer versions stable enough for download and installation are tagged in git.

Report issues or questions - email admin@dasoftver.org.

Hello world

Here is a program that outputs 'Hello World!' to the browser (and here' a database-enabled one):

Basics

The big picture

Cloudgizer is a tool for building web applications as Apache modules in C language enhanced with simple markup, with emphasis on performance, small-footprint, and more productive and safer programming in C.

The programmer writes simple markup language mixed with C code, which is then translated entirely into C code and compiled natively as Apache module. The resulting application is fast and takes less memory, as there are no interpreters or virtual machines.

Features include easy markups to use MariaDB database, HTML input parameters, cookies, simpler outputting of web pages, files storage and manipulation, encryption, encoding, program execution, web calls, safer and easier string manipulation etc. - the list is too long to place in one sentence. Overall Cloudgizer does a lot of stuff for you that you'd otherwise need to do yourself.

A memory garbage collection system and memory overwrite/underwrite detection comes in handy for program stability. The same goes for string and memory handling markups to help write applications that won't crash.

Also included is an application packaging system and an automated application installer. This makes rollout of products and release cycle more manageable.

Cloudgizer source files have extension .v.

Cloudgizer pre-compiler (cld program) will turn your .v files into .c files, ready for compilation as pure C programs.

Then, your program will be compiled and linked with Apache web server on RH/Centos systems. It links with Apache as an Apache module in a "prefork" configuration. It does the work of communicating with Apache, and it makes it easier to write high-performance/small-footprint web programs in C.

Cloudgizer is not designed to be thread-safe as it works in a "prefork" configuration of Apache.

You can also build command-line programs. The same program can serve as both command-line utility and a web program linked with Apache.

Cloudgizer works with RedHat/Centos 7 operating system, Apache web server and mariaDB database.

Basic components

Below are the files installed.

These are the internal files used by Cloudgizer:

• cld.h: include file for Cloudgizer programs.
  
  
• libacld, libcld: shared libraries that implement Cloudgizer features.
  
  
• cldmakefile: common Makefile used for all Cloudgizer programs - do not invoke this file with make utility.
  
  
• cldwhichis: common script to determine which platform you're running.
  
  

These are the utilities you'll use as you develop applications:

• cld command line utility. Once installed, just type cld to get help for it. cld will turn the Cloudgizer code into C code you can view, and that is ready for compilation and linking.
  
  
• cldbuild script that will compile and link your program.
  
  
• cldpackapp script that will create installation file for your application.
  
  
• cldgoapp script that will install your application.
  

All scripts, the makefile and the command line utility are located in /usr/bin directory. Include file is in /usr/local/include/cld directory. Libraries are in /usr/local/lib/cld directory.

The architecture

Apache server is the container which holds your Cloudgizer applications as Apache modules. The module mechanism allows for fast response times and very little overhead.

Apache server can house many Cloudgizer applications, each being a separate Apache module. These separate modules are generally entirely different applications.

Apache handles the infrastructure part while your Cloudgizer code makes up the applications themselves.

All Cloudgizer applications are hosted under a single Linux user, with each application within its own subdirectory under the user's home directory. The Apache server user is set to this Linux user during the application installation - it is the currently logged-on user during installation. Make sure to install all applications under the same Linux user. Set the Apache's DocumentRoot to be accessible by this user.

Each Cloudgizer application has its own database schema within a MariaDB database server.

Structure of an application

Each application is installed in its own directory, known as the application home directory. If application name (given by CLD_APP_NAME in appinfo file during installation) is 'your_app_name', then application home directory is /home/user/your_app_name.

The following are important files your project must have - they all have default implementation in the Example Application:

• cld_handle_request.v is a file that implements cld_handle_request function. This is the function called from the framework whenever there is a web request, or a command-line execution. The function doesn't return a value and has no parameters.
  The implementation typically calls whatever handler you want to process the incoming request based on some input parameter. In the Example application we use 'page' input parameter in the URL. Typically an input parameter named 'page' signifies the request, and a given function is called to handle the request - a function that you implement.
  
  
• file_too_large.v file contains implementation for what happens if uploaded file is too large.
  
  
• oops.v file contains implementation for what happens when your program errors-out (i.e. when you call report-error) or when it crashes. The framework will call this function most of the times (sometimes the crash is too severe and it won't be called). By default, this will show a 'Oops' screen and it will email the details of the crash (including the stack) to the email address in the config file.
  
  
• cldbuild will make your application. It uses sourcelist file to do that. sourcelist is provided so you can add your source files easily. Suppose you want to add a new handler for whatever functionality:
  
  • Add your_file.o to SOURCE_FILES list
    
    
  • Below SOURCE_FILES, add line:
    
    your_file.o: your_file.v $(CLDINCLUDE)/cld.h $(HEADER_FILES)
    
  
  That's it. If you add an include file, add it to the list in HEADER_FILES variable (all in sourcelist).

In short, you must have the following implemented for an application to work:

• cld_handle_request function which is called on every request and which routes requests to any number of your functions, each handling a different request, based on input parameters.
  
  
• file_too_large and oops functions which handle what happens when uploaded file is too large or when an error or crash happens. You can keep default implementations.
  

The rest is you implementing the handler functions for different kinds of requests. To get started without writing everything from scratch, you should take the Example application and change it into your own.

Hello World

This is the Hello World example that is included in the Example application. It reads data from the database and displays it in the browser. It exemplifies the coding style of Cloudgizer, which is C code with markup. Markup code is enclosed in /*< and >*/ tags:

Download and Installation

You need RedHat/Centos 7 on a dedicated server or a VPS (virtual private server) and Internet connectivity.

You'll first get the source code from git repository, then install from source. The benefit of source distribution like this is that you will get the highest possible performance by compiling on your specific hardware.

Install Cloudgizer

Requirements

To install Cloudgizer you'll need at least a minimal installation of RedHat/CentOS version 7 Linux operating system and an internet connection.

Other software is installed and configured, such as MariaDB database, Apache web server and Postfix mail transfer agent. Read an overview.

Create a Linux user

Create cld user to host Cloudgizer applications. Login as root before proceeding:


Create a cld user and set password:


When prompted, enter your password twice.

Add sudo capability to this user:


In order to get the source code for Cloudgizer, install git:

Install Cloudgizer

Login as cld user:


Get source code into a new directory. You must know the version you want (see main web page for the latest). For example  to get version 1.2, specify it (to see the list of available versions, use git tag):


Do not use current main line (meaning git clone without --branch) because it's the development version and is not stable.

Next setup the environment and dependencies.

The MariaDB database setup utility will first setup root database password. In here root_pwd is used - use your own password instead. Press Enter to other questions. Note that MariaDB setup may change so the answers may vary.

For Postfix setup, enter web domain of your server (for example myserver.com or localdomain) and web address (for example dev.myserver.com or localhost.localdomain). This sets up capability to send emails using TLS encryption.


Install the Cloudgizer installer:


Cloudgizer is now installed.

To test the installation, type:


You should see Cloudgizer help page. The documentation is in docs/index.html file.

In order to get started with your own application, you must install the Example application.

Create the Example application

Login as cld user and get the source code for the Example application. You need to know which version you're getting, and it needs to match the Cloudgizer version. For example to get version 1.2, specify it (to see a list of available versions, use git tag):


Don't use the current version in git repository (i.e. do not use git clone without --branch) as that is unstable development code.

Create database objects. We will assume root mariaDB password is root_pwd - substitute for your root password:


Execute this in mariaDB shell - we will assume newly created user will have password pwd - substitute for your desired password:


Edit .db file (for example vi .db) to have only the four lines in it:


Set proper permissions on this file:


Create the Example application installation file:


This will create file example.tar.gz in the home directory which you can use to install the example application on any machine that has Cloudgizer installed - see the following.

Install the Example application

First unpack the example.tar.gz file (see above on how to create it):


Edit file appinfo. Assuming your email address is youremail@somewhere.com, your server name is yourserver.com, root database password is root_pwd, and the password for new database to be created is example_pwd, set these variables:


Install the Example application:


At the end of installation try the URLs shown to validate the installation. In general, the URL's path is always go.your_app_name, where your_app_name is the application name, in this case 'example'. Application name is always the value of CLD_APP_NAME in appinfo file.

Any application errors are emailed to CLD_EMAIL email address.

If you want to re-install, you must edit appinfo and supply the passwords again.

The Example application serves as an example and a smoke test for Cloudgizer.

To create your own application, you'll clone the Example application. You can clone any existing application (including the Example) by simply changing its name and then creating an installation file.  

Clone the Example application into your own

You will create a new application named myapp. Go to the Example application's source code:


Edit appinfo file to change the application name:


Create a new installation file and copy it to home directory:


You have created the installation file and now you'll install it in order to clone the Example application.

Once installed, it will be a separate application as it will have its own directory, database and Apache handler.

Install your application

To install the application from the installation file created, first unpack it:


Edit appinfo file to set the root database password (root_pwd) and assuming the password for the new database myapp is myapp_pwd:


If you're installing on a different server, change CLD_SERVER appropriately and if application email address is different, change CLD_EMAIL too.

Install your application:


You have created a new application under ~/myapp directory. Now you can run it and develop it any way you want.

If you are delivering a new version of your application:


This will only update the code (and files and database objects if you specify this in update.sh).

Application is always deployed from binaries. If you distribute source code, then the end-user can recompile the source code by using cldbuild script.

Any appinfo variable that has PWD in the name will be cleared upon installation for security reasons.

Develop your application

Your code

You'll add your own code here as an example of writing with Cloudgizer. Go to the source code:


Add your own code by creating new file mycode.v with the following content:


Add the declaration for the above function mycode(). Edit common.h file:

GET/POST handler

Add your code to the request handler. In this case when URL has page=myrequest, your code will run.

Edit cld_handle_request.v file:

Make

Add your new file to sourcelist. Edit sourcelist file and change/add the following lines as indicated:

To make your code:

Test

To test it in the browser, enter this URL and replace myserver.com with your server name:

Tips

If you change database tables or want to recompile all Cloudgizer source files, use cldbuild clean to touch all source code files and then cldbuild to rebuild them:


You can remove the example code such as home.v and test_cld.v (generally it's the code that's called from the initial cld_handle_request.v) by editing the same files above.

Take a look also at create.sql (where create statements for database objects must be listed) and create.sh (where you'd setup anything that Cloudgizer doesn't already do, such as create the database objects your application needs).

Most of the time you'd change your source files only (such as .v files). From time to time you'd make more structural changes. For example, when changing the database tables or adding or removing files (such as CSS, images, cron jobs) etc., make sure your create.sh (and update.sh for upgrades) reflect those changes.

Most of the stuff done during installation is the same for any application. The application-specific part of installation is done through create.sh file. This is a script you provide in which you can setup anything that installation process can't do, for example you can create database tables or any other custom setup your application needs. If the application is being updated (as opposed to created for the very first time), you would create update.sh file instead and write your application-specific code there. You can use CLD_APP_INSTALL_DIR in these shell scripts to locate files in the installation.

appinfo file is a configuration file for the installation. It always has these variables: CLD_SERVER, CLD_APP_NAME, CLD_EMAIL, CLD_DB_ROOT_PWD and CLD_DB_APP_PWD - these variables are set by the customer during installation. Your responsibility is to set the following variables in appinfo:

• CLD_APP_FILES: the list of files you want to package. This could be anything: images, CSS stylesheets etc. If you distribute source code, this is where you put the list of source files too. Do not state again any files that are already in CLD_REQUIRED_FILES - these are files that installation must have to work anyways. Two of the required files are mod.c and app.c - never modify these files!


• CLD_APP_NAME: the application name. Each application is housed in its own application home directory with this name under user's home directory.


• Any other variables you'd need to install the application. These would be used in create.sh and/or update.sh.

Distribute your application

To create installation file for distribution use cldpackapp. This installation file can be deployed anywhere, such as a QA box or to production.

If you want to distribute the source code, edit appinfo file to add the new source file (in this case mycode.v), otherwise skip this step:


Create the installer:


The appinfo file is the configuration file for the installation process, and it should contain any variables your installation needs. Do not write appinfo from scratch - always start from the file provided in the Example application and build on it.

This will create file myapp.tar.gz you can deploy anywhere, the same way as explained in Install your application.

Software dependencies

MariaDB

MariaDB database and MariaDB LGPL client library will be installed. my.cnf file is configured for better performance.

Postfix

Postfix is installed to replace existing sendmail. It is configured to send email, including generating a TLS (Transport Layer Security) key for encryption.

Note however that email delivery depends on factors outside of your server.

For example, your server should have a reverse DNS (Domain Name System) record and an SPF (Sender Policy Framework) record. You can typically set these through your name registrar and server/VPS (Virtual Private Server) providers' online tools.

Email providers don't accept mail from local computers, such as a home computer. You can still send emails to local Linux users for development and testing purposes.

SELinux

SELinux mode is set to permissive; if you need it you can set policies yourself. Many VPS boxes, dedicated servers or cloud instances have it set to permissive by default.

Apache

Apache web server will be setup with firewalld configured.

The default Apache user is set to the Cloudgizer user, in this case cld user.

So User and Group in /etc/httpd/conf/httpd.conf file will be:


All Cloudgizer applications have Apache module handler names starting with cld_handler_:


When application is removed, remove it's AddHandler.

Any existing web content should be under the home directory of Apache user, which is now cld, so for example your DocumentRoot might be:

Other software

The setup will also install other necessary software, such as gcc C compiler, OpenSSL libraries etc.

Large example

Take a look at Rentomy. In the Download and Installation section you'll see the same deployment process as described here.

All Cloudgizer applications follow the same process.

Rentomy also has additional installation variables, backup system, application updates, background jobs etc. It's a large business application - look at the source code and especially appinfo, create.sql, create.sh files to learn more.

Smoke tests

A battery of tests designed to shake out any obvious issues is incorporated in the Example application. Install it and run as prescribed - all tests run and display results in web browser. Typically each test will show OKAY if succeeded, or otherwise describe what is the desired outcome.

Getting started

Configuration, database and debug files

These files direct Cloudgizer in some important aspects. Note that these are setup by cldgoapp script based on your appinfo file. cldgoapp script installs a Cloudgizer application. Your own create.sh script (a customizable part of installation) can further change these files.

Configuration file

A configuration file (named config) in the application home directory typically has something similar to this
version determines the application version. Typically it is used in constructed URL to force refreshment of cached files, but it can be used for any other versioning purpose.
web_address contains the server address where the application runs on, and is a base URL for Cloudgizer requests. You can use http:// or https://.
email_address is the email where status emails would be sent (for example in case of a program crash) and it can be used for any other emailing purpose by the application.
application_name is the name of application - it can be any name that is 16 bytes or smaller, composed of alphanumeric characters and  underscore, cannot start with a digit and cannot be 'deploy'.
max_upload_size is the maximum size of an upload file - uploading larger file will invoke predefined  file_too_large function, implemented by you.
mariadb_socket is the database identification, a means to connect to the database.
ignore_mismatch is by default "no", meaning that if shared library used to build application doesn't match what's installed on deployment server, stop the program. If "yes", skip this check and proceed. Use "yes" with caution and only if you know why you're doing it.

You can also define user parameters, which are always precedeed by _ (an underscore).

You can use all of these parameters in your code, see configuration parameters API.
If you need to use a Cloudgizer application home directory (for example in a user parameter), use tilde (~) sign, for example:

Database file

.db file is located in the application's home directory and it contains database login information. By default its permissions are set to 600 - do not change this. It has these four lines:

Debug file

A debug file (named debug in trace directory) determines the application behavior with respect to debugging. Take a look at debug file options for more details.

How to write code

Markup code block

Markup code block is written between /*< and >*/. It is a comment technically, but cld utility will parse it and generate C code for it. For example:
In this example, the output of the program (meaning output to web browser) is:

Any free text that's not a markup is output.

---

hello

---

The actual C code generated by Cloudgizer for this will look like:
So you can write the web output by simply writing the HTML code (or any other code, such as Javascript, or anything else that works for you). In this documentation, we'll talk about "HTML code" for simplicity, but when we say "HTML code" it means any kind of web code.

Anything else that is not HTML code, you will use markups such as print-web to output variables, run-query# to run database queries, input-param to get URL GET/POST input parameters etc.

If /*< and >*/ are not feasible, you can use /*CLD_BEGIN and CLD_END*/ as markup boundaries.

The markup beginning (i.e. /*<) must be the beginning of the line and markup ending (i.e. >*/) must be the ending of the line.

Markup usage

The markup (such as print-web) can be used in-between <? and ?> or without them in most cases, but not all. For example:
is just fine on a single line. But if you want to combine it with other output on the same line, as in:
then you must write the markup within <? and ?>. You can also always use these brackets if you prefer - if you are starting with Cloudgizer, it may help you catch errors sooner. Consider if you wrote:
In this case, printa-web is not a valid markup, even though you intended it to be. The output from this will be:

printa-web my_var

i.e. the literal output of what you wrote.  But if you wrote:
you would get an error. One might say that seeing your code in the output is a good enough way to find the error in fix it, but using markup will detect an error earlier - however the code might look a little less verbose.  

Line continuation and whitespaces

To continue a line of code over several lines, use a backslash (\). It can be used anywhere on the line, including in the middle of a string. Example:
is the same as:
Use only spaces as separators in markup code, i.e. do not use tabs and other whitespaces. A line may begin and end with tabs but do not use tabs within markup code itself.

A typical program

Example application provided with installation provides a good starting point. You can take it and grow it into your application, it is meant to be used that way.

Generally, you will get a request via cld_handle_request function. You implement this function (example is provided), and based on some input parameter (typically a page name specified in a URL), you'd call other functions. Most of these other functions would be implemented in their own separate files, thus typically each page would have its own implementation file.

These other functions are conceptually just like Hello World example. They usually query database and do some work for you. They may write files, read files, process data, generate HTML output, show images and documents and anything else you need.

You will notice that you generally shouldn't free the memory you allocate - it will be safely freed at the end of a request. Most of the time you won't need to allocate any memory at all, and that's a good thing. The markups chosen are what's usually needed. If something isn't there, you can use the API provided. If that's not enough, write your own C code for it - you can do just about anything in C.

If you allocate memory on your own always use Cloudgizer memory allocation API such as cld_malloc for example, since all memory allocated this way is automatically released at the end of the request.

Errors in your program

Cloudgizer tries to find as many errors in your program as possible. This also means uncovering some errors that might otherwise find their way into run-time. For example, all your non-dynamic SQL (which hopefully is all the SQL you'd ever use) is checked at run-time with the database, so for example syntax errors and using columns that do not exist are likely to be caught at compile time. Cloudgizer will try to figure out if you forgot to use c markup for the C code within the markup, which can cause code not to execute (and instead display) if you've forgotten it.

The code compiled by C compiler is generated from your original .v file. The error reporting from the C compiler (gcc) will show line numbers from your original code, not the generated code, sparing you the hunt for the actual line in .v file that caused an error. Note that line numbers from your original code have been multiplied by 1,000. This means a line number 351 in your original code will appear as 351000. This is because a single line in your original code can expand to many lines in generated code. So when looking at the generated code, an error at line 351019 means the problem is 19 lines after the line marked with #line 351000. This allows for exact pinpointing of the location where error ocurred.

At run-time, you'll have a number of facilities available for debugging, which is explained here in this documentation. You can learn how to use gdb to debug your program, how to check the validity of your generated XHTML at run-time, how to use tracing etc.

CLD utility

cld utility translates your .v file into .c file which is then compiled and linked with your program. If you type cld at the command line, you will get this help:

   Name
   
   Cloudgizer code generator, markup language and application server API, version [1.2]
   
   Description
   
   Cloudgizer is a tool for building Web applications in C that run as modules on Apache web server on RedHat/Centos. It supports mariaDB database by using LGPL mariaDB client that enables connectivity to mariaDB database. Each application runs under the same Apache web server user, under its own directory (i.e. application's home directory).
   
   Synopsis
   
   cld [<input-file-name.v>] [<command-line-options>]
   
   Options
   
   -help
       Display this help.
   
   -out <output-file-name.c>
       Write generated code to output file <output-file-name.c>. If this option is not used, generated code is written to stdout (standard output).
   
   -main
       Generate main C code. This option cannot be used when <input-file-name.c> is specified, i.e. either C code is generated for input-file-name.c or the main() function C code is generated.
   
   -cmd
       Generate C code for use as a standalone program (a command line program), rather than as an Apache module (Apache Mod) program which is the default. This option can only be used together with -main.
   
   -mariasock <socket-file-location>
       Specify the location of the mariaDB socket file, used by the database server (socket option in my.cnf).
   
   -v
       Print out verbose information about what is being done.
   
   -urlencode <string>
       Prints URL encoded <string>.
   
   -webencode <string>
       Prints web encoded <string>.
   

   COPYRIGHT AND LICENSE
   
   Copyright (c) 2017 Dasoftver LLC (on the web at https://bitbucket.org/dasoftver/cloudgizer).
   Cloudgizer is free Open Source Software licensed under Apache License 2. Cloudgizer is "AS IS" without warranties or guarantees of any kind.

Processing of requests

The cld_handle_request function (the "request processor") is called from generated code to handle incoming requests and it must be implemented. The Example application already has an implementation.

A simple implementation may look like:

The request processor function is called both for web requests (through Apache module mechanism), or for command line program execution. You can use any input parameters to differentiate input requests ('page' is used here as an example only).

Typically file cld_handle_request.v is created to hold the request processor code.

Constructs

The markups are always within /*<  ... >*/ - that's a markup block. They are parsed by cld utility and C code is produced where comment was before. You will see that you can also have pure C code within /*< ... >*/, so while /*< ... >*/ is within a C code already, you can have C code again within it. It's useful because it's easier to write code this way - sometimes you'll need to have small snippets of C code (such as function calls or small blocks of code) to augment your markups.

Comments

There are a few ways to comment your code while in a markup block.

Use either:

• start-comment / end-comment:
  
  start-comment
  This is a comment.
  end-comment
  
  In this case, both start-comment and end-comment must be alone on a line.
  
  
• Line comment:
  
  // This is a comment
  
  The comment must take the entire line.
  

Outputting data

Whitespaces and empty lines

• Whitespaces are not output for programming markups that do not output anything. For example:
  
  <hr/>
  define-string my_str
  <hr/>
  
  will output
  
  <hr/>
  <hr/>
  
  There is no empty line in place of define-string my_str, because this markup does not output anything.
  
  
• However if a line has output in addition:
  
  <hr/>
  <?define-string my_str?>Hi
  <hr/>
  
  or
  
  <hr/>
  <?define-string my_str?><?print-web "Hi\n"?>
  <hr/>
  
  will output
  
  <hr/>
  Hi
  <hr/>
  
  
• The outputting markups do so precisely, i.e. if there is no specific new line, it won't be output:
  
  <hr/>
  <?define-string my_str?><?print-web "Hi"?>
  <hr/>
  
  will output:
  
  <hr/>
  Hi<hr/>
  
  
• Empty lines are not output. This makes it easier to write readable programs. Comment lines are not output, as you'd expect.

Semicolon

If semicolon is the last outputted character on the line, it must be escaped:
This is because any line that ends with semicolon is expected to be C code.

If you have lots of semicolons (for example in Javascript code), you can use start-verbatim/end-verbatim markups, in which case nothing in the output (including semicolon) is interpreted.

Encoding output

You can output data without any encoding, by web encoding or URL encoding:

• No encoding (print-noenc), the data is ready to be output as-is:
  
  define-string my_string="Hello world!<hr/>"
  print-noenc my_string
  
  The output is:
  
  Hello world!

  ---

  
  
• Any data that is free floating, i.e. that is not a part of a command is output as not encoded (print-noenc), for example:
  
  This is the non-encoded output<br/>
  <hr/>
  
  is the same as:
  
  print-noenc "This is the non-encoded output<br/>"
  print-noenc "<hr/>"
  
• Web encoding, the data may contain characters such as < or >:
  
  define-string my_string="Hello <world>!"
  print-web my_string
  <hr/>
  
  The output is:
  
  Hello <world>!
  

  ---

  
  
• URL encoding, the data is used in URL strings, such as links or images:
  
  define-string my_url_data="="
  <a href="https://my_web_site.com/go.your_app_name?param1=<?print-url "&"?>&amp;param2=<?print-url my_url_data?>" >
  
  The output is:
  
  <a href="https://my_web_site.com/go.your_app_name?param1=%26&param2=%3D" >

Ignoring markup

Common outputting of HTML code is just to write it without any markup, as in this code:
will produce:

Hello

---

This is HTML

If your output happens to coincide with a markup, such as for example, if it begins with if, then you could either output with a print-web (for example):
or use w markup, which does nothing, but it positions whatever comes next as not being the first on the line, which precludes it from being interpreted as markup, for example:
resulting in output:

if here won't be treated as if markup

If you have a large segment of text such as JavaScript that you just want to output to web page without worrying about any Cloudgizer markups being interpreted, or about trailing semicolons, use start-verbatim and end-verbatim:
resulting in output:

if here won't be treated as if markup
for here won't be treated as for markup

When start-verbatim is used, anything up to end-verbatim is output as if with print-noenc.

Outputting preprocessor data to a file

Use preprocessor-output# to output data during processing of source code files. For example:
This will write to 'indexes.clo' file the line after the file name, in this case 'employee:name'. Such output can be used to determine what indexes are needed on each table used. In general any information can be added to any file. The purpose is to help with static analysis of code as in aforementioned example.

Outputting HTTP header for a typical web page

Before outputting any text to a web page, HTTP headers need to be sent out:
The header will contain any cookies that are present, meaning that had been received from the client, added and have not been deleted. Because this is the dynamic output from the program, the client is instructed not to cache.

If you want to send custom headers (for instance change content type, caching, status or any other options), you can use custom header API.

Defining, setting and outputting integers

Integers can be used via following markups:
To output an integer:
To output a long:

Outputting data from a command line program

To output to standard output, use:
To output to standard error, use:
These constructs can be used only from a command line program. The syntax of the format and the data output is the same as for C printf() function.

Embedded C code

Use either:

• c markup:
  
  c int x=1;
  
  or
  
• start-c markup:
  
  start-c
  int x = 1;
  x++;
  end-c
  

With c, only one line of C code can be written that accompanies c.
With start-c...end-c, multiple lines of C code can be written. This C code is NOT placed in curly braces.

URL input parameters (GET and POST)

Input parameters from an incoming request are obtained by using input-param:
This will create two string variables par1 and par2 and store input parameters par1 and par2 into them, respectively. For example, if URL that led here was:
then string variable par1 will have value "value1" and par2 will have value "value2", and the output from the above code is:

Input parameter par1 has value value1, and input parameter par2 has value value2

input-param works the same for both GET and POST requests. Input parameters are trimmed for whitespace (both on left and right).

Input parameter name can be made up of alphanumeric characters or underscore only and cannot start with a digit.

Cookies, setting and getting

• Cookies can be obtained from an incoming request by using get-cookie:
  
  define-string my_cookie_value
  
  get-cookie my_cookie_value="my_cookie_name"
  
  or to define the cookie value string within the markup:
  
  get-cookie define my_cookie_value="my_cookie_name"
  
  If an incoming request had a cookie from the browser named "my_cookie_name", then the value of that cookie will be stored in string variable my_cookie_value.
  
  
• To set a cookie that will go with the reply (back to browser), use:
  
  set-cookie "my_cookie_name"=my_cookie_value expires time_of_expiration path "/"
  
  When setting a cookie, you specify cookie name, its value, time of expiration and its path. You must set a cookie before outputting the HTTP header, such as in output-http-header, or otherwise it won't be set.
  
  
• To delete a cookie, so it is sent back in the reply telling the browser to delete it, use delete-cookie:
  
  delete-cookie "my_cookie_name"
  
  This also must be done before outputting the HTTP header, such as in output-http-header, or otherwise it won't be deleted.
  

Use cld_time API function to produce time suitable for cookies.

Database queries

You can SELECT, INSERT, UPDATE or DELETE database table, retrieve results, check for errors. You can not perform any other SQL statements with markups, for example DDL statements - if you want that, use the API.

You can connect to a single database, specified in .db file.

Writing queries, especially when many queries have common text, is supported with additional features such as query fragments and query shards.

Basic usage of queries

• Execute a query:
  
  run-query#my_query="select name, extract(year from dateOfHire) yearOfHire from employee"
  end-query
  
  Note that all query column names must be unique. In this case column names are 'name' and 'yearOfHire'. Duplicate column names will cause a Cloudgizer error.
  
  
• To output results from a query:
  
  run-query#my_query="select name, extract(year from dateOfHire) yearOfHire from employee"
     query-result#my_query, name
     ,
     query-result#my_query, yearOfHire
     <br/>
  end-query
  
  This produces output:
  
  Linda,2001
  John,2003
  
  
• To get column data into string variables:
  
  run-query#my_query="select name, extract(year from dateOfHire) yearOfHire from employee"
     query-result#my_query, name as define name
     define-string year_of_hire
     query-result#my_query, yearOfHire as year_of_hire
     print-web name
     ,
     print-web year_of_hire
     <br/>
  end-query
  
  This produces the same output as the previous example, the only difference is that we get column values into string variables first. Variable can be defined on the spot using as define  in query-result, or by defining string first via define-string and then using as to store column value in it.
  
  
• To create a table output:
  
  <table style='border:1px solid black'>
  run-query#my_query="select name, extract(year from dateOfHire) yearOfHire from employee"
     <tr>
         <td style='border:1px solid black'>
             query-result#my_query, name
         </td>
         <td style='border:1px solid black'>
             query-result#my_query, yearOfHire
         </td>
     </tr>
  end-query
  </table>
  
  This produces output:
  
  

  Linda	2001
  John	2003

query-result# can be used with noencode (no encoding), urlencode (URL encoding) or webencode (web encoding), depending on where it used. For example, if it is used in construction of a <a href ..> link in the list of parameters, urlencode should be used. Default is webencode. These can be combined with define to store the value into it.
This will URL encode value of column 'name', then create string variable my_var and store the value into the string variable.

Database transactions

• Start transaction, execute DML, COMMIT transaction:
  
  begin-transaction
  run-query#my_query="insert into employee (name, dateOfHire) values ('Terry', now())"
  end-query
  commit-transaction
  
• Start transaction, execute DML, ROLLBACK transaction:
  
  begin-transaction
  run-query#my_query="insert into employee (name, dateOfHire) values ('Terry', now())"
  end-query
  rollback-transaction
  

Once you start transaction with begin-transaction, you must either commit it with commit-transaction or rollback with rollback-transaction. If you do neither, your transaction will be rolled back once control is passed out of your request handler. Opening a transaction and leaving without committing or a rollback is a bug in your program.  If you want to catch this kind of situation and possibly either commit or rollback, use cld_check_transaction() API function (possibly within a function dispatcher in cld_handle_request(), after the request handling), where you can detect this and either rollback, commit, or error out.

Column Length

To output column length for a column in a table:
The length obtained is the maximum number of characters in a column when it is output as a string. The supported database types for use in this markup are varchar, char and number types.

When query has no results

If your query returns no rows and you want still to get a single row made of empty strings for each column, use use-no-result:
This will produce output:

,

meaning empty name, then a comma, and then an empty year of hire.

Force query to produce a single empty row

Sometimes you may want to get a single row made of empty strings for each column, in which case use create-empty-row:
This will produce output:

,

meaning empty name, then a comma, and then an empty year of hire. Even though query would have produced some rows, you will still get a single empty row. The query is not actually executed to do this.

You may want to use this to conditionally either execute the query, or just produce an empty row, for example:
In this case, the same code is used to either show the data from the database or an empty row, such as if you wanted to present a blank form to be filled out.

Current row in a query result set

Use current-row# to get the current row number, starting with 1.
This produces output:
Row #1
Linda,2001
Row #2
John,2003

You can also store current row in a string variable first:
The output produced is the same.

Number of rows and columns in a query result set

Use row-count# and column-count# to get the number of rows and columns returned by the query.
This produces output:
Data is Linda, 2001 (row 1 out of 2 with 2 columns)
Data is John, 2003 (row 2 out of 2 with 2 columns)
Number of rows: 2
Number of columns: 2

You can also store number of rows and columns in a string variable:
If number of rows in the table is 3, the following output is produced:

Number of rows is not 2, but rather it is 3!

Note that row-count and column-count can be used within run-query loop and also right outside of it as well.

Number of affected rows in DML

Use query-result#query_name,affected_rows to get the number of rows affected in INSERT, UPDATE or DELETE.
In the above example, we check the number of rows affected (in this case inserted). Consult database manual for more information about number of rows affected - it may not always be what you'd expect.

Input parameters to queries

Query input parameters are specified via <?...?> markup. Do not confuse query input parameters (data used in SQL statements) with web input parameters (which are name/value pairs from input URL specified with input-param).
In the above example, web input parameters employee_name and year_of_hire (specified in the URL such as yourserver/go.your_application?employee_name=...&year_of_hire=...) are used as query input parameters in INSERT statements.

Query input parameters are always strings (i.e. char*) by type and can be any C expression, for example:
In the above example, both employee name and year of hire are results of C expressions.

Another example:
Query input parameters are sanitized against SQL injection attacks, and they are also trimmed on both left and right if trim-query-input is in effect.

To trim all query input parameters, use:
To not trim, use:
Any query occurring at run-time after either markup will be under its effect. By default, all query input parameters are not trimmed.

Column names

You can obtain the names of query columns by using column-names# markup:
Note that column-names# means the names of query columns, which may or may not match any actual table column names, since query outputs can have aliases (and they should have them if the output is computed). In the following example, the output will be 'employeeFirstName' and 'employeeLastName' as they are aliases:
column-names# must have as clause. In the above example, the variable 'col_names' is defined automatically, but you can also define it yourself and omit the define clause:
Note that column-names can be used within a query loop (like we did above, such as within run-query/end-query for example), or just outside of it.

Nesting queries

Queries can be nested, for example:
In this example, query2 is nested within query1, using its results. Note that query-result# for a query can be used only directly within a query loop, and not within another query's loop. For instance, query-result#query1,id cannot be used within a query loop for query2. This restriction is solely in place to prevent errors that are hard to track, such as having same column names under different queries. It is always possible to use query results directly within the loop, and is a better programming practice.

Using multiple query texts at run-time (conditional queries)

A query can have different text depending on run-time conditions. The text of the query is still static though:
If the input parameter for my_action is 'show_all_records' (for example URL is https://mysite.com/go.your_app_name?my_action=show_all_records), the output is:

Name is Linda, year of hire is 2001
Name is John, year of hire is 2003

If the input parameter for my_action is empty and input parameter for my_name_filter is 'L' (for example URL is https://mysite.com/go.your_app_name?my_name_filter=L), the output is:

Name is Linda, year of hire is 2001

For conditional queries with the same name, even though the query texts (the SQL texts) can be different and they can have different input parameters, they must have the same output, because the results sets of all such query texts are used in a single loop-query loop. For example, in the above conditional query my_query, one query text has no input parameters, and the other one has a single input parameter. However, both  texts have the exact same output ('name' and 'yearOfHire').

Dynamic queries

A dynamic query has text that is not known at compile time, i.e. it is produced at run-time. Dynamic query cannot be checked at compile time. Dynamic query should be used rarely and only when absolutely necessary. The following is an example and would be normally written as a conditional query.
The text of query is a variable query_text. This variable is constructed at run-time based on whether input parameter employee_name is provided or not. Clause with-output is used to specify what are the names of output columns - their order and names must match the query's output columns.

Since the query is dynamic, the query's input variables are not known and must be specified. Input variable is specified with '%s'. The actual input variables are provided in add-query-input# clause.

If the input parameter for employee_name is Linda (for example URL is https://mysite.com/go.your_app_name?employee_year=1990&employee_name=Linda), the output is:

Employee Linda was hired in year 2001

If the input parameter for employee_name is empty (for example URL is https://mysite.com/go.your_app_name?employee_year=1990&employee_name=   or just    https://mysite.com/go.your_app_name?employee_year=1990), the output is:

Employee Linda was hired in year 2001
Employee John was hired in year 2003

Dynamic queries when table structure is unknown

In some cases, you would not know the output columns of a dynamic query. For example, a dynamic query could be constructed in form of 'SELECT * from ...'. In general it may be beneficial in certain situations to obtain query results even if you don't know (or is cumbersome to obtain) the query output columns. In these cases you can use with-unknown-output markup, as in this example:
In this example, we don't know table names (or their columns) because we get the list of tables from the current database. Query text is constructed on the fly and we define dynamic query with-unknown-output because we don't know the output column names. After running the query we obtain the number of rows (row-count#), the number of columns (column-count#), the output column names (column-names#) and the actual data (column-data#).

The example above is typical for applications that export data or move it around while massaging the data in some ways.

Result-set data array

Normally you'd obtain query results using query-result# as in:
In some cases, it may be better to not refer to result data set in this fashion, meaning by column name. For instance, in a dynamic query you may not know the table name, nor column names. In these cases, you can use column-data# markup:
In the above, a C function get_table_data prints out (to stdout) a list of columns, and a column value (note that this would have to be a command-line program since that's where we'd use print-out).

column-data lets us obtain all table's data in a char**, i.e. in an array of strings, where all table's data is laid out in a single data array, organized by repeating rows. For instance, suppose that table name in our example has 2 columns. In that case, col_data[0] and col_data[1] would be the two columns' values from the first row, col_data[2] and col_data[3] would be the two columns' values from the second row, col_data[4] and col_data[5] would be the the columns' values from the third row etc.

column-data# must be used with as - in other words a suitable char** variable must be provided, either defined with as define or provided as in:

Using query results more than once

A query result set can be looped through again:

loop-query# will go through the entire result set again, producing this output:

Linda
John
Linda
John

Note that loop-query# does not execute a query again, but rather only uses the already obtained results.

Copying query text in multiple places safely (query shards)

• To copy a query text segment in multiple places, use query shards:
  
  input-param find_name
  
  define-shard#my_shard
  
  define-query#my_query
  
  if-string find_name=""
     start-query#my_query="<?shard#my_shard?>select name, extract(year from dateOfHire) yearOfHire from employee <?end-shard?>"
  else
     start-query#my_query="<?shard#my_shard?>select name, extract(year from dateOfHire) yearOfHire from employee <?end-shard?> where name=<?find_name?>"
  end-if
  
  If you change the text between shard# and end-shard tags in any one shard, and you forget to do so in others, you will get an error. Shards allow safe replication of query segments. Shards make it easy to not use dynamic queries which have serious drawbacks. Query text segment is easiest to read within a query itself - and the text of a query is known at compile time, allowing for a compile time check.
  
  
• If your query has input parameters in a shard, you can enforce shard equality with define-soft-shard#:
  
  define-soft-shard#my_shard
  
  run-query#my_query="<?shard#my_shard?>select name, extract(year from dateOfHire) yearOfHire from employee where name=<?variable_one?><?end-shard?>"
  
  ...
  
  run-query#my_query="<?shard#my_shard?>select name, extract(year from dateOfHire) yearOfHire from employee where name=<?variable_two?><?end-shard?>
  
  In this case, the literal texts of shards are not compared. Rather, shard texts without input parameters are compared.
  
  
• Shards can be nested, i.e. shard within a shard, up to 5 levels can be specified, for instance:
  
     define-shard#my_shard
     define-shard#another_shard
  
     start-query#my_query="<?shard#my_shard?>select name, extract(year from dateOfHire) yearOfHire from employee <?shard#another_shard?>where name=<?find_name?><?end-shard?> order by name<?end-shard?>"
  
     Shards nested within other shards can be used as such, or as standalone queries. For example, a nested shard can be a SELECT subquery that can be used as a standalone query elsewhere in the application.
  
  
• Shards can be global, i.e. across multiple files. For that, create a file named shard with content like this:
  
  define-shard#shard_name_one="select name from employee"
  define-shard#shard_name_two="select name, extract(year from yearOfHire) from employee"
  ...
  
  As long as shard file is in the current directory, you can use these shards as if they were defined in a file you use.

Re-using query text in multiple places (query fragments)

To reuse the text of query segment, use query-fragment#:
Query fragment is a string constant that can be used within a query text. It is useful where shards are not practical, such as if a query fragment is too long, or used in too many places. Each query is still static because the text is known at compile time. A fragment can have other constructs in it, such as input parameters, other fragments or shards.

Loop control in result set

When looping through the result set, you can use continue-query and exit-query to continue at the top of the loop or exit the loop, respectively:

This will print only the first employee name:
This will skip the first employee name and print the rest:

Error handling in executing queries

For INSERT, DELETE and UPDATE statements, error value is available in the result set:
SELECT statements must succeed (with or without results). If not, it is an irrecoverable error.

Getting auto_increment value

To obtain auto_increment value after insert, use insert_id value:
Just like with most other markups, you can define the string as you're getting it, or use the string you already defined:

NULL and result column data types

All results from the database come as a string type (i.e. char*). NULL value is always an empty string (""). If you want to know if a value is NULL (versus an actual empty value), use a function such as ISNULL() in the database queries.

Executing Cloudgizer program from command line

See this chapter in API on more information about building and executing Cloudgizer program from command line.

Executing external programs

For most use cases, use exec-program:
This will execute program specified by program_path with arguments specified under program-args. Program arguments are separated by a comma. If a comma is a part of an argument, it must be escaped, as in \, and if double quote is a part of an argument it should be escaped as in \" as well.

On return, the exit status will be st, and any output (stdout and stderr) will be in out_var. Note that out_var is allocated inside the execution function, and the length used to allocate it is out_var_len.

If program-output-length is not specified, the out_var output variable is allocated with a default 256 bytes. Either way, any output in excess of what's available is truncated.

You can also define the status of execution and the output buffer in the markup itself:
If you want more complex use cases, such as redirecting file to stdin, and redirecting stdout/stderr to a file, or if you want to create a "pipe", i.e. execute two programs where output of one is the input of another use program execution functions.

Sending emails

Use send-email to send emails:
The sender of email is given by from clause ("joe@xyz.com") and the email recipient is given with to ("mike@zyx.com"). The subject is provided with subject clause ("Hi there"). Any headers are in headers clause (which indicate this is an HTML email), and body of the email is given with body clause.. The status clause ('st') is the status of sendmail program used to send the message. Headers and status are optional while other clauses are mandatory.

Loading URL content (calling a web page) programmatically

Use web-call to get the result of loading the content of a URL via GET method:
A web response to a given URL is loaded into a string variable that is defined with a mandatory with-response clause. In this case variable webres is defined via define clause, but it could be defined prior to web-call. Other clauses are not mandatory. with-error specifies a string variable to hold an error text, if any. with-cert is used to specify the location of HTTPS certificate. You can also use with-no-cert if the certificate is not to be checked.

cookie-jar specifies the location of a file holding cookies. Cookies are read from this file (which can be empty or non-existent to begin with) before making a web-call and any changes to cookies are reflected in this file after the call. This way, multiple calls to the same server maintain cookies the same way browser would do. Make sure the same cookie-jar file is not used across different application spaces.

A simple use of web-call:
or without checking HTTPS certificate:
Response that redirects to another URL will be followed up to 4 times. The response is the body message, not the headers.

This function does not return length of a response, because it is meant to be used as a text-based (i.e. null-terminated string based) messaging system. For uploading or downloading files, a more encapsulated method would be to use command-line utilities (such as curl or rcopy) via program execution functions.

Strings

Strings are 'char *' variables that are allocated by Cloudgizer's memory allocation system. Typically you never free them. They are freed at the end of each request.

If you are using any cld_* function that alters strings (i.e. as an output parameter) or in markup constructs that alter strings (such as append-string or write-string), then such strings must be defined using one of the following methods, or by means of API functions such as cld_malloc, cld_calloc or cld_realloc. Usage of other kinds of 'char *' variables will likely be detected by Cloudgizer and program halted.

Defining and copying strings

• To define a string, use define-string:
  
  // Initialize string to be empty ("")
  define-string my_str
  
  // Initialize string to some expression
  define-string my_str="some string expression"
  
• To copy string from another string expression, use copy-string:
  
  define-string my_str
  copy-string my_str=other_string
  
  When you copy into a string with copy-string, the string must have been defined with define-string.
  
  
• To convert an integer into a string and then copy:
  
  define-int my_int=10
  define-string my_str
  copy-string-from-int my_str=my_int
  

You should not assign NULL value to a string. Use empty strings (as described above) instead.

Appending string

Use append-string:
The output is:

Hello world!

Search and replace string

Use subst-string and subst-string-all:
In the above example, the very first occurance of 'good' is replaced with 'great', producing the output:

Have a great day and good night!

If you wish to replace all occurances, use subst-string-all:
The above will produce the output:

Have a great day and great night!

The string where replacement takes place (in this case 'my_str') must have been defined with define-string.

Constructing complex strings

Instead of output being sent to the Web client, it can be directed into a string.  Use write-string and end-write-string to do this:

• A simple example:
  
  define-string my_str="world"
  define-string my_str1="and have a nice day too!"
  
  write-string define result_str
  Hello <?print-web my_str?> (<?print-web my_str1?>)
  end-write-string
  
  print-web result_str
  
  The output is:
  
  Hello world (and have a nice day too!)
  
  
• Using code inside write-string markup:
  
  input-param selector
  
  define-string my_str="world"
  
  write-string define result_str
     if-string selector="simple"
         Hello <?print-web my_string?> (and have a nice day too!)
     else-if-string selector="database"
         run-query#my_query="select name from employee"
             Hello <?query-result#my_query,name?>
             <br/>
         end-query
     else
         No message
     end-if
  end-write-string
  
  print-web result_str
  
  If selector variable is "simple" (as in URL https://mysite.com/go.your_app_name?selector=simple), the result is:
  
  Hello world (and have a nice day too!)
  
  If selector variable is "database" (as in URL https://mysite.com/go.your_app_name?selector=database), the result is:
  
  Hello Linda
  Hello John
  
  If selector variable is anything else (as in URL https://mysite.com/go.your_app_name?selector=something_else), the result is:
  
  No message
  
  In the above example, result_str variable is defined on the spot, but it can also be defined elsewhere without using define.
  
  
• Use functions inside write-string:
  
  void func1 ()
  {
     /*<
     define-string result_str
  
     write-string result_str
         <?print-web "Result from func2()"?> is <?c func2();?>
     end-write-string
     >*/
  }
  
  void func2()
  {
     /*<
     print-web "Hello from func2"
     >*/
  }
  
  The output from func1() is:
  
  Result from func2() is Hello from func2
  
  
• Nest write-strings, directly:
  
  write-string define str1
     Hi!
     write-string define str2
         Hi Again!
    end-write-string
    print-web str2
  end-write-string
  print-web str1
  
  The result is:
  
  Hi! Hi Again!
  
  
• An example of nesting through function calls:
  
  void func1 ()
  {
     /*<
     define-string result_str
  
     write-string result_str
         define-string func2_result
         <?print-web "Result from func2()"?> is <?c func2(&func2_result);?>
     end-write-string
     >*/
  }
  
  void func2(char **result)
  {
     /*<
     write-string *result
         <hr/>
         run-query#my_query="select name from employee"
             Hello <?query-result#my_query,name?>
             <br/>
         end-query
         <hr/>
     end-write-string
     >*/
  }
  
  The output from func1() is:
  
  Result from func2() is
  

  ---

  Hello Linda
  Hello John
  

  ---

  
  
• Because defined string (be it in define-string or via define in any other markup) allocates new heap space, the result can be returned as well, as in this example:
  
  void func1 ()
  {
     /*<
     write-string result_str
         define-string func2_result
         <?print-web "Result from func2()"?> is <?print-web func2();?>
     end-write-string
     >*/
  }
  
  char *func2()
  {
     /*<
     write-string define result
         <hr/>
         run-query#my_query="select name from employee"
             Hello <?query-result#my_query,name?>
             <br/>
         end-query
         <hr/>
     end-write-string
     >*/
     return result;
  }
  
  The output is the same.

All leading and trailing whitespaces are trimmed from each line. Only the whitespaces within each line are output. Text is output as non-encoded (as opposed to URL or web encoded), unless you specifically output something encoded otherwise.

Program flow

Loops

Use for and end-for markups:
In the above example, a simple loop outputs this to the web page:

Outputting #0
Outputting #1
Outputting #2
Outputting #3
Outputting #4
Outputting #5
Outputting #6
Outputting #7
Outputting #8
Outputting #9

Conditional statements (if, else...)

Conditional statements can be used as follows:

• if statement uses any C expression, without parenthesis needed:
  
  if x==2 && y==2 || !(z==3 && w==4)
     print-web "Something"
  
  else-if w==4 && !strcmp(t,"...")
     print-web "Something else"
  
  else
     print-web "Anything else"
  
  end-if
  
• if-string statement is used for comparing strings only. With if-string, single equal sign (=) is used for equal condition, and negative equal (!=) for negative condition.
  
  define-string my_str
  define-string my_str1
  
  if-string my_str="abc"
     print-web "Something"
  
  else-if-string my_str="def" or my_string!="klm"
     print-web "Something else "
  
  else-if-string my_str="gef" and my_str1!="..."
     print-web "Something else entirely"
  
  else
     print-web "Anything else"
  
  end-if
  
  With if-string markups, and and or can be used in simple conditional logic with no parenthesis allowed, except when escaped with a backslash in cases when more complex expressions are used in string comparision.
  
  In general, use variables and multiple if-strings to break down the logic and write simpler constructs. The intention of if-string is to make complex decision making process easier to read, and not to enable short and obfuscated code.
  
  Use if for more complex conditional expressions, if needed. To compare strings case-insensitive, use if-string-case and else-if-string-case.

Files

File storage

You can store your files anywhere you like and use either standard C file mechanism to handle them or Cloudgizer API (such as reading/writing files etc.). Cloudgizer however, also provides a file storage mechanism that you can use for any general purpose. This file storage is used for automatic upload of files as well.

In this file storage, files are generally stored in file directory under application's home directory. Your application may use this storage for any documents you create, see the API you can use to create your own files. This storage is also used for uploading of files from web clients (such as uploading files from web browsers or mobile device cameras) - the uploading is handled automatically by Cloudgizer.

About 30,000 files will be stored in a single subdirectory (i.e. /home/user/file/d<number>) before moving to the next subdirectory. This number of files may increase in the future, however that will not affect files in existing installations, i.e. they will stay where they are.

The number of actual subdirectories and files is in theory limited only by the filesystem used, and Cloudgizer's choice of the number of files is not a hard limit, hence it may increase in the future. The number chosen currently is reflective of the common device storage available at present and the subjective typical file size distribution across typical business applications, so clearly the choice is not related to theoretical limits or considerations.

Modern filesystems can support great many files. For example, if you had 120 million files, they would be spread across some 40,000 directories with 30,000 files each. For example, files might be named /home/user/file/d0/f31881, /home/user/file/d10/f321214, etc.

File names are always based on the ID number, so that changing the number of files per subdirectory will never overwrite files. This scheme also allows for faster access to file nodes due to relatively low number of files per subdirectory, and also might allow for hardware or network partitioning.

Typically, an application will store file names in the database and actual files in file storage in file directory. Each file has a unique ID, and you can use this ID to reference a file in the database, see an example in file creation API.

The table cldDocumentIDGenerator is used to create unique file names across the application, even when multiple requests are made at the same time. This table is created as part of Cloudgizer's installation and used internally to deliver this functionality - you don't have to ever deal with it.

Permissions and ownership

Any files created by Cloudgizer (i.e. through uploading from web clients, writing files etc.) are owned by Cloudgizer user and have 700 access permission (owner-only reading, writing and accessing). Group has no privileges, and neither have other users. The Cloudgizer user's home directory is also set up with 700 access permission.

Uploading files

Cloudgizer will upload files for you automatically. The file will be stored in file directory by using the document ID generator as a basis for subdirectory and file name under the file directory.

For example, files uploaded might be named /home/user/file/d0/f31881, /home/user/file/d10/f321214, etc. See File storage for more details on how files are stored.

• If your upload file is named 'myfile' in the HTML form you're using to upload the file, you will get the following input parameters when upload happens: myfile_filename, myfile_location, myfile_ext, myfile_size and myfile_id. They are as follows:
  
  • myfile_filename is the name of the file as provided by the client.
    
    
  • myfile_location is the full path to the location on the server where file is stored (such as /home/user/file/d10/f214 for example)
    
    
  • myfile_ext is the extension of the file, for example ".jpg" or ".pdf". Note that ".jpeg" is always showing as ".jpg". The extension is always lower case.
    
    
  • myfile_size is the size of the file uploaded.
    
    
  • myfile_id is the ID of the file, as obtained from cldDocumentIDGenerator, which is used to generate the file's path and name on the server.
    
  
  For example, for an HTML form which is uploading a file with a input HTML file of type "file" that is named "myfile" (such as <input type="file" name="myfile">), your code that handles this POST might be:
  
  input-param myfile_filename
  input-param myfile_location
  input-param myfile_ext
  input-param myfile_size
  input-param myfile_id
  
  You have uploaded file <?print-web myfile_filename?> to a server file at <?print-web myfile_location?>  ...
  

Reading a whole file

Use read-file to read a whole file:
The above example will read a file /home/user/some_file and store the result into a variable file_content and the status into variable st.  Variable st would be -1 if cannot open the file, -2 if cannot read the file, and the size of the file read (0, or a positive number) if reading succeeded.  

define in both the content variable and the status are optional, so it could be:

Writing a whole file or appending to a file

Use write-file to write to a file:

• Create a file and write to it:
  
  define-string my_string="Hello world!"
  write-file "/home/myuser/file_name" from my_string
  
  This will write string "Hello world!" to file "/home/myuser/file_name".
  
  
• Append to an existing file:
  
  write-file "/home/myuser/file_name" from "Some string expression" append
  
  This will append string "Some string expression" (without quotes) to the file.
  
  
• Specify length of the buffer being written:
  
  define-string file_name="myFile"
  write-file file_name from "Some string expression" length 7 append
  
  This will append string "Some st" (length 7) to the file.
  
  
• Get status from writing:
  
  write-file "/home/myuser/file_name" from "Some string expression" length 7 status define my_status append
  
  This will also return the status of file writing to integer variable my_status. Return values are 1 if succeeded, -1 if could not open file, -2 if could not write file.
  
  
  
• Status variable is defined in the above example, or without defining it:
  
  define-int my_status
  write-file "/home/myuser/file_name" from "Some string expression" length 7 status my_status append
  
  This is the same as above, only with explicitly defining my_status variable.

Copying a file

Use copy-file to copy a file to another file. The target file is created if it does not exist.
This copies from file source_file to file target_file. The result is -1 if cannot open source_file, -2 if cannot open target_file, -3 if cannot read source_file, -4 if cannot write target_file, and 1 on success.

You can omit define for status:

Web address of server

Web address is the URL specified in config file in web_address variable.

Use web-address to get the base URL for server. Use it for links and forms:

• Web address used in a form:
  
  <form action="<?web-address?>">
  
  will produce for example:
  
  <form action="https://myserver.com/go.your_app_name">
  
  
• Web address used in a URL:
  
  <a href="<?web-address?>?page=abc&amp;action=do_something">
  
  will produce for example:
  
  <a href="https://myserver.com/go.your_app_name?page=abc&action=do_something">

Error handling in general

If an irrecoverable error occurs, then oops function will be called. Irrecoverable error is an error that cannot be handled, it always means the end of a request. Examples of such errors are invalid SQL statements or an invalid URL request. oops function is like this:
input_req is a type that contains information relating to the current request. err is an error message itself.

You can change the implementation of oops function from what it is by default.

When checking errors in your application (i.e. errors that are recoverable), and if upon the examination of the error, your code decides it is still unrecoverable, do not call oops directly. Rather use report-error:
report-error takes arguments the same way as standard printf function.  

Include files

Do not use Cloudgizer markup code in include files. Instead place all of it in .v files, which are translated into .c files. Use inline code if you need to avoid function calls.

Debugging your code

Generally, you can debug Apache server by forcing it into a single-process mode, running it in gdb and hunting for problems there. A good tutorial on this can be found at https://httpd.apache.org/dev/debugging.html. Once in debugger, you'd want to break in cld_main function, which is the root function for any Cloudgizer application. If for some reason this doesn't work, you have another option, described here.

Tracing and debugging options

These options are located in the trace/debug file, meaning debug file in the trace directory under application's home directory. Typically, you'd have this in it during development:
Here is the breakdown of what these do:

• sleep is the number of seconds your code will sleep before processing a request. For example, if you set it to 50, this is 50 seconds sleeping before processing the request. You now have the time to find the PID of your process and attach to it. You might do this:
  
  ls -aslrt ~/trace/*
  
  This will list all trace files, with the latest ones in at the bottom. Trace file names look something like trace-9833-2017-05-15-16-57-06. What this means is that PID (process ID) is 9833, and that it was created on 2017-05-16 at 16:57:06. So by looking at the last trace file and getting a PID, you can now call the debugger:
  
  sudo gdb /usr/sbin/httpd
  
  (you are attaching to httpd process, because that's Apache and that's where your code is running!)
  
  Type in the 'att' command to attach to httpd process in the debugger, and replace 9833 with your actual PID:
  
  att 9833  
  
  Now if you did all this within 50 seconds (choose the number of seconds to match how long you need), you will be in the middle of a sleep call. Type:
  
  next
  
  and wait until you get out of it. Now you will be in the generated code, and you can step through (with 's' or 'n' commands) as you like. At this point you haven't reached cld_handle_request yet, so you might create a break point there:
  
  br cld_handle_request
  
  or you may do something else entirely, depending on where you suspect the problem with your code it. Note that all requests will have this sleep, so things will be slow to startup, and once you find and fix the issue, don't forget to turn sleep back to -1 (i.e. no delay):
  
  sleep=-1
  
• trace parameter creates trace files. If it's zero, trace files won't be written. Each trace file name has a timestamp and a PID (process ID) of the process writing it, making it easier to identify the moment and identity of the process writing the trace, as well as to attach to it via gdb. Trace files take a little bit of time to be written (they will probably be cached in memory most of the time), but you can choose not to write them for extra speed. However, then you won't have the history of traces in case something goes wrong - however, you will still have the backtrace and/or web-page-crash files that are generated on program error that should have the source code stack where the problem happened. So even if you don't enable trace files, in case of error there should be file(s) available to assist you in debugging. Cloudgizer will also email the report of error to administration email (email_address in config file) at the moment it happens.
  
  
• lint parameter. If set to 1, the HTML output your program creates dynamically will be checked in real-time with xmllint. If any error is detected (such as bad HTML tags), this will display at the top of the page as an error. You'll also see a path to a file that contains the error. The actual file with HTML code (that your program generated) is in the file with the same name, only without an .err extension. Go there and check it out, then fix your code.
  
  
• memorycheck parameter. If set to 1, every tracing call (CLD_TRACE API call) will perform memory check of all allocated memory and likely detect any overwrites or underwrites. Since tracing calls are generally well interspersed throughout typical code, this provides higher confidence level that any hard-to-find bugs will be found early on. Set this to 0 in production.
  
  
• tag is a parameter than can have any one-line string. This will be accessible  in cld_get_config()->debug.tag variable and you can use it for any debugging purposes you'd like.
  

Make sure not to use sleep, lint, memorycheck and tag in your production code.

Finding where program crashed

When your program crashes, your best bets are to look in:

• trace directory and read the trace file, see where it crashed. Use CDL_TRACE() in your code to pinpoint the location.
  
  
• Check trace/web-page-crash file for more information. This file is generated whenever possible. You'd look here if your program caught the error via report-error or cld_report_error().
  
  
• Check trace/backtrace file for more information, especially if your program crashed due to a signal such as SIGSEGV for instance.
  
  
• Check the core dump. Enabling the core dump and locating it are beyond the scope of this documentation. See your OS documentation.
  

Both web-page-crash and backtrace file will attempt to show the full stack dump, and there you can see function names and line numbers (if available and if you compiled with debugging information included). Cloudgizer will analyze your executable and attempt to show the exact line in your source where the problem happened (meaning the exact line in .v code, and not in the generated .c code, alleviating the need to connect the two files!). Note that line numbers are multipled by 1,000. This is because a single line of .v code can expand to many lines of .c code. For instance, line 291104 means you need to look for a line that starts with #line 291000 and then look for 104 lines below this line. This way the location of an error is exactly shown.

For example, you'd see a report like this that exactly pinpoints the location of the crash (in this case due to segmentation fault) - you'd look for the source code just before entering signal_handler and you'll also see the entire stack leading up to invocation of the function where the problem is:

Enabling debugging information

To enable debugging with gdb, set CLDDEBUG variable in supplied cldmakefile to 1 when making your application. This will turn on debug code generation for gdb. Do not call this makefile directly.

Which shared libraries are loaded?

Check the beginning of the request's trace file - it shows all shared objects loaded, their names and their address ranges. This is useful when figuring out the configuration of Apache server, and otherwise.

API

The following is the list of publicly available data types and functions.

Do not use API for common markups provided otherwise. For example, do not use input parameters API, but rather use input-param markup. If underlying API and types change, you'll have to change your code.

Use API only if there is no alternative. The same goes for any other C code you may write, be in direct C code or through c and start-c markups.

Memory allocation

Allocation and garbage collection

The following memory allocation functions are available:
The above have the same interface as the standard library functions without the 'cld_' prefix.

Always use define-string to allocate memory - only if otherwise necessary, use above cld_* functions for memory allocation.

Most all markups and API will automatically create or expand/shrink memory when needed.

Never use cld_free unless absolutely needed, for example if your request allocates lots of memory in a loop and needs to release it in each pass during a single request.

Memory garbage collector is provided and will release all allocated memory at the end of request.

Do not try to minimize memory usage of a request unless you have a very good reason to, because most requests take relatively short time to complete and memory will be released shortly. Great many bugs and crashes come out of using free()-like functions improperly.

Never use library functions malloc(), free() etc. unless you have an extremely compelling reason, for example if you need to allocate memory and some library frees it. Do not use pointers obtained from Cloudgizer with library functions such as free() or realloc(), and vice versa.

Get size of memory allocated for variable

When variable is allocated by means of define-string or cld_malloc (or such) functions, you can determine at run-time how many bytes are currently allocated for this variable:
Variable 'sz' will have value of somewhat over 200 (accounting for overhead in allocating memory). If pointer 'ptr' was not allocated by Cloudgizer functions or markup, program will error out.

Check if allocated memory is valid, overwritten or underwritten

If you want to check if memory pointer is valid and if memory hasn't been overwritten or underwritten, use cld_check_memory:
p is a pointer returned from define-string, cld_malloc or other such functions. This is an assertive function, i.e. your program will report an error if the memory block is invalid. If memory is okay, it returns an index into an internal memory array that holds information about allocated pointers. This index is for internal purposes only, do not use it in any way.

Configuration parameters

Configuration parameters are filled from config file, located in the application's home directory.

Use members of cld_get_config()->app structure to get the following:

• Version of the software:
  
  print-web cld_get_config()->app->version
  
  Version is stated in the version field in the config file.
  
  
• Tracing and logging files directory
  
  print-web cld_get_config()->app->log_directory
  
• Temporary directory
  
  print-web cld_get_config()->app->tmp_directory
  
  Use temporary directory for any temporary files your application creates.
  
  
• Uploads directory
  
  print-web cld_get_config()->app->file_directory
  
  This is where uploaded files are stored (within enumerated subdirectories). This is also where Cloudgizer file system is located, see file storage - you can use it for any files your application creates.
  
  
• Maximum upload size
  
  print-web cld_get_config()->app.max_upload_size
  
  This is the maximum file size that can be uploaded.
  
  
• Web directory
  
  print-web cld_get_config()->app->html_directory
  
  Typically html, css, image files etc. are stored here.
  
  
• Administrative email
  
  print-web cld_get_config()->app->email
  
  This is email_address field in the config file. It should be an email that your application uses for contact and other purposes. This email is also used by default to email crash information to you.
  
  
• Server web address
  
  print-web cld_get_config()->app->web
  
  This is web_address field in the config file. This is the submit URL for forms and links.
  
  
• Custom config parameters
  
  You can add any parameters to config file that you like. They must be prefixed with underscore ('_'). Those parameters are stored in the following data structure:
  
  cld_get_config()->app->user_params
  
  To obtain them in C code:
  
  cld_config *pc = cld_get_config ();
  char *user_option = NULL;
  char *user_option_value = NULL;
  
  cld_rewind (&(pc->app.user_params));
  while (1)
  {
     cld_retrieve (&(pc->app.user_params), &user_option, &user_option_value);
      if (user_option != NULL)
      {
          // make use of user_option and user_option value. For example, if in config file:
          //
          // _my_option = some option value
          //
          // then user option would be "_my_option" and user_option_value would be "some option value"
          ...
      }
      else
          break;
  }
  

Tracing and debugging

Write to trace file

Trace call allows you to write to current process' trace file:
Trace call uses printf syntax to output data.  

Trace will be written only if trace parameter in debug file is 1.

Which trace file is being written to?

The name of current trace file is:

Using custom tag value for debugging

Use cld_get_config()->debug.tag to access tag field in the debug file. This field can have any value you want. Use it to control some aspect of debugging process, in a conditional fashion:
In production, you would clear the tag value.  

Linting your HTML code dynamically

Use cld_lint_text to check validity of HTML code generated dynamically at run-time (for example check HTML emails before sending or check snippets of generated code not directly displayed):
In this example, Cloudgizer will check validity of HTML in html_code (as XHTML) by using xmllint utility. lint in debug file must be set to 1 in order for cld_lint_text to do this. If lint is 0, nothing will be done.

If there is an error, program will stop and you can see more information in program's trace file (under trace directory).

Note that Cloudgizer will lint your web output automatically if lint is 1. Use this function to check snippets of HTML that are not output directly by your program.

URL input

URL input parameters

Input parameters are stored in
Total number of input parameters is:
Names and values of input parameters are:
etc. up to the total number of input parameters

Is URL referrer from the same site?

Use cld_get_config()->ctx.req->from_here to determine if the current web request originated from the same site or not. For example, you may not want to spend bandwidth on images not shown from your application, if that's how it's designed. This flag is 1 if the current web request originated from the same site, otherwise 0.

Note that from_here will be 1 if the URL is opened from a web client directly by the end-user.

URL string that is being processed

The URL of current request is:
and the referring URL is:

URL parameters manipulation

There is a cld_input_params data type that can hold input parameters. You can manipulate URL parameters directly by using cld_replace_input_param function with cld_get_config()->ctx.req->ip as input.

You can use the following:

• Copy URL parameters to cld_input_params type variable:
  
  cld_input_params ip;
  
  cld_get_input_params (cld_get_config()->ctx.req, &ip );
  
  cld_input_params has the same members (as far as input parameters go) as input_req type, i.e. you can access:
  
  ip.names[0], ip.values[0] up to ip.num_of_input_params.
  
  cld_get_input_params does not return a result (i.e. it's return type is void).
  
  
• Replace input parameters' value
  
  An example of replacing value of an input parameter, from above example:
  
  cld_input_params ip;
  ...
  cld_replace_input_param (&ip, "param1", "new value 1");
  
  If parameter "param1" already exists, this will replace the value of existing parameter "param1" with new value "new value 1", and the function returns 1.
  
  If parameter "param1" does not already exists, this will add new parameter "param1" with value "new value 1", and the function returns 2.
  
  You can also directly manipulate input parameters before input-param is used, for instance:
  
  cld_replace_input_param (&(cld_get_config()->ctx.req->ip), "param1", "new value 1");
  
  
  
• Generate URL from an cld_input_params type variable
  
  An example:
  
  cld_input_params ip;
  ...
  char *new_url = cld_construct_url (&ip);
  
  new_url variable will contain valid URL made out of base URL address of the server and all the parameters, for example 'https://myserver.com/cld.do?param1=value1&param2=value2'
  
  If you need URL part without the server web address, use cld_construct_input_params:
  
  char *new_url = cld_construct_input_params (&ip);
  
  new_url variable will now contain 'param1=value1&param2=value2'
  
  
• Simulate input request from a URL
  
  If you have a URL (perhaps saved or constructed URL) that you'd like to manipulate, use first cld_get_input to get the input_req type variable for this URL:
  
  input_req my_req;
  const char *my_URL = "https://myserver.com/cld.do?param1=value1&param2=value2";
  cld_get_input (&my_req, "GET", my_URL);
  
  Now my_req contains information about this URL, including its input parameters. Other information, such as cookies, is obtained as if the URL came from the client.
  
  Then you can manipulate this URL, for example:
  
  cld_input_params ip;
  
  cld_get_input_params (&my_req, &ip );
  
  cld_replace_input_param (&ip, "param1", "new value 1");
  
  char *new_url = cld_construct_url (&ip);
  
  Variable new_url now has value "https://myserver.com/cld.do?param1=new%20value%201&param2=value2".

Cookies

Data type for storing

Cookies passed from HTTP are in:
up to the number of cookies, which is:

Cookies: get, set, delete, find

• Cookies can be obtained by using cld_find_cookie:
  
  input_req *req = cld_get_config()->ctx.req;
  
  int cookie_index;
  char *path;
  char *exp;
  
  char *cookie_value = cld_find_cookie (req, "my_cookie", &cookie_index,  &path, &exp);
  
  In this example, we search for cookie "my_cookie" in the input request. If it doesn't exist, variable cookie_value will be empty ("").
  
  If it does exist, variable cookie_value will have its value, and variable cookie_index will point to cookie's entry in cld_get_config()->ctx.req->cookies[] array. Variable path will have the path for the cookie, and variable exp will have its expiration date.
  
  
• To set cookie (for a response to client):
  
  input_req *req = cld_get_config()->ctx.req;
  
  cld_set_cookie (req, "my_cookie", "some value", "/", "Wed, 31 May 2012 00:00:01 GMT");
  
  The above sets values for a cookie, including path ("/") and the expiration date. Path and expiration date can be NULL in which case they are not set. This function does not return a value. Use cld_time API function to produce time suitable for cookies.
  
  You must set a cookie before outputting the HTTP header, such as in output-http-header, or otherwise it won't be set.
  
  
• To delete a cookie:
  
  input_req *req = cld_get_config()->ctx.req;
  
  int deleted = cld_delete_cookie (req, "my_cookie");
  
  This will delete cookie "my_cookie" (cookie can still be found, but it is set to a value that will delete it in the web client such as browser). If it is not found, this function returns -1, otherwise it returns index into cld_get_config()->ctx.req->cookies[] array where it was found.

Global data

If you need global data in your program (data accessible to any function) and share it between different parts of your program, you can use:
This is a global void* pointer you can use any way you like for sharing global data unrelated to the current request data.

Encoding and Decoding, URL encoding, Web encoding, Base64 encoding

• To URL encode a string, for use in URL links, images etc.:
  
  char *result = NULL:
  int enc_len = cld_encode (CLD_URL, "some text to URL encode", &result);
  
  Variable 'result' will be  "some%20text%20to%20URL%20encode" and enc_len will be its length.
  
  
• To web-encode a string, for displaying data in web pages:
  
  char *result = NULL:
  int enc_len = cld_encode (CLD_WEB, "some <text> to web encode", &result);
  
  Variable 'result' will be  "some &lt;text&gt; to web encode" and enc_len will be its length.
  
  
• Decoding URL encoded data:
  
  char *str = "some%20text";
  int str_len = cld_decode (CLD_URL, str);
  
  After this, str will be "some text" and str_len will be the length of decoded string.
  
  
• Decoding web encoded data:
  
  char *str = "some&amp;text";
  int str_len = cld_decode (CLD_WEB, str);
  
  After this, str will be "some&text" and str_len will be the length of decoded string.
  
  
• Encode data to Base64
  
  To encode data (for example binary jpg image), you can use:
  
  char *data = NULL;
  int file_size =  cld_read_whole_file ("/home/user/myimage.jpg", &data);
  
  char *result = NULL;
  int result_len = 0;
  cld_b64_encode (data, file_size, &result, &result_len);
  
  In this example, we read the whole file of an image. We pass the data and its length ('data' and 'file_size') to cld_b64_encode and get base64 encoded string in 'result' variable with result_len being its length.
  The cld_b64_encode does not return a value.
  
  
• Decode base64 data
  
  Data already encoded in base64 can be decoded, if we take from above example:
  
  char *original_data = NULL;
  int original_data_len = 0;
  
  cld_b64_decode (result, result_len, &original_data, &original_data_len);
  
  In this example, original_data will match data, and original_data_len will match file_size.

Numbers

Create string from integer

To get a new string from an integer, use cld_i2s function:
The result will be:

55

To store the value in a string:
The result is the same.  

Check if string is a positive integer or a number

• To check if string is a positive number:
  
  int is_positive =  cld_is_positive_int ("-23");
  
  The above returns 0, while:
  
  int is_positive =  cld_is_positive_int ("23");
  
  returns 1. The function returns 1 if it is an integer number comprised of digits only and 0 in any other case.
  
  
• Check if string is a number and get sign, precision and scale:
  
  int prec;
  int scale;
  int positive;
  
  int is_number =  cld_is_number ("-24.335", &prec, &scale, &positive);
  
  If string is not a number, cld_is_number returns 0, otherwise 1. If positive, variable positive is 1, otherwise 0. Total number of digits is precision and is stored in variable prec. Scale is the number of digits after the decimal point, and is stored in variable scale. Any of variables prec, scale and positive can be NULL if you don't want that information.
  
  In the above example, prec is 5, scale is 3 and positive is 0.

Execution of external programs, piping from one program to another

You can execute external programs by using several functions. All of these functions return the status of program (typically 0 if okay, non-zero otherwise).

Typical use cases are:

• If you just want to execute a program with command line arguments and capture its exit status (and you don't care about stdin, stdout and stderr), the simplest one for this purpose is cld_exec_program_out_data. This is the simplest use case, and good amount of programs are executed this way.
  
  
• If you want to execute a program with command line arguments and capture its exit status, and want to get just the first line of its stdout/stderr output (and you don't care about stdin), use cld_exec_program_out_data. Many programs produce one-liner outputs, and this is useful for that. Or the first line tells you all you need to know and so you just get the first line. Probably most programs would fall into this category.
  
  
• If you want to execute a program with command line arguments and capture its exit status, and be able to pass some input to it through stdin from a variable, and be able to get stdout/stderr output into a variable, and you know the maximum size of such output or the leading output you care about, use cld_exec_program_with_input.
  
  
• If you want to execute a program with command line arguments and capture its exit status, and be able to pass an open file pointer to it as an input, and get the output into an open file pointer, use cld_exec_program_with_in_out. This function allows for unlimited input and unlimited output, so it's the most generic of all, but if you don't need all that, it's better to use a simpler one. This function also lets you pipe two programs together, i.e. use output of one program as the input to another.
  

Here are the details on these functions:

• cld_exec_program_with_input, which takes command line arguments, input from a variable and produces output to another variable.
  
  Assume you are executing the following from the command line:
  
  echo "This is input to program through standard input" | /usr/bin/my_program -switch1 40 -fast > out.txt 2>&1
  
  (2>&1 means stderr goes to stdout)
  
  and assume that out.txt (the output of program to the stdout and stderr) is "program finished" and is never larger than 300 characters (or you don't care for anything beyond that), including zero terminator.
  
  In this case, you can do the same programmatically like this:
  
  const char *cmd =  "/usr/bin/my_program";
  const char *argv[] = {"my_program", "-switch1", "40", "-fast", NULL};
  const char *inp = "This is input to program through standard input";
  char out_buf[300];
  cld_exec_program_with_input (cmd, argv, 4, inp, strlen(inp), out_buf, sizeof(out_buf));
  
  
  In this case, program at path "/usr/bin/my_program" will execute. Input parameters are in argv. Note that the first input parameter always must be program's name, which is "my_program" in this case. The last input argument must always be NULL. Number of arguments is 4, which is excluding NULL. The output of the program is stored into variable out_buf, and the size of this variable is provided as the last argument.
  
  If inp is NULL or inp is empty string (i.e. inp[0]==0), then no data is written to stdin of the executing program.
  
  
• cld_exec_program_out_data which takes command line arguments and produces standard output, the first line of which is captured.
  
  Assume you are executing the following from the command line:
  
  /usr/bin/my_program -switch xyz some_arg > out.txt 2>&1
  
  (2>&1 means stderr goes to stdout)
  
  and assume you are interested only in the very first line of out.txt, and you don't have any standard input to it.
  
  In this case, you can do the same programmatically like this:
  
  char buf[1024];
  int buf_len = sizeof (buf);
  const char *argv[] = {"my_program", "-switch", "xyz", "some_arg", NULL};
  
  int st = cld_exec_program_out_data ("/usr/bin/my_program", argv, 4, buf, buf_len);
  
  In this case, program at path "/usr/bin/my_program" will execute. Input parameters are in argv. Note that the first input parameter always must be program's name, which is "my_program" in this case. The last input argument must always be NULL. Number of arguments is 4, which is excluding NULL. The first line of the output of the program is stored into variable buf, and the size of this variable is buf_len.
  
  
• cld_exec_program_with_in_out which takes command line arguments, takes input from a file pointer provided, and writes output to another file pointer provided.
  
  
  • Assume you want to execute the program, and you will provide the input to it from one file, and want to get output as a file pointer you want to read.
    
    const char *ap3[] = {"my_program", "-switch", "40", "-fast", NULL};
    FILE *fin1 = fopen ("/home/user/somefile", "r");
    FILE *fout3 = NULL; // create temp file in cld_exec_program_with_in_out
    int st = cld_exec_program_with_in_out ("/usr/bin/my_program", ap3, 4, fin1, &fout3);
    // now you can read from fout3 with fgets in a loop for example
    
    In this case, program at path "/usr/bin/my_program" will execute. Input parameters are in argv. Note that the first input parameter always must be program's name, which is "my_program" in this case. The last input argument must always be NULL. Number of arguments is 4, which is excluding NULL. The input of the program (stdin) will be taken from file "/home/user/somefile", which we opened, and we passed the file pointer to it to cld_exec_program_with_in_out. The output of my_program will go to file pointer fout3, which in this case is NULL, and that means cld_exec_program_with_in_out will create a temporary file, open it and assign its file pointer to fout3. After writing to fout3 is done, fout3 will remain open and will be rewound to its very beginning, so your program can read it. Since it's a temporary file, it will be automatically deleted once you close it (with fclose()).
    
    
  • To write to a file of your choice, open file for writing and assign the file pointer to fout3:
    
    const char *ap3[] = {"my_program", "-switch", "40", "-fast", NULL};
    FILE *fin1 = fopen ("/home/user/somefile", "r");
    FILE *fout3 = fopen ("home/user/outfile", "w+");
    int st = cld_exec_program_with_in_out ("/usr/bin/my_program", ap3, 4, fin1, &fout3);
    // now you can read from fout3 (it is rewound to its beginning), or just close it
    fclose (fout3);
    
  
  
  
• You can also use cld_exec_program_with_in_out to  pipe from one program to another:
  
  // You execute my_program_1 and take input from file /home/user/somefile and produce output to file pointer fout3 which is created for you
  const char *ap3[] = {"my_program_1", "-switch", "40", "-fast", NULL};
  FILE *fin1 = fopen ("/home/user/somefile", "r");
  FILE *fout3 = NULL; // create temp file in cld_exec_program_with_in_out
  int st = cld_exec_program_with_in_out ("/usr/bin/my_program1", ap3, 4, fin1, &fout3);
  
  // Now you execute my_program_2 and you take input from fout3 (which contains output from my_program_1, we had it created above) and
  // produces output in fout4 which is file pointer we created for file /home/user/outfile, so the output from my_program_2 goes there.
  const char *ap3[] = {"my_program_2", "-switch", "50", "-fast", NULL};
  FILE *fout4 = fopen ("/home/user/outfile", "w+");
  int st = cld_exec_program_with_in_out ("/usr/bin/my_program_2", ap3, 4, fout3, &fout4);
  // now file /home/user/outfile has the final output from my_program_2 and fout4 is file pointer to it, and it is rewound
  // to the very beginning of the file. We can read it, or if the goal is just to have the file created, we can just close it now.
  fclose (fout4);
  

Output data and HTTP header

Outputting HTTP header, custom HTTP response headers

To output HTTP header for dynamically generated web pages, use cld_output_http_header:
In most cases, you'd just output header as shown above. This means a client (such as browser) is instructed not to cache since pages are dynamically generated in a typical scenario and content type is HTML.

If you however want to send a custom header, you can set it through header member of input_req:
In the above example, custom header is constructed and output.

Encoding data for output

To output data, use cld_printf or cld_puts.

• To web-encode (i.e. substitute & with &amp;, < with &lt; etc):
  
  int bytes_output =  cld_printf (CLD_WEB, "Output web-encoded like printf, using %s, %d etc, ", string, 100);
  
• To URL-encode (i.e. substitute space with %20 etc.):
  
  int bytes_output =  cld_printf (CLD_URL, "Output URL-encoded like printf, using %s, %d etc, ", string, 100);
  
• To print non-encoded (i.e. verbatim):
  
  int bytes_output =  cld_printf (CLD_NOENC, "Output not-encoded like printf, using %s, %d etc, ", string, 100);
  
• To output a single string:
  
  int bytes_output =  cld_puts (CLD_NOENC, "Output not-encoded string");
  int bytes_output =  cld_puts (CLD_URL, "Output URL-encoded string");
  int bytes_output =  cld_puts (CLD_WEB, "Output Web-encoded string");
  
  This outputs a single string, in different encodings.
  

Each of the above functions returns number of bytes written. Writing is typically buffered for maximum performance.

"Outputting data" means outputting to the web client, or the string. If the above functions are used within write-string and end-write-string (or API equivalents), the output goes to the string, otherwise it goes to the web client, except if the program is in batch mode. In batch mode, there is no output produced by these functions - you have to output data yourself (to a file, stdout, stderr etc.) or by using print-out and print-error markups. In batch mode, you can still write to a string and then output the string however you see fit.  

Output text without breaks

If you want to output text to web client and substitute new lines with <br/>s, use:
This outputs:

this is<br/>
some text<br/>

Disable and Enable HTML output, status of enablement

The output of text to web client can be enabled or disabled. By default it is enabled. In order to output a file, it has to be disabled.

To disable output:
To enable output:
You would disable HTML output when you want to output a file from your program, in which case you would output HTTP headers on your own (see cld_out_file()).

When HTML output is disabled, anything written so far into the web output buffer (that hasn't been output yet) is cleared. Also, anything output from that point onward is never written to the output buffer.

If you need to know if html output is enabled or disabled, use cld_is_disabled_output() function. It returns 1 if HTML output is disabled, otherwise 0.

Send files to the client and output HTTP headers for files

Use cld_out_file to send files to the client, for example images, documents etc. You can do this to display these files or to have the client download them.

Because the output from your program is always generated text, it is always sent to client with a note not to cache (unless you use custom headers).

For outputting files, however, you can control HTTP headers. cld_header data type can be used to control it:
Content type must be specified.
Default values disp and file_name are  NULL.
Default cache value is to cache almost forever (or rather for 53 years).
Default etag value is 1.
etc. up to CLD_MAX_HTTP_HEADER options. All options in control/value members must be continuosly present from index 0 up to whatever index is used.
By default, all custom fields are NULL.

An example:
Both cld_init_header and cld_out_file do not return a value.

Note that cld_out_file will error out if your file name has dot-dot (..) in it - such files will not be served to avoid dot-dot (or path-traversal) attacks. Your file name should never have dot-dot (i.e. "..") in it.

File not found (404)

To output File Not Found message (i.e. 404 code back to the web client), use:
To use this function, HTTP header must not have been output.

Flush output

The program output can be flushed with  cld_flush_printf:
The input parameter to this function is always 0. Returns -1 if no output could be flushed (meaning HTML output is disabled and no writing to string is happening now), or number of bytes written (0 or more).
Typically you don't need to call this function, and it may slow down the output if you do, even if your output is large, since flushing is done automatically when needed. In rare occassions you might use it, such as if your output consists of a number of parts and each part takes some time to compute.

Create new database document and a new associated file

Use cld_make_document:

Strings

Initialize, Copy, Append strings

The following functions are used for string creating and manipulation:

• Initialize string:
  
  char *str = cld_init_string("some init value");
  
  Variable str will have value of "some init value".
  
  To define an empty string faster than cld_init_string:
  
  CLD_DEFINE_STRING (empty_str);
  
  To initialize an existing string faster than cld_init_string:
  
  CLD_INIT_STRING (empty_str);
  
• Copy strings:
  
  char *str = cld_init_string ("some init value");
  
  int len = cld_copy_data (&str, "some new value");
  
  New value of variable str is "some new value" with variable len being its length.
  
  
• Copy integer as a string:
  
  char *str = cld_init_string ("some init value");
  
  int len = cld_copy_data_from_int (&str, 204);
  
  New value of variable str is "204" with variable len being its length.
  
  
• Copy string in the middle of another string. The string being copied to is resized to accomodate new size. Zero bytes is placed at the end.
  
  char *str = cld_init_string ("some init value");
  
  int len = cld_copy_data_at_offset (&str, 5, "entirely new");
  
  String "entirely new" will be written starting at offset 5 in variable str, so the new value of variable str is "some entirely new" with variable len being its length.
  
  This function simply copies string  at the given offset and terminates at the end of a string being copied. Everything from the given offset onward in the original string is lost.
  
  
• Append string:
  
  char *to_str = cld_init_string ("some init value");
  
  cld_append_string ("copy over", &to_str);
  
  The new value of variable to_str is "some init valuecopy over". This function does not return a value.
  
  
• Copy string up to given length:
  
  char *to_str = cld_init_string ("some init value");
  
  cld_strncpy(to_str, "hello", 3);
  
  This will copy maximum of 3 bytes, including zero byte, so variable to_str will have a value of "he", because the third byte will be zero terminator. This function does not return a value.

Output data to string

Program output normally goes to the web client. You can redirect it to a string by using:
In the above example, the first call to cld_write_to_string signifies that all output will go to variable str. This is so until the next call to cld_write_to_string happens with NULL parameter. The length of the string written can be obtained immediately after the closing call with cld_write_to_string_length.

Calls to cld_write_to_string can be nested, i.e.:
In this case the second cld_printf goes to my_str_1 variable, and not to my_str variable. Variable bytes_written_1 has the length of this output only. The result for the first cld_printf is the same as before.

cld_write_to_string can be used to capture page output:
In this above example, the output (Hello!... up to and including <hr/>) is written into my_str string, which is then output.

Change case of strings (upper, lower)

To lower or uppercase a string, use:
Variable my_str is now "some string".
Variable my_str is now "SOME STRING".

Both cld_lower and cld_upper return the input string, in this case they would both return my_str.

Substrings

• To count the number of substrings, use cld_count_substring:
  
  int num = cld_count_substring ("Hello world, and welcome to the world!", "world");
  
  In this example, variable num will have a value of 2. Strings are searched case-sensitive.
  
  
• To search and replace substrings, use cld_replace_string:
  
  char str[100];
  cld_strncpy (str, "Hello world, and welcome to the world!", sizeof(str));
  char *past_last;
  
  int num = cld_replace_string (str, sizeof(str), "world", "life", 1, &past_last);
  
  In this case, variable num would be 2 (number of replacements), and str would be "Hello life, and welcome to the life!". Variable past_last would be the pointer to the very first character past the last substitution, and here it would point to the final "!". The argument prior to the last is 1, and it signifies to search and replace all occurances. If it were 0, only the first occurance would be replaced:
  
  int num = cld_replace_string (str, sizeof(str), "world", "life", 0, &past_last);
  
  Variable num would be 1, and str would be "Hello life, and welcome to the world!".
  
  The last argument is optional if you don't care about where the search and replace ended:
  
  int num = cld_replace_string (str, sizeof(str), "world", "life", 0, NULL);
  
  The function returns the number of occurances/replacements, or -1 if the buffer was too small to complete the replacements. Strings are searched case sensitive.
  
  If -1 is returned, whatever substitutions could have been made (i.e. the buffer was big enough for them), were actually made, and it will stop when the buffer would be too small for the next one. Use the 6th parameter to know what was the last location where substitution was made.
  
  
• If you want Cloudgizer to allocate the space for the result of search and replace (including when additional space is needed) , use cld_subst:
  
  char *str = cld_init_string ("1 two 1 three");
  char *search = "1";
  char *replace_with = "one";
  cld_subst (&src, search, replace_with, 1);
  
  In this example, 'src' variable will be:
  
  one two one three
  
  Parameter 'src' must be allocated by define-string or cld_malloc (or such). Second parameter is replaced with the third in 'src'. Fourth parameter is 1, meaning to substitute all occurances - if it were 0 then only the first one would be substituted. Variable 'src' will be allocated more memory if needed for search and replace to complete.
  

Trim string

To trim string of whitespace both on left and right, use cld_trim:
Variable str will be "ABC" and len will be 3 (i.e. the new length). This function doesn't return a value.  

Break down string into an array of strings based on a delimiter

Often times a string needs to be broken down into pieces based on a variable delimiter. To do that, use cld_break_down:
The output would be:

Name is name, value is value
Name is name1, value is value1
Name is name2, value is value2

The string to_break is broken by inserting zero characters, for better performance. If you want it unchanged, use cld_strdup to make a copy first, and then break down the copy. The variable 'broken' (of cld_broken type) has num_pieces member (the number of pieces broken down to) and pieces (the array of pieces).  

In the above example, we first break down the original string into pieces separated by "+", and then break those down separated by "=" (in general the separator is any string). Since the original string is broken down, you can also traverse the pieces by reading them zero-terminated one by one from the original string to_break.

This is an efficient way of breaking down a string without making any copies.

Clear Unused variable error

It is a good practice to delete unused variables, but sometimes they cannot be. To prevent compiler warnings, use:

Error reporting

Fatal errors (resulting in program termination) can be reported by cld_report_error which takes the arguments the same as printf and returns number of bytes written:
To report errors and do not exit, use:
In either case, any currently open database transactions are rolled back.

Encryption and hashing

Cloudgizer uses 256 bit SHA hashing and AES encryption. The cipher used is AES-256-CBC.

Hashing

To create a 256-bit SHA hash, use cld_sha:
Variable hash now contains hashed value of "some value to hash". This is a string terminated by null character, always 64 bytes in length. Hashed value might look something like 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'.

Encrypting data

Use cld_aes_encrypt, for example:
The output of the function ('encrypted_data') contains encrypted data, which is allocated by Cloudgizer.

In  the above example, we first create an encryption context out of password and salt ("password" and "salt" in the above example) and encrypt string 'to_encrypt' of length 'len'. The fourth parameter is 0 (character mode of encryption), meaning the result is the character string (i.e. the encrypted value is null-terminated and suitable for using in database varchar columns, for example).  If the fourth parameter is 1 (binary mode of encryption), the result is a binary encrypted string.

If it is character mode, then the encrypted output will be converted into a string of hexadecimal characters (i.e. ranging from '0' to '9' and from 'a' to 'f') terminated by null character. The maximum size of a buffer of encrypted string is 2*(length_of_input_string+16)+1. This accounts for the maximum of 16 bytes extra for AES, and double for hexadecimal representation (in case of character mode of encryption).  Character mode of encryption is convenient if the result of encryption should be a human readable string, or for the purposes of non-binary storage in the database.

Variable 'len' holds the length (in bytes) of data to encrypt, and on return it holds the length (in bytes) of the encrypted data (excluding zero byte at the end if the fourth parameter is 0, i.e. if the result is a character string).

The salt can be NULL in which case no salt is used.

Decrypting data

Use cld_aes_decrypt. If 'encrypted_data' is encrypted data produced by cld_aes_encrypt:
The output of the function ('decrypted_data') contains decrypted data, which is allocated by Cloudgizer.

In  the above example, we first create a decryption context out of password and salt ("password" and "salt" in the above example) and decrypt string 'encrypted_data' of length 'len'. The fourth parameter is 0, meaning that 'encrypted_data' is a character string produced by cld_aes_encrypt with fourth parameter of 0. When decrypting, password, salt and the mode of encryption (binary or character) must match between cld_aes_encrypt and cld_aes_decrypt.

Variable 'len' holds the length (in bytes) of encrypted data (excluding zero byte at the end in case of character mode of encryption), and on return it holds the length (in bytes) of the decrypted data (excluding zero byte at the end which is always placed at the end of decrypted data).

Generating random string

To generate a random string (null-terminated) use cld_make_random(). For example, to generate a random string, use:
Variable 'rnd' now holds random string of length 19. The buffer 'rnd' must be at least a byte longer than the length of random string you desire, to accomodate null terminator.

Storing and retrieving data in a sequential list (FIFO)

To store data in a sequential list, and be able to rewind to the beginning and retrieve later, use functions related to cld_store_data type:

Executing Cloudgizer program from command line (Batch processing)

Using batch processing

Batch processing is using the program as a command line program. To enable batch processing, use cld_enable_batch_processing:
Batch processing disables web output (HTML output). Only output to a string will work, while web output will not. You can output to stdout and stderr (either via C functions like printf or via markups like print-out and print-error), and read from stdin. A batch program can still receive input parameters via URL, through environment variables, much like web server would:
When writing QUERY_STRING, make sure that actual data is URL encoded. For that, use -urlencode option for cld command line utility, like in this example:
cld -urlencode "hello world" will output URL encoded "hello world" string, with space substituted with '%20'. This output is stored into an environment variable, and its contents then used in QUERY_STRING as URL-encoded string for a URL passed to your program.

In the above bash example, REQUEST_METHOD is set to GET, and QUERY_STRING is set to request's input parameters in URL notation. You must set CLD_BATCH_PROCESSING to yes, and examine it in your program:
In this program, cld_ctx_getenv is first used to enable batch processing with cld_enable_batch_processing, meaning there is no web output. However, you can use most all other features such as working with input parameters, writing strings, queries etc. In the end, the program outputs to standard output:

List of employees
<hr/>
Linda,2001<br/>
John,2003<br/>
<hr/>

Batch programs can be often written together with web programs if their business logic is intertwined. Effectively you can write programs that could be used as both web and command-line programs, for example:
The above program can be called both from the web client to output a list of employees, and it can output this list to standard output. The URL parameters used are the same. Batch program's output would be the same as above, while the output to web client would be (for URL such as http://myserver.com/go.your_app_name?page=home&action=employees):

List of employees

---

Linda,2001
John,2003

---

Exit code for batch processing

To set exit code for a command-line program, use:
This sets exit code to 3.

POST URL (web call)

To perform a web call via HTTP/HTTPS:
The function returns 1 on success and 0 on failure. Variable error has error text in case of failure. If HTTPS is used the location of certificate file can be provided in variable cert. If cert is NULL, certificate is not checked. The actual response (minus headers) is stored in variable response. Response that redirects to another URL will be followed up to 4 times. The response is the body message, not the headers.

Files

File storage

You can read and write any files accessible to you, using either standard C mechanisms, or the file API explained in this documentation.

You can also use a provided file storage under 'file' directory - see more about this file storage.

To create a file in this file storage, use the following code:
Output variables are document_id (containing the unique ID of the file created, produced by using cldDocumentGenerator table), document_file (containing unique file name with a complete path to it), and file descriptor 'f' as the file created is opened and ready to write to.

You'd typically store file ID and its path in the database, and use them to later manipulate the file (read, write, delete etc.).

Get file size

To get the size of a file:
The return value will be -1 if cannot open file or its size.

Copy files

This copies from file from_file to file to_file. The result is -1 if cannot open from_file, -2 if cannot open to_file, -3 if cannot read from_file, -4 if cannot write to_file, and 1 on success.

Read entire file into a string variable

This reads file my_file into string variable file_data, which is cld_malloc() allocated (like all Cloudgizer memory is). Variable 'result' is -1 if cannot open my_file, -2 if cannot read my_file, and the size of the file read (0, or a positive number) if reading succeeded.  

Write whole file from a string

This writes "some content" to my_file. Variable 'result' is -1 if cannot open my_file, -2 if cannot write it, and 1 if writing succeeded. The whole file is overwritten with the new content.

Append to file from a string

This appends "new content" to the end of my_file. Variable 'result' is -1 if cannot open my_file, -2 if cannot write it, and 1 if writing succeeded.

Lock a file

You can create a file and lock it so your process has exclusive read and write lock on it. This can be useful as a process control means, for example to ensure only one process can continue work.
The function returns -2 if file path is invalid, -1 if cannot open file, 0 if cannot lock, and 1 if locked.

The process must not close stdout, stderr or stdin while file lock is in effect.

The file stays locked until the program ends, or until it's closed, for instance:

Get application home directory

Application's home directory is a directory named after application name located directly under the home directory of the user who executes the program:
If cannot determine application home directory, empty string ("") is returned.

Application's home directory is based on application name, which you can obtain via cld_app_name().

Check if directory

To determine if something is a directory:
Variable is_dir will be 1 if something is a directory, 0 otherwise.  

Temporary files

To store temporary files, use temporary directory:

Send email

To send email via sendmail, use:
Variable 'result' is the exit code of sendmail program. In the previous example, 4th parameter was NULL, meaning no additional header was added to the email. Email sender is 'from' and recipient 'to', followed by the subject of the message, while the message itself is the 5th parameter.

If you want to add custom headers to the email sent (for example to send HTML email, for attachments etc.), you can add them:

Queries and Transactions

SELECT from the database

'nrow' is the number of rows returned. 'ncol' is the number of columns. 'colnames' is a list of column names returned. 'data' holds all column data in order in which it is retrieved (first all columns from the first row, then from the second etc.), for example if there are two columns returned then data[0] is the first column of the first row, data[3] is the second column of the second row etc.

'data' can be NULL, while 'colnames' cannot be NULL. Maximum  number of output columns is 1000.

To get column names only, without the data:
In this case, col_names[0] is the name of the first column, col_names[1] is the name of the second column and so forth.

This function does not return value, and its failure will stop the program (i.e. it is expected to always succeed).  

Get value from auto-increment column

Insert into a table with auto increment column produces new value for it. To obtain it:
'val' is the output buffer. This function must be called immediately after INSERT and it does not return a value.

Execute any SQL other than SELECT, including DDL statements

Varable 'rows' is the number of rows affected, 'er' is the error number, and 'err_message' is the error message. If failed, the function returns 0, otherwise 1.

Use this to execute any SQL, including DDL (Data Definition Language) such as CREATE TABLE, DROP TABLE etc.

Check for open transaction

If input parameter is 1, the function returns 1 if there is an open transaction and 0 if not. If input parameter is 0 then it will report an error if there is an open transaction and it will return 0 if not.

If input parameter is 2, and there is an open transaction, rollback this transaction and return 0.

Get miscellaneous

Get web address for forms and links

Web address (for forms and links) is obtained from config file under web_address field. You can get it from:

Get Base URL of server

Base URL for "https://myserver.com/go.your_app_name?par1=val1" is "myserver.com". To obtain it, use cld_web_name and pass any URL leading to the server:
This will produce the base name of a web server running the program.

Get version

The software version can be obtained via following call:

Get current, past or future time, including GMT

To get current, past or future time, suitable for cookies, use cld_time:
Returns time (now, in the future, or the past). Input parameter 'timezone' is the name of TZ (timezone). So to get GMT time then timezone should be "GMT", if it is Mountain Standard then it is "MST" etc.

Input parameters year,month,day,hour,min,sec are the time to add to current time (they can be negative too). So for example ..(0,0,1,0,0,1) adds 1 day and 1 second to the current time, while ..(0,-1,0,0,0) is one month in the past.

Get current time

To get current time, per local time zone, use cld_current_time. The arguments are the buffer where the time should be stored and its length:
The time returned shows year, month, day of month, hour, minute, second, separated by a dash, such as '2017-07-30-18:48:13', with hours in 0-24 range.

Get application name

Application name can be obtained via  cld_app_name function call, this is the same as CLD_APP_NAME in appinfo file during installation.
Application's home directory is based on it. Always use cld_home_dir() to get the application home directory.

Get environment variable (web or command shell)

Environment variables can be available from the operating system or the web server. If the program is running in batch mode (i.e. command line), the environment used is that of the OS. When a program is running within a web server, first web server's variables are searched for a match, and if not found, the OS environment is used. The call that does this is cld_ctx_getenv:

---