Add View Description (QteAddViewDescription) API

The program uses the Add View Description (QteAddViewDescription) API to add a new view in the existing view information. The added view can then be used on subsequent APIs when providing text and map details associated with this view.

It is the responsibility of each processor to create its input view, which is the root source file read by the processor. Each processor must also create its output view, which is the source produced by the processor. Other intermediate views may be produced, but, as a minimum, there must be a map between a processor's input and output view.

If a processor discards views produced by previous preprocessors, then it is not necessary for the input source view to be created. For example, the C compiler can create only a listing file view, as long as it discards all previous views.

It is possible to create several views at one time. It is the responsibility of the processes creating multiple views to manage them.

When a view is created, a handle to that view is returned in the form of a view number. This number is needed when adding text or maps that refer to the view. Once a view has been created, it cannot be created again. However, text and maps can be added to the view if it already exists. Thus, one processor can create the view, and another processor can add a map to the view, if that processor knows the view number.

There is only one statement view per module. If the statement view is created more than once, an error results. However, the statement view number is returned. This allows one processor to create the statement view and another processor to determine which number the view is.

Note: The following restrictions apply to the adding of views.

1. If a *TEXT view is added and that view refers to text in a previous view, the previous view must also be a *TEXT view.
2. The *INPUT and *OUTPUT views of a processor must be *TEXT views. A processor does not have to create these views.

Authorities and Locks

None.

Required Parameter Group

Previous view number

INPUT; BINARY(4)

The view number of a previous view whose text is used in creating the text for this view. When describing text for this view, it can be indicated that part of the text is a direct copy of text in the previous view. This allows the API to automatically generate a map between this view and the previous view.

As an example, if a preprocessor takes as input some source, changes it by expanding macros or SQL statements, and outputs the changed source, then the output view would have the input view as its previous view. When creating text from the output view, some of the text could come from the input view.

The previous view of a *TEXT view must also be a *TEXT view.

If there is no previous view, specify zero for the view number.

View type

INPUT; CHAR(10)

The type of view being created. Not all view types need be present in the view information. View type can be one of the following values:

*TEXT	The view may contain supplied text as a result of macro expansions. Text may also come from a previous view or from files.
*LISTING	Text for this view comes entirely from supplied text. Thus, the entire text for this view is encapsulated with the view debug data and is not dependent on the existence of source files.
*STATEMENT	This view has no source text. Instead, the text of the view consists of HLL statement number, statement type, and the procedure dictionary ID. This view is necessary because breakpoint positions are given in terms of positions in this view.

Input/output

INPUT; CHAR(10)

Indicates whether the view is an input view, an output view, or an intermediate view. An input view is the view created from the output of the previous processor, or the view created from the root source file. It is not necessary for each processor to have an input view.

An output view is the view created by the processor to be input to the next processor. If a processor creates views that will not be used by any subsequent processors, then no output view is specified.

The allowable values for this parameter are:

*INPUT	The view is an input view. This means that it must come from a root source file created by the user or by a previous processor, generally the input file specified on Start View Creation.
*OUTPUT	The view is an output view. This means that it forms the text of a view that may be read by a subsequent processor, and is generally stored in the output file specified on Start View Creation.
blank	The view is neither an input nor an output view, but is an intermediate view produced by the processor.

Create map

INPUT; CHAR(10)

Specifies whether the using program will be supplying mapping information for this view, or whether the source debugger support should infer (create) the mapping at the time the text is described.

The purpose of the automatic mapping is to allow the ease of creating an include view. An include view has a previous view (usually the input view) which consists of only one file. The include view gets its text from this file and from include files.

This parameter applies only when the view type specified in the previous parameter is *TEXT, and when this view has a previous view. A map can then be inferred from the previous view to this view. To do so, the following criteria must be met:

• This view must contain text from the previous view whenever possible.
• The first file specified on the QteAddViewFile API call for this view must be the file which is equivalent to the previous view.
• When constructing the include view, the line with the include statement must never be included in the text of the view. Instead, it is replaced with the file that is specified.

Create map can be one of the following values:

*YES	The source debugger support should infer the map between this *TEXT view and its previous view based on the text added with the QteAddViewText API. This is the only map to this view that is inferred.
*NO	The program creating this *TEXT view uses the QteAddViewMap API to provide mapping information for this view.

View description

INPUT; CHAR(50)

A character string that describes the view being created. The source debugger has the option of displaying this text with the view for identification purposes. The description should be left-justified.

View number

OUTPUT; BINARY(4)

A number used to identify the view. Other APIs must be passed this number when they require a view.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

[ Back to top | Debugger APIs | APIs by category ]