RXS_Transmit()
Performs a HTTP/HTTPS request - allowing you to exchange data with a remote web service.
To properly communicate with a web service, you will need to configure the RXS_TransmitDS_t data structure passed in as a parameter.
Subprocedure Prototype
|
Returns the response data. Note that if RXS_TransmitDS_t.ResponseStmf is set to an IFS path, the response will be stored there instead. |
|
Holds the request data. Note that if RXS_TransmitDS_t.RequestStmf is set to an IFS path, the request will be read from there instead. |
|
Controls how RXS_Transmit performs the HTTP/HTTPs request. Uses RXS_TransmitDS_t as a template. |
Example Code
*--------------------------------------------------------------
* This example performs a simple HTTP GET operation against the URL example.com and stores the retrieved response data in the field Response.
* Because this is a HTTP GET, we don't need to pass a Request parameter.
* During the execution of RXS_Transmit(), the API will create a log file at '/tmp/rxs_transmit1_log.txt'
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'https://example.com/';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_GET;
TransmitDS.LogFile = '/tmp/rxs_transmit1_log.txt';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free*--------------------------------------------------------------
* This example performs a HTTP POST against a public web service that provides conversion between Fahrenheit and Celsius.
* This is a HTTP POST, so we need to provide a Request parameter.
* Because this is using SOAP, we need to specify Content-type and SOAPAction headers.
* Lastly, this example uses RXS_JobLog() to write the full response XML to the job log.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Request S Like(RXS_Var64Kv_t)
D Response S Like(RXS_Var64Kv_t)
/free
Request = '<?xml version="1.0" encoding="utf-8"?>' +
'<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'+
' xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="' +
'http://schemas.xmlsoap.org/soap/envelope/"><soap:Body>' +
'<FahrenheitToCelsius xmlns="http://www.w3schools.com/webservices/">'+
'<Fahrenheit>100</Fahrenheit></FahrenheitToCelsius>' +
'</soap:Body></soap:Envelope>';
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI =
'http://www.w3schools.com/webservices/tempconvert.asmx';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_POST;
TransmitDS.LogFile = '/tmp/rxs_transmit2_log.txt';
TransmitDS.HeaderContentType = 'text/xml; charset=utf-8';
TransmitDS.HeaderSOAPAction =
'"http://www.w3schools.com/webservices/FahrenheitToCelsius"';
Response = RXS_Transmit( Request : TransmitDS );
RXS_JobLog( Response );
*INLR = *ON;
/end-free*--------------------------------------------------------------
* This example demonstrates how to set custom HTTP headers with RXS_Transmit().
* You may specify up to 50 custom HTTP headers sent with a request.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'https://example.com/';
// Set a custom HTTP header that looks like this:
// X-API-Token: [your-api-token]
TransmitDS.CustomHeaderName(1) = 'X-API-Token';
TransmitDS.CustomHeaderValue(1) = '[your-api-token]';
// Set a custom HTTP header that looks like this:
// ExampleHeader: hello world
TransmitDS.CustomHeaderName(2) = 'ExampleHeader';
TransmitDS.CustomHeaderValue(2) = 'hello world';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free*--------------------------------------------------------------
* This example demonstrates how to specify a username and
* password for HTTP Basic Authentication with RXS_Transmit().
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'https://example.com/';
TransmitDS.BasicAuthUser = 'username';
TransmitDS.BasicAuthPassword = 'password';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free*--------------------------------------------------------------
* This examples showcases using RXS_Transmit to set an Authorization header.
* When using CustomHeaderName and CustomHeaderValue arrays with RXS_Transmit()
* to set an Authorization header, the Bearer portion needs to go in the Value
* field, followed by a space before the API key is concatenated to the Value field.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'https://example.com/';
TransmitDS.CustomHeaderName(1) = 'Authorization';
TransmitDS.CustomHeaderValue(1) = 'Bearer ' + '[your-api-token]';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free
*--------------------------------------------------------------
* This example showcases sending cookie data. However, instead of
* reading the data from a file, you may specify it by utilizing
* HeaderCookieData.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieData = 'your cookie data';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free*--------------------------------------------------------------
* This example showcases sending cookie data, utilizing an IFS
* file which contains said data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieFiles(1) = '/tmp/cookie.txt';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-freeData Structures
|
|
|
If an error occurs during processing, additional error information may be returned in this data structure. |
|
Internal use only |
|
|
|
Specify the full URI used for the request. If a non-standard port (e.g. other than 80 for an HTTP request, and 443 for an HTTPS request) is needed, this must be specified in the request. Example: |
|
An IFS path can be specified in this subfield - if it is, it will be used as the request data instead of the value of the pRequest parm. |
|
Specify the CCSID of the data to be sent to the remote server. If required, the data in the Request parameter will be converted to this CCSID before transmission to the remote server. Default Value: |
|
An IFS path can be specified in this subfield - if it is, any output of the RXS_Transmit operation will be stored in the specified IFS file. |
|
If the response is being stored in an IFS stream file (determined by whether or not the ResponseStmf subfield is occupied), the response data will be converted to this CCSID. The stream file will also be created with this CCSID. Default Value: |
|
Specify a value in seconds for a timeout on the request. Default Value: |
|
Determines the HTTP request method used. Valid Values:
Default Value: |
|
An IFS path can be specified to log the request & response, as well as additional HTTP request debugging information. This option is disabled by default, and should not be left enabled in production environments due to increased execution time and privacy concerns. |
|
Specify a value in seconds to cause a timeout during an SSL handshake. Default Value: |
|
Used to assign an application ID for RXS_Transmit. |
|
If a SSL certificate store other than the *SYSTEM store should be used, the IFS path can be specified here. |
|
If using a non-*SYSTEM SSL certificate store, the password can be specified here. |
|
This option determines whether RXS_Transmit verifies the authenticity of the peer's certificate. Setting this to RXS_NO this in a production capacity is strongly discouraged. Valid Values:
Default Value: |
|
This option determines whether RXS_Transmit verifies that the server certificate is for the server it is known as. Setting this to RXS_NO this in a production capacity is strongly discouraged. Valid Values:
Default Value: |
|
Specify the HTTP protocol version being used. Valid Values:
Default Value: |
|
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. |
|
Specifies the URI used as a proxy for the request. |
|
If using a proxy on this request that requires a user id and password, specify the proxy user id in this subfield. |
|
If using a proxy on this request that requires a user id and password, specify the proxy password in this subfield. |
|
Specifies if HTTP headers should be sent with the request. RXS_YES will tell RXS_Transmit that all HTTP headers as well as the user defined headers are sent with the request. RXS_NO will tell RXS_Transmit that no HTTP headers are sent with the request - only the request data is sent. Valid Values:
Default Value: |
|
Specify any cookie data to be sent with this request. Further instructions for formatting this data is available at RFC2109. |
|
Paths to IFS files may be specified which contain cookie data. Further instructions for formatting this data is available at RFC2109. Size of array reduced from 50 to 10 in RXS 3.4.3. |
|
If calling a SOAP web service, the SOAPAction HTTP header field is generally required. This is typically surrounded by double quotes. Example: |
|
Some web applications may function differently depending upon the user agent specified. Default Value: |
|
Populates the HTTP Accept header, used to specify which data type(s) this service will accept in a response. |
|
Populates the HTTP Host header, which specifies the host address and port number of the requested resource. This information is generally obtained from the service URI. This field is required for HTTP/1.1 communications. |
|
Sets the HTTP Referer header, which can be used to specify a URI from which this service address was obtained. |
|
Sets the HTTP Connection header, which is used to specify connection-specific options. |
|
The MIME type of the body of the request (used with POST requests). Default Value: |
|
Specifies the name of up to 50 custom HTTP headers sent with the request. These names are paired with the values, below. |
|
Specifies the value of up to 50 custom HTTP headers sent with the request. These values are paired with the names, above. Size increased from 1k to 4k in RXS 3.4.3. |
|
Populated by RXS_Transmit at the end of the request. Contains response information from the completed HTTP communication. |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
The CCSID of the data supplied in the Request parameter of RXS_Transmit(). If required, the data will be converted from the InputCcsid into the RequestCcsid before being transmitted. Default Value: |
|
The CCSID of the data to be returned in the Response parameter of RXS_Transmit(). Default Value: |
|
The CCSID of the data to be written to the logfile, when logfile creation is enabled. Default Value: |
|
Controls whether new logging data will be appended to the logfile, or if any existing data will be overwritten. Valid Values:
Default Value: |
|
Specify a procedure pointer to a custom logging handler |
|
Internal use only |
|
Internal use only |
|
Specifies that the expect header should be sent with the request Valid Values:
Default Value: |
|
Specify the IP address and optionally the port of the desired interface to bind to when transmiting to the remote server. When a port is specified, it will be separated from the IP with a colon: IP:Port |
|
Allow RXS_Transmit() to use IPv6 protocol Valid Values:
Default Value: |
|
Controls whether RXS_Transmit() should follow HTTP 3XX redirects Valid Values:
Default Value: |
|
|
|
HTTP status code returned by the remote server |
|
A string containing all headers returned by the server. These headers are further parsed individually below. |
|
An array of the parsed header names. These are paired with the header values, below. |
|
An array of the parsed header values. These are paired with the header names, above. Size increased from 1k to 4k in RXS 3.4.3. |
|
Timestamp for the start of the connection |
|
Timestamp for the end of the connection |
|
Total duration of the HTTP communication |