PI74835: New BASE64ENCODE and BASE64DECODE built-in functions

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• The new BASE64ENCODE and BASE64DECODE built-in functions will
  produce and consume an EBCDIC encoding.
  

Local fix

• N/A
  

Problem summary

• ****************************************************************
  * USERS AFFECTED: Enterprise PL/I users who want to perform    *
  *                 base 64 encoding and decoding from EBCDIC    *
  *                 or ASCII.                                    *
  *                                                              *
  ****************************************************************
  * PROBLEM DESCRIPTION: Add support for the BASE64ENCODE and    *
  *                      BASE64DECODE built-in functions to the  *
  *                      Enterprise PL/I runtime library. These  *
  *                      new built-in functions encode an        *
  *                      input buffer into base 64 as CHARACTER  *
  *                      and decode a buffer holding base 64     *
  *                      held as CHARACTER to an output buffer.  *
  *                                                              *
  ****************************************************************
  * RECOMMENDATION: Apply the PTF for this APAR.                 *
  *                                                              *
  ****************************************************************
  This APAR will provide the complete library support for the
  BASE64ENCODE and BASE64DECODE as described above.
  

Problem conclusion

Temporary fix

Comments

• This APAR will provide the complete library support for the
  BASE64ENCODE and BASE64DECODE built-in functions.
  
  The Enterprise PL/I Language Reference manual, SC27-8940-00,
  will also be updated as follows:
  
  In chapter "Built-in functions, pseudovariables, and
  subroutines"
    section "Categories of built-in functions"
    subsection "Buffer-Management built-i functions"
  
    In table Buffer-management built-in functions:
    - Add to the table new built-in function BASE64ENCODE with the
      following description:
      Encodes the source buffer into base 64 that is encoded as
      CHARACTER. Returns a size_t value that indicates the number
      of bytes that are written into the target buffer.
    - Add to the table new built-in function BASE64DECODE with the
      following description:
      Decodes the source buffer from base 64 that is encoded as
      CHARACTER. Returns a size_t value that indicates the number
      of bytes that are written into the target buffer.
  
    Add the new built-in functions BASE64ENCODE and BASE64DECODE
    in the paragraph before the bif BASE64ENCODE8 with the
    following descriptions:
  
    BASE64DECODE decodes the source buffer from base 64 that is
    encoded as CHARACTER. It returns a size_t value that indicates
    the number of bytes that are written into the target buffer.
  
    +------------------------------------------------------------+
    |                                                            |
    | >>--BASE64DECODE(p,m,q,n)----------------------------------|
    |                                                            |
    +------------------------------------------------------------+
  
    p Specifies the address of the target buffer.
    m Specifies the length in bytes of the target buffer. It must
      have a computational type and is converted to type size_t.
    q Specifies the address of the source buffer.
    n Specifies the length in bytes of the source buffer. It must
      have a computational type and is converted to type size_t.
  
    If the address of the target buffer is zero, the number of
    bytes that would be written is returned. If the target buffer
    is not large enough, a value of -1 is returned. If the target
    buffer is large enough, the number of bytes that is written
    to the buffer is returned.
  
    This function is the reverse of the function BASE64ENCODE and
    expects that the base 64 source was encoded by using the same
    convention that the BASE64ENCODE function uses. See
    "Convention for encoding a source buffer into base 64 as
    EBCDIC" for details. If other conventions were used, the
    results are unpredictable.
  
  
    BASE64ENCODE encodes the source buffer into base 64 that is
    encoded as CHARACTER. It returns a size_t value that
    indicates the number of bytes that are written into the
    target buffer.
  
    +------------------------------------------------------------+
    |                                                            |
    | >>--BASE64ENCODE(p,m,q,n)----------------------------------|
    |                                                            |
    +------------------------------------------------------------+
  
    p Specifies the address of the target buffer.
    m Specifies the length in bytes of the target buffer. It must
      have a computational type and is converted to type size_t.
    q Specifies the address of the source buffer.
    n Specifies the length in bytes of the source buffer. It must
      have a computational type and is converted to type size_t.
  
    If the address of the target buffer is zero, the number of
    bytes that would be written is returned. If the target buffer
    is not large enough, a value of -1 is returned. If the target
    buffer is large enough, the number of bytes that is written
    to the buffer is returned.
  
    Under the compiler option DFT(ASCII), BASE64ENCODE behaves
    the same as BASE64ENCODE8 (since the base 64 "digites" in
    ASCII are the same as they are in UTF-8).
  
    Convention for encoding a source buffer into base 64 as
    EBCDIC
  
    This encoding uses the following set of base 64 "digits":
  
    ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
    0123456789+/
  
    Each 6 bits of the source is converted to the corresponding
    EBCDIC "digit" in this base 64 string. If the source length
    in bits is not a multiple of 6, the result concludes with
    one or two '='e symbols as needed.
    The source buffer is treated as a bit string, so the result
    in the target buffer varies with the code page of the
    source.
  
    The following table shows the example of the sources and the
    corresponding results when converting source buffer into
    base 64 that is encoded as EBCDIC by using the BASE64ENCODE.
  
    Table n. Example of encoding a source buffer into base 64
  
    +-----------------------------------------------------------+
    |Source length | Source value | Result length | Result value|
    +-----------------------------------------------------------+
    | 6            | 'please'A    | 8             | cGxlYXNl    |
    +-----------------------------------------------------------+
    | 5            | 'pleas'A     | 8             | cGxlYXM=    |
    +-----------------------------------------------------------+
    | 4            | 'plea'A      | 8             | cGxlYQ==    |
    +-----------------------------------------------------------+
  
  PUBS CLOSING CODE: DEVCHNG
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UI44442 UI44443

Modules/Macros

• HLE77A0J HLE7790J IBMPB64  IBMPLIB0 IBMPLVD
  IBMQB64N IBMQB64U
  

Fix information

• Fixed component name

  LE VA PL/I

• Fixed component ID

  568819806

Applicable component levels

• R7A0 PSY UI44442

     UP17/02/08 P F702

• R790 PSY UI44443

     UP17/02/08 P F702

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.