# 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 `<`
* `>` to `>`
* 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
### IBM i 7.1+
| Field | Description |
|---|---|
| ` 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` |
### IBM i 6.1
| Field | Description |
|---|---|
| ` 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
### IBM i 7.1+
#### Base64 Encoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### Base64 Decoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### XML Entity Encoding
```rpgle
*--------------------------------------------------------------
* 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 & Mary
*INLR = *ON;
/end-free
```
#### XML Entity Decoding
```rpgle
*--------------------------------------------------------------
* 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 = 'Bob & Mary';
RXS_ResetDS( gConvXMLEntDS : RXS_DS_TYPE_CONVERTXMLENTITIES );
gConvXMLEntDS.EncodeDecode = RXS_DECODE;
gDecoded = RXS_Convert( gXML : gConvXMLEntDS );
// After decoding, gDecoded will contain:
// Bob & Mary
*INLR = *ON;
/end-free
```
#### URL Percent Encoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### URL Percent Decoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### CCSID Conversion
```rpgle
*--------------------------------------------------------------
* 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
```
#### Convert to Uppercase
```rpgle
*--------------------------------------------------------------
* 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
```
#### Convert to Lowercase
```rpgle
*--------------------------------------------------------------
* 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
```
#### User Defined Conversion (Scan & Replace)
```rpgle
*--------------------------------------------------------------
* 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
```
### IBM i 6.1
#### Base64 Encoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### Base64 Decoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### XML Entity Encoding
```rpgle
*--------------------------------------------------------------
* 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 & Mary
*INLR = *ON;
/end-free
```
#### XML Entity Decoding
```rpgle
*--------------------------------------------------------------
* 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 = 'Bob & Mary';
RXS_ResetDS( gConvXMLEntDS : RXS_DS_TYPE_CONVERTXMLENTITIES );
gConvXMLEntDS.EncodeDecode = RXS_DECODE;
RXS_Convert( gDecoded : gXML : gConvXMLEntDS );
// After decoding, gDecoded will contain:
// Bob & Mary
*INLR = *ON;
/end-free
```
#### URL Percent Encoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### URL Percent Decoding
```rpgle
*--------------------------------------------------------------
* 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
```
#### CCSID Conversion
```rpgle
*--------------------------------------------------------------
* 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
```
#### Convert to Uppercase
```rpgle
*--------------------------------------------------------------
* 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
```
#### Convert to Lowercase
```rpgle
*--------------------------------------------------------------
* 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
```
#### User Defined Conversion (Scan & Replace)
```rpgle
*--------------------------------------------------------------
* 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
### RXS_ConvertBase64DS_t
| Field | Description |
|---|---|
| ` 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** |
### RXS_ConvertXmlEntitiesDS_t
| Field | Description |
|---|---|
| ` 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** |
### RXS_ConvertUrlPercentDS_t
| Field | Description |
|---|---|
| ` 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** |
### RXS_ConvertCcsidDS_t
| Field | Description |
|---|---|
| ` 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** |
### RXS_ConvertCaseDS_t
| Field | Description |
|---|---|
| ` 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** |
### RXS_ConvertUserDefinedDS_t
| Field | Description |
|---|---|
| ` 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** |