Chapter 2 - The GETURI API Interface (GETURIRG)

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
  • Input Data Structure
  • Receiver Variable
  • Header Receiver Variable
  • Data Variable
  • Message Code
  • Message Text
  • Example

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  GI_URI                      256                                         URI               
 D  GI_OutType                   10                                         Output Type       
 D  GI_UserAgent                128                                         User Agent        
 D  GI_Data                    2048                                         Data              
 D  GI_DSTMF                    256                                         Data Stream File  
 D  GI_Proxy                    128                                         Proxy             
 D  GI_Port                      10i 0                                      Port              
 D  GI_ReqMeth                   10                                         Request Method    
 D  GI_Accept                   128                                         Accept            
 D  GI_Host                      64                                         Host              
 D  GI_Cookie                  4096                                         Cookie            
 D  GI_Referer                  128                                         Referer           
 D  GI_Connection               128                                         Connection        
 D  GI_ContType                 128                                         Content Type      
 D  GI_Proto                     20                                         Protocol          
 D  GI_HTTPVer                   10                                         ProtoVersion      
 D  GI_NbrHdrs                   10i 0                                      Number of Headers 
 D  GI_UsrHdr                   128    DIM(20)                              User Headers
 D  GI_UsrHdrDta               2048    DIM(20)                              User Header Data
 D  GI_File                      20                                         Output File
 D  GI_Mbr                       10                                         Output Member
 D  GI_STMF                     128                                         Stream File
 D  GI_UpFile                     4                                         Upload File 
 D  GI_UpStmf                   128                                         Upload Stream File
 D  GI_UpName                   128                                         Upload File Name (v3.35 and up)
 D  GI_UpField                   64                                         Upload Field Name
 D  GI_UpCont                    64                                         Upload File ContType
 D  GI_BUser                    128                                         Bas Auth User
 D  GI_BPW                      128                                         Bas Auth PW
 D  GI_PUser                     64                                         Proxy User 
 D  GI_PPW                       64                                         Proxy PW   
 D  GI_SSL                        4                                         SSL?
 D  GI_SSLApp                    64                                         SSL Application ID
 D  GI_CStore                   128                                         CertStore
 D  GI_CPW                       64                                         Cert Password
 D  GI_SSLTime                   10i 0                                      SSL Timeout
 D  GI_Timeout                   10i 0                                      Timeout
 D  GI_CodPag                    10i 0                                      Code Page
 D  GI_Close                      4                                         Close connection
 D  GI_Debug                      4                                         Debug 
 D  GI_DebugFile                256                                         Debug File  
 D  GI_CCSID                     10i 0                                      CCSID (v3.36 and up)
 D  GI_EATable                   10                                         EBCDIC to ASCII
 D  GI_AETable                   10                                         ASCII to EBCDIC
 D  GI_LocalIP                   32                                         Bind Local IP      
 D  GI_LocalPort                 10i 0                                      Bind Local Port    
 D  GI_SprHead                    4                                         Supress Headers    
 D  GI_HTTPHead                   7                                         Send HTTP Headers
 D  GI_PContType                 64                                         Parm Content Type 
 D  GI_SContType                 64                                         STMF Content Type     
 D  GI_SSLMode                   10                                         SSL Mode 
 D  GI_SNI                      256                                         SNI      
 D GetUri_Out      S          65535    
 D GetUri_Head     S          65535                                         Returned HTTP Header 
 D GetUri_Data     S          65535                                         Data Input Parm   
 D GetUri_MsgCd    S              1                                         Error Code        
  * C = Completed, E = Error, D = Diagnostic                                                  
 D GetUri_Msg      S          65535                                         Returned Errors   

Input Data Structure

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.

GI_URI (Required)

Enter the URI to be used. Do not include any data (GET or POST) parameters on this command. Example:

Note: In GETURI 3.42 and higher this parameter is 256 bytes instead of 128.

GI_OutType (Required)

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

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


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.


Specify the 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.


Specify the 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: 1208)

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


Specify to use the default SSL APIs (*DFT) or the GSKit SSL Functions (*GSKIT). The default is to use the system APIs but in the future this make change to GSKit as IBM seems to be dropping support for the "legacy" APIs.


Specify the Server Name ID (SNI) for the SSL communications. By default (*DFT) this will use the host name in the URI but it can be overridden if needed. This field is only valid when using *GSKIT for SSL communications.

Receiver Variable

The receiver variable is used to return the data retrieved from the URI. The field is named GetUri_Out in the included /COPY member.

Header Receiver Variable

The header receiver variable is used to return the HTTP headers. The headers from the response will always be contained in this variable.

Data 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

Message Code

The message code will contain the completed message code after the call to the GETURI API. C=Completed, E=Error, D=Diagnostic.

Message Text

The message text will contain a description of the messages returned by GETURI.


Following is a simple example of using the GETURI API interface.


  * GETURI API Parameters
 C                   EXSR      $LoadParms
 C                   CALL      'GETURIRG'                           99    
 C                   PARM                    GetUri_In                    
 C                   PARM                    GetUri_Out                   
 C                   PARM                    GetUri_Head                  
 C                   PARM                    GetUri_Data                  
 C                   PARM                    GetUri_MsgCd                 
 C                   PARM                    GetUri_Msg                   
 C                   SetOn                                        LR      
  * Load Parameters to call GETURIRG
 C     $LoadParms    BEGSR
 C                   CLEAR                   GetUri_In
 C                   eval      GI_URI = ''
 C                   eval      GI_OutType = '*RETURN'
 C                   ENDSR