# 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** |