Code Evaluation

HANDLE         nameHandle;
short         nameLength;
short         direction;
char        *fieldName;

Any time you evaluate a function that returns a variable length string, you will need at least three variables:

The direction variable in this example will hold the sort direction and is specific to PEGetNthSQLExpression.

It is important to note that although the PEGetNthSortField function is defined in the Crystal Report Engine as accepting a pointer to a handle (HANDLE*) and a pointer to a short (short*), nameHandle and nameLength are not defined as pointer variables. Instead, they are defined simply as a HANDLE and a short integer, then passed to PEGetNthSortField with the & operator. This technique automatically initializes the variables with the address of the variable itself. Since the PEGetNthSortField function requires the address in memory to place the information, this is the most convenient method to define and pass the variables.

PEGetNthSortField (printJob, sortFieldN,
            &nameHandle, &nameLength,
            &direction);

The PEGetNthSortField function places a handle to the sort field name in the nameHandle location and the length of the field name (all characters in the name plus a terminating null byte) in the nameLength location. These values will be used to extract the actual field name.

/*allocate fieldName buffer*/
fieldName = (char*)malloc(nameLength);

Now that you know the actual length of the field name you are trying to obtain, you can allocate exactly the right amount of memory to store that name. The malloc function does this.

Note:     Malloc is defined in the C runtime library stdlib.h.

PEGetHandleString (                nameHandle,
                fieldName,
                nameLength);

PEGetHandleString, uses the string handle to retrieve the field name and store it in fieldName. At the same time, nameHandle is invalidated. Now, the text can be used like any other character string.

Note:    This code is meant as a basis for your own code. Although these elements shown here are necessary for extracting a variable length string from certain Crystal Report Engine functions, experienced programmers may wish to expand the code to trap errors or handle the string text differently.

The following is a list of the Crystal REAPI functions that return variable length strings:



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