You may find examples about these functions by scanning through PDM the source file QRPGLESRC in library CGIDEV2.

1. Conversion procedures from module XXXDATA
   1. Subprocedure char2hex converts a character string to its hexadecimal representation.
   2. Subprocedure hex2char converts a character string in hexadecimal format to its character representation.
   3. Subprocedure chknbr accepts a character string and an optional parameter specifying the maximum number of digits to the left of the decimal point. Additional optional parameters are available to request that any errors found should be formatted as messages and added to the service program's message arrays, the text that should be used to describe the field in the messages, and whether a message should be sent if the field's value is less than zero.
      Chknbr returns a structure containing seven indicators. The indicators and their meaning when *on are:
      1. one or more errors occurred
      2. non-numeric characters (includes minus sign in wrong place)
      3. multiple decimal points
      4. multiple signs (both leading and trailing)
      5. zero length input or no numeric characters
      6. too many digits to the left of the decimal point
      7. no errors, but value is less than 0.
      Note 1. Indicator 7 *on does not set indicator 1 *on.
   4. Subprocedure c2n converts a character string to a floating point number. It is recommended that you check the string with chknbr before calling c2n.
   5. Subprocedurec2n2 converts a character string to a packed 30.9 number. c2n2 performs faster than c2n and has none of c2n's floating point precision problems. Therefore, it is recommended that you use c2n2 instead of c2n. It is recommended that you check the string with chknbr before calling c2n2.
   6. SubprocedurexlatWCCSIDs uses CCSIDs to translate variable length strings up to 32767 characters in length.
      If optional parameters fromCCSID and toCCSID are specified, they are used for the translation.
      Otherwise, translation between ASCII and EBCDIC is performed using the CCSIDs found in the CGI_EBCDIC_CCSID and CGI_ASCII_CCSID environment variables. Input parameter, toebcdic, is used to determine whether translation is from ASCII to EBCDIC (*on) or from EBCDIC to ASCII (*off).
   7. Subprocedure uppify converts all the characters in a string to upper case.
      An optional CCSID parameter may be used to support non-english language characters.
      Examples:

      D ccsid 10i 0 * If you want the best possible performance and the * English language characters are sufficient, do * not use the CCSID parameter. C eval charstring = uppify(charstring) * To convert to uppercase a non-english language * character string, you must pass the correct CCSID * as second parameter. * This takes 2 times as long as using no CCSID. * For instance, if the character string is in swedish language: C eval ccsid = 278 C eval charstring = uppify(charstring:ccsid) * A value 0 for the CCSID parameter instructs the uppify * procedure to use the job CCSID. * This takes 3 times as long as using no CCSID. C eval charstring = uppify(charstring:0)

   8. Subprocedure lowfy converts all the characters in a string to lower case.
      An optional CCSID parameter may be used to support non-english language characters.
      Examples:

      D ccsid 10i 0 * If you want the best possible performance and the * English language characters are sufficient, do * not use the CCSID parameter. C eval charstring = lowfy(charstring) * To convert to uppercase a non-english language * character string, you must pass the correct CCSID * as second parameter. * This takes 2 times as long as using no CCSID. * For instance, if the character string is in swedish language: C eval ccsid = 278 C eval charstring = lowfy(charstring:ccsid) * A value 0 for the CCSID parameter instructs the uppify * procedure to use the job CCSID. * This takes 3 times as long as using no CCSID. C eval charstring = lowfy(charstring:0)

   
   
   
2. Conversion procedures from module XXXDATA1
   • When using the GET method to send input to a CGI program, non-alphanumeric characters in the query string must be replaced by so called "escape sequences".
     An escape sequence is made of
     • an escape character "%"
     • followed by two characters which represent the hexadecimal value of the corresponding ASCII character.
     For instance, if the query string contains the following input
        cusname=Van der Meer
     then each of the two spaces in "Van der Meer" must be replaced by the escape sequence %20 (as the ASCII representation of a space character is x'20').

     The tool to replace non-aplhanumeric characters with the corresponding escape sequences is subprocedure UrlEscSeq:

     D inpString s 32767 varying D outString s 32767 varying * C eval outString=UrlEscSeq(inpString)

     A "trim right" indicator can be optionally passed to subprocedure UrlEscSeq.
     If it is not passed, or if it is passed and it is *on, the input string is trimmed right before being processed.
     If it is passed and it is *off, the input string is not trimmed right (trailing blanks are converted to escape sequences %20):

     D inpString s 32767 varying D outString s 32767 varying D trimRightInd s n /free trimRightInd=*off; outString=UrlEscSeq(inpString:trimRightInd);

     You may use CGI program TSTESCSEQ to display the result of converting an input string to an output string containing escaped sequences. In this example, the input string is trimmed right before being processed.
     A third parameter ("Options") can be used to replace characters in the input string before it is escaped. This parameter is a character variable, length of 10. Each character in this string has a special meaning. The following characters are supported:

     Character value	Action performed
     1	Replaces CarriageReturnLineFeed (x'0d25') with html tag <br>

     Example:

     D unescaped s 5000 varying D escaped s 5000 varying D trimRightInd s n D options s 10 varying /free trimRightInd=*on; options='1'; escaped=UrlEscSeq(unescaped:trimRightInd:options);

     See program ESCUNESC.
   • Subprocedure UrlUnEscSeq may be used to convert back a string containing escape sequences, for instance to convert the string "Van%20der%20Meer" to "Van der Meer":

     D inpString s 32767 varying D outString s 32767 varying * C eval outString=UrlUnEscSeq(inpString)

     A second parameter ("Options") can be used to replace characters in the input string after it has been unescaped. This parameter is a character variable, length of 10. Each character in this string has a special meaning. The following characters are supported:

     Character value	Action performed
     1	Replaces html tag <br> with CarriageReturnLinefeed (x'0d25')

     Example:

     D escaped s 5000 varying D unescaped s 5000 varying D options s 10 varying /free options='1'; unescaped=UrlUnEscSeq(escaped:options);

     See program ESCUNESC.
   
   
   
3. Conversion procedures from module XXXWRKHTML
   • When displaying database fields in a HTML page, it may happen that some data containing special HTML characters are interpreted as HTML tag delimiters thus generating ununderstandable strings. On the other way, multiple consecutive blanks in a field are displayed as a single space, which in some cases may be unappropriate.
     The following three subprocedures allow to convert special characters and blanks into their corresponding HTML character entities, in order to display field data exactly as they are on databases.
     All procedures require
     • the input and the ouput fields be defined with varying length not exceeding 32767
     1. Subprocedure encode
        converts the following special characters to their HTML entity equivalents:

        "	is converted to	"
        &	is converted to	&
        <	is converted to	&lt;
        >	is converted to	&gt;

     2. Subprocedure encodeBlanks
        converts blanks to non-breaking spaces ( ).
        This procedure is an alternative to use the traditional HTML tags <pre> and </pre>.

        Examples:

        •  
          

          D VarOutput s 1000 varying ................ /free read record; dow not %eof; VarOutput=%trimr(recordField); VarOutput=Encode(VarOutput); VarOutput=EncodeBlanks(VarOutput); updhtmlvar('htmlvar':VarOutput); wrtsection('TableRow'); read record; enddo; /end-free

        •  
          

          /free read record; dow not %eof; updHtmlVar('htmlvar':EncodeBlanks( Encode(%trimr(recordField)))); wrtsection('TableRow'); read record; enddo; /end-free

        
        
     3. Subprocedure encode2
        allows to translate special characters to their corresponding entities as documented in a user specified "entity" stream file.
        CGIDEV2 provides two "entity" stream files:
        • /cgidevexthtml/encode2Fil.txt
          This is a named entity conversion table, by which, for instance,
             character < is translated to &lt;
          This "entity" stream file is the default value for subprocedure encode2
        • /cgidevexthtml/encode2Fil2.txt
          This is a decimal entity conversion table, by which, for instance,
             character < is translated to &#60;
          

        Required parameter group:

        returned value:	65528 char max,	input string with special characters converted to HTML named entities
        inputs:	1891 char max,	input string with special characters to be converted to HTML named entities
        	10i 0,	return code:	0 = successful -1 = file error. Could be any of the following: file not found file not accessible (authority, etc.) file empty file contains no valid records (at run time, a detailed message is sent to the CGIDEBUG debugging file)
        	256 char max,  (optional)	"entities" stream file, the file that contains the arrays of characters and character entities. If omitted, file /cgidevexthtml/encode2fil.txt is used.

        Note 2. Click

        • here to display named entities stream file /cgidevexthtml/encode2fil.txt
        • here to display decimal entities stream file /cgidevexthtml/encode2fil2.txt

        Note 3. Click here to run CGI dspencode2. This program may be used to validate an "entity" stream files used by encode2.

        Note 4. To customize the arrays:

        • Never modify, move, or rename the CGIDEV2-provided stream files
          • /cgidevexthtml/encode2fil.txt (named entities)
          • /cgidevexthtml/encode2fil2.txt (decimal entities)
        • Copy a CGIDEV2-provided stream file to an IFS file of your own.
        • Make sure QTMHHTP1 has *RX authority to your file.
        • Modify your file:
          • Record format, one record per line
          • Comment records:
            • positions 1 -2 must be //
          • Data records:
            • Position 1 = the character to be encoded
            • Positions 2 - 9 = the character entity to be substituted for the character. If these positions are blank, the record is ignored.
            • Remainder of record = blanks or comments
        • Use your file in the EntitiesFile parameter.

        Coding examples:

        •  
          

          D inputString s 1891 varying D outputString s 65528 varying D numberEntFile s 256 D rc s 10i 0 inz(0) /free // Convert inputString to named entities outputString=encode2(inputString:rc); // Convert inputString to decimal entities numberEntFile='/cgidevexthtml/encode2fil2.txt'; outputString=encode2(inputString:rc:numberEntFile); /end-free

        •  
          

          * Passing a literal
          C                   eval      result = encode2('':rc)
          * Passing a varying field.
          C                   eval      vfield = ''
          C                   eval      result = encode2(vfield:rc)
          * Passing from a fixed length field
          C                   eval      ffield = ''
          C                   eval      result = encode2(%trimr(ffield):rc)
          * Passing an expression
          C                   eval      result = encode2('abc' +
          C                             %trimr(ffield) +
          C                             vfield + 'xyz':rc)
                      

   
   
   
4. Conversion procedures from module XXXDECODE2
   • Subprocedure Decode2 can be used to convert a string containing HTML named or number entities to a string containing their corresponding special characters. The conversion is performed through a special user specified stream file (the same stream file used for subprocedure encode2).
     CGIDEV2 provides two "entity" stream files:
     • /cgidevexthtml/encode2Fil.txt
       This is a named entity conversion table, by which, for instance,
          character &lt; is translated to <
       This "entity" stream file is the default value for subprocedure encode2
     • /cgidevexthtml/encode2Fil2.txt
       This is a decimal entity conversion table, by which, for instance,
          character &#60; is translated to <
       
     In other words, subprocedure decode2 is exactly the opposite of subprocedure encode2.

     Required parameter group:

     returned value:	65528 char max, fixed or variable length	input string with HTML named entities converted to special characters
     inputs:	65528 char max, fixed or variable length	input string with HTML named entities to be converted to special characters
     	10i 0,	return code:	0 = successful -1 = file error. Could be any of the following: file not found file not accessible (authority, etc.) file empty file contains no valid records (at run time, a detailed message is sent to the CGIDEBUG debugging file)
     	256 char max,  (optional)	"entities" stream file, the file that contains the arrays of characters and character entities. If omitted, file /cgidevexthtml/encode2fil.txt is used.

     Note 5. Variables inputString and outputString can be fixed or varying length. Their lengths must not exceed 65528.
     

     Note 6. Third parameter dftFile of decode2() can be omitted, thus defaulting to stream file /cgidevexthtml/encode2fil.txt .
     See also notes 2 to 4 for encode2.

     Coding example:

     •  
       

       D inputString s 65528 varying D outputString s 65528 varying D outputString2 s 65528 varying D numberEntFile s 256 D rc s 10i 0 inz(0) /free // Convert named entities from inputString outputString=decode2(inputString:rc); // Convert decimal entities from inputString numberEntFile='/cgidevexthtml/encode2fil2.txt'; outputString=decode2(inputString:rc:numberEntFile); // Convert named AND decimal entities from inputString outputString=decode2(inputString:rc); numberEntFile='/cgidevexthtml/encode2fil2.txt'; outputString2=decode2(outputString:rc:numberEntFile); /end-free

   
   
   
5. Conversion procedures from module XXXCVTSTG
   • Subprocedure CvtStg (Convert String) can be used to convert a memory string from one CCSID to another CCSID. For instance you could convert a memory string from CCSID 1208 (Unicode, UTF-8 Level 3) to CCSID 37 (EBCDIC USA, Canada, Netherlands, Portugal, Brazil, Australia, New Zealand).
     This is how you use it:

     * "InpCCSID" is the CCSID of the input string * (the string to be converted) * "InpBufP" is a pointer to the input string * "InpBufLen" is the length on the input string * "OutCCSID" is the CCSID of the output string * (the string to receive the converted value) * "OutBufP" is a pointer to the output string * "OutBufLen" is the length of the output string * (this length must be large enough * to contain the converted value) * "OutDtaLen" is the length of the converted value * once it is converted in the output string D InpCCSID s 10u 0 D InpBufP s * D InpBufLen s 10u 0 D OutCCSID s 10u 0 D OutBufP s * D OutBufLen s 10u 0 D OutDtaLen s 10u 0 /free // Convert a memory string from CCSID 1208 to CCSID 37 InpCCSID=1208; OutCCSID=37; CvtStg(InpCCSID:InpBufP:InpBufLen; OutCCSID:OutBufP:OutBufLen:OutDtaLen);