Add View Map (QteAddViewMap) API

The Add View Map (QteAddViewMap) API is used to map positions in one view to positions in another view. Both the view being mapped from and the view being mapped to must be previously added with the Add View Description API.

When mapping one view to another view, positions on both views are specified. There are two ways of specifying a position in the view:

• A line and column number in the view can be specified. This is the line number of the text of the view. The text is the concatenation of all text described by text descriptors.
• Alternatively, a file index, and a line and column in the file, can be specified. This allows view positions to be specified in terms of file positions.

A few rules must be followed when using the file method to specify positions. These rules pertain to the view for which file positions are to be specified:

1. The view must be a text view (type *TEXT).
2. All positions in the view must be specified using the file method. File positions and view positions may not be mixed.
3. The view may have a *TEXT view as a previous view, but the text from the previous view must consist of exactly one text descriptor, and that text descriptor must indicate that text comes from a file.

All lines in the from view must map to a position in the to view. For this reason, the first element in the mapping must specify line 1 of the from view.

This API is also used when mapping locations in a view to HLL statement numbers (the *STATEMENT view). This is accomplished by referencing the locations in the from view parameters (from view number and from line) and specifying the statement view number in the to view parameters (to view number and to line).

This API is also used when mapping HLL statement numbers (the statement view) to block numbers. This is accomplished by putting positions in the *STATEMENT view in the from line parameter and the block number in the to line parameter.

All the map positions for the two views must be added at once, with one call to this API. For this reason, the maps must be built up in a buffer as the processor produces its output. At the end of view creation, all maps are then supplied to this API.

Authorities and Locks

None.

Required Parameter Group

Map descriptor buffer

INPUT; CHAR(*)

The input variable containing view-mapping information that is to be passed to the API. This variable may contain multiple sets of information as long as each format in the variable is the same and the number of entries is specified appropriately.

Note: It is required that all map descriptors for a view be supplied with one call to this API.

Number of entries

INPUT; BINARY(4)

The number of map descriptors that are provided in the map descriptor buffer parameter.

Many map entries may be described in a single map descriptor buffer. However, each entry must represent a single map descriptor, and this parameter must be a count of the number of entries provided.

Each entry must contain all fields indicated, but, depending on the type of map being described by the entry, certain fields will not be used by the API.

Format name

INPUT; CHAR(8)

The content and format of the information supplied by the calling program in the map descriptor buffer. The valid values for format name are:

MAPA0100

Line and column mapping

From view number

INPUT; BINARY(4)

The number of the view being mapped from. This number must have been obtained from a previously added view with the Add View Description API.

Note: The from view number cannot refer to a statement view unless a map block is being created. In other words, a statement view cannot be mapped to a text view. However, text views may be mapped to the statement view.

To view number

INPUT; BINARY(4)

The number of the view being mapped to. This number must have been obtained from a view previously added with the Add View Description API. The special value supported is:

-1	This may be specified when providing a map from a *STATEMENT view to block identifiers.

Error code

I/O; CHAR(*)

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

MAPA0100 Format

The following table shows the information supplied in the MAPA0100 format:

Field Descriptions

From column. The column number where text is located. This is the character position on the line specified above. Column numbers in the range 1 through 255 can be specified.

Note: Column numbers are not supported at this time. For upward compatibility, you should specify a value of 1.

From file index. The number of the file, if the position is specified in terms of a file. This file must have been added and used in a text descriptor of the view. If the position is specified in terms of a view, the file index must be set to special value -1.

When file 0 is specified and the view has a previous view, then this file is assumed to mean a line in the previous view, because the first file specified in the file descriptor must be the root source file used to construct this view. This root source file is the same as the previous view.

From line. The line number of the view or file where the text is mapped from.

When the from view is a *STATEMENT view, this parameter indicates which statement to map from. Its position in the *STATEMENT view is supplied, the first statement having position 1.

Map type. Specifies how text from the from view is being mapped to the to view at the position indicated.

To column. The column number specifying the starting character position within the line where the text is to go. Column numbers in the range 1 through 255 can be specified.

Note: Column numbers are not supported at this time. For upward compatibility, you should specify a value of 1.

To file index. The number of the file, if the position is specified in terms of a file. This file must have been added and used in a text descriptor of the view. If the position is specified in terms of a view, the file index must be set to special value -1.

When file 0 is specified and the view has a previous view, then this file is assumed to mean a line in the previous view, because the first file specified in the file descriptor must be the root source file used to construct this view. This root source file is the same as the previous view.

To line. The line number of the view or file where the text is mapped to.

When the to view is a *STATEMENT view, this parameter indicates which statement to map to, the first view having position 1.

When the to view is a block view (special value -1), this parameter indicates which block number to map to.

Error Messages