Crystal Report Engine API variable length strings

Several REAPI functions provide information in the form of a variable length string value or character array. When your program calls an REAPI function that produces a variable-length string, the Crystal Report Engine saves the string, creates a string handle which refers to the string, and returns that handle along with a value indicating the length of the string. To retrieve the contents of the string, you must call PEGetHandleString. This approach allows you to allocate a buffer of the exact size needed to hold the string before obtaining the actual string.

If your development language cannot allocate a buffer at runtime, you should declare a reasonably large buffer. Field names and error messages will generally be less than 100 bytes, but formulas may be 1000 bytes or longer. You can control how much data is copied to the buffer when you call PEGetHandleString.

Here is the procedure to follow when obtaining a variable length string:

  1. Call-up the function which produces the string. This returns the string handle and length. The length includes all characters in the string plus a terminating null byte.
  2. If necessary, allocate the string buffer.
  3. Call-up PEGetHandleString to copy the string from the handle into the buffer.

Note:    PEGetHandleString frees the memory occupied by the string handle, so you can only call this function once for a given handle.

Note:    For experienced Windows programmers: text and name handles are Global Memory Handles for memory segments on the global heap. If you prefer, you can access these segments using the Windows GlobalLock, GlobalUnlock, and GlobalFree functions. Contents of name and text handles are null terminated ASCII strings. You must free the text handle with GlobalFree when you are done with it (PEGetHandleString does this for you, if you use it).



Seagate Software IMG Holdings, Inc.
http://www.seagatesoftware.com
Support services:
http://support.seagatesoftware.com