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)
  • Encodes or decodes a URL’s querystring
  • Replace characters with the appropriate XML entities:
    • & = &
    • = "
    • ' = '
    • < = &lt;
    • > = &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.

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, outlined below.

Valid Values:

  • RXS_ConvertCcsidDS_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)

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, outlined below.

Valid Values:

  • RXS_ConvertCcsidDS_t
  • RXS_ConvertBase64DS_t
  • RXS_ConvertXMLEntitiesDS_t
  • RXS_ConvertUrlPercentDS_t
  • RXS_ConvertUserDefinedDS_t

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) 
D                                     Inz(*Likeds)
 /free
  reset gConvertCcsidDS;
  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) 
D                                     Inz(*LIKEDS)                  
 /free
  reset gConvertBase64DS;                              
  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) 
D                                     Inz(*Likeds)                       
 /free
  reset gConvertXMLEntitiesDS;                          
  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) 
D                                     Inz(*Likeds)           
 /free
  reset gConvertUrlPercentDS;                          
  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) 
D                                     Inz(*Likeds)                       
 /free
  reset gConvertUsrDfnDS;                             
  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 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) 
D                                     Inz(*Likeds)
 /free
  reset gConvertCcsidDS;
  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) 
D                                     Inz(*LIKEDS)
 /free
  reset gConvertBase64DS;                              
  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) 
D                                     Inz(*Likeds)                       
 /free
  reset gConvertXMLEntitiesDS;                          
  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) 
D                                     Inz(*Likeds)           
 /free
  reset gConvertUrlPercentDS;                          
  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) 
D                                     Inz(*Likeds)                       
 /free
  reset gConvertUsrDfnDS;                             
  gConvertUsrDfnDS.From(1) = x'3F';                     
  gConvertUsrDfnDS.To(1) = x'4015';                       
  RXS_Convert( convData : gData : gConvertUsrDfnDS );

  *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

Valid Values:

  • RXS_ENCODE
  • 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_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

Valid Values:

  • RXS_ENCODE
  • 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

Valid Values:

  • RXS_ENCODE
  • 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