RXS_Convert()
RXS_Convert is a flexible subprocedure allowing you to perform many commonly required text and data conversions:
- Convert to/from Base64 encoding
- Convert to/from Base64Url 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
|
The output of the specified conversion operation is returned. |
|
Field to hold the input of the selected conversion operation. You can pass a field smaller than 16M without any additional effort. |
|
Holds settings which control how RXS_Convert operates. This parm can accomodate a number of possible data structures, listed below. Valid Values:
|
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 & 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 & 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
Data Structures
|
|
|
|
|
Internal use only |
|
|
|
Set to RXS_ENCODE or RXS_DECODE. Valid Values:
Default Value: |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
Internal use only |
|
|
|
Set to RXS_ENCODE or RXS_DECODE. Valid Values:
Default Value: |
|
Set to RXS_YES or RXS_NO. Valid Values:
Default Value: |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
|
|
|
|
The CCSID of the input string. Defaults to the CCSID of the current job. |
|
Set to RXS_UPPERCASE or RXS_LOWERCASE. Valid Values:
Default Value: |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
Internal use only |
|
|
|
CCSID to convert the input data from. |
|
CCSID to convert the input data to. |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
Internal use only |
|
|
|
Set to RXS_ENCODE or RXS_DECODE. Valid Values:
Default Value: |
|
Determines whether the returned encoded hexadecimal values are returned as ASCII bytes (RXS_ASCII) or converted to EBCDIC (RXS_EBCDIC). Valid Values:
Default Value: |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
Internal use only |
|
|
|
|
|
|
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
|
|
|
|
Internal use only |
|
|
|
Set to RXS_ENCODE or RXS_DECODE. Valid Values:
Default Value: |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |
|
Internal use only |