NAME

       get-req -  (request-information)

PURPOSE

       Obtain data that describes the input request.

SYNTAX

           get-req \
                   errno | error | cookie-count | cookie <cookie index> \
                   | arg-count | arg-value <arg index> \
                   | header <header> | referring-url | method \
                   | content-type | trace-file | process-id | name \
                   | external-call | directory | source-file
               to <variable>

DESCRIPTION

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

           • "errno" obtains the integer value of operating system "errno" tied to a last  Golf  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 Golf statement (such as with call-extended), 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 Golf and not by operating system.

           • "error" returns the error message that correlates to "errno" value.

           • "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 sequential number starting with  1
           up to the number of cookies), for instance:

               get-req cookie-count to cookie_c
               start-loop repeat cookie_c use i
                   get-req cookie i to cookie_val
                   print-format "cookie %s\n", cookie_val web-encode
                   @<br/>
               end-loop

           In this example, we get the number of cookies, and then print out each cookie value.

           • "arg-count" is the number of input arguments to your application (passed from a program caller, see
           "-a" option in mgrg and "--arg" in gg).

           • "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 1 to the value obtained by "arg-count". Here is an example of
           using arg-count and arg-value:

               get-req arg-count to ac
               print-format "Total args [%ld]", ac
               start-loop repeat ac use i
                   get-req arg-value i to av
                   print-format "%s\n", av
               end-loop

           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.

           •  "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 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 GG_GET, GG_POST, GG_PUT, GG_PATCH
           or GG_DELETE for GET, POST, PUT, PATCH or DELETE requests, respectively. If it is not  any  of  those
           commonly  used  ones, then the value is GG_OTHER and you can use get-sys with "environment" clause to
           obtain "REQUEST_METHOD" variable.

           • "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).

           • "directory" is the current working directory, which is by default the  application  home  directory
           (see  directories)  and  can be changed with change-dir. Note that maximum length of a directory path
           should not exceed 1024 bytes.

           • "trace-file" is the full path of the trace file for this request (if enabled, see trace-run).

           • "process-id" is the "PID" (process ID) number of the currently executing process, as a number.

           • "external-call" is a boolean that is true if the call to the current request  handler  is  from  an
           external caller, or false if called from another handler.

           • "source-file" is the name of the current source file (a string).

           • "name" is the request name as specified in the request URL.

EXAMPLES

       Get the name of current trace file:

           get-req trace-file to trace_file

SEE ALSO

        Request information

       get-req See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)