Working with Parameter Values and Ranges

Parameters can contain discrete values, ranges, or both discrete values and ranges together. The following discussion outlines how Seagate Crystal Reports handles parameter values and ranges.

Before retrieving a parameter current value or range, Call PEGetParameterValueInfo, Volume 2, Chapter 1, to determine what type of value(s) are stored. PEParameterValueInfo, Volume 2, Chapter 1, member hasDiscreteValues will contain one of the following three constants.

The functions listed below are used to add and retrieve parameter discrete values and parameter ranges. The sequence of functions that you call in your application will depend on whether discrete values, ranges, or a combination of both are present.

Use the following guidelines when deciding which sequence of functions to call.

PEParameterValueInfo.hasDiscreteValues = PE_DR_HASRANGE

¾The parameter field contains only ranges.

¾All values will be treated as ranges.

¾Use the PEXXXParameterCurrentRange(s) function calls. PEParameterValueInfo.hasDiscreteValues = PE_DR_HASDISCRETE

¾The parameter field contains only discrete values.

¾All values will be treated as discrete values.

¾Use the PEXXXParameterCurrentValue(s) function calls. PEParameterValueInfo.hasDiscreteValues = PE_DR_HASDISCRETEANDRANGE

¾The parameter field contains both discrete values and ranges.

¾All values will be treated as ranges.

¾Use the PEXXXParameterCurrentRange(s) function calls.

¾You can also call PEAddParameterCurrentValue to add a discrete value, but the discrete value will be stored internally as a range and you will need to call PEGetNParameterCurrentRanges and then PEGetNthParameterCurrentRange when you want to retrieve it. If you try to retrieve the discrete

value using PEGetNParameterCurrentValues, 0 will be returned.

Working with section codes

The following topics relating to section codes are presented in this section.

Overview, Page 84

Encoding, Page 84

Decoding, Page 86

Section Map, Page 87

Section Codes in Visual Basic, Page 88

Overview

A report, by default, contains five areas: Report Header, Page Header, Details, Report Footer, and Page Footer. Each of those areas can contain one or more sections. When you add groups, subtotals, or other summaries to your report, the program adds Group Header and Group Footer areas as needed, and each of those areas can contain one or more sections as well. Since one report can have a totally different section configuration from the next, Seagate Crystal Reports uses calculated section codes to identify the sections in each report.

In Seagate Crystal Report Engine API functions that affect report sections, the sectionCode parameter encodes the section type, the group number (if the section is a Group Header or Group Footer section), and the section number (if there are multiple sections in an area) together in a single value.

The Seagate Crystal Report Engine API also includes macros for encoding section codes (PE_SECTION_CODE, for use with functions that require a section code) and for decoding section codes (PE_SECTION_TYPE, PE_GROUP_N, and PE_SECTION_N, for use with functions that return a section code). The examples that follow show how the encoding and decoding macros can be used.

NOTE: You can not pass the above values directly to a function as section codes. You must use the encoding macro to create a valid section code based on one of the above constants.

Encoding

The PE_SECTION_CODE macro allows you to define a section code to pass as a parameter in Seagate Crystal Report Engine functions that require a section code. The syntax for the macro is:

PE_SECTION_CODE (sectionType, groupNumber, sectionNumber)

The PE_AREA_CODE macro allows you to define a corresponding area code. The following syntax is used:

PE_AREA_CODE(sectionType,groupN)

sectionType

This indicates the report area or section type that the section is in. For section type, use any of the following constants:

groupNumber

Indicates which group the section is in. If the sectionType value indicated is PE_SECT_GROUP_HEADER or PE_SECT_GROUP_FOOTER, the groupNumber is a zero (0) based index for the group section. If the sectionType value is not one of these group section constants, the groupNumber value should always be zero.

sectionNumber

If the report area has been split into more than one section, sectionNumber indicates which section within the area you are using. This value is a zero (0) based index. In other words, the first section in an area is 0, the next section is 1, etc.

NOTE: The macro PE_SECTION_CODE calculates and returns the section code number; it does not return an error code.

The following example demonstrates how to obtain a section code using the PE_SECTION_CODE macro. The section code obtained here is for the second section in the Group Header 1 area:

code = PE_SECTION_CODE(PE_SECT_GROUP_HEADER, 0, 1); PESetSectionFormat(job, code, &mySectionOptions);

In this case you pass the section type (PE_SECT_GROUP_HEADER), the group number (since this is the first group, use the zero indexed group number 0) and section number (since this is the second section in the Group Header, use the zero indexed section number 1). The program uses the encoding macro and returns a section code which is then passed in the PESetSectionFormat call.

When using PE_ALLSECTIONS in your macro, code can be written in one of two ways:

code = PE_SECTION_CODE(PE_ALLSECTIONS, 0, 0);

// the code value returned is 0 - NOT an error code PESetSectionFormat(job, code, &mySectionOptions);

or, you can eliminate using the macro all together:

PESetSectionFormat(job, PE_ALLSECTIONS, & mySectionOptions)

NOTE: The maximum number of groups is 25 (possible values of 0 to 24). The maximum number of sections is 40 (possible values of 0 to 39).

Decoding

Some Seagate Crystal Report Engine functions return section codes. These values can be decoded using one of three macros:

1.PE_SECTION_TYPE (sectionCode),

2.PE_GROUP_N (sectionCode), or

3.PE_SECTION_N (sectionCode).

Each macro accepts an encoded section code as a parameter.

In the following example, you determine the number of sections in the report (using PEGetNSections), obtain the section code for each section (using PEGetSectionCode), and then decode the section code using the PE_SECTION_TYPE, PE_GROUP_N, and PE_SECTION_N macros.

numSections = PEGetNSections(job); for (i = 0;i < numSections;i++)

{

code = PEGetSectionCode(job, loopSectionN); areaType = PE_SECTION_TYPE(code);

groupN = PE_GROUP_N(code); sectionN = PE_SECTION_N(code);

// Perform section specific code here

}

Once you’ve identified the area, group, and section you want, you can then set the section format using code similar to this:

PESetSectionFormat(job, code, &mySectionOptions);

NOTE: Earlier versions of Seagate Crystal Reports used different section code constants. Those constants have been remapped to the new section code format so reports created with earlier versions of Seagate Crystal Reports can run with applications created with the current version.

Section Map

The following map shows the pattern of section code assignment:

Report Header

GF1

Section Codes in Visual Basic

The following functions provide Visual Basic equivalents.

Create a section code:

¾This representation allows up to 25 groups and 40 sections of a given type, although Seagate Crystal Reports itself has no such limitations.

Function PE_SECTION_CODE(sectionType As Integer, groupN As Integer, sectionN As Integer) As Integer

PE_SECTION_CODE = (((sectionType) * 1000) + ((groupN) Mod 25) +

(((sectionN) Mod 40) * 25))

End Function