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

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.

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

*--------------------------------------------------------------
* 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
*--------------------------------------------------------------
* 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>';

   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
*--------------------------------------------------------------
* 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
*--------------------------------------------------------------
* 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
*--------------------------------------------------------------
* 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
*--------------------------------------------------------------
* 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
*--------------------------------------------------------------
* 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 = '<?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>';

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

Data Structures

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
  • RXS_HTTP_METHOD_PUT
  • RXS_HTTP_METHOD_DELETE
  • RXS_HTTP_METHOD_PATCH
  • RXS_HTTP_METHOD_HEAD
  • RXS_HTTP_METHOD_OPTIONS

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. Setting this to RXS_NO this in a production capacity is strongly discouraged.

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. Setting this to RXS_NO this in a production capacity is strongly discouraged.

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