_storclen()
 Assign a character value to a referenced variable using a string with
 explicit length
------------------------------------------------------------------------------
 C Prototype

     #include "extend.api"
     int _storclen(
                    char far * fpString,
                    unsigned int uiLength,
                    int iParamNum
                    [, int iArrayIndex]
                  )

 Arguments

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

     uiLength specifies the logical length of the character value to be
     assigned.

     iParamNum is the one-based ordinal position in the parameter list of
     the parameter to be assigned.

     iArrayIndex is an array index that specifies a particular element if
     the iParamNum parameter is an array.

 Returns

     _storclen() returns one if the function is successful; otherwise, it
     returns zero.

 Description

     _storclen() stores a character value to a variable passed by reference
     as a parameter from CA-Clipper.  If the parameter specified by iParamNum
     is not passed by reference, _storclen() ignores the call and returns a
     value of zero.

     Since _storclen() 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:  _storclen() 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 _storclen().

 Examples

     .  From C:

        char data[5] = {1, 0, 2, 0, 3, 3};
        _storclen(data, 5, 1);

     .  From Assembly language:

        EXTRN __storclen:FAR
              mov   ax, 1               ; iParamNum
              push  ax
              mov   ax, 5               ; logical length
              push  ax
              mov   dx, seg MyData      ; pass address of data
                                        ; (creation of MyData not shown)
              mov   ax, offset MyData
              push  dx
              push  ax
              call  __storclen
              add   sp, 8               ; reset stack pointer

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