vely:get-req

get-req

Purpose: Obtain data that describes the input request.

get-req \
    data | errno | error | cookie-count | cookie <cookie index> \
        | arg-count | arg-value <arg index> | input-count | \
        | input-value <input index> | input-name <input index> \
        | header <header> | referring-url | method \
        | content-type | trace-file | process-id | name \
    to [ define ] <variable>

Variables related to an input request can be obtained with get-req statement and the result stored into <variable>. The following request variables can be obtained (they are strings except where stated otherwise):

"data" obtains the pointer to global_request_data.
"errno" obtains the integer value of operating system "errno" tied to a last Vely statement that can return a status code. The "errno" value is saved internally; and restored here. It means that if "errno" changed for whatever reason since such Vely statement, you will still obtain the correct value. See error_code for an example. Note that errno value is undefined if there is no error, and can be 0 if the error is reported by Vely and not by operating system.
"error" returns the error message (a string) that correlates to "errno" value. The result of "error" clause is allocated memory.
"cookie-count" returns the number of cookies. This means any cookies received from the client plus any cookies added (with set-cookie) in the application minus any cookies deleted (with delete-cookie).
"cookie" returns the cookie value specified by <cookie index> (a number (0, 1, 2...) up to number of cookies), for instance in the block of C code:
```
num i;
get-req cookie-count to define cookie_c
for (i = 0; i < cookie_c; i++) {
    get-req cookie i to define cookie_val
    pf-web "cookie %s\n", cookie_val
    @<br/>
}
```
In this example, we get the number of input parameters, and then print out each name/value pair.
"arg-count" is the number of input arguments to your application (passed from a program caller, see vv).
"arg-value" is the string value of a single element from the array of input arguments, specified by <arg_index>. This array is indexed from 0 to one less than value obtained by "arg-count". Here is an example of using arg-count and arg-value:
```
get-req arg-count to define ac
pf-out "Total args [%lld]", ac
num i;
for (i=0; i<ac; i++) {
    get-req arg-value i to define av
    pf-out "%s\n", av
}
```
This code will display the number of input arguments (as passed to main() function of your program, excluding the first argument which is the name of the program), and then all the arguments. If there are no arguments, then variable 'ac' would be 0. See vv on passing arguments to your application.
"input-count" is the number of input parameters (from a request). Together with input-name and input-value, this lets you examine all input parameters in a request, especially in situations where the parameters are dynamic in nature.
"input-name" is the string value of a single element from the array of input parameter names (from a request), specified by <input_index>. This array is indexed from 0 to one less than value obtained by "input-count". See "input-value" for an example.
"input-value" is the string value of a single element from the array of input parameter values (from a request), specified by <input_index>. This array is indexed from 0 to one less than value obtained by "input-count". For example:
```
num i;
get-req input-count to define input_c
for (i = 0; i < input_c; i++) {
    get-req input-name i to define input_n
    get-req input-value i to define input_v
    pf-web "Input parameter #%lld, name is %s, value is %s\n", i, input_n, input_v
    @<br/>
}
```
In this example, we get the number of cookies, and then print out each. The cookie value is the full cookie string, including expiration date, strictness etc.
"header" is the value of HTTP request header <header> that is set by the client. For example, if the HTTP request contains header "My-Header:30", then hval would be "30":
```
get-req header "My-Header" to define hval
```
Note that not all HTTP request headers are set by the caller. For example, SERVER_NAME or QUERY_STRING are set by the web server, and to get such headers, use get-sys.
"method" is the request method. This is a number with values of VV_GET, VV_POST, VV_PUT, VV_PATCH or VV_DELETE for GET, POST, PUT, PATCH or DELETE requests, respectively. If it is not any of those commonly used ones, then the value is VV_OTHER and you can use get-sys with "web-environment" clause to obtain "REQUEST_METHOD" variable.

If you are writing a REST API, then you can use the method to implement Create, Read, Update, Delete (CRUD) operations, for instance:
```
get-req method to define request_method
if (request_method == VV_POST) {
    // create resource action
}
if (request_method == VV_GET) {
    // read resource action
}
if (request_method == VV_PUT) {
    // replace resource action
}
if (request_method == VV_PATCH) {
    // update resource action
}
if (request_method == VV_DELETE) {
    // delete resource action
}
```
"content-type" is the request content type. It is a string and generally denotes the content type of a request-body, if included in the request. Common examples are "application/x-www-form-urlencoded", "multipart/form-data" or "application/json".
"referring-url" is the referring URL (i.e. the page from which this request was called, for example by clicking a link).
"trace-file" is the full path of the trace file for this request (if enabled, see vv).
"process-id" is the "PID" (process ID) number of the currently executing process, as an integer.
"name" is the request name as specified in the request_URL.

Note that all the string values above (except "data") should be treated as constants - do not change them as that may cause program to malfunction. If you want to alter any of these values, make a copy first (see copy-string).

Examples

Get the name of current trace file:

get-req trace-file to define trace_file