RXS_Convert()

RXS_Convert is a flexible subprocedure allowing you to perform many commonly required text and data conversions:

  • Convert to/from Base64 encoding
  • Perform XML entity encoding/decoding to replace characters with the appropriate XML entities:
    • & to &
    • " to "
    • ' to '
    • < to &lt;
    • > to &gt;
  • Encode or decode a URL's querystring
  • Convert between CCSIDs (character sets)
  • Convert to uppercase or lowercase in a CCSID-aware manner - preferable to the common practice of using the %XLATE built-in function
  • General find & replace - you can specify your own characters/strings to perform replacements with. Essentially, this allows developers on IBM i OS 6.1 to access functionality similar to that of the %SCANRPL built-in function added in IBM i OS 7.1.

Subprocedure Prototype

     D RXS_Convert...
     D                 PR                  Extproc('RXS_Convert') Opdesc
     D                                     Like(RXS_Var16Mv_t)
     D                                     Rtnparm

The output of the specified conversion operation is returned.

     D   Input                             Like(RXS_Var16Mv_t) Const
     D                                     Options(*Varsize)

Field to hold the input of the selected conversion operation. You can pass a field smaller than 16M without any additional effort.

     D   DS                                Like(RXS_Var64K_t)
     D                                     Options(*Varsize)

Holds settings which control how RXS_Convert operates. This parm can accomodate a number of possible data structures, listed below.

Valid Values:

  • RXS_ConvertCcsidDS_t
  • RXS_ConvertCaseDS_t
  • RXS_ConvertBase64DS_t
  • RXS_ConvertXMLEntitiesDS_t
  • RXS_ConvertUrlPercentDS_t
  • RXS_ConvertUserDefinedDS_t

     D RXS_Convert...
     D                 PR                  Extproc('RXS_Convert') Opdesc

     D   Output                            Like(RXS_Var16Mv_t)
     D                                     Options(*Varsize:*Omit)

Field to hold the output of the selected conversion operation. Note that if you pass a field smaller than 16M, you will need to specify the length of the Output in the subfield OutputLength.

     D   Input                             Like(RXS_Var16Mv_t) Const
     D                                     Options(*Varsize:*Omit)

Field to hold the input of the selected conversion operation. You can pass a field smaller than 16M without any additional effort.

     D   DS                                Like(RXS_Var64K_t)
     D                                     Options(*Varsize)

Holds settings which control how RXS_Convert operates. This parm can accomodate a number of possible data structures, listed below.

Valid Values:

  • RXS_ConvertCcsidDS_t
  • RXS_ConvertCaseDS_t
  • RXS_ConvertBase64DS_t
  • RXS_ConvertXMLEntitiesDS_t
  • RXS_ConvertUrlPercentDS_t
  • RXS_ConvertUserDefinedDS_t

Example Code

      *--------------------------------------------------------------
      * This example uses RXS_Convert() to encode data to Base64.
      * 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 sending text, the receiver will
      * most likely not expect the data to be in EBCDIC, so you may
      * need to use RXS_Convert() to perform CCSID conversion prior
      * to performing Base64 encoding.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D gRawData        S                   Like(RXS_Var8Kv_t)
     D gBase64         S                   Like(RXS_Var8Kv_t)

     D gConvBase64DS   DS                  LikeDS(RXS_ConvertBase64DS_t)
      /free
       gRawData = 'hello world!';

       RXS_ResetDS( gConvBase64DS : RXS_DS_TYPE_CONVERTBASE64 );
       gConvBase64DS.EncodeDecode = RXS_ENCODE;
       gBase64 = RXS_Convert( gRawData : gConvBase64DS );

       // After encoding, gBase64 will contain:
       //  aGVsbG8gd29ybGQh

       *INLR = *ON;
      /end-free
      *--------------------------------------------------------------
      * 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
      *--------------------------------------------------------------
      * This example uses RXS_Convert() to encode data to Base64.
      * 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 sending text, the receiver will
      * most likely not expect the data to be in EBCDIC, so you may
      * need to use RXS_Convert() to perform CCSID conversion prior
      * to performing Base64 encoding.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /define RXSV6R1
      /copy QRPGLECPY,RXSCB

     D gRawData        S                   Like(RXS_Var8Kv_t)
     D gBase64         S                   Like(RXS_Var8Kv_t)

     D gConvBase64DS   DS                  LikeDS(RXS_ConvertBase64DS_t)
      /free
       gRawData = 'hello world!';

       RXS_ResetDS( gConvBase64DS : RXS_DS_TYPE_CONVERTBASE64 );
       gConvBase64DS.EncodeDecode = RXS_ENCODE;
       RXS_Convert( gBase64 : gRawData : gConvBase64DS );

       // After encoding, gBase64 will contain:
       //  aGVsbG8gd29ybGQh

       *INLR = *ON;
      /end-free
      *--------------------------------------------------------------
      * 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gDecoded : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gEncoded : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gDecoded : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gEncoded : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gDecoded : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gData37 : 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gUppercase : gData : gConvCaseDS );

       // After conversion, gUppercase 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)

      /define RXSV6R1
      /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;
       RXS_Convert( gLowercase : 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)

      /define RXSV6R1
      /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!';
       RXS_Convert( gOutput : gInput : gConvUsrDfnDS );

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

       *INLR = *ON;
      /end-free

Data Structures

     D RXS_ConvertBase64DS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTBASE64)

     D   OnErrorMessageType...
     D                                5I 0

     D   EncodeDecode                  N

Set to RXS_ENCODE or RXS_DECODE.

Valid Values:

  • RXS_ENCODE
  • RXS_DECODE

Default Value: RXS_DECODE

     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                  2048A

Internal use only

     D RXS_ConvertXMLEntitiesDS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTXMLENTITIES)

     D   OnErrorMessageType...
     D                                5I 0

     D   EncodeDecode                  N

Set to RXS_ENCODE or RXS_DECODE.

Valid Values:

  • RXS_ENCODE
  • RXS_DECODE

Default Value: RXS_DECODE

     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                  2049A

Internal use only

     D RXS_ConvertUrlPercentDS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTURLPERCENT)

     D   OnErrorMessageType...
     D                                5I 0

     D   EncodeDecode                  N

Set to RXS_ENCODE or RXS_DECODE.

Valid Values:

  • RXS_ENCODE
  • RXS_DECODE

Default Value: RXS_DECODE

     D   AsciiEbcdic                   N

Determines whether the returned encoded hexadecimal values are returned as ASCII bytes (RXS_ASCII) or converted to EBCDIC (RXS_EBCDIC).

Valid Values:

  • RXS_ASCII
  • RXS_EBCDIC

Default Value: RXS_ASCII

     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                  2050A

Internal use only

     D RXS_ConvertCcsidDS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTCCSID)

     D   OnErrorMessageType...
     D                                5I 0

     D   From                        10I 0

CCSID to convert the input data from.

     D   To                          10I 0

CCSID to convert the input data to.

     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                  2048A

Internal use only

     D RXS_ConvertCaseDS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTCASE)

     D   OnErrorMessageType...
     D                                5I 0

     D   Ccsid                       10I 0

The CCSID of the input string. Defaults to the CCSID of the current job.

     D   UpperLower                    N

Set to RXS_UPPERCASE or RXS_LOWERCASE.

Valid Values:

  • RXS_UPPERCASE
  • RXS_LOWERCASE

Default Value: RXS_UPPERCASE

     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                  2050A

Internal use only

     D RXS_ConvertUserDefinedDS_t...
     D                 DS                  Qualified Template Inz

     D   ReturnedErrorInfo...
     D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz

     D   DataStructureType...
     D                                5I 0 Inz(RXS_DS_TYPE_CONVERTUSERDEFINED)

     D   OnErrorMessageType...
     D                                5I 0

     D   From                        32A   Varying Dim(50)

     D   To                          32A   Varying Dim(50)

     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                  2048A

Internal use only