RXS_Convert()

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

  • Convert to/from Base64
  • Convert between CCSIDs (character sets)
  • Encode or decode a URL’s querystring
  • Replace characters with the appropriate XML entities:
    • & to &
    • to "
    • ' to '
    • < to &lt;
    • > to &gt;
  • Decode a CGI string
    • Plus-signs (‘+’) are converted to blanks
    • Escaped octets (e.g. ‘%C3’) are converted to x’C3’
    • Characters < x’40’ except for x’0E’ and x’0F’ are converted to blanks - this step is done to avoid errors where data may have been pasted into a web page input field from e.g.a Word document and contain hidden ‘control’ characters.)
  • 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.
  • Convert to uppercase or lowercase in a CCSID-aware manner - preferable to the common practice of using the %XLATE built-in function

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.

D RXS_Convert...
D                 PR                  Extproc('RXS_Convert') Opdesc
 
D   Output                            Like(RXS_Var16Mv_t)
D                                     Options(*Varsize)

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)

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.

Example Code

*--------------------------------------------------------------
* This example uses RXS_Convert() to convert XML response data from
*  ISO 8859-1 to EBCDIC, and saves the converted data to convXmlResponse.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gXmlResponse    S                   Like(RXS_Var8KV_t)   
D convXmlResponse...
D                 S                   Like(RXS_Var8KV_t) 

D gConvertCcsidDS...
D                 DS                  Likeds(RXS_ConvertCcsidDS_t)
 /free
  RXS_ResetDS( gConvertCcsidDS : RXS_DS_TYPE_CONVERTCCSID );
  gConvertCcsidDS.From = RXS_CCSID_ISO88591;
  gConvertCcsidDS.To = RXS_CCSID_EBCDIC;  
  gXmlResponse = RXS_Convert( gXmlResponse : gConvertCcsidDS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to convert Base64 data to binary data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gBase64         S                   Like(RXS_Var8KV_t)
D gBinary         S                   Like(RXS_Var8KV_t)

D gConvertBase64DS...                                               
D                 DS                  LikeDS(RXS_ConvertBase64DS_t)      
 /free
  RXS_ResetDS( gConvertBase64DS : RXS_DS_TYPE_CONVERTBASE64 );                              
  gConvertBase64DS.EncodeDecode = RXS_DECODE;          
  gBinary = RXS_Convert( gBase64 : gConvertBase64DS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to encode XML entites in character data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D encData         S                   Like(RXS_Var8KV_t)

D gConvertXMLEntitiesDS...                                               
D                 DS                  Likeds(RXS_ConvertXMLEntitiesDS_t) 
 /free
  RXS_ResetDS( gConvertXMLEntitiesDS : RXS_DS_TYPE_CONVERTXMLENTITIES );                          
  gConvertXMLEntitiesDS.EncodeDecode = RXS_ENCODE;      
  encData = RXS_Convert( gData : gConvertXMLEntitiesDS);

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to decode URL-encoded character data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D encData         S                   Like(RXS_Var8KV_t)

D gConvertUrlPercentDS...                                               
D                 DS                  Likeds(RXS_ConvertUrlPercentDS_t)
 /free
  RXS_ResetDS( RXS_ConvertUrlPercentDS: RXS_DS_TYPE_CONVERTURLPERCENT );                          
  gConvertUrlPercentDS.EncodeDecode = RXS_DECODE;      
  gData = RXS_Convert( encData : gConvertUrlPercentDS);

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to replace instances of specified characters
*  with the provided replacements.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D convData        S                   Like(RXS_Var8KV_t)

D gConvertUsrDfnDS...                                                    
D                 DS                  Likeds(RXS_ConvertUserDefinedDS_t)      
 /free
  RXS_ResetDS( gConvertUsrDfnDS : RXS_DS_TYPE_CONVERTUSERDEFINED );                         
  gConvertUsrDfnDS.From(1) = x'3F';                     
  gConvertUsrDfnDS.To(1) = x'4015';                       
  convData = RXS_Convert( gData : gConvertUsrDfnDS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to convert lowercase characters 
*  in gData to uppercase.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D convData        S                   Like(RXS_Var8KV_t)

D gConvertCaseDS...                                                    
D                 DS                  Likeds(RXS_ConvertCaseDS_t)                  
 /free
  RXS_ResetDS( gConvertCaseDS : RXS_DS_TYPE_CONVERTCASE );  
  gConvertCaseDS.UpperLower = RXS_UPPERCASE;                     
  convData = RXS_Convert( gData : gConvertCaseDS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to convert XML response data from
*  ISO 8859-1 to EBCDIC, and saves the converted data to convXmlResponse.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB

D gXmlResponse    S                   Like(RXS_Var8KV_t)
D convXmlResponse...
D                 S                   Like(RXS_Var8KV_t)     
 
D gConvertCcsidDS...
D                 DS                  Likeds(RXS_ConvertCcsidDS_t)
 /free
  RXS_ResetDS( gConvertCcsidDS : RXS_DS_TYPE_CONVERTCCSID );
  gConvertCcsidDS.From = RXS_CCSID_ISO88591;
  gConvertCcsidDS.To = RXS_CCSID_EBCDIC;  
  RXS_Convert( convXmlResponse: gXmlResponse : gConvertCcsidDS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to convert Base64 data to binary data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB
 
D gBase64         S                   Like(RXS_Var8KV_t)
D gBinary         S                   Like(RXS_Var8KV_t)

D gConvertBase64DS...                                               
D                 DS                  LikeDS(RXS_ConvertBase64DS_t)
 /free
  RXS_ResetDS( gConvertBase64DS : RXS_DS_TYPE_CONVERTBASE64 );                              
  gConvertBase64DS.EncodeDecode = RXS_DECODE;          
  RXS_Convert( gBinary : gBase64 : gConvertBase64DS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to encode XML entites in character data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D encData         S                   Like(RXS_Var8KV_t)

D gConvertXMLEntitiesDS...                                               
D                 DS                  Likeds(RXS_ConvertXMLEntitiesDS_t) 
 /free
  RXS_ResetDS( gConvertXMLEntitiesDS : RXS_DS_TYPE_CONVERTXMLENTITIES );                          
  gConvertXMLEntitiesDS.EncodeDecode = RXS_ENCODE;      
  RXS_Convert( encData : gData : gConvertXMLEntitiesDS);

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to decode URL-encoded character data.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D encData         S                   Like(RXS_Var8KV_t)

D gConvertUrlPercentDS...                                               
D                 DS                  Likeds(RXS_ConvertUrlPercentDS_t)
 /free
  RXS_ResetDS( RXS_ConvertUrlPercentDS: RXS_DS_TYPE_CONVERTURLPERCENT );                          
  gConvertUrlPercentDS.EncodeDecode = RXS_DECODE;      
  RXS_Convert( gData : encData : gConvertUrlPercentDS);

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to replace instances of specified characters
*  with the provided replacements.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D convData        S                   Like(RXS_Var8KV_t)

D gConvertUsrDfnDS...                                                    
D                 DS                  Likeds(RXS_ConvertUserDefinedDS_t)      
 /free
  RXS_ResetDS( gConvertUsrDfnDS : RXS_DS_TYPE_CONVERTUSERDEFINED );                             
  gConvertUsrDfnDS.From(1) = x'3F';                     
  gConvertUsrDfnDS.To(1) = x'4015';                       
  RXS_Convert( convData : gData : gConvertUsrDfnDS );

  *INLR = *ON;
 /end-free
*--------------------------------------------------------------
* This example uses RXS_Convert() to convert lowercase characters 
*  in gData to uppercase.
*--------------------------------------------------------------
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

 /define RXSV6R1
 /copy QRPGLECPY,RXSCB

D gData           S                   Like(RXS_Var8KV_t)
D convData        S                   Like(RXS_Var8KV_t)

D gConvertCaseDS...                                                    
D                 DS                  Likeds(RXS_ConvertCaseDS_t)                  
 /free
  RXS_ResetDS( gConvertCaseDS : RXS_DS_TYPE_CONVERTCASE );  
  gConvertCaseDS.UpperLower = RXS_UPPERCASE;                     
  RXS_Convert( convData : gData : gConvertCaseDS );

  *INLR = *ON;
 /end-free

Data Structures

D RXS_ConvertBase64DS_t...
D                 DS                  Qualified Template Inz
 
D   ReturnedErrorInfo...
D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz
 
D   OnErrorMessageType...
D                               10I 0
 
D   EncodeDecode                  N

Set to RXS_ENCODE or 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_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.

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   OnErrorMessageType...
D                               10I 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_ConvertUrlPercentDS_t...
D                 DS                  Qualified Template Inz
 
D   ReturnedErrorInfo...
D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz
 
D   OnErrorMessageType...
D                               10I 0
 
D   EncodeDecode                  N

Set to RXS_ENCODE or RXS_DECODE.

D   AsciiEbcdic                   N

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

Valid Values:

  • RXS_YES
  • RXS_NO

Default Value: RXS_NO

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   OnErrorMessageType...
D                               10I 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

D RXS_ConvertXMLEntitiesDS_t...
D                 DS                  Qualified Template Inz
 
D   ReturnedErrorInfo...
D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz
 
D   OnErrorMessageType...
D                               10I 0
 
D   EncodeDecode                  N

Set to RXS_ENCODE or 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