RXS_getUri()

Sends an XML stream to an end point for the web service you are calling or consuming.

Required

This parameter allows you to describe the communication that will happen with the server on the other end of the line. The data structure is broken out below by field with a definition.

This parameter should be specified if you are not using an IFS file to hold your XML request but instead have it in an RPG variable. To get your XML into an RPG variable you would have specified RXS_VAR as the pOutType on RXS_initTplEng() and then used RXS_getBuffData(). Note that a max of 65535 bytes can be sent using this method. If more XML is to be sent then an IFS file should be used. If an IFS file is used you can use *OMIT to omit this parameter.

This parameter should be specified if you are not using an IFS file to hold your XML response but instead wish to have it placed in an RPG variable. Note that RPG-XML Suite can parse XML that resides in either an RPG variable or an IFS file. Note that a max of 65535 bytes can be received using this method. If more XML is to be received then an IFS file should be used. If an IFS file is used you can use *OMIT to omit this parameter.

This parameter will receive back the raw HTTP response headers which can be used for debugging purposes. *OMIT can be specified if you do not wish to receive back the HTTP response headers.

Enter the URI to be used. Do not include any data (GET or POST) parameters or port in this field. Use pInCfg.port to specify a specific port.

Example: http://www.myserver.com/apps/getcustomer.asp

Specify the output type to be used. When using the RXS_getUri to return a value to your application, set this value to RXS_VAR. To return the data to a physical file, use RXS_PHY_FILE. To return the data to a stream file, set the value to RXS_STMF. If you intend to parse the data using RXS_parse, use RXS_VAR or RXS_STMF. The parser does not parse XML stored in a physical file.

Valid Values:

• RXS_VAR
• RXS_PHY_FILE
• RXS_STMF

Default Value: RXS_VAR

Enter the user agent that you wish to be used for the request. This parameter may or may not have an effect on the success of the request. The default value previous to v2.70 was "Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)".

Default Value: KrengelTech HTTP Client

Specify constant RXS_STMF to have the XML request pulled from a file in the IFS or RXS_VAR if you are passing the XML in via an RPG variable through RXS_getURI parameter pReqData.

Valid Values:

• RXS_STMF
• RXS_VAR

Default Value: RXS_VAR

If RXS_STMF was specified on the ReqType parameter then specify the fully qualified path of the stream file containing the XML. If it resides in the default transaction directory, just specify it as 'mydoc.xml'.

Specify the IP address or DNS-resolvable name of a proxy server if required.

Enter the port number used to make the request. If using a proxy server, pass the proxy server port. In this case, if you make a URI request from a server on a port other than 80, that port must be specified in the URI request. For example, www.myserver.com:442

Default Value: 80

Specify the request method used for the web service request.

Valid Values:

• RXS_GET
• RXS_POST

Default Value: RXS_POST

Specify the type of data that you will accept. This value should be in a valid content-type form. The default value previous to v2.70 was "text/html".

Default Value: text/xml

Specify the host name that will be sent with the request. The default will be set to the host on the domain used in the request.

Default Value: localhost

Specify any cookie data to be sent with this request. Further instructions for formatting this data is available at RFC2109.

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

Specify a value to be sent with the Connection HTTP header.

Example: keep-alive

Specify the content type of the request.

Default Value: text/xml

Specify the protocol being used.

Example: HTTP

Specify the protocol version being used.

Example: Version 1.0

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 user defined generic header data to be used in this array. Each element should relate to a header in the RXS_getUriIn.UsrHdr array.

Specify the library and physical file to be used to store the data results if RXS_PHY_FILE was specified on the RXS_getUriIn.RspType parameter. The first ten characters should be the file name and the second ten characters should contain the library name. This should be used infrequently.

Specify the name of the physical file member to store the data results if RXS_PHY_FILE was specified on the RXS_getUriIn.RspType parameter. This should be used infrequently.

Specify the fully qualified path of the stream file to store the data results if RXS_STMF was specified on the RXS_getUriIn.RspType parameter. If it resides in the default transaction directory, just specify it as 'mydoc.xml.'

Specify RXS_YES on this parameter if you are simulating an HTML file upload web page. Note that this does not refer to the XML document being sent but a separate file. This should be used infrequently.

Specify the fully qualified location of the stream file that will be uploaded if RXS_STMF (RXS_YES?) was specified for the RXS_getUriIn.UpFile parameter. Note that this does not refer to the XML document being sent but a separate file. This should be used infrequently.

Specifies the name of the file as the server will see it. This value defaults to the file name specified on RXS_getUriIn.UpStmf. Note that this does not refer to the XML document being sent but a separate file. This should be used infrequently.

When specifying RXS_YES for the RXS_getUriIn.UpFile parameter, name the form field from the upload page that is being simulated. Note that this does not refer to the XML document being sent, but a separate file. This should be used infrequently.

When specifying RXS_YES for the RXS_getUriIn.UpFile parameter, specify the content-type of the file being uploaded. Note that this does not refer to the XML document being sent but a separate file. This should be used infrequently.

Specify the user ID for this parameter if Basic Authentication is used on this request.

Specify the password for this parameter if Basic Authentication is used on this request.

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.

Specify RXS_YES on this parameter if a Secure Sockets Layer (SSL) request is being made.

Used to assign an application ID for RXS_getUri.

Default Value: none

Specify the certificate store to use with the SSL request. This value defaults to RXS_SYSTEM which uses the system certificate store. If you wish to use another certificate store, specify the qualified location of the store.

Default Value: RXS_SYSTEM

Specify the certificate store password, if applicable.

Specify a value in seconds to cause a timeout during an SSL handshake. A value of RXS_NONE will specify no timeout value.

Default Value: RXS_NONE

Specify a value in seconds for a timeout on the request.

Default Value: 30

Specify a code page to be used when creating stream files.

Default Value: 819

Specify whether or not to close the connection after the request has completed. Leaving the connection open may increase performance with multiple calls to the same server.

Default Value: RXS_YES

Specify RXS_YES to debug the request that was made. A file will be created in the IFS named /tmp/getUridebug.txt which includes the actual request that was made with the RXS_getUri call. You can override this value by specifying a different file in RXS_getUriIn.DebugFile.

Specify the location of a file to place debug information to override the default of /tmp/getUridebug.txt.

Specify the CCSID to use for EBCDIC to ASCII and ASCII to EBCDIC translations. This parameter will override the tables if specified. If the tables are used 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 in use. The table used must reside in library QUSRSYS.

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

Specify a port number to bind the request to a specific IP/Port combination. This value is only valid if a value is specified for RXS_getUriIn.LocalIP.

Communicating via HTTP requires that certain "headers" be sent first on the communication line between the client and the server - your IBM i is the client in this case. When your program calls RXS_getUri, it sends HTTP headers to the remote web service based on the values specified in the data structure passed on the RXS_getUri API call. The web remote server will use those HTTP headers to know how to process the request. When that server responds to your request it will also send HTTP headers that detail the communication that took place and give information about the content passed back from the server (i.e. Content-type: text/xml). Since you will want to parse the response from the server 99% of the time we need to make sure the file or data we are parsing only contains valid XML. HTTP headers are not valid XML, so with this parameter we can tell the RXS_getUri sub procedure to separate the HTTP headers out into a separate file with a .hdr extension. Specify RXS_YES to suppress and separate out the HTTP headers or RXS_NO to keep the HTTP headers in the response. If RXS_YES is specified and RXS_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 response headers. Note that the headers will also be present in returned in the fourth parm of the call to RXS_getUri if it was not omitted. One final note - specify RXS_YES all the time unless you have requirements that dictate otherwise.

Specifies if the HTTP headers should be sent with the request. Specifying anything other than RXS_YES, the request must be a POST. RXS_YES will tell RXS_getUri that all HTTP headers as well as the user defined headers are se the request. RXS_NO will tell RXS_getUri that no HTTP headers are sent with the request and only the pReqData parameter is sent as-is. The value of RXS_USRHDR means that only the user defined headers are sent with the request.