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

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_UTF8)

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: RXS_CCSID_UTF8

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 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: 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.

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)

Populates the HTTP Accept header, used to specify which data type(s) this service will accept in a response.

D   HeaderHost                        Like(RXS_Var1Kv_t)

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.

D   HeaderReferer...
D                                     Like(RXS_Var1Kv_t)

Sets the HTTP Referer header, which can be used to specify a URI from which this service address was obtained.

D   HeaderConnection...
D                                     Like(RXS_Var1Kv_t)

Sets the HTTP Connection header, which is used to specify connection-specific options.

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)

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.

D   OutputCCSID                 10I 0 Inz(RXS_CCSID_JOB)

The CCSID of the data to be returned in the Response parameter of RXS_Transmit().

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