HLI: Function summary
Overview
This topic summarizes the calls that are available using the Model 204 Host Language Interface facility. Read this topic if you are using the HLI facility for the first time.
See HLI: Function call list for a complete listing of HLI function calls.
See HLI: Function calls for a detailed description of each call.
This topic does not provide specific descriptions of HLI calls or information about coding an application program using the calls. For sample coding sequences using HLI calls, see HLI: Threads.
IFDIAL thread calls
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.
With an IFDIAL thread, an application that is written in a host language can transmit data to and from Model 204 using the IFWRITE and IFREAD calls.
See HLI: Job requirements for information about setting up and running the batch Model 204 job using an IFDIAL thread.
Summary of IFDIAL calls
The following table summarizes the HLI calls that are available for use only with an IFDIAL thread. See HLI: Function calls for a detailed description of each call.
IFDIAL functions
| Call | Function |
|---|---|
| IFATTN | Sends an attention interrupt. |
| IFDIAL | Starts an IFDIAL thread. |
| IFDIALN | Starts an IFDIAL thread using a specified communications channel name. |
| IFHNGUP | Ends all threads that are started in a job. |
| IFREAD | Gets a line of output from Model 204. |
| IFSETUP | Initiates contact with Model 204 and sets the PARM parameters and CCAIN statements for the IFAM1 job. |
| IFWRITE | Sends a line of input to Model 204. |
IFSTRT thread calls
IFSTRT thread
An IFSTRT thread provides a user interface between Model 204 and a host language program that is running in batch.
With an IFSTRT thread, an application that is written in a host language can issue calls to Model 204 that perform operations against the database which are similar to Model 204 commands and SOUL statements.
See HLI: Job requirements for information about setting up and running the Online or batch Model 204 job using an IFSTRT thread. See HLI: Function calls for a detailed description of the IFSTRT call.
Different operational levels
The HLI calls that are available for use with an IFSTRT thread are categorized by functionality and operate at the following levels:
- System
- Transaction
- File or group
- Set
- Single record
A typical application program works at all levels, using the HLI calls that are available at each level. The calls that are available in each of these categories are summarized in the tables on the following pages.
Enqueuing action and record locking behavior
When several users have access to the same files or groups, Model 204 prevents conflicting, simultaneous use of records with a facility called enqueuing. Enqueuing is performed at the thread level.
With an IFSTRT thread, most HLI function calls automatically enqueue and dequeue on the resources, such as the files, groups, sets, or records, to which they refer.
See HLI: Function calls for detailed information about the record locking behavior of individual calls. See HLI: Locking behavior of HLI calls for more information about enqueueing on an IFSTRT thread.
System level IFSTRT calls
System level functions constitute the highest level of access to the Host Language Interface Model 204 service routines. At the system level, most functions do not require a file or group context.
The following table summarizes the IFSTRT calls that function at the system level.
System level IFSTRT calls
| Call | Function |
|---|---|
| IFCALL | Calls another HLI function by number. |
| IFCHKPT | Requests a checkpoint, checkpoint status information, or both. (Note that IFCHKPT is also a transaction-level function.) |
| IFDTHRD | Deletes the current thread and switches to another thread. |
| IFEFCC | Returns specific information about field values or record numbers that cause a field constraint conflict using the IFSTOR, IFUPDT, or IFPUT HLI calls |
| IFEPRM | Reads a parameter. |
| IFERLC | Returns a file name, record number, and user name after a record locking conflict occurs in an HLI program that issues a call that requires locking a record |
| IFERR | Places a message on the journal, requests a snap dump of the Model 204 region, or both. |
| IFFNSH | Deallocates all threads; finishes HLI portion of program. |
| IFGERR | Reads the latest error message produced by Model 204. |
| IFLOG | Logs in user with user ID and password (IFAM1). |
| IFRPRM | Resets a parameter. |
| IIFSPRM | Sets a parameter. |
| IFSTHRD | Switches from one thread to another. |
| IIFSTRT | Establishes an IFSTRT thread connection. |
| IFSTRTN | Establishes an IFSTRT thread connection to an alternate HLI Model 204 service program. |
| IFUTBL | Resets the size of a user's server tables. |
Transaction level IFSTRT calls
Transaction level functions operate in a job that uses the Host Language Interface facility to manage transactions for a logical unit of work processing against the Model 204 database.
The following table summarizes the IFSTRT calls that function at the transaction level.
Transaction level IFSTRT calls
| Call | Function |
|---|---|
| IFBOUT | Backs out current transaction. |
| IFCHKPT | Requests a checkpoint or checkpoint status or both.
Note: IFCHKPT is also a system-level function. |
| IFCMMT | Commits the current transaction. |
| IFCMTR | Releases all record sets and commits the current transaction. |
| IFRELA | Releases all record sets. |
File or group level IFSTRT calls
HLI functions at the file or group level operate with a file or group.
For example, whenever an application program requires access to a Model 204 file, a file or group must be opened. IFOPEN must be called before any other file or group level functions. IFOPEN establishes the current file or group on which subsequent file or group level, record level, and set level functions operate.
Note: On a single cursor IFSTRT thread, each thread can have only one current file or group. All functions operate against this file or group.
On a multiple cursor IFSTRT thread, multiple files or groups can be accessed, and the file or group that is specified in the HLI call is the one that is current for processing. If the file specification is optional and no file is specified, the file that was opened last is current, by default.
The following table summarizes the IFSTRT calls that function at the file or group level.
File or group level IFSTRT calls
| Call | Function |
|---|---|
| IFCLOSE | Closes all files and groups for the current thread. |
| IFDELF | Deletes a field definition in a file. IFDELF can be used only if the current context is a file. |
| IFDFLD | Defines new fields in a file. |
| IFDISP | Displays file, group, and other information. |
| IFFLS | Checks for field-level security violations. |
| IFINIT | Initializes a file. IFINIT can be used only if the current context is a file. |
| IFNFLD | Renames fields in a file. IFNFLD can be used only if the current contest is a file. |
| IFOPEN | Opens a file or group. |
| IFOPENX | Opens a file or group, enqueuing upon the file(s) in exclusive status. |
| IFRFLD | Redefines fields in a file. IFRFLD can be used only if the current context is a file. |
Record set level IFSTRT calls
Functions at the record set level operate with sets of records or field values.
For example, the IFFIND function must be called to establish a current set before any other set level functions can operate successfully.
On a multiple cursor IFSTRT thread, the set that is specified in the HLI call is the one that is current for processing. On a single cursor IFSTRT thread, the current set is the one last created.
The IFSTRT calls that function at the record set level are summarized in the following tables:
- Record set level calls on any IFSTRT thread lists calls that can be used on both multiple cursor and single cursor IFSTRT threads.
- Record set level calls on a multiple cursor IFSTRT thread lists calls that can be used only on a multiple cursor IFSTRT thread.
- Record set level calls on a single cursor IFSTRT thread lists calls that can be used only on a single cursor IFSTRT thread.
Record set level calls on any IFSTRT thread
The following table lists calls that can be used on both multiple cursor and single cursor IFSTRT threads.
Record set level calls on any IFSTRT thread
| Call | Function |
|---|---|
| IFCOUNT | Counts the number of records in the current set. |
| IFDSET | Deletes the current set of records from the file or group. |
| IFFAC | Finds and returns record count. |
| IFFACC | Compiles an IFFAC specification. |
| IFFACE | Executes a precompiled IFFAC specification. |
| IFFDV | Selects a set of field values to become the current value set. |
| IFFDVC | Compiles an IFFDV specification. |
| IFFDVE | Executes a precompiled IFFDV specification. |
| IFFILE | Adds an invisible key field to all records in the current set. |
| IFFIND | Selects a set of records as the current set. |
| IFFINDC | Compiles an IFFIND specification. |
| IFFINDE | Executes a precompiled IFFIND specification. |
| IFFNDX | Selects a set of records and enqueues upon them exclusively. |
| IFFNDXC | Compiles an IFFNDX specification. |
| IFFNDXE | Executes a precompiled IFFNDX specification. |
| IFFWOL | Selects a set of records as the current set, without locking. |
| IFFWOLC | Compiles an IFFWOL specification. |
| IFFWOLE | Executes a precompiled IFFWOL specification. |
| IFSKEY | Sorts the records in the current IFFIND set; only the record key is written to the sort records. |
| IFSKYC | Compiles the IFSKEY specification. |
| IFSKYE | Executes the precompiled IFSKEY specification. |
| IFSORT | Sorts the records in the current set. |
| IFSRTC | Compiles the IFSORT sort specification. |
| IFSRTE | Executes the precompiled IFSORT or IFSRTC specification. |
| IFSRTV | Sorts the values in the current value set. |
| IFSTVC | Compiles the IFSRTV specification. |
| IFSTVE | Executes the precompiled IFSRTV specification. |
Record set level calls on a multiple cursor IFSTRT thread
The following table lists those calls that can be used only on a multiple cursor IFSTRT thread.
Record set level calls on a multiple cursor IFSTRT thread
| Call | Function |
|---|---|
| IFCCUR | Closes a cursor on a set. |
| IFCLST | Clears a list. |
| IFOCUR | Opens a cursor on a set. |
| IFOCURC | Compiles the IFOCUR specification. |
| IFOCURE | Executes the precompiled IFOCUR specification. |
| IFPROLS | Places records from a found set onto a list. |
| IFRELR | Releases records in a found set. |
| IFRRFLS | Removes records in a found set from a list. |
Record set level calls on a single cursor IFSTRT thread
The following table lists those calls that can be used only on a single cursor IFSTRT thread.
Record set level calls on a single cursor IFSTRT thread
| Call | Function |
|---|---|
| IFDEQL | Dequeues the set of records on a specified list. |
| IFENQL | Enqueues in share or exclusive mode on the set of records of the specified list. |
| IFLIST | Places the records in the current set onto a named list. |
Individual record level IFSTRT calls
Individual record functions operate on a record.
On a single cursor IFSTRT thread, IFGET, IFBREC, and IFPOINT establish the current record on which they and other functions at this level operate.
On a multiple cursor IFSTRT thread, the current record in the cursor that is specified in the HLI call is the record that is current for processing. The current record in a cursor is established by an IFFTCH, IFSTOR, or IFFRN call.
The IFSTRT calls that function at the single record level are summarized in the following tables:
- Individual record level calls on any IFSTRT thread lists calls that can be used on both multiple cursor and single cursor IFSTRT threads.
- Individual record level calls on a Multiple Cursor IFSTRT thread lists calls that can be used only on a multiple cursor IFSTRT thread.
- Individual record level calls on a single cursor IFSTRT thread lists calls that can be used only on a single cursor IFSTRT thread.
Individual record level calls on any IFSTRT thread
| Call | Function |
|---|---|
| IFDALL | Deletes all the occurrences of a field from the current record. |
| IFDREC | Deletes the current record from its file. |
| IFDVAL | Deletes a field name = value pair. |
| IFPROL | Places the current record on a named list. |
| IFRRFL | Removes the current record from a named list. |
Individual record level calls on a multiple cursor IFSTRT thread
The following table lists those calls that can be used only on a multiple cursor IFSTRT thread.
Individual record level calls on a Multiple Cursor IFSTRT thread
| Call | Function |
|---|---|
| IFFRN | Points to the specified record in the specified file and makes it the current record. |
| IFFRNC | Compiles the IFFRN specification. |
| IFFRNE | Executes the precompiled IFFRN specification. |
| IFFTCH | Processes the next logical record or value and returns the specified data. |
| IFFTCHC | Compiles the IFFTCH specification. |
| IFFTCHE | Executes the precompiled IFFTCH specification. |
| IFOCC | Counts the number of occurrences of the specified field in the current record and returns a count. |
| IFOCCC | Compiles the IFOCC specification. |
| IFOCCE | Executes the precompiled IFOCC specification. |
| IFRNUM | Returns the number of the current record in the specified cursor. |
| IFSTOR | Creates a new record with the specified data and adds the record to the specified file. |
| IFSTRC | Compiles the IFSTOR specification. |
| IFSTRE | Executes the precompiled IFSTOR specification. |
| IFUPDT | Updates the current record with the specified data. |
| IFUPDTC | Compiles the IFUPDT specification. |
| IFUPDTE | Executes the precompiled IFUPDT specification. |
Individual record level calls on a single cursor IFSTRT thread
The following table lists those calls that can be used only on a single cursor IFSTRT thread.
Individual record level calls on a single cursor IFSTRT thread
| Call | Function |
|---|---|
| IFBREC | Creates a new record. |
| IFCTO | Counts the number of field occurrences in the current record. |
| IFCTOC | Compiles an IFCTO specification. |
| IFCTOE | Executes a precompiled IFCTO specification. |
| IFGET | Reads information from the next record in the current set. |
| IFGETC | Compiles an IFGET specification. |
| IFGETE | Executes a precompiled IFGET specification. |
| IFGETV | Reads the next value from the current value set. |
| IFGETX | Reads information from the next record, enqueuing upon it exclusively. |
| IFGETXE | Executes a precompiled IFGET specification, enqueuing upon the record exclusively. |
| IFGTVC | Compiles the IFGETV specification. |
| IFGTVE | Executes the precompiled IFGETV. |
| IFMORE | Reads more information from the current record. |
| IFMOREC | Compiles an IFMORE specification. |
| IFMOREE | Executes a precompiled IFMORE specification. |
| IFMOREX | Reads more information from the current record, enqueuing upon the record exclusively. |
| IFMORXE | Executes a precompiled IFMORE specification, enqueuing upon the record exclusively. |
| IFPOINT | Specifies a new current record. |
| IFPUT | Updates the current record. |
| IFPUTC | Compiles an IFPUT record. |
| IFPUTE | Executes a precompiled IFPUT specification. |
IFSTRT thread calls and compiled IFAM
Compiled IFAM facility
The Compiled IFAM (Inverted File Access Method) facility allows IFSTRT thread calls to be compiled and stored.
Using the Compiled IFAM facility, you can execute a compilation at a later time by specifying the name under which it was stored. You do not need to recompile the stored call.
A compilation must be uniquely identified so that multiple calls can use it. The name parameter included in all Compiled IFAM calls specifies a character string that is used to identify the compilation. A null name string is the same as an omitted parameter.
Three forms of Compiled IFAM calls
Three forms of IFSTRT calls are available using the Compiled IFAM facility: compile and execute, compile-only, and execute-only. The following options are available to accommodate different programming styles:
-
Using a single call that compiles and executes with the name parameter that identifies the compilation. The call executes and the compiled version of the call is saved.
When the same call is executed again or when another call containing the same name parameter is executed, the stored compilation is executed without requiring recompilation.
-
Using two calls, one is compile-only and one is execute-only, with the name parameter that identifies the compilation for the two phases of Compiled IFAM processing: compilation and execution.
This option involves a two-call procedure, useful in loop processing. The compilation form of the call is used outside the loop to compile (but not execute) the call specification. Within the loop, the execution form of the call is issued, thereby executing the previously compiled call.
See HLI: Function call list for an overview of the calls that provide Compiled IFAM functionality for IFSTRT thread processing.
See HLI: IFSTRT processing for more information about IFSTRT calls and the Compiled IFAM facility.
See HLI: Function call list for a complete listing of HLI function calls.