HLI: Job design factors

Overview

This topic gives the application programmer an overview of the IFAM1, IFAM2, and IFAM4 Model 204 environments that support HLI processing.

This topic presents the factors that determine the type of job to run using the Model 204 Host Language Interface facility. Each type of job provides certain processing capabilities within a particular system environment.

See HLI: Job requirements for details about setting up and running HLI jobs. See HLI: Threads, HLI: IFSTRT processing, and HLI: IFDIAL processing for more information about coding applications.

Processing in different Model 204 environments

The "Summary of HLI processing environments" table summarizes host language application program processing in the different Model 204 environments:

Summary of HLI processing environments

Item	IFAM1	IFAM2	IFAM4
Operating system	z/OS, VSE, CMS	z/OS, VSE, CMS	z/OS
Teleprocessing monitors	--	CICS, INTERCOMM	--
Model 204 copy	Private	Shared	Private
Threads	Single	Multiple	Multiple
Protocol	IFSTRT IFDIAL	IFSTRT IFDIAL	IFSTRT
Enqueuing, with other application programs	File	Record, with those sharing Model 204	File
Recovery	RESTART (rollback only)	RESTART	RESTART
Performance	--	Cross-region overhead	Scheduler overhead

See HLI: Transactions for more information about enqueuing and recovery in the HLI processing environment.

Call protocols

IFSTRT and IFDIAL protocols

The Model 204 Host Language Interface facility supports two types of call protocols: IFSTRT and IFDIAL.

Each of the protocols is available using a different type of thread connection to Model 204. The protocols operate differently and provide different types of host language functionality.

To use IFSTRT protocols, you start an IFSTRT thread (by coding an IFSTRT or IFTSTRTN call in your HLI application). To use IFDIAL protocols, you start an IFDIAL thread (by coding an IFDIAL or IFDIALN call). The functionality that is available using a particular thread is determined by the type of protocol that it uses.

See the IFSTRT (IFAM1), IFSTRT (IFAM2/IFAM4), and IFDIAL pages for details. For more information about coding applications using the two protocols, see HLI: Threads.

IFDIAL thread

An IFDIAL thread provides a line-at-a-time terminal type interface between Model 204 and a host language program that is running in batch. An IFDIAL connection allows an HLI application to issue commands (such as LOGWHO, MONITOR, and LOGCTO) and run SOUL requests, and to receive responses from Model 204.

IFSTRT thread

An IFSTRT thread provides a user interface between Model 204 and a program that uses the Host Language Interface (which runs in batch).

IFSTRT protocols allow an application that is written in a host language to issue calls to Model 204 that perform functions against the database which are similar to Model 204 commands and SOUL statements.

Each IFSTRT connection supports either multiple cursor or single cursor IFSTRT functionality.

Multiple cursor and single cursor IFSTRT threads

An IFSTRT or IFSTRTN call starts either a multiple cursor or single cursor thread by setting a thread type parameter. A multiple cursor type thread supports only multiple cursor HLI functionality, and a single cursor type thread supports only single cursor HLI functionality.

A multiple cursor IFSTRT thread supports host language program access to multiple files and to multiple record sets, using a single thread. By contrast, each single cursor IFSTRT thread allows only single file, single record set database access.

With a multiple cursor IFSTRT thread, the file, set, or record that is specified in the HLI call is the one that is current for processing. In contrast, the current item to be processed on a single cursor IFSTRT thread is always relative to the last file opened, the last set created, and the record last referenced.

Certain IFSTRT calls are supported for use only on a multiple cursor or a single cursor IFSTRT thread, while other IFSTRT calls are supported for use on both multiple cursor and single cursor IFSTRT threads. The application programmer must code only the calls, specifications, and corresponding program logic that are valid for use with the particular type of IFSTRT thread that is started.

See Multiple cursor and single cursor IFSTRT threads for an overview of the calls that are valid for use with a multiple cursor IFSTRT thread. See HLI: Transactions for more information about multiple cursor IFSTRT functionality.

Multiple cursor IFSTRT thread

For an application that requires access to multiple files concurrently, Rocket recommends that you use a multiple cursor IFSTRT thread and that you do not run a multithreaded job (IFAM2 or IFAM4).

For an application that requires access to a single file, or to one file at a time, you can use either a multiple cursor IFSTRT thread or a single cursor IFSTRT thread. Note, however, that if you are performing update processing using one thread, checkpointing is easier on a multiple cursor IFSTRT thread.

Recovery considerations for single and multicursor IFAM2 threads

Single cursor IFAM update threads differ from SOUL and multicursor IFAM threads in that the single cursor threads start an update unit during their IFSTRTN call and end the update unit when IFFNSH is issued. This means that with single cursor IFAM threads active, all transaction checkpoints fail — meaning: time-out. For these threads, you must use IFCHKPT calls to end single cursor update units, wait for a transaction checkpoint attempt, and then start new single cursor update units.

Multicursor IFAM, like SOUL, starts an update unit at the first file update and ends the update unit at update commit (IFCMMT ccall in IFAM). Therefore, multicursor IFAM threads do not require IFCHKPT calls to let a transaction checkpoint proceed, although they may issue IFCHKPT calls to initiate transaction checkpoint attempts or query transaction checkpoint status.

You can use sub-transaction checkpoints to recover files in active update by either single or multicursor IFAM threads; they require no form of IFCHKPT call. When IFAM threads on a sub-transaction enabled Online issue IFCHKPT calls, they are requesting transaction checkpoints. If no IFCHKPT calls are made, IFAM updates are recoverable with sub-transaction checkpoints.

System configurations

IFAM1

The Host Language Interface facility is supported in the IFAM1 configuration running under an z/OS, VSE, or CMS operating system.

IFAM1 supports a single program (that is, a single user), in a single region (that is, the IFAM1 job runs in a region that is separate from the Model 204 Online region using a private copy of Model 204), using a singly-threaded connection (that is, using one thread, either IFSTRT or IFDIAL).

IFAM1 provides the most efficient system access which is useful for testing program modules and applications.

IFAM2

The Host Language Interface facility is supported in the IFAM2 configuration running under an z/OS, VSE, or CMS operating system. IFAM2 is supported in CICS.

IFAM2 supports one or more programs (that is, multiple users sharing the same copy of Model 204), running in separate regions or machines or partitions (that is, the user program runs in a separate region from Model 204 requiring communications between the regions), using a multithreaded connection (that is, using one or more threads, and except for IFDIAL under CMS, can be both IFSTRT and IFDIAL threads).

Note: A batch utility program, BATCH2, is provided by Rocket for use in the IFAM2 environment. For information about the BATCH2 utility, see BATCH2 facility.

For more information about IFAM2, see IFAM2 configurations, below.

IFAM4

The Host Language Interface facility is supported in the IFAM4 configuration running under the z/OS operating system.

IFAM4 supports a single program (that is, a single user), running in a single region (that is, the user program and Model 204 run in the same region), using a multithreaded connection (that is, using one or more IFSTRT threads).

IFAM4 provides the most core-efficient way to run a multithreaded HLI application and is useful in certain test and batch production situations.

Setting up an HLI job

You must set up your HLI job for the particular Model 204 configuration (that is, IFAM1, IFAM2, or IFAM4) in which it will run. To connect to Model 204, the job references a particular link module or set of link modules.

For detailed information about setting up jobs, see HLI: Job requirements.

Call protocols and Model 204 configurations

Each of the HLI protocols may be used in several different Model 204 configurations as summarized below.

Protocol	Model 204 configuration
IFSTRT	IFAM1, IFAM2, IFAM4
IFDIAL	IFAM1, IFAM2

For more information

The following diagrams of HLI application processing in the IFAM1, IFAM2, and IFAM4 configurations show the basic components of each configuration.

For more information about the Model 204 configurations, see Model 204 configurations and operating environments.

IFAM1 configurations

In IFAM1, the HLI batch application program and Model 204 run together in the same region, which is separate from the Online region. There are two basic configurations of the IFAM1 processing environment, one for z/OS and VSE, and one for CMS.

IFAM1 under z/OS and VSE

The following figure shows the logical view of the IFAM1 processing environment for an HLI application running under z/OS or VSE. The figure shows the application program linking to Model 204 with the IFIF1 interface (IFIF1OS for z/OS or IFIF1DOS for VSE).

Note: The Model 204 system manager must build the IFAM1 link with the IFID module included for a user to allow an HLI program to access Model 204 using an IFDIAL thread.

IFAM1 under z/OS and VSE

IFAM1 under CMS

The following figure shows the logical view of the IFAM1 processing environment for an HLI application running under CMS.

The HLI application program is loaded to include a library (not shown) that contains the IFIF1 object module (IFIF1CMS) which must be linked to the program as shown below. The following figure shows the saved segments in a common storage area separate from the user's CMS application.

IFAM1 under CMS

IFAM2 configurations

In IFAM2, the HLI application program runs as a job in a separate region from Model 204, sharing a copy of Model 204 with other users who access the database from host language and SOUL applications.

IFAM2 requires communications between regions, using the Model 204 Cross-Region Access Method (CRAM).

There are two basic configurations of the IFAM2 processing environment, one for z/OS and VSE, and one for CMS.

Logical view of IFAM2 under z/OS and VSE

The following figure shows the logical view of the IFAM2 processing environment for an HLI application running under z/OS or VSE.

The figure shows the following components:

• A host language program is running in Region 1 as a batch job. The HLI application communicates to Model 204 through CRAM. The HLI application program links to Model 204 with the IFIF object module.
• Model 204 resides in Region 2 and runs with the interfaces that enable CRAM communications and teleprocessing.
• An Online application is running in Region 3 under a teleprocessing monitor. The Online application also communicates to Model 204 through CRAM.

IFAM2 under z/OS and VSE

IFAM2 under CMS

The following figure shows the logical view of the IFAM2 processing environment for an HLI application running under CMS.

The IBM inter-user communication vehicle (IUCV) allows a host language program running under CMS to communicate with a Model 204 system running in a separate virtual machine under CMS.

The HLI application program is loaded to include a library (not shown) that contains the following object modules (shown in IFAM1 under CMS) which must be linked to the program: CMIF, IFIF, IFCM, and IUCV.

As the following figure illustrates:

• Model 204 runs under the CMS interface in virtual machine 1 with the VMIF interface that enables IUCV communications.
• A host language program is running in virtual machine 2 as a batch job. The HLI application communicates to Model 204 through IUCV.
• Another host language application is running in virtual machine 3 as a batch job, and communicates to Model 204 through IUCV.

IFAM2 under CMS

IFAM4 configuration

There is one basic configuration of the IFAM4 processing environment, for z/OS. The HLI application program and Model 204 run in the same region as separate subtasks of a single batch job.

Logical view of IFAM4 under z/OS

The following figure shows the logical view of the IFAM4 processing environment for an HLI application running under z/OS.

IFAM4 under z/OS

Converting HLI applications for different environments

Running in different Model 204 environments

In many cases, applications written to operate with the Host Language Interface in one Model 204 environment require little or no change to operate in another environment.

Before you can run a host language program with any version of the Host Language Interface, you must link-edit it with one or more Model 204 modules. In general, you can convert a host language application program which runs in one environment to run in another by linking the appropriate interface module.

Use the guidelines in the following sections to convert HLI applications to run in the different Model 204 environments that support HLI processing.

Applications using different call protocols

Note the following restrictions on converting applications that use different call protocols or different types of threads:

• You cannot convert an application program using IFSTRT protocols to IFDIAL, and vice versa.
• For applications using IFSTRT threads, a user may choose to convert applications from single cursor IFSTRT processing to multiple cursor IFSTRT processing. Note, however, that this conversion requires modifying existing code in both the calls and the logic.

Applications using IFSTRT threads, from IFAM2 to IFAM4

Converting an IFAM2 application program that uses IFSTRT threads to run in IFAM4 does not require recompilation of the IFAM2 program. Only the interface module changes.

To convert an IFAM2 application program to run in IFAM4, modify the link-edit job step to reference the IFIF4 link module (instead of IFIF) and run IFAM4 to execute the application program.

Note: IFAM4 applications cannot use IFDIAL. You cannot convert an IFAM2 application program that is using an IFDIAL connection to run in IFAM4. See Applications that require coding changes.

Applications from IFAM4 to IFAM2

With simple link-edit modifications, IFAM4 applications can be converted to run in IFAM2. To convert an IFAM4 application program to run in IFAM2, modify the link-edit job step to reference the IFIF link module (instead of IFIF4) and execute the application program.

Converting from IFAM4 to IFAM2 is useful for allowing multiple applications or copies to share a single copy of Model 204.

Applications that require coding changes

Certain of the HLI calls that are supported in one environment may not be supported in another. For example, the same calls that are valid for use in IFAM2 can be used in IFAM4, and vice versa, with the following exceptions:

• IFSTRTN, which can be used only in IFAM2
• IFABXIT and IFCSA, which are valid only for IFAM2 under CICS

There are differences in using certain calls in the different environments. For example, there are two different forms of IFSTRT (using different parameter lists); one is for IFAM1 and the other is for IFAM2 and IFAM4.

In general, you must modify an application program to convert the following types of HLI applications (using IFSTRT threads):

• From IFAM1 to IFAM2 or IFAM4
• From IFAM2 or IFAM4 to IFAM1

Use the following guidelines when converting to or from IFAM1:

• You can use IFCALL (with function numbers) only in IFAM2 or IFAM4.
• Note that IFGERR functions somewhat differently in IFAM2 and IFAM4 than in IFAM1.
• The following calls are valid for use only in IFAM1: IFSETUP (which can only be used with an IFDIAL connection) and IFLOG.
• In general, you cannot use calls that perform thread management or checkpointing functions in IFAM1, including: IFDTHRD, IFSTHRD, and IFCHKPT.

See HLI functions for information about individual calls and their usage.

See also

• Introduction to the HLI facility
• HLI: Job design factors
• HLI: Job requirements
• HLI: Coding conventions
• HLI: Function summary
• HLI functions
• HLI: Field formatting options for HLI calls
• HLI: Model 204 completion and ABEND codes
• HLI: IFAM1 job program examples
• HLI: IFAM2/IFAM4 job program examples