# 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
### V7R1+
| Field | Description |
|---|---|
| ` D RXS_Transmit... D PR Extproc('RXS_Transmit') Opdesc D Like(RXS_Var16Mv_t) D Rtnparm` | Returns the response data. Note that if RXS_TransmitDS_t.ResponseStmf is set to an IFS path, the response will be stored there instead. |
| ` D Request Like(RXS_Var16Mv_t) Const D Options(*Omit : *Varsize)` | 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. |
| ` D DS LikeDS(RXS_TransmitDS_t)` | Controls how RXS_Transmit performs the HTTP/HTTPs request. Uses RXS_TransmitDS_t as a template. |
### V6R1
| Field | Description |
|---|---|
| ` D RXS_Transmit... D PR Extproc('RXS_Transmit') Opdesc` | |
| ` D Response Like(RXS_Var16Mv_t) D Options(*Omit : *Varsize)` | Holds the response data. Note that if RXS_TransmitDS_t.ResponseStmf is set to an IFS path, the response will be stored there instead. |
| ` D Request Like(RXS_Var16Mv_t) Const D Options(*Omit : *Varsize)` | 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. |
| ` D DS LikeDS(RXS_TransmitDS_t)` | Controls how RXS_Transmit performs the HTTP/HTTPs request. Uses RXS_TransmitDS_t as a template. |
## Example Code
### IBM i 7.1+
#### HTTP GET
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
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
```
#### HTTP POST
```rpgle
*--------------------------------------------------------------
* 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 = '' +
'' +
''+
'100' +
'';
reset TransmitDS;
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
```
#### HTTP Custom Headers
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
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
```
#### HTTP Basic Authentication
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
TransmitDS.URI = 'https://example.com/';
TransmitDS.BasicAuthUser = 'username';
TransmitDS.BasicAuthPassword = 'password';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Bearer Authentication
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
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
```
#### HTTP Cookie Header Data
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieData = 'your cookie data';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Cookie Header File
```rpgle
*--------------------------------------------------------------
* 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
reset TransmitDS;
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieFiles(1) = '/tmp/cookie.txt';
Response = RXS_Transmit( *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
### IBM i 6.1
#### HTTP GET
```rpgle
*--------------------------------------------------------------
* 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'
* Note that the compiler directive RXSV6R1 is defined. This ensures that if you upgrade your 6.1 system
* to 7.1 at a later date that you will not need to make changes to this program to be able to compile
* it again due to the structural differences between how RXS APIs function on 6.1 vs 7.1 / 7.2
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS;
TransmitDS.URI = 'https://example.com/';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_GET;
TransmitDS.LogFile = '/tmp/rxs_transmit1_log.txt';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP POST
```rpgle
*--------------------------------------------------------------
* 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)
/define RXSV6R1
/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 = '' +
'' +
''+
'100' +
'';
reset TransmitDS;
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"';
RXS_Transmit( Response : Request : TransmitDS );
RXS_JobLog( Response );
*INLR = *ON;
/end-free
```
#### HTTP Custom Headers
```rpgle
*--------------------------------------------------------------
* 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)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS;
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';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Basic Authentication
```rpgle
*--------------------------------------------------------------
* This example demonstrates how to specify a username and
* password for HTTP Basic Authentication with RXS_Transmit().
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS;
TransmitDS.URI = 'https://example.com/';
TransmitDS.BasicAuthUser = 'username';
TransmitDS.BasicAuthPassword = 'password';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Bearer Authentication
```rpgle
*--------------------------------------------------------------
* 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)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS
TransmitDS.URI = 'https://example.com/';
TransmitDS.CustomHeaderName(1) = 'Authorization';
TransmitDS.CustomHeaderValue(1) = 'Bearer ' + '[your-api-token]';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Cookie Header Data
```rpgle
*--------------------------------------------------------------
* 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)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS;
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieData = 'your cookie data';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
#### HTTP Cookie Header File
```rpgle
*--------------------------------------------------------------
* This example showcases sending cookie data, utilizing an IFS
* file which contains said data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/define RXSV6R1
/copy QRPGLECPY,RXSCB
D TransmitDS DS LikeDS(RXS_TransmitDS_t)
D Inz(*LikeDS)
D Response S Like(RXS_Var64Kv_t)
/free
reset TransmitDS;
TransmitDS.URI = 'example.com';
TransmitDS.HeaderCookieFiles(1) = '/tmp/cookie.txt';
RXS_Transmit( Response : *Omit : TransmitDS );
*INLR = *ON;
/end-free
```
## Data Structures
### RXS_TransmitDS_t
| Field | Description |
|---|---|
| ` D RXS_TransmitDS_t... D DS Qualified Template Inz` | |
| ` D ReturnedErrorInfo... D LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` | |
| ` D OnErrorMessageType... D 10I 0` | |
| ` D URI Like(RXS_Var8Kv_t)` | 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:** `https://testuri.org:9001/webservice` |
| ` D RequestStmf Like(RXS_Var1Kv_t)` | 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. |
| ` D RequestCcsid 10I 0 Inz(RXS_CCSID_ISO88591)` | Specify the CCSID that the request data will be converted into, and the response data will be converted from. **Default Value:** `RXS_CCSID_ISO88591` |
| ` D ResponseStmf Like(RXS_Var1Kv_t)` | 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. |
| ` D ResponseStmfCcsid... D 10I 0 Inz(RXS_CCSID_UTF8)` | If the response is being stored in an IFS file (determined by whether or not the ResponseStmf subfield is occupied), the response data will be converted to this CCSID. **Default Value:** `RXS_CCSID_UTF8` |
| ` D Timeout 10U 0 Inz(60)` | Specify a value in seconds for a timeout on the request. **Default Value:** `60` |
| ` D HTTPMethod 3I 0 Inz(RXS_HTTP_METHOD_POST)` | Determines the HTTP request method used. **Valid Values:** `RXS_HTTP_METHOD_GET`, `RXS_HTTP_METHOD_POST` **Default Value:** `RXS_HTTP_METHOD_POST` |
| ` D LogFile Like(RXS_Var1Kv_t)` | 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. |
| ` D SSLTimeout 10U 0 Inz(300)` | Specify a value in seconds to cause a timeout during an SSL handshake. **Default Value:** `300` |
| ` D SSLApplicationID... D Like(RXS_Var1Kv_t)` | Used to assign an application ID for RXS_Transmit. |
| ` D SSLCertStore... D Like(RXS_Var1Kv_t)` | If a SSL certificate store other than the *SYSTEM store should be used, the IFS path can be specified here. |
| ` D SSLCertStorePassword... D Like(RXS_Var1Kv_t)` | If using a non-*SYSTEM SSL certificate store, the password can be specified here. |
| ` D SSLVerifyPeer... D N Inz(RXS_YES)` | This option determines whether RXS_Transmit verifies the authenticity of the peer's certificate. **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_YES` |
| ` D SSLVerifyHost... D N Inz(RXS_YES)` | This option determines whether RXS_Transmit verifies that the server certificate is for the server it is known as. **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_YES` |
| ` D HTTPVersion 4P 2 Inz(RXS_HTTP_VERSION_ANY)` | Specify the HTTP protocol version being used. **Valid Values:** `RXS_HTTP_VERSION_ANY`, `RXS_HTTP_VERSION_11`, `RXS_HTTP_VERSION_10` **Default Value:** `RXS_HTTP_VERSION_ANY` |
| ` D BasicAuthUser... D Like(RXS_Var1Kv_t)` | Specify the user ID for this parameter if Basic Authentication is used on this request. |
| ` D BasicAuthPassword... D Like(RXS_Var1Kv_t)` | Specify the password for this parameter if Basic Authentication is used on this request. |
| ` D ProxyURI Like(RXS_Var1Kv_t)` | Specifies the URI used as a proxy for the request. |
| ` D ProxyUser... D Like(RXS_Var1Kv_t)` | If using a proxy on this request that requires a user id and password, specify the proxy user id in this subfield. |
| ` D ProxyPassword... D Like(RXS_Var1Kv_t)` | If using a proxy on this request that requires a user id and password, specify the proxy password in this subfield. |
| ` D SendHTTPHeaders... D N Inz(RXS_YES)` | 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:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_YES` |
| ` D HeaderCookieData... D Like(RXS_Var8Kv_t)` | Specify any cookie data to be sent with this request. Further instructions for formatting this data is available at RFC2109. |
| ` D HeaderCookieFiles... D Like(RXS_Var1Kv_t) Dim(50)` | Up to 50 paths to IFS files may be specified which contain cookie data. Further instructions for formatting this data is available at RFC2109. |
| ` D HeaderSOAPAction... D Like(RXS_Var1Kv_t)` | If calling a SOAP web service, the SOAPAction HTTP header field is generally required. This is typically surrounded by double quotes. **Example:** `"http://electrocommerce.org/abc#MyMessage"` |
| ` D HeaderUserAgent... D Like(RXS_Var1Kv_t) D Inz('KrengelTech HTTP Client')` | Some web applications may function differently depending upon the user agent specified. **Default Value:** `KrengelTech HTTP Client` |
| ` D HeaderAccept Like(RXS_Var1Kv_t)` | |
| ` D HeaderHost Like(RXS_Var1Kv_t)` | |
| ` D HeaderReferer... D Like(RXS_Var1Kv_t)` | |
| ` D HeaderConnection... D Like(RXS_Var1Kv_t)` | |
| ` D HeaderContentType... D Like(RXS_Var1Kv_t)` | The MIME type of the body of the request (used with POST requests). **Default Value:** `text/xml` |
| ` D CustomHeaderName... D 64A Varying Dim(50)` | Specifies the name of up to 50 custom HTTP headers sent with the request. |
| ` D CustomHeaderValue... D Like(RXS_Var1Kv_t) Dim(50)` | Specifies the value of up to 50 custom HTTP headers sent with the request. |
| ` D HTTPResponse LikeDS(RXS_HTTPResponseDS_t) D Inz(*LikeDS)` | Data structure using RXS_HTTPResponseDS_t as a template. Populated by RXS_Transmit at the end of the request. |
| ` D InputPointer... D *` | **Internal use only** |
| ` D InputLength 10I 0` | **Internal use only** |
| ` D OutputPointer... D *` | **Internal use only** |
| ` D OutputLength 10I 0` | **Internal use only** |