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

 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"';
 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
   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';     
   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
   RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
   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
   RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
   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

D   Reserved                  4096A

Internal use only

D   InputCCSID                  10I 0 Inz(RXS_CCSID_JOB)
 
D   OutputCCSID                 10I 0 Inz(RXS_CCSID_JOB)
 
D   LogFileCCSID                10I 0 Inz(RXS_CCSID_UTF8)
 
D   LogFileAppend...
D                                 N   Inz(RXS_NO)
 
D   LogHandler...
D                                 *   Procptr
 
D   LogHandlerData...
D                                 *
 
D   LogHandlerDataLength...
D                               10I 0
 
D   EnableExpectHeader...
D                                 N   Inz(RXS_NO)
 
D   LocalInterface...
D                               64A   Varying

Specify the IP address and optionally the port of the desired interface to bind to when transmiting to the remote server. When specify port, it will be separated from the IP with a colon: IP:Port