HLI: Threads

Overview

A thread is a connection to Model 204. This topic describes Model 204 threads for application programmers who are using the Host Language Interface facility.

• An HLI application must start a thread to do processing under Model 204.

• The total number of Model 204 threads available to connect users is set by the system administrator. The total number of available threads equals the number of IODEV statements specified in the Model 204 online run. A host language application must start at least one thread in order to access Model 204 and process against the database.

  Refer to HLI: Job requirements for information about IODEVs required for HLI threads.

• The host language application initiates a request to start a connection to Model 204 by issuing a call to IFSTRT (or IFSTRTN) or IFDIAL (or IFDIALN). If a connection is available for the host language program, Model 204 starts the thread.
• Once a thread is started, the host language application can issue other HLI calls to Model 204.

For more information

• Read the section Multiple cursor IFSTRT threads if you are using multiple cursor functionality in your host language program for the first time.
• For examples of HLI applications that use different types of threads and for information about IFAM1, IFAM2, and IFAM4, see HLI: Job design factors and HLI: IFAM2/IFAM4 job program examples.

Types of threads: IFSTRT and IFDIAL

There is a fundamental difference between IFSTRT and IFDIAL threads, based on the underlying call protocols, which provide the host language interface to Model 204. The protocols operate differently and provide different types of host language functionality.

You must know which type of functionality is required for a particular application to determine which type of thread to use. You must code only the calls, specifications, and corresponding program logic that are available for use with the type of thread that you start.

The functionality of IFSTRT and IFDIAL threads is described in the following sections.

Note: In IFAM2 under z/OS or z/VSE, you can elect to start both types of threads in a host language job; however, IFDIAL and IFSTRT threads function independently of one another as separate transactions. See HLI: Transactions for a description of HLI threads and Model 204 transactions in IFAM1, IFAM2, and IFAM4.

IFSTRT threads

An IFSTRT thread provides a user interface between a host language application and Model 204 that allows the program to issue calls that perform functions against the database similarly to Model 204 SOUL and Command Language.

For example, the IFOPEN call, which is comparable to the Model 204 OPEN command, can be issued on an IFSTRT thread to open a file for processing. An IFFIND call, which is comparable to the SOUL FIND statement, can be issued to create a found set of records. The IFCLOSE call, which is comparable to the Model 204 CLOSE command, closes a file on an IFSTRT thread.

A number of HLI calls perform retrieval and update functions that are available for use with an IFSTRT thread.

Using an IFSTRT thread, you can run a batch host language application that functions similarly to a SOUL request. The IFSTRT application can issue HLI calls that access the database and process data.

Different types of IFSTRT threads

The following types of IFSTRT threads are available using the HLI facility:

• Multiple cursor IFSTRT thread
• Single cursor IFSTRT thread, with update privileges
• Single cursor IFSTRT thread, with read-only privileges (available only in IFAM2 and IFAM4)

Each IFSTRT thread supports one type of functionality. You must code only the calls, specifications, and corresponding program logic that are valid for the particular type of IFSTRT thread that you start.

For example, the call that opens a cursor, IFOCUR, is valid only on a multiple cursor IFSTRT thread; a particular updating call, IFPUT, is valid only on a single cursor IFSTRT thread with update privileges. See HLI: Function summary for a description of individual calls.

Comparison of multiple and single cursor IFSTRT threads

There is a basic difference in functionality between a multiple cursor IFSTRT thread, which functions very much like SOUL by allowing access to multiple files and record sets, and a single cursor IFSTRT thread, which limits access to one file and one record set at a time.

The following table summarizes the differences in access to files and data between multiple cursor and single cursor IFSTRT threads.

Comparison of multiple cursor and single cursor IFSTRT threads

Item	Multiple cursor thread	Single cursor thread
Number of threads per application	One	One (IFAM1) Multiple (IFAM2, IFAM4)
Number of active update units	Only between first update and commit	Continuously
Transaction commit	Explicitly, at user option	Explicitly, at user option IFCMMT or IFCMTR should always be called before an IFDTHRD
Number of open files or groups concurrently per thread	Multiple	One (last one opened)
Current file is...	1. Default 2. Specify (IN FILE)	Last one opened
Number of found sets per thread	Multiple	One
Found set availability	Retained until explicitly released	Not retained
Retrieval of records or values from sets	Multiple times	Once
Current set is...	Specify (set name)	Last one found
Number of current records per thread	Multiple	One
Current record is...	Specify (cursor)	Next record in current set

Note: Update units must begin and end on the same thread. If using IFDTHRD, assure that any in-progress update unit ends on the current thread by issuing an IFCMMT or IFCMTR on the current thread before the IFDTHRD call.

For host language applications that use IFSTRT threads, Technical Support recommends that you use a multiple cursor IFSTRT thread. See Advantages of a multiple cursor IFSTRT thread.

Multiple cursor IFSTRT threads

A multiple cursor IFSTRT thread supports access to multiple:

• Files or groups, using functions that specify which file or group
• Record or value sets, using functions that specify which set
• Records or values, using functions that specify which record or value (that is, which cursor)

With a multiple cursor IFSTRT thread, the file, set, record, or value that is specified in the HLI call is the one that is current for processing. For calls that use a set or cursor parameter, you must always code the specification to indicate which set, record, or value is current.

For calls that provide an optional file specification, if you do not specify a file, the file that was opened last is current by default.

You can use a multiple cursor IFSTRT thread in an IFAM1, IFAM2, or IFAM4 host language job.

Starting a multiple cursor IFSTRT thread

To start a multiple cursor IFSTRT thread, you must specify a value of 2 for the thread type indicator (THRD-TYP is 2).

For example, the following COBOL statement in an IFAM2 job starts a multiple cursor IFSTRT thread:

CALL "IFSTRT" USING RETCODE,LANG-IND,LOGIN,THRD-TYP,THRD-ID.

where the following variables are specified in the WORKING-STORAGE SECTION of the program:

• LOGIN is USERABC;ECP; (login account name is USERABC, and password is ECP)
• LANG-IND is 2 (COBOL)
• THRD-TYP is 2 (a multiple cursor IFSTRT thread)
• THRD-ID is a required output integer variable for the thread identifier

Note: In IFAM1, if you do not specify a thread type, the thread defaults to a single cursor IFSTRT thread (THRD-TYP is 0). See IFSTRT (IFAM1) (HLI function) and IFSTRT (IFAM2/IFAM4) (HLI function) for a description of the IFSTRT call.

Sample coding sequence

Using a multiple cursor IFSTRT thread, a host language application might perform database operations in the following order:

1. Start the multiple cursor thread (IFSTRT)
2. Open Customer file (IFOPEN)
3. Open Orders file (IFOPEN)
4. In Customers, find all records (IFFIND)
5. Open the cursor to the Customers found set (IFOCUR)
6. Loop until there are no more Customer records:
• Fetch the customer name (IFFTCH)
• In Orders, find Order records for this customer (IFFIND)
• Open a cursor to the Orders found set (IFOCUR)
• Loop until there are no more Order records:

  Fetch the order name (IFFTCH)

  Print a report line.

  Close the cursor to the Orders found set (IFCCUR)

7. Close the cursor to the Customers found set (IFCCUR)
8. Finish processing (IFFNSH)

Advantages of a multiple cursor IFSTRT thread

Compared to a single cursor IFSTRT thread, a multiple cursor IFSTRT thread provides the more powerful host language interface to Model 204. A multiple cursor IFSTRT thread:

• Always uses a single connection, which allows a more efficient host language program to be coded.
• Activates a transaction only for updating calls allowing for checkpoints to be taken between update units.
• Allows more facile access to the Model 204 database, with access to multiple files or groups, sets, records, and values on a single thread.
• Provides a broader range of database operations with certain calls for list and record processing that are only available using this type of thread.
• Provides a processing environment that is similar to SOUL by allowing a record set to be:
  • Retained until explicitly released, so that, once created, a record set is available for processing until it is released by the host language program.
  • Symbolically referenced using the name of the function that created it, which is analogous to using a statement label in User Language (SOUL).

Using a multiple cursor IFSTRT thread

For an application that requires access to multiple files concurrently, Technical Support recommends that you use a multiple cursor IFSTRT thread and that you do not run a multithreaded HLI job (in 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: If you are performing update processing using one thread, checkpoints are easier on a multiple cursor IFSTRT thread.

Single cursor IFSTRT threads

A single cursor IFSTRT thread allows access to logical database entities, such as files and record sets, in a serial processing mode. Each single cursor IFSTRT thread processes a single file or group at a time and, for the current file or group, can have active one current record set, one current record, one current value set, and one current value at a time.

For each single cursor IFSTRT thread, all processing against one file or group is completed before processing against the next file or group is begun.

Note that, in IFAM2 and IFAM4, a host language application can process records from different files and groups or different sets of records from the same file or group by using a technique called multithreading.

Read-only or update privileges

In IFAM1, a single cursor IFSTRT thread provides update privileges. In IFAM2 and IFAM4, you can specify a single cursor IFSTRT thread with update privileges by specifying a value of 1 for the THRD-TYP parameter.

For example, the following COBOL statement in an IFAM2 application starts a single cursor IFSTRT thread with update privileges:

CALL "IFSTRT" USING RETCODE,LANG-IND,LOGIN,THRD-TYP,THRD-ID.

where the following variables are specified in the WORKING-STORAGE SECTION of the program:

• LOGIN is USERABC;ECP; (login account name is USERABC and password is ECP)
• LANG-IND is 2 (COBOL)
• THRD-TYP is 1 (a single cursor IFSTRT thread with update privileges)
• THRD-ID is a required output integer variable for the thread identifier

Note: In IFAM2 and IFAM4 with a read-only IFSTRT thread (THRD-TYP is 0), you cannot issue calls that perform updating functions. You can open files or groups using passwords with update privileges, but no updates are allowed. If a host language program issues an updating call on a read-only IFSTRT thread, Model 204 returns an error code of 40.

Sample coding sequence using a single cursor IFSTRT thread

Using a single cursor IFSTRT thread, a host language application might perform database operations in the following order:

1. Start a standard thread (IFSTRT)
2. Open Customer file (IFOPEN)
3. In Customers, find all records (IFFIND)
4. Loop until there are no more Customer records:
   • Get the customer record (IFGET)
   • Update the customer record (IFPUT)
   • Print a report line
5. Finish processing (IFFNSH)

Multithreaded IFSTRT application

You can use two or more single cursor IFSTRT threads to process data from multiple files and record sets in an IFAM2 or IFAM4 application.

In a multithreaded application, using two or more single cursor IFSTRT threads, a host language program can perform parallel processing of records from different files and groups, or different sets of records from the same file or group.

Each single cursor IFSTRT thread processes one single file or group at a time and, for the current file or group, can have active one current record set, one current record, one current value set, and one current value. The IFSTHRD call switches from one thread to another, thereby establishing the current thread.

Update units must begin and end on the same thread. If using IFDTHRD, assure that any in-progress update unit ends on the current thread by issuing an IFCMMT or IFCMTR on the current thread before the IFDTHRD call.

See HLI: Transactions for information about a multithreaded transaction.

Sample coding sequence for a multithreaded IFSTRT application

Assume, for example, that you want to cross-reference a customer file with an accounts receivable file. The host language program uses two single cursor IFSTRT threads, one to process each file.

Using two single cursor IFSTRT threads, a host language application performs database operations in the following order:

1. Start a standard thread (IFSTRT)
2. Open Customer file (IFOPEN)
3. In Customers, find all records (IFFIND)
4. Start a standard thread (IFSTRT)
5. Open Accounts Receivable file (IFOPEN)
6. Switch to the Customer thread (IFSTHRD)
7. Loop until there are no more Customer records:
   • Get the Customer record (IFGET)
   • Save the value of the Customer account number.
   • Switch to the Accounts Receivable thread (IFSTHRD)
   • Find any matching Account Receivable records (IFFIND)
   • Loop until there are no more matching records:

     Get the Accounts Receivable record (IFGET)

     Update the Accounts Receivable record (IFPUT)

   • Switch back to the Customer thread (IFSTHRD)
8. Finish processing (IFFNSH)

Note: To relate multiple records within the same file, you apply the same logic used to process records in separate files.

See Multithreaded (single cursor) IFSTRT example for a sample HLI application that uses multiple IFSTRT threads.

IFDIAL thread line-at-a-time interface

An IFDIAL thread provides a line-at-a-time terminal type interface between a host language application and Model 204. With an IFDIAL thread, a host language program functions as a terminal, transmitting a line of input to Model 204 or receiving a line of output from Model 204.

An IFDIAL thread allows a host language application to issue Model 204 commands, such as LOGIN, LOGWHO, LOGCTL, and MONITOR, or other commands that perform operations against the database, for example, to execute a SOUL request. An IFDIAL thread also allows the host language program to receive messages and data from Model 204.

An IFDIAL thread supports the use of the companion calls, IFREAD and IFWRITE, to communicate with Model 204.

Note: If you are using an IFDIAL thread, you must code the calls, specifications, and corresponding program logic that are valid for use with this thread.

See IFDIAL thread example (z/OS) for an example of an HLI application that uses an IFDIAL thread. Also see HLI: Function summary for descriptions of HLI calls.

Starting an IFDIAL thread

To start an IFDIAL thread, you must specify the IFDIAL call in your host language program. For example, the following COBOL statement starts an IFDIAL thread:

CALL "IFDIAL" USING RETCODE,LANG-IND.

where the following variable is specified in the WORKING-STORAGE SECTION of the program:

LANG-IND is 2 (COBOL)

Sample coding sequence

Using an IFDIAL thread, a host language application might perform database operations in the following order:

1. Start a Model 204 terminal interface thread (IFDIAL)
2. Log in to Model 204 (IFWRITE)
3. Receive the login message from Model 204(IFREAD)
4. Read the first record from an input file that contains a SOUL request into a program storage area (named, for example, IN-AREA)

   For example, the input file might contain the following records:

   BEGIN PRINT 'HELLO' END

5. Send a line of input (BEGIN) to Model 204 (IFWRITE using IN-AREA).
6. Loop until there are no more records in the input file:
   • Read the next record from the input file into the program storage area.
   • Send a line of input to Model 204 (IFWRITE using IN-AREA).
7. Receive a line of output from Model 204 (IFREAD).
8. Finish processing. (IFHNGUP)

Note: If the SOUL request generated multiple lines of output, the IFDIAL application loops using IFREAD to get each line of output.

Checking the IFREAD and IFWRITE return codes

Before issuing IFREAD or IFWRITE, the IFDIAL application must check the Model 204 completion return code from the previous IFREAD or IFWRITE to determine which call is required next by Model 204. For a return code of 1, IFWRITE is required next; for a return code of 2, IFREAD is required next.

The previous sample coding sequence shows just the basic program logic without the necessary return code checking.

See HLI: IFDIAL processing for more information about checking IFREAD and IFWRITE return codes.

See also

• HLI: Threads
• HLI: IFSTRT processing
• HLI: IFDIAL processing
• HLI: Using Model 204 completion return codes
• HLI: Model 204 parameters
• HLI: Model 204 files and records
• HLI: Model 204 fields and variables
• HLI: Find criteria for Model 204 data
• HLI: Locking behavior of HLI calls
• HLI: Record locking conflicts
• HLI: Model 204 security
• HLI: Model 204 tables
• HLI: Model 204 data sets in HLI jobs
• HLI: IFAM2 CICS processing
• HLI: Transactions
• HLI: Model 204 recovery and checkpoints