_retclen()
 Post a character return value with explicit length
------------------------------------------------------------------------------
 C Prototype

     #include "extend.api"
     void _retclen(
                    char far * fpString,
                    unsigned int uiLength
                  )

 Arguments

     fpString is a far pointer to the data representing the character
     value to be returned.

     uiLength is the logical length of the string.

 Returns

     _retclen() has no return value.

 Description

     _retclen() posts a character value into CA-Clipper's return value area.
     When your Extend routine returns control to the calling CA-Clipper
     program, the posted value becomes the CA-Clipper return value of your
     Extend routine.

     Since _retclen() allows you to specify an explicit logical length for
     the character value, the string you supply does not need to be
     null-terminated and may safely contain embedded null bytes.

     Note:  _retclen() automatically allocates memory in the CA-Clipper
     heap and makes a copy of the supplied string.  The string need not be
     preserved after the call to _retclen().

 Examples

     .  From C:

        char data[5] = {1, 0, 2, 0, 3, 3};  // two embedded null bytes
        _retclen(data, 5);

     .  From Assembly language:

        EXTRN __retclen:FAR
              mov   ax, 5                ; params pushed in reverse
              push  ax
              mov   dx, seg MyData       ; pass address of data
                                         ; (creation of MyData not shown)
              mov   ax, offset MyData
              push  dx
              push  ax
              call  __retclen
              add   sp, 6                ; reset stack pointer

 Files  Library is CLIPPER.LIB, header file is Extend.api.