HLI: Model 204 tables: Difference between revisions

Latest revision as of 23:21, 15 July 2016

Overview

This topic describes Model 204 tables, which comprise the user work area, for application programmers who are using the Host Language Interface facility. Use the information in this topic to avoid or correct table full conditions that occur during program execution.

Refer to the descriptions of table entries for multiple cursor IFSTRT thread calls if you are using multiple cursor functionality in your HLI application for the first time.

See Large request considerations for more information about user work areas.

See HLI: Function summary for a description of individual HLI calls.

User work area

Model 204 allocates an internal work area for each IFSTRT and IFDIAL thread to store the information necessary to evaluate a call or to run a request.

Each work area is composed of a set of tables. The internal work areas for IFSTRT and IFDIAL threads include the following Model 204 tables:

FTBL, for file groups
NTBL, for names of cursors, lists, %variables, compilations
QTBL, for quadruples, that is, statements in internal form
STBL, for character strings
TTBL, for temporary work pages
VTBL, for compiler variables

In IFAM2 and IFAM4, the CCASERVR data set stores a user's work area, including these tables, when the user is swapped out of memory. See HLI: Model 204 files and records for information about CCASERVR.

The next two sections provide information about specifying the size of these tables and avoiding table full conditions. The sections that follow describe each of the user work tables for HLI processing.

See Large request considerations for more information about user work areas.

Managing table sizes

Specifying user table size

You can specify the size of a user work area table by setting the corresponding user table parameter in any user parameter line in an IFAM1 or IFAM4 job. In an IFAM2 or IFAM4 job, you can reset a user table parameter by using the IFUTBL call.

The following user table parameters correspond to the user tables:

Parameter	Table	Specifies...	Default value	Maximum
LFTBL	FTBL	Length in bytes	1000 bytes	65,528 bytes
LNTBL	NTBL	Number of entries	50 entries	5,460 entries
LQTBL	QTBL	Number of entries	400 entries	262,143 entries
LSTBL	STBL	Length in bytes	600 bytes	16 megabytes
LTTBL	TTBL	Number of entries	50 entries	8,190 entries
LVTBL	VTBL	Number of entries	50 entries	524,287 entries

See HLI: Job design factors for information about IFAM1, IFAM2, and IFAM4 jobs. See IFUTBL for a description of the IFUTBL call.

Note: In IFAM1, IFAM2, and IFAM4, the Model 204 server area must be large enough to accommodate the aggregate work area table size for HLI threads in the job.

If you override the default server area that is allocated by specifying the SERVSIZE User 0 parameter, calculate a value using the appropriate SERVSIZE formula that includes the sum of the user table sizes.

For more information about server areas, SERVSIZE, and user work area table parameters, see Server areas.

For more information about UTABLE parameters, see Overview of Model 204 parameters.

Avoiding table full conditions

Model 204 keeps user work area table entries for precompiled specifications and %variables for use by later calls. On a multiple cursor IFSTRT thread, Model 204 also stores compilations and retains multiple record sets.

On each thread, Model 204 clears table entries for noncompiled HLI calls after processing each call. It is unlikely that noncompiled calls would generate enough table entries to cause table full conditions.

However, you might encounter a table full condition for a noncompiled call when the table is already full of entries for calls issued by the thread. If a table is full, Model 204 returns a completion code of 7 to the HLI program.

To avoid table full conditions, when a compilation is no longer needed, delete it with a call to IFFLUSH.

File group table (FTBL)

Model 204 stores data structures related to file groups, as opposed to single files, in FTBL. There are two types of FTBL entries. Model 204 allocates an entry under each of the following conditions:

Each time a group is opened.
This type of entry has a fixed-size portion of 56 bytes, plus 2 bytes per file in the group definition. Model 204 releases this entry when the group is closed.
For collecting field name codes and properties, each time a new field name is encountered in a HLI call.
The entry size is variable, consisting of 9 fixed bytes, plus a number of bytes equal to the length of the field name plus 11 bytes for each file in the group. Model 204 does not delete this entry until the group is closed or until IFFNSH is executed.

In addition to the space required by these two types of entries, Model 204 allocates a fixed amount of space in FTBL equal to 2 bytes times the value of the NGROUP runtime parameter.

Names table (NTBL)

Model 204 creates one entry for each cursor, list name, %variable, or compilation name. On a single cursor IFSTRT thread, the first IFFDV call also generates an entry, and Model 204 saves entries until a new file or group is opened or until the thread is deleted.

NTBL entries are 12 bytes long.

Note: You can explicitly delete compilation names and %variables with the IFFLUSH call.

Internal statements/quad table (QTBL)

Quadruples are the internal version of many HLI calls. The Host Language Interface evaluates some calls directly. Others, like IFFIND, IFCOUNT, and list manipulations, build quadruples (quads) so that the SOUL evaluator routines can be used.

QTBL entries range from 4 to 40 bytes in length. The following sections describe QTBL entries.

QTBL requirements for search functions

The following HLI calls, which perform find functions, use space in QTBL:

Each IFCTO generates 8 bytes of control information. Additionally, each field name takes 16 bytes.
IFFIND generates 20 bytes of control information.
For information about additional QTBL bytes used by IFFIND, see the description of storage requirements for FIND in Large request considerations.
IFFAC uses the same amount as IFFIND plus an additional 40 bytes.
IFFDV generates 20 bytes of control information. Additional bytes are generated depending on the type of field used in IFFDV, as follows:
- For an FRV field, an additional 76 bytes are generated for single files and 96 bytes for a group.
- For an ORDERED field, an additional 32 bytes are generated.
  For information about additional QTBL bytes used by IFFDV, see the description of QTBL storage requirements for FIND ALL VALUES in Large request considerations.

QTBL requirements for retrieval and update functions

The following HLI calls, which perform get and store functions, use space in QTBL:

Each IFGET compilation generates 12 bytes of control information. Additionally, each field name takes 16 bytes.
Additional bytes in QTBL are used by IFFTCH, IFUPDT, IFGET, and IFPUT as necessary based on the following storage requirements:
- If a field name list is specified, each field name or field name variable in the list takes 8 bytes.
- If an EDIT specification exists, each EDIT item takes approximately 3 bytes.
- Iteration factors take 4 bytes each.
- If a secondary field name list is specified with EDIT, the list uses 4 extra bytes plus the space taken for the fields and extra format items.
An IFGETV compilation requires 12 bytes. Additionally, if an EDIT specification exists, each EDIT item takes approximately 3 bytes.
IFSTOR takes the same amount as IFGET, plus an additional 20 bytes.

QTBL requirements for %variables

HLI calls, which assign %variables in specifications, use space in QTBL. %Variable assignment specifications use the same amount of space as IFGET specifications. Model 204 deletes a %variable specification as soon as the assignment is completed.

QTBL requirements for sort functions

The following HLI calls, which perform sort functions, use space in QTBL:

Each IFSORT compilation uses 72 bytes.
Each IFSRTV compilation uses 76 bytes.

QTBL requirements for cursor functions

The following HLI calls, which perform cursor functions, use space in QTBL:

Each IFOCUR compilation uses 20 bytes.
IFFRN uses 8 bytes.

Character string table (STBL)

Model 204 stores all character strings in STBL. Each stored string is preceded by a field that is 1 byte in length.

STBL entries are as follows:

IFDVAL and IFFILE use STBL to store the value string from the input parameter.
Any values specified for IFFIND are stored in STBL.
The EDIT form of IFPUT or of a %variable assignment uses STBL for each value, reusing the space from previous values.
Each %variable uses enough space to hold its current value, plus 1 byte. If the length of the value changes, the amount of STBL space changes accordingly.
When an IFOCUR that specifies an IN ORDER BY [ordered field] clause is executed, Model 204 allocates 256 bytes of STBL space. Model 204 frees the STBL space when the cursor is closed.
Additionally, if LIKE is specified on the IN ORDER clause, Model 204 allocates storage for the pattern terms. This amount depends on the length and format of the pattern string and cannot exceed 255 bytes.

Temporary work table (TTBL)

TTBL is a collection of 4-byte CCATEMP page numbers currently in use by each user. Those entries point to CCATEMP pages that have been allocated by:

Various Find statements. Most prominently, IFFIND calls, direct searches, including IS PRESENT, and range retrievals using the Ordered Index.
These statements require some number of CCATEMP pages (depending on the complexity of the selection criteria) for evaluation, and each CCATEMP page allocated is tracked by an entry in TTBL. These CCATEMP pages and their corresponding entries in TTBL are released after the Find is evaluated.

Compiler variable table (VTBL)

Entries in VTBL are variable, with most ranging from 8 to 20 bytes.

Note: In addition to the requirements described in the following sections, the Host Language Interface uses some additional VTBL entries for temporary work space.

VTBL requirements for search functions

The following HLI calls, which perform search functions, use space in VTBL:

IFCOUNT allocates one 8-byte entry.
On a single cursor IFSTRT thread, each IFFIND allocates one basic entry, either 8 bytes for a single file or (8 + 8*number-of-files) bytes for a group. On a multiple cursor IFSTRT thread, each compiled IFFIND generates one basic entry for a single file or group.
In addition to the basic entry, IFFIND allocates additional bytes in VTBL as listed below. Model 204 releases all but the basic entry after evaluating the IFFIND call.
- IFFIND allocates at least two 20-byte entries for scratch purposes, and more for complex Boolean criteria. Also, one entry is allocated for each field name = value pair referenced.
- The length of a field name = value entry is at least 20 bytes and is greater for large files.
- IFFIND generates one 8-byte entry in VTBL if any direct search condition is specified in the IFFIND, and allocates one 28-byte entry for each such direct search condition.
For information about additional VTBL bytes used by IFFIND, see the description of VTBL storage requirements for FIND in Large request considerations.
On a single cursor IFSTRT thread, each IFFDV allocates one basic entry, either 20 bytes for a single file or (12 + 8 + 8*number-of-files) bytes for a group. On a multiple cursor IFSTRT thread, each compiled IFFDV generates one basic entry for a single file or group.
In addition to the basic entry, IFFDV allocates additional bytes in VTBL as listed below. Model 204 releases all but the basic entry after evaluating the IFFDV call.
- IFFDV allocates two 20-byte entries for scratch purposes, and another 64 bytes for a group.
- If an IFFDV call containing the FROM/TO option is used with an FRV field, IFFDV allocates one 44-byte entry. With ORDERED fields, IFFDV allocates two 44-byte entries.

VTBL requirements for retrieval functions

IFGET allocates no VTBL entry unless it specifies the IN ORDER clause, which uses 168 bytes.

VTBL requirements for sort functions

The following HLI calls, which perform sort functions, use space in VTBL:

Each IFSORT compilation uses 76 bytes in VTBL.
Each IFSRTV compilation uses 80 bytes in VTBL.
Each IFFRN uses 32 bytes.
Each IFSTOR uses 32 bytes.

VTBL requirements for cursor functions