Embedded Files
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. The data can be returned to your program or a stream file.
Required Parameter Group
Required Parameter Group
Input Data Structure (GetUri_In) - Input - Char(*)
Receiver Variable (GetUri_Out) - Output - VarChar(1048576)
Header Receiver Variable (GetUri_Head) - Input/Output - VarChar(1048576)
Data Variable (GetUri_Data) - Input - VarChar(1048576)
Message Code (GetUri_MsgCd) - Output - Char(1)
Message Text (GetUri_Msg) - Output - VarChar(2048)
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 65535 URI
D GI_OutType 10 Output Type
D GI_UserAgent 128 User Agent
D GI_Data 65535 Data
D GI_DSTMF 256 Data Stream File
D GI_Port 10i 0 Port
D GI_ReqMeth 10 Request Method
D GI_Accept 128 Accept
D GI_Host 64 Host
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 2048 DIM(20) User Headers
D GI_UsrHdrDta 65535 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
D GI_UpField 64 Upload Field Name
D GI_UpCont 128 Upload File ContType
D GI_BUser 128 Bas Auth User
D GI_BPW 128 Bas Auth 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
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 A Varying Len(1048576) Returned Data
D GetUri_Head S A Varying Len(1048576) Returned HTTP Header
D GetUri_Data S A Varying Len(1048576) Data Input Parm
D GetUri_MsgCd S 1 Error Code
* C = Completed, E = Error, D = Diagnostic
D GetUri_Msg S A Varying Len(2048) Returned Errors
Input Data Structure
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.
The special value of *GETURI_HEAD will allow you to use the GetURI_Head (Header Receiver Variable) parameter as the URI. This is useful in cases where the URI may be larger than the GI_URI parameter allows.
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 and the data will be returned to the GetUri_Out parameter.
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 (not recommended), 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 or *STMFRAW (for no conversion of the data) 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, *STMFRAW or *MULTIPARM was specified on the URL String parameter, specify the fully qualified path of the stream file containing the URL String data.
GI_Port (Default: *DFT)
Enter the port number used to make the request. If *DFT is specified then the application will use port 80 if SSL is set to *NO, or 443 if it is set to *YES.
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_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. The value of *NONE will leave the Content-type header off the request. 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.1)
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_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: 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.
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.
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 *ALL is specified and *STMF is the output type no .hdr file will be created. 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
GI_SSLMode
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.
GI_SNI
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
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
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
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
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
Message Text
The message text will contain a description of the messages returned by GETURI.
Example
Example
Following is a simple example of using the GETURI API interface.
****************************************************************
/COPY GETURI/QCOPYSRC,GETURICOPY
****************************************************************
D GetUriRG pr extpgm('GETURIRG')
D PR_In like(GetUri_In)
D PR_Out like(GetUri_Out)
D PR_Head like(GetUri_Head)
D PR_Data like(GetUri_Data)
D PR_MsgCd like(GetUri_MsgCd)
D PR_Msg like(GetUri_Msg)
****************************************************************
/free
EXSR $LoadParms;
EXSR $GETURI;
*INLR = *ON;
//***************************************************************
//* Call GETUI
//***************************************************************
BegSr $GETURI;
GetUriRG(GetUri_In:GetUri_Out:GetUri_Head:GetUri_Data:
GetUri_MsgCd:GetUri_Msg);
// be sure to reference any of the variables defined now as varchar (varying)
// and the %addr() BIF to specify *DATA... ie:
// %addr(GetUri_Out:*DATA)
// docNode = yajl_buf_load_tree(%addr(GetUri_Out:*DATA):
// %len(GetUri_Out):j_errMsg);
EndSr;
//***************************************************************
//* Load Parameters to call GETURIRG
//***************************************************************
BegSr $LoadParms;
Clear GetUri_In;
GI_URI = 'www.webservice.com/application/function';
GI_SSL = '*YES';
GI_NbrHdrs = 1;
GI_UsrHdr = 'Authorization';
GI_UsrHdrDta = 'Bearer ' + %trimr(token);
GI_OutType = '*RETURN';
GI_SprHead = '*YES';
EndSr;
/end-free
Report abuse