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:

1 Input Data Structure Input Char(*)
2 Receiver Variable Output

Char(65535)

3 Header Receiver Variable Output

Char(65535)

4 Data Variable Input Char(65535)
5 Message Code Output Char(1)
6 Message Text Output Char(65525)

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 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: www.myserver.com/apps/getcustomer.asp

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

GI_Data

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.

GI_DSTMF

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.

GI_Proxy

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.

GI_Cookie

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.

GI_Referer

Specify the value to be used as the referer for this request.

GI_Connection

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.

GI_NbrHdrs

Specify the number of user defined generic headers to be used.

GI_UsrHdr

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.

GI_UsrHdrDta

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.

GI_File

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.

GI_Mbr

Specify the name of the physical file member to store the data results if *FILE was specified on the GI_OutType parameter.

GI_STMF

Specify the fully qualified path of the stream file to store the data results if *STMF was specified on the GI_OutType parameter.

GI_UpFile

Specify *YES on this parameter if you are simulating an HTML file upload web page.

GI_UpStmf

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.

GI_UpField

When specifying *YES for the Upload File parameter, you will need to name the form field from the upload page that you are simulating.

GI_UpCont

When specifying *YES for the Upload File parameter, specify the content-type of the file being uploaded.

GI_BUser

If using Basic Authentication on this request, specify the user id on this parameter.

GI_BPW

If using Basic Authentication on this request, specify the password on this parameter.

GI_PUser

If using a proxy on this request that requires a user id and password, specify the proxy user id on this parameter.

GI_PPW

If using a proxy on this request that requires a user id and password, specify the proxy password on this parameter.

GI_SSL

If making a Secure Sockets Layer (SSL) request, specify *YES on this parameter.

GI_SSLApp

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.

GI_SSLTime

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.

GI_Debug

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.

GI_DebugFile

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

GI_CCSID

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.

GI_EATable

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.

GI_AETable

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.

GI_LocalIP

Specify an IP address if you wish to bind the request to a specific Local IP address.

GI_LocalPort

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.

GI_SprHead

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.

GI_HTTPHead

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.

GI_PContType

Specify the content type of the data in the GetUri_Parm field when specifying *MULTIPARM for GI_Data

GI_SContType

Specify the content type of the data in the file specified in GI_DStmf when specifying *MULTIPARM for GI_Data

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.

Example

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

  ****************************************************************
* GETURI API Parameters
****************************************************************
/COPY GETURI/QCOPYSRC,GETURICOPY
****************************************************************
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 = 'www.bvstools.com'
C eval GI_OutType = '*RETURN'
*
C ENDSR

Comments