RXS_Convert()

*--------------------------------------------------------------
* This example uses RXS_Convert() to decode Base64 encoded data.
* Base64 is commonly used to transfer binary data such as images
* or cryptographic keys/hashes, but may be used on any data.
* Important to note is that no CCSID conversion is performed on
* the decoded data. If you are receiving ASCII data that was
* Base64 encoded, you may need to use RXS_Convert() to convert
* it to a non-ASCII CCSID.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gBase64         S                   Like(RXS_Var8Kv_t)
D gDecoded        S                   Like(RXS_Var8Kv_t)

D gConvBase64DS   DS                  LikeDS(RXS_ConvertBase64DS_t)
 /free
  gBase64 = 'aGVsbG8gd29ybGQh';

  RXS_ResetDS( gConvBase64DS : RXS_DS_TYPE_CONVERTBASE64 );
  gConvBase64DS.EncodeDecode = RXS_DECODE;
  gDecoded = RXS_Convert( gBase64 : gConvBase64DS );

  // After decoding, gDecoded will contain:
  //  hello world!

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to encode XML entites in
* character data. Note that because < and > would need to be
* encoded, you cannot use RXS_Convert() to encode a complete
* XML document. Each item being composed into an XML element
* would need to be individually encoded.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData            S                  Like(RXS_Var8Kv_t)
D gEncoded         S                  Like(RXS_Var8Kv_t)

D gConvXMLEntDS    DS                 LikeDS(RXS_ConvertXMLEntitiesDS_t)
 /free
  gData = 'Bob & Mary';

  RXS_ResetDS( gConvXMLEntDS : RXS_DS_TYPE_CONVERTXMLENTITIES );
  gConvXMLEntDS.EncodeDecode = RXS_ENCODE;
  gEncoded = RXS_Convert( gData : gConvXMLEntDS );

  // After encoding, gEncoded will contain:
  //  Bob &amp; Mary

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to decode XML entites back
* to the corresponding character data. If you have an XML
* document with encoded characters, it is generally safe to use
* RXS_Convert() on the entire XML document. One exception to this
* is when the XML document contains a nested complete XML document
* which frequently occurs with .Net SOAP services. In that scenario,
* you need to first parse the inner XML document out, and then
* perform conversion. Failure to do this may result in an invalid
* XML document.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gXML             S                  Like(RXS_Var8Kv_t)
D gDecoded         S                  Like(RXS_Var8Kv_t)

D gConvXMLEntDS    DS                 LikeDS(RXS_ConvertXMLEntitiesDS_t)
 /free
  gXML = '<xml>Bob &amp; Mary</xml>';

  RXS_ResetDS( gConvXMLEntDS : RXS_DS_TYPE_CONVERTXMLENTITIES );
  gConvXMLEntDS.EncodeDecode = RXS_DECODE;
  gDecoded = RXS_Convert( gXML : gConvXMLEntDS );

  // After decoding, gDecoded will contain:
  //  <xml>Bob & Mary</xml>

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to URL-encode data
* (also known as 'percent encoding'). This is generally used
* when passing values in a querystring within a URL. Note that
* it is not possible to perform URL encoding on a complete URL
* as many of the characters that make up a URL would be
* erroneously converted. Instead, each value must be encoded
* and concatenated to the URL.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gUrl            S                   Like(RXS_Var1Kv_t)
D gRawData        S                   Like(RXS_Var8Kv_t)
D gEncoded        S                   Like(RXS_Var8Kv_t)

D gConvUrlDS      DS                  LikeDS(RXS_ConvertUrlPercentDS_t)
 /free
  gURL = 'http://www.example.com?key='

  gRawData = 'hello world!';

  RXS_ResetDS( gConvUrlDS : RXS_DS_TYPE_CONVERTURLPERCENT );
  gConvUrlDS.EncodeDecode = RXS_ENCODE;
  gEncoded = RXS_Convert( gRawData : gConvUrlDS );

  // After encoding, gEncoded will contain:
  //  hello%20world%21

  gURL += gEncoded;

  // gURL now contains:
  //  http://www.example.com?key=hello%20world%21

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to decode URL-encoded data
* (also known as 'percent encoded').
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gEncoded        S                   Like(RXS_Var8Kv_t)
D gDecoded        S                   Like(RXS_Var8Kv_t)

D gConvUrlDS      DS                  LikeDS(RXS_ConvertUrlPercentDS_t)
 /free
  gEncoded = 'key%3Dhello%20world%21';

  RXS_ResetDS( gConvUrlDS : RXS_DS_TYPE_CONVERTURLPERCENT );
  gConvUrlDS.EncodeDecode = RXS_DECODE;
  gDecoded = RXS_Convert( gEncoded : gConvUrlDS );

  // After decoding, gDecoded will contain:
  //  key=hello world!

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to perform CCSID conversion to
* convert from ISO 8859-1 (CCSID 819) to EBCDIC (CCSID 37).
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData819        S                   Like(RXS_Var8Kv_t)
D gData37         S                   Like(RXS_Var8Kv_t)

D gConvCcsidDS    DS                  LikeDS(RXS_ConvertCcsidDS_t)
 /free
  gData819 = x'48656C6C6F20576F726C6421'; 
  RXS_ResetDS( gConvCcsidDS : RXS_DS_TYPE_CONVERTCCSID );
  gConvCcsidDS.From = RXS_CCSID_ISO88591;
  gConvCcsidDS.To = RXS_CCSID_EBCDIC;
  gData37 = RXS_Convert( gData819 : gConvCcsidDS );

  // After conversion, gData37 will contain:
  //  Hello World!

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to convert lowercase characters
*  in gData to uppercase. This conversion happens in a CCSID
*  aware manner. For example, ü will be converted to Ü. This
*  is recommended over the common practice of using the %Xlate
*  function with A-Z/a-z constants.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8Kv_t)
D gUppercase      S                   Like(RXS_Var8Kv_t)

D gConvCaseDS     DS                  LikeDS(RXS_ConvertCaseDS_t)
 /free
  gData = 'Hello Günter';

  RXS_ResetDS( gConvCaseDS : RXS_DS_TYPE_CONVERTCASE );
  gConvCaseDS.UpperLower = RXS_UPPERCASE;
  gUppercase = RXS_Convert( gData : gConvCaseDS );

  // After conversion, gLowercase will now contain
  //  HELLO GÜNTER

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to convert uppercase characters
*  in gData to lowercase. This conversion happens in a CCSID
*  aware manner. For example, Ü will be converted to ü. This
*  is recommended over the common practice of using the %Xlate
*  function with A-Z/a-z constants.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8Kv_t)
D gLowercase      S                   Like(RXS_Var8Kv_t)

D gConvCaseDS     DS                  LikeDS(RXS_ConvertCaseDS_t)
 /free
  gData = 'HELLO GÜNTER';

  RXS_ResetDS( gConvCaseDS : RXS_DS_TYPE_CONVERTCASE );
  gConvCaseDS.UpperLower = RXS_LOWERCASE;
  gLowercase = RXS_Convert( gData : gConvCaseDS );

  // After conversion, gLowercase will now contain
  //  hello günter

  *INLR = *ON;
 /end-free

*--------------------------------------------------------------
* This example uses RXS_Convert() to replace instances of
* specified characters or bytes with the provided replacements.
* This was originally introduced to provide customers on IBM i
* 6.1 with something similar to the %ScanRpl built-in function
* which was only available on IBM i 7.1 or higher. Generally
* if you are on IBM i 7.1 or higher, you can just use %ScanRpl.
* The only advantage offered by using RXS_Convert() is that
* up to 50 replacements may be specified, but each From and To
* are limited to 32 bytes.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gInput          S                   Like(RXS_Var8Kv_t)
D gOutput         S                   Like(RXS_Var8Kv_t)

D gConvUsrDfnDS   DS                  LikeDS(RXS_ConvertUserDefinedDS_t)
 /free
  gInput = 'This is a sample message';

  RXS_ResetDS( gConvUsrDfnDS : RXS_DS_TYPE_CONVERTUSERDEFINED );
  gConvUsrDfnDS.From(1) = 'sample';
  gConvUsrDfnDS.To(1) = 'cool';
  gConvUsrDfnDS.From(2) = 'message';
  gConvUsrDfnDS.To(2) = 'message!';
  gOutput = RXS_Convert( gInput : gConvUsrDfnDS );

  // gOutput now contains:
  //  This is a cool message!

  *INLR = *ON;
 /end-free