So, why is this useful to me? OWA_UTIL holds a significant amount of information about the environment in which your ORDS PL/SQL handler is being called. This includes information such as the character set, host name, port, web service name and even information about the caller of the service such as the user agent.
In this post I will take you through an example of how to tap into the CGI information available to you in OWA_UTIL. Before we get started, however, you should know that the OWA environment is only available for ORDS POST, PUT and DELETE services. The OWA environment is not set for Collection or Query GET handler types.
What CGI Variables are Available?
First of all, let's create a basic ORDS module, resource template and GET handler to use for our CGI tinkering. The slide show below, illustrates my example service:
curl -X GET -H "Accept: application/json" -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"
After running the CURL command, you should see a list of the CGI variables, I have a link below to a file with the full response but wanted to illustrate some some of the more interesting ones:
- accept = application/json
- APEX_LISTENER_VERSION = 22.214.171.124.10.54
- REQUEST_METHOD = GET
- PATH_INFO = /owablog
- SCRIPT_NAME = /ords/ordstest/master
- REMOTE_USER = ORDSTEST
- REQUEST_CHARSET = AL32UTF8
- REQUEST_IANA_CHARSET = UTF-8
- REQUEST_PROTOCOL = https
- REQUEST_SCHEME = https
- SERVER_NAME = example.com
- SERVER_PORT = 443
Having this information available opens up some interesting possibilities:
- You can develop a generic logging API to log web service calls. A combination of PATH_INFO, SCRIPT_NAME and REQUEST_METHOD can be used to identify the service and log all your web service calls to to a log table.
- The caller of the service (in this case our CURL command) indicated they wanted a JSON response. Having access to this HTTP header value is key in us being able to honor this response. Of course, in this case we could have added a parameter to our handler to get this HTTP header value from a bind variable.
- If you have some code that is ORDS version specific, it may be handy to know the version of ORDS which is running.
Referencing Individual Values
The short answer is to use 'owa_util.get_cgi_env'. You simply pass the name of the variable you want and it will return the value. Let's change the Handler for our GET service so that it responds with the URL used to call the web service.
curl -X GET -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"
We should get the following:
You called me with: https://example.com:443/ords/ordstest/master/owablog