RXS_getUri()

Call this subprocedure to send an XML stream to an “end point”. An “end point” describes a web service you call or “consume”. Program GETURI3 provides an example of calling end point RXS3 which resides on your IBM i from the initial install of RPG-XML Suite. The RXS_getURI API is VERY configurable concerning what can be sent to the remote server. When doing standard web services there are only a handful of values for the pInCfg data structure that need to be filled which is detailed by way of the examples in RXS/EXAMPLE.

Subprocedure Prototype

D RXS_getUri      pr

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

D  pInCfg                             likeds(RXS_GetUriIn)

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.

D  pReqData                           like(RXS_XMLData) options(*omit)

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.

D  pRspData                           like(RXS_XMLData) options(*omit)

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.

D  pHttpHdr                           like(RXS_XMLData) options(*omit)

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.

D  pErr                               likeds(RXS_Error) options(*nopass)
 

Data Structures

D RXS_getUriIn    ds                  qualified inz
 
D  URI                         256

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

D  RspType                      10

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

D  UserAgent                   128

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

D  ReqType                    2048

Specify contstant 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

D  ReqStmf                     256

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

D  Proxy                       128

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

D  Port                         10i 0

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

D  ReqMeth                      10

Specify the request method used for the web service request.

Valid Values:

  • RXS_GET
  • RXS_POST

Default Value: RXS_POST

D  Accept                      128

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

D  Host                         64

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

D  Cookie                     4096

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

D  Referer                     128

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

D  Connection                  128

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

Example: keep-alive

D  ContType                    128

Specify the content type of the request.

Default Value: text/xml

D  Proto                        20

Specify the protocol being used.

Example: HTTP

D  HTTPVer                      10

Specify the protocol version being used.

Example: Version 1.0

D  NbrHdrs                      10i 0

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

D  UsrHdr                       32    dim(50)

Specify the user defined generic headers to be used in this array.

D  UsrHdrDta                   128    dim(50)

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.

D  File                         20

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.

D  Mbr                          10

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.

D  RspStmf                     128

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

D  UpFile                        4

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.

D  UpStmf                      128

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.

D  UpName                      128

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.

D  UpField                      64

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.

D  UpCont                       64

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.

D  BUser                        64

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

D  BPW                          64

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

D  PUser                        64

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

D  PPW                          64

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

D  SSL                           4

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

D  SSLApp                       64

Used to assign an application ID for RXS_getUri.

Default Value: none

D  CStore                      128

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

D  CPW                          64

Specify the certificate store password, if applicable.

D  SSLTime                      10i 0

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

D  Timeout                      10i 0

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

Default Value: 30

D  CodPag                       10i 0

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

Default Value: 819

D  Close                         4

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

D  Debug                         4

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.

D  DebugFile                   256

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

D  CCSID                        10i 0

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.

D  EATable                      10

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.

D  AETable                      10

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.

D  LocalIP                      32

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

D  LocalPort                    10i 0

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.

D  SprHead                       4

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.

D  HTTPHead                      7

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.