Create an area code:

Function PE_AREA_CODE(sectionType As Integer, groupN As Integer) As Integer PE_AREA_CODE = PE_SECTION_CODE(sectionType, groupN, 0)

End Function

Decode a group number from a section code:

Function PE_GROUP_N(sectionCode As Integer) As Integer

PE_GROUP_N = ((sectionCode) Mod 25)

End Function

Decode a section number from a section code:

Function PE_SECTION_N(sectionCode) As Integer

PE_SECTION_N = (((sectionCode \ 25) Mod 40))

End Function

Decode a section type from a section code:

Function PE_SECTION_TYPE(sectionCode As Integer) As Integer

PE_SECTION_TYPE = ((sectionCode) \ 1000)

End Function

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, Volume 2, Chapter 1. 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 can not 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:

1Call-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.

2If necessary, allocate the string buffer.

3Call-up PEGetHandleString to copy the string from the handle into the buffer.

Crystal Report Engine

89

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).

Sample Code

Use the following C code as an example of how to call a function that returns a variable length string. The code uses the PEGetNthSortField, Volume 2, Chapter 1, function which obtains the name of a field being used to sort the report and the direction of the sort. There are several other functions that return variable length strings, all of which are handled in a similar fashion.

Examine this code carefully and try to incorporate it into your own application without modifying the basic procedure. Only experienced programmers should try making changes to this technique since small mistakes here can cause major errors in your application. If you expect to use several REAPI functions that return variable length strings, you may want to set this code up in a separate function to avoid repetition and errors.

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

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

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

PEGetHandleString (	nameHandle,
	fieldName,
	nameLength);
/*

**fieldName now contains name

**of field and nameHandle is no

**longer valid.

*/

NOTE: If you retrieve a string handle but do not retrieve the string itself (i.e., you do not use PEGetHandleString), you should free up the string memory by calling GlobalFree (nameHandle).

Crystal Report Engine

90

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:

1.a handle to the string,

2.a short integer to hold the length of the string, and

3.a character array or pointer to a character array.

The direction variable in this example will hold the sort direction and is specific to PEGetNthSQLExpression, Volume 2, Chapter 1.

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, Volume 2, Chapter 1, 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.

Crystal Report Engine

91

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

PEGetAreaFormatFormula, Volume 2, Chapter 1

PEGetErrorText, Volume 2, Chapter 1

PEGetFormula, Volume 2, Chapter 1

PEGetGroupOptions, Volume 2, Chapter 1

PEGetGroupSelectionFormula, Volume 2, Chapter 1

PEGetNthFormula, Volume 2, Chapter 1

PEGetNthGroupSortField, Volume 2, Chapter 1

PEGetNthParam, Volume 2, Chapter 1

PEGetNthSortField, Volume 2, Chapter 1

PEGetReportTitle, Volume 2, Chapter 1

PEGetSectionFormatFormula, Volume 2, Chapter 1

PEGetSelectedPrinter, Volume 2, Chapter 1

PEGetSelectionFormula, Volume 2, Chapter 1

PEGetSQLQuery, Volume 2, Chapter 1

Crystal Report Engine API structures

Several REAPI functions require a structure or user-defined variable type to be passed as one or more arguments. Some of these functions require that you assign values to all members of the structure before calling the function so that the information can be used to make various settings in the Crystal Report Engine. Other functions require only the size of the structure be assigned to the StructSize member. These functions fill in the rest of the structure members for you, providing you with valuable information about a print job.

NOTE: The term structure is used here to mean both C structures and other user-defined types or records in languages such as Visual Basic and Delphi. If you are unfamiliar with this type of data, refer to the documentation for the programming language you are using.

Each structure used by REAPI is defined and explained in Developer’s online Help with a link to the function that uses it. Functions that use structures also have hypertext links to the structure definitions.

Some of the structures, PEMouseClickEventInfo(Other Declares), Volume 2, Chapter 1, for example, are complex, requiring other structures be passed as member values. Not all programming languages support this feature. If you are using a programming language that does not allow the use of a structure variable as a member variable defined inside other structures, declare the member variable as another data type, such as an integer or a variant data type, and assign it a value of 0 (zero) at runtime. The Crystal Report Engine will automatically provide default values or will request information from the user.

NOTE: Structure variables can not be created using Visual dBASE. Crystal Report Engine functions requiring structures as parameters are not available to dBASE.

Crystal Report Engine

92