The GETURI API interface allows you to retrieve data from a URI from within a program. The API is used by calling the GETURIRG program passing in the specified parameters and specifying *RETURN as the output type. The API will then return the request data to the calling program
The data returned to the API is a maximum of 32767 bytes. If you require any more data to be returned then you should use the GETURI command to retrieve the information to a stream file and then process that stream file.
Required Parameter Group:
The Input Data Structure and Receiver Variable are included as a /COPY member in the GETURI library. It is located in file QCOPYSRC member GETURICOPY. It is defined as follows:
D GetUri_In DS
D GetUri_Out S 65535
Listed below are descriptions of each of the input fields used with the GETURI API (GETURIRG). If a field is noted as Required you must specify a value. For all other parameters they may be left blank or zero. If default values are to be used they are specified.
Before loading the values you should be sure to initialize the GetUri_In data structure.
Enter the URI to be used. Do not include any data (GET or POST) parameters on this command. Example: www.myserver.com/apps/getcustomer.asp
Note: In GETURI 3.42 and higher this parameter is 256 bytes instead of 128.
Specify the output type to be used. When using the GETURI API to return a value to your application, this value should be set to *RETURN. If you wish the data to be returned to the calling program without being converted to EBCDIC, the value of *RETNC may be used. This value can also be *FILE to return the data to a physical file, or *STMF to return the data to a stream file.
GI_UserAgent (Default: Mozilla/4.0 (compatible; MSIE
5.5; Windows 98))
Enter the user agent that you wish to be used for the request. This parameter may or may not have an affect on the success of the request. If you are having problems you can try a common user agent value such as "Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)" (without the quotes).
Specify the data you wish to pass to the application for a GET or POST as name-value pairs. For example: name=Brad&age=45&eyecolor=blue. If you are including a large amount of data you can specify *STMF on this parameter so that the URL string will be read from a pre-created stream file. You can also specify *PARM for this value and use the GetUri_Data parm to pass in up to 65k work of data. Specifying *MULTIPARM will create a multi-parm form using the data in the GetUri_Data parameter followed by the data in the GI_Data parameter.
If *STMF or *MULTIPARM was specified on the URL String parameter, specify the fully qualified path of the stream file containing the URL String data.
Specify the IP address or DNS-resolvable name of a proxy server if required.
GI_Port (Default: 80)
Enter the port number used to make the request. If you are using a proxy server, this should be the proxy server port that is used. In this case, if you are making a URI request from a server on a port other than 80, you will need to specify that port in the URI request. For example www.myserver.com:442.
GI_ReqMeth (Default: GET)
Specify the request method used for the URI request. The valid values are HEAD, GET, and POST.
GI_Accept (Default: text/html)
Specify the type of data that you will accept. This value should be in a valid content-type form (such as "text/html").
GI_Host (Default: localhost)
Specify the host name that will be sent with the request.
In version 3.41 and up the default is *DFT which will default the host to the domain used in the requst.
Specify any cookie data to be sent with this request. If you are unfamiliar with how to format this data then you should read RFC2109 at http://www.w3.org/Protocols/rfc2109/rfc2109.
Specify the value to be used as the referer for this request.
Specify a value to sent with the Connection HTTP header. For example the value "keep-alive" may be used.
GI_ContType (Default: *DFT)
Specify the content type of the request. The value of *DFT will specify the content type of application/x-www-form-urlencoded. If you are uploading a file using GETURI this parmater will be ignored and the value of multipart/form-data; boundary=<boundaryid> will be used.
GI_Proto (Default: HTTP)
Specify the protocol being used.
GI_HTTPVer (Default: 1.0)
Specify the protocol version being used.
Specify the number of user defined generic headers to be used.
user defined generic headers to be used in this array. Specify the special value of *STMF in order to use a stream file that contains headers.
user defined generic header data to be used in this array. Each element
should relate to a header in the GI_UsrHdr array. If a matching element has the value *STMF, then this should contain the path to a stream file in the IFS.
Specify the library and physical file to be used to store the data results if *FILE was specified on the GI_OutType parameter. The first ten characters should be the file name and the second ten characters should contain the library name.
Specify the name of the physical file member to store the data results if *FILE was specified on the GI_OutType parameter.
Specify the fully qualified path of the stream file to store the data results if *STMF was specified on the GI_OutType parameter.
Specify *YES on this parameter if you are simulating an HTML file upload web page.
Specify the fully qualified location of the stream file that you will be uploaded if *YES was specified for the Upload File parameter.
GI_UpName (v3.35 and up)
Used to specify the name of the file as the server will see it. Default will be the file name specified on GI_UpStmf.
When specifying *YES for the Upload File parameter, you will need to name the form field from the upload page that you are simulating.
When specifying *YES for the Upload File parameter, specify the content-type of the file being uploaded.
If using Basic Authentication on this request, specify the user id on this parameter.
If using Basic Authentication on this request, specify the password on this parameter.
If using a proxy on this request that requires a user id and password, specify the proxy user id on this parameter.
If using a proxy on this request that requires a user id and password, specify the proxy password on this parameter.
If making a Secure Sockets Layer (SSL) request, specify *YES on this parameter.
Used to assign an application ID for GETURI. Default is blank (none).
GI_CStore (v 3.25 and up - Default: *SYSTEM)
Specify the certificate store to use with the SSL request. This value defaults to *SYSTEM which will specify to use the system certificate store. If you wish to use another certificate store, specify the qualified location of the store.
GI_CPW (v3.10b and up)
Specify the certificate password, if applicable.
Specify a value in seconds to cause a timeout during an SSL handshake. A value of *NONE will specify no timeout value.
GI_Timeout (Default: 30)
Specify a value in seconds for a time out on the request.
GI_CodPag (Default: 819)
Specify a code page to be used when creating stream files.
GI_Close (v3.25 and up - Default: *YES)
Specify whether to close the connection or not after the request has completed. Leaving the connection open may increase performance with multiple calls to the same server.
Specify *YES to debug the request that was made. Specify *OFF to tell GETURI to not send any messages during the running of the command.
Specify the fully qualified path and file name of the debug file. If this is left blank this will default to /tmp/geturidebug.txt. A file with the .log extension will also be created to show a trace of the communications during the call (ie, /tmp/geturidebug.txt.log).
Specify the CCSID to use for EBCDIC to ASCII and ASCII to EBCDIC translations. This parameter will override the tables if specified. If you wish to use the tables instead of the CCSID for translations, specify 0 (zero) for this value.
Specify EBCDIC to ASCII translation table to be used. This is normally QTCPASC but can be other table depending on the code page you may be using. In some cases using code page 37 table Q037337850 works better. The table used must reside in library QUSRSYS.
Specify the ASCII to EBCDIC translation table to be used. This is normally QEBCDIC but can be a different table depending on the code page you may be using. The table used must reside in library QUSRSYS.
Specify an IP address if you wish to bind the request to a specific Local IP address.
Specify a port number if you wish to bind the request to a specific IP/Port combination. This value is only valid if a value is specified for GI_LocalIP.
Specify *YES to supress HTTP headers or *NO to not supress HTTP headers. If *YES is specified and *STMF is the output type, a file named "xxxxx.hdr" will be created (where "xxxxx" is the filename specified to contain the output) that will contain the headers. If *YES is specified and *STMF or *RETURN is used as the output type, the headers will be returned in the GetUri_Head parameter.
Specifies if the HTTP headers should be sent with the request. specifying anything other than *YES, the request must be a POST. *YES will tell GETURI that all HTTP headers as well as the user defined headers are se the request. *NO will tell GETURI that no HTTP headers are sent with the request and only the data data parameter are sent as-is. The value of *USRHDR means that only the user defined headers are sent with the request.
Specify the content type of the data in the GetUri_Parm field when specifying *MULTIPARM for GI_Data
Specify the content type of the data in the file specified in GI_DStmf when specifying *MULTIPARM for GI_Data
The receiver variable is used to return the data retrieved from the URI. The field is named GetUri_Out in the included /COPY member.
The header receiver variable is used to return the HTTP headers. The headers from the response will always be contained in this variable.
The data variable is used to pass up to 65k worth of data to the application instead of specifying data in the GI_Data parm or using a stream file. To use this variable you must specify the special value of *PARM for GI_Data
The message code will contain the completed message code after the call to the GETURI API. C=Completed, E=Error, D=Diagnostic.
The message text will contain a description of the messages returned by GETURI.
Following is a simple example of using the GETURI API interface.