HLI: Job requirements

Overview

This topic details the job requirements for the application programmer using the Host Language Interface facility in the IFAM1, IFAM2, and IFAM4 Model 204 environments.

Contents of this topic

There are three broad categories of batch jobs that you can run corresponding to the IFAM1, IFAM2, and IFAM4 Model 204 environments that support HLI processing. This topic presents job information in the following order:

• IFAM1 jobs
  • Under z/OS, VSE, CMS
• IFAM2 jobs
  • Under z/OS, VSE, CMS
  • Using the CICS interface

  Note: The INTERCOMM interface (supporting the use of Teletype and 3270 terminals in line-at-a-time mode) is no longer supported as of Model 204 version 7.5.

• IFAM4 jobs (under z/OS only)

This topic describes each type of job and includes examples of job setup and execution in the different operating environments.

For more information

See the individual HLI function pages in HLI functions for a detailed description of HLI function calls and call parameters. See HLI: IFAM1 job program examples and HLI: IFAM2/IFAM4 job program examples for examples of applications using HLI function calls.

IFAM1 jobs

IFAM1 applications can run under z/OS, VSE, or CMS operating systems. An IFAM1 job involves a two-step procedure: step one is to link-edit the application program and step two is to run it.

Examples of the IFAM1 job steps are provided in the sections which follow. Sample setups are shown for each of the operating systems. The following topics are covered for each system:

• Link-editing the application program
• Running the application program

See IFAM1 jobs: Job control statements for a description of the control statements that are used with an IFAM1 job. See IFAM1 jobs: Using an IFSTRT or IFDIAL thread for more information about applications in the IFAM1 environment.

IFAM1 dynamic loading

Rocket recommends that the IFAM1 application load the Model 204 portion of the application at runtime.

Invoke IFAM1 dynamic loading by link-editing the IFAM1 application program with the appropriate module:

• IFIF1OS for z/OS
• IFIF1DOS for VSE
• IFIF1 for CMS

See the examples of link-editing with IFIF1OS for z/OS and with IFIF1DOS for VSE.

Notes: The IFIF1 module is automatically invoked at runtime for CMS.

In order to use the dynamic loading facility, the Model 204 system manager must initially build the IFAM1 load module for your installation site.

Contact your Model 204 system manager to get the name of the Model 204 load library that is used to run IFAM1 programs at your site. For more information about creating the IFAM1 module, refer to the Rocket Model 204 installation instructions for your operating system.

Advantages of dynamic loading

The IFAM1 dynamic loading facility reduces application maintenance and storage by allowing the Model 204 IFAM1 interface to dynamically load the IFAM1 code at runtime.

Dynamic loading provides the application programmer with the easiest and most efficient method for running IFAM1 applications and is the preferred method recommended by Rocket.

Note that the direct link-edit method which statically link-edits IFAM1 applications with Model 204 routines can be used by the application programmer to run IFAM1 jobs. However, using this method requires that:

• All IFAM1 application programs must be link-edited again each time any Model 204 routines change.
• Each IFAM1 application must carry its own copy of all the Model 204 routines, thereby increasing the application's load module size and load library disk space requirements.

Examples of directly link-editing IFAM1 applications are not provided in this document.

IFAM1 jobs: Compiling under Enterprise PL/I for z/OS

When compiling a PL/I application under the Enterprise PL/I for z/OS compiler, the following compiler parameter is required:

DEFAULT(LINKAGE(SYSTEM))

This causes the parameter list to be built in the same way that it was built by the old compilers (including turning on the high-order bit of the address of the last parameter).

For example:

//PLICMPL EXEC PGM=IBMZPLI,PARM='OBJECT,OPTIONS, // DEFAULT(LINKAGE(SYSTEM))',REGION=512K,...

If this compiler option is not specified, subsequent executions of the application will fail with 0C4 abends.

IFAM1 jobs: Link-editing under z/OS

Link with IFIF1OS

To link-edit your IFAM1 job running under z/OS, link the IFAM1 application with the Model 204 module IFIF1OS using the INCLUDE CCA statement in SYSLIN DD.

Example of z/OS JCL to Link-Edit Application (IFAM1)

The following sample code shows JCL that might be used to link-edit an IFAM1 application to build the application load module. In this example, the program name is IFAMTEST.

//LINKAPPL JOB,LINKAPPL,MSGLEVEL=(1,1),CLASS=T,MSGCLASS=C //LINK EXEC PGM=IEWL,PARM='LIST,MAP,LET,NCAL,SIZE=(250K,150K)' //SYSPRINT DD SYSOUT=C //SYSUT1 DD UNIT=WORK,SPACE=(TRK,(40,20)) //USEROBJ DD DSN=LOCAL.M204.OBJLIB,DISP=SHR //OBJLIB DD DSN=M204.V220.OBJLIB,DISP=SHR //SYSLMOD DD DSN=LOCAL.M204.IFAM1.APPLIC,DISP=OLD //SYSLIN DD * INCLUDE USEROBJ(IFAMTEST) INCLUDE OBJLIB(IFIF1OS) ENTRY IFAMTEST NAME IFAMTEST(R) /*

Note: Before the individual Host Language Interface application programmer can link an IFAM1 application, the Model 204 system manager must build the IFAM1 load module containing the IFII1 member. Contact your Model 204 system manager to get the name of the Model 204 object and load libraries that are used to link-edit and run IFAM1 programs at your site.

IFAM1 jobs: Running under z/OS

Execute with dynamic loading

Once you have link-edited the application program, run the IFAM1 application in z/OS.

Example of z/OS JCL to Run Application (IFAM1)

The following sample code shows an excerpt of the JCL that might be used to run an IFAM1 application that was link-edited as shown in the previous example. In the following example, the program name is IFAMTEST.

//RUNIFAM1 JOB,'RUNIFAM1',MSGLEVEL=(1,1),MSGCLASS=C,CLASS=T //* //IFAM1 EXEC PGM=IFAMTEST //* //STEPLIB DD DSN=LOCAL.M204.IFAM1.APPLIC,DISP=SHR // DD DSN=M204.V220.LOADLIB,DISP=SHR //CCAAUDIT DD SYSOUT=C //CCAPRINT DD SYSOUT=C //CCASNAP DD SYSOUT=C //SYSUDUMP DD SYSOUT=C //CCATEMP DD DISP=NEW,UNIT=SYSDA,SPACE=(TRK,20) //CCASTAT DD DSN=M204.CCASTAT,DISP=OLD . . ...application program DD statements .

Using the STEPLIB statement

The STEPLIB file points to the load module libraries where the application program and the Model 204 IFAM1 interface program reside.

This statement must specify the load module library or libraries that contain IFAM1 and the Host Language Interface user's application program.

Note: One of the following requirements must be met for IFAM1 applications:

• M204XSVC must be installed as an SVC and that SVC number must be passed to Model 204 in the IFSTRT or IFLOG call as the value of the XMEMSVC parameter. XMEMOPT must also be set to 2 or 4, or
• The load library where the IFAM1 application resides (and all run-time concatenated libraries) must be APF authorized.

Unless one of these requirements is met, IFAM1 applications will terminate with:

MODEL 204 IS NOT AUTHORIZED FOR THIS CPUID: 0000000000000000

Use the DSN of the Model 204 load library that is used to run IFAM1 programs at your site. If the Model 204 load module library and application load library are in separate libraries, use concatenated data set or file definition statements.

Using the EXEC statement

You can specify the following parameters in the EXEC statement:

• PGM -- Required; Indicates the name of the application program being run. Note that application programs cannot be called IFAM1.
• REGION -- Optional; Indicates the size of the memory area to be allocated for IFAM1 and the application. Note that REGION can be specified depending on your site's Model 204 configuration. For information about setting the REGION parameter, see Runtime environment specifications.
• TIME -- Optional; Indicates how much time the application program and Model 204 together can use before being cancelled by the operating system. TIME depends on the requirements of the application.
• PARM -- Optional; Indicates any application runtime parameters to be set.

See IFAM1 jobs: Job control statements for more information about the job control statements that are used with an IFAM1 job.

IFAM1 jobs: Link-editing under VSE

Link with IFIF1DOS

To link-edit your IFAM1 job running under VSE, link the IFAM1 application with the Model 204 module IFIF1DOS using the INCLUDE statement in OPTION CATAL.

Example of VSE JCL to Link-Edit Application (IFAM1)

The following sample code shows JCL that might be used to link-edit an IFAM1 application to build the application load module. In this example, the program name is IFAMTEST.

// JOB LINKAPPL FOR IFAM1TEST // DLBL PRIVLIB,'PRIV.USER.LIBRARY' // EXTENT,SYSnnn,volser,balance of extent information // LIBDEF CL,TO=PVTCL // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT,SYSnnn,volser,balance of extent information // LIBDEF OBJ.SEARCH=(M204LIB.V220,PRIVLIB.XXXX) // LIBDEF PHASE.CATALOG=PRIVLIB.xxxx // OPTION CATAL PHASE IFAMTEST,* INCLUDE usermodule INCLUDE IFIF1DOS /* // EXEC LNKEDT /&

Note: Before the individual Host Language Interface application programmer can link an IFAM1 application, the Model 204 system manager must build the IFAM1 load module containing the IFII1 member. IFAM1 is provided as a phase in the distribution sublibrary and may need to be relinked by the Model 204 system manager.

Contact your Model 204 system manager to get the name of the Model 204 object and load sublibraries that are used to link-edit and run IFAM1 programs at your site.

IFAM1 jobs: Running under VSE

Execute with dynamic loading

Once you have link-edited the application program, run the IFAM1 application in VSE.

Example of VSE JCL to run application (IFAM1)

The following sample code shows an excerpt of the JCL that might be used to run an IFAM1 application that was link-edited as shown in the previous example. The EXEC statement specifies the name of the application program to be executed. In this example, the program name is IFAMTEST.

// JOB DOS IFAM1 DYNAMIC LINKEDIT TEST // DLBL PRIVLIB,'PRIV.USER.LIBRARY' // EXTENT,SYSnnn,volser,balance of extent information // LIBDEF CL,TO=PVTCL // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT ,SYSnnn,volser,balance of extent information // LIBDEF PHASE.SEARCH=(PRIVLIB.xxxx,M204LIB.V220) // DLBL CCAJRNL,'MODEL204.CCAJRNL' // EXTENT SYS001,balance of extent information // DLBL CCATEMP,'MODEL204.CCATEMP',,DA // EXTENT SYS001 // DLBL CCASTAT,'MODEL204.CCASTAT' // EXTENT SYS001,balance of extent information // ASSGN SYS001,DISK,VOL=SYSWK1,SHR // UPSI 10111000 // EXEC IFAMTEST,SIZE=AUTO /* /&

Using the LIBDEF statement

In VSE, a LIBDEF JCL card must point to the library and sublibrary that contain the Model 204 IFAM1 interface program and the HLI user's application program. Use the name of the Model 204 load sublibrary that is used to run IFAM1 programs at your site.

If the Model 204 load module library and application load library are in separate libraries, the LIBDEF must specify both the library and the sublibrary in the search chain.

For more information

See IFAM1 jobs: Job control statements for more information about the job control statements that are used with an IFAM1 job. Note that VSE allows a seven-character file name to be used for DLBL in the JCL.

IFAM1 jobs: Link-editing under CMS

Execute with dynamic loading

In CMS, the process of generating an application module that uses IFAM1 can be done at runtime. No additional facility is required to make the process dynamic.

Example of CMS link-edit and execution (IFAM1)

The following sample code shows CMS commands that might be used to run an IFAM1 application. This set of commands loads the application module and executes the program. In this example, the program name is IFM1PRGM.

&CONTROL OFF * EXAMPLE TO GENERATE AN APPLICATION MODULE THAT USES * IFAM1. PROGRAM NAME = IFM1PRGM GLOBAL TXTLIB M204IFM1 LOAD IFM1PRGM IFIF1 (RESET IFM1PRGM) GENMOD IFM1PRGM &TYPE &TYPE IFM1PRGM MODULE A HAS BEEN GENERATED FOR YOUR USE. &TYPE &EXIT 0 IFAM1 FILES

Using the IFAM1 command

The previous example uses the IFAM1 command to execute a host language application that uses IFAM1.

The IFAM1 command in the previous sample code specifies the name of an EXEC (FILES) that defines system and database files for IFAM1 and stacks the name of the application program to be executed. See the following sample code for an example of the FILES EXEC that is used.

Note: You can use the IFAM1 EXEC command to run your IFAM1 program assuming that CMS Model 204 has been correctly installed and configured at your site. For IFAM1 under CMS, the IFAM1 saved segments must have been generated and the appropriate minidisks that contain Model 204 EXECs and MODULEs must be accessible.

A return code of 0 from the EXEC invokes the application program. A return code of 1 bypasses the invocation of the program. Any other return code is considered an error condition and ends the response to the IFAM1 EXEC command.

Example of the FILES EXEC

The following sample code shows FILES EXEC, the EXEC named in the IFAM1 command in the previous example, which might contain the following statements (shown in REXX):

'FILEDEF * CLEAR' 'FILEDEF CCATEMP DISK CCATEMP M204SYS A' 'FILEDEF CCAJRNL DISK CCAJRNL M204SYS A' 'FILEDEF CCAGRP DISK CCAGRP M204SYS A' 'FILEDEF CCASTAT DISK CCASTAT M204SYS A' 'FILEDEF CCASNAP DISK CCASNAP M204SYS A' 'FILEDEF CCAPRINT DISK CCAPRINT M204SYS A' 'FILEDEF CCAAUDIT DISK CCAAUDIT M204SYS A' 'FILEDEF CHKPOINT DISK CHKPOINT M204SYS A' /**/ /*! include additional FILEDEF commands for database files */ /**/ push 'IFM1PGRM' exit 0

IFAM1 jobs: Job control statements

The control statements in the following table are used in an IFAM1 job.

IFAM1 control statements

Statement	Use
EXEC	required
STEPLIB/LIBDEF/TXTLIB	required
CCAJRNL	optional (used for audit information only)
CCAJLOG	optional (used for audit information)
CCAAUDIT	optional
CHKPOINT	required for roll-back recovery
CCATEMP	required
CCASNAP, SYSUDUMP	required for error diagnostics
CCAPRINT	required
CCASTAT	required for security
CCAGRP	required for permanent file groups
Model 204 files	required
Application program files	optional

Note: VSE allows a seven-character DLBL name while z/OS allows an eight-character DD name. The actual names that are used in VSE JCL may differ in this regard from those that are listed above.

General information about the EXEC, Model 204 file, and application program file statements for IFAM1 jobs is provided below.

For a detailed description of the Model 204 data sets that are used for HLI jobs, see HLI: Model 204 data sets in HLI jobs. For additional information about the Model 204 job control statements, see Using HLI and batch configurations.

EXEC statement

For IFAM1, the EXEC statement does not refer to Model 204 directly. When an IFAM1 job is running, Model 204 parameters cannot be specified in the EXEC statement, that is, not in the PARM field for z/OS, and not in the OPTION SYSPARM statement for VSE.

In IFAM1, any Model 204 parameter settings must be passed to Model 204 inside the application program using HLI calls. See IFAM1 jobs: Using an IFSTRT or IFDIAL thread for more information about using IFSTRT and IFDIAL threads in IFAM1.

Model 204 files

The control statements must contain a data set or file definition statement for each data set of each Model 204 file to be used in the run.

A disposition of either SHR or OLD can be specified, depending whether the Host Language Interface job runs concurrently with other Model 204 programs which use the file. Usually SHR is the recommended disposition. Model 204 uses its own system of enqueuing to resolve updating conflicts.

Application program files

The application program may need data set or file definition statements of its own for various data sets. Be careful not to specify file names that are the same as the names of any of the data set or file definition statements needed by the IFAM1 Host Language Interface itself.

IFAM1 jobs: Using an IFSTRT or IFDIAL thread

Using a single thread

IFAM1 is a single-region configuration of Model 204 that supports a single user using a private copy of Model 204. IFAM1 supports a single thread, either an IFSTRT thread or an IFDIAL thread.

The specific Model 204 interface modules that are used by the Host Language Interface for the IFAM1 job run are automatically invoked by Model 204 and depend on whether you are using an IFSTRT or an IFDIAL thread in your application program.

Specifying Model 204 runtime parameters

In IFAM1 the EXEC parameter which is specified in the job control EXEC statement is not available to Model 204.

The IFAM1 application programmer can optionally specify Model 204 system and User 0 runtime parameters inside the application program using either the IFSTRT call, if the job starts an IFSTRT thread, or the IFSETUP call, if the job starts an IFDIAL thread.

Note that there are other differences in coding calls when using either an IFSTRT or an IFDIAL thread. See the individual wiki pages for detailed descriptions of the IFSTRT and IFSETUP calls. See HLI: IFAM1 job program examples for sample IFAM1 applications.

IFAM2 jobs

IFAM2 jobs can run under z/OS, VSE, or CMS.

Except for IFDIAL under CMS, an IFAM2 job can establish multiple threads. Under z/OS and VSE, an IFAM2 job can start one or more IFSTRT threads and one IFDIAL thread. Under CMS, a IFAM2 job can start either an IFSTRT thread (or threads) or an IFDIAL thread.

The Model 204 service program operates in its own region or virtual machine. The region processes requests from an arbitrary number of host language programs, each of which operates in its own region or virtual machine. IFAM2 requires the use of communications facilities.

Communications facilities (CRAM or IUCV)

For z/OS and VSE, communication between Model 204 and a host language program in a different region is enabled by the Model 204 Cross-Region Access Method (CRAM), a special inter-region communications facility.

For CMS, a host language program communicates with Model 204 in a separate virtual machine through the IBM inter-user communication vehicle (IUCV).

See the next section for specific information about the subsystem name, channel names and IODEV settings that are used for IFAM2 jobs running under z/OS, VSE, and CMS.

Subsystem names, channel names, and IODEV settings

Model 204 uses the following subsystem names, channel names, and IODEV settings for IFAM2 threads:

• For IFSTRT threads, Model 204 uses the default channel name supplied by Rocket.
• For IFSTRTN threads, Model 204 uses the channel name that is specified in the HLI call.
• For IFSTRTN threads and z/OS with XDM, Model 204 uses the default subsystem name found in the IGCLM244 load module or the subsystem name found in the HLI as well as the channel name in the HLI call.

  The following default channel names and IODEV settings are used for IFSTRT threads:

  Facility	Parameter	Default subsystem name	Default channel name	IODEV setting
  CRAM	IFAMCHNL	Value in the IGCLM244 load module	IFAMPROD	23
  IUCV	VMIFCHNL	Not Applicable	M204VMIF	43

• For IFDIAL threads, Model 204 uses the default channel name supplied by Rocket.
• For IFDIALN threads, Model 204 uses the channel name specified in the HLI call.
• For IFDIALN threads and z/OS with XDM, Model 204 uses the default subsystem name found in the IGCLM244 load module or the subsystem name found in the HLI as well as the channel name in the HLI call.

  The following default channel names and IODEV settings are used for IFDIAL threads:

  Facility	Parameter	Default subsystem name	Default channel name	IODEV setting
  CRAM	CRIOCHNL	Value in the IGCLM244 load module	M204PROD	29
  IUCV	VMIOCHNL	Not Applicable	M204VMIO	39

Note: The IODEV settings listed above are the ones that are used by Model 204 for IFAM2 processing. You can specify VMIOCHNL and VMIFCHNL (and the corresponding IODEVs) only for CMS. You can specify CRIOCHNL and IFAMCHNL (and the corresponding IODEVs) only for z/OS and VSE.

These threads must be defined in the Model 204 Online run to provide IFAM2 communications. One IODEV is required by Model 204 for each thread that is started in the HLI program.

Compiling under Enterprise PL/I for z/OS

When compiling a PL/I application under the Enterprise PL/I for z/OS compiler, the following compiler parameter is required:

DEFAULT(LINKAGE(SYSTEM))

This causes the parameter list to be built in the same way that it was built by the old compilers (including turning on the high-order bit of the address of the last parameter).

For example:

//PLICMPL EXEC PGM=IBMZPLI,PARM='OBJECT,OPTIONS, // DEFAULT(LINKAGE(SYSTEM))',REGION=512K,...

If this compiler option is not specified, subsequent executions of the application will fail with 0C4 abends.

IFAM2 jobs: Running under z/OS and VSE

Using the CRAM facility

CRAM is an interregion facility that allows two or more programs to communicate with each other over an arbitrary number of distinct connections, called channels.

In any communication handled by CRAM, one program is the master and the other is a user. The master is always the Model 204 service program, which can communicate with several users over the same channel. After a connection is established, the user thread can issue requests, as required, for the application.

Several versions of Model 204 can run concurrently by establishing a distinct CRAM channel name for each version. Also, one user program can simultaneously communicate with multiple Model 204 service programs in different regions. For more information about CRAM, see CRAM (IODEV=11, 23, 29).

Linking with the IFIF module

A batch IFAM2 program running under z/OS and VSE must be linked with the IFIF object module, which condenses the data pertinent to each Host Language Interface call, passes it to CRAM, and sends the information to an interface routine in the Model 204 region.

Model 204 services the call and returns the information to the appropriate host language program that uses CRAM as the intermediary.

Link-editing and executing the application program

The IFAM2 application program requires its own job control statements to execute.

Note that the IFAM2 job control statements are independent of the Model 204 job because the IFAM2 application program executes as a separate job in its own region. The control statements for Model 204 files are included in the Model 204 run.

IFAM2 programs must be link-edited with the NODYNAM option set. If NODYNAM is not set, your program may abend when executed.

Example of z/OS JCL to run application (IFAM2)

The following sample job excerpt shows the z/OS JCL that runs an IFAM2 application program. In this example, COBUCLG is a COBOL compile-link-and-go procedure.

//CPLLKGO EXEC COBUCLG, //PARM.COB='LOAD,NOSEQ,NODYNAM,APOST', //REGION.LKED=200K, //PARM.LKED='LIST,LET,SIZE=(192K,100K),MAP',REGION,GO=64K //COB.SYSIN DD * IDENTIFICATION DIVISION. PROGRAM-ID. CRAMDIAL. . . . STOP RUN. //LKED.OBJLIB DD DSN=M204.V220.OBJLIB,DISP=SHR //LKED.SYSIN DD * INCLUDE OBJLIB(IFIF) //GO.SYSUDUMP DD SYSOUT=A //GO.SYSOUT DD SYSOUT=A //GO.INFILE DD * . . . /* //

To link-edit your IFAM2 job running under z/OS, link the IFAM2 application with the Model 204 module IFIF using the INCLUDE OB statement in SYSIN DD.

IFAM2 jobs: Running under CMS

Using the M204IFAM object modules

The IBM inter-user communication vehicle (iUCV) allows HLI programs running under CMS to communicate with a Model 204 system running in a separate virtual machine.

The application program must be loaded to include a library of object modules, named M204IFAM TXTLIB, that contains the CMIF, IFIF, IFCM, and IUCV interface routines that are necessary for this communication.

Using the M204IFAM EXEC

The CMIF routine in M204IFAM TXTLIB invokes a procedure called M204IFAM EXEC to obtain the name of the virtual machine that is running Model 204 and to obtain the needed IUCV communications method.

Both M204IFAM TXTLIB and M204IFAM EXEC must be available on the CMS machine for an IFAM2 host language program.

You can use any of the following values in the line that indicates the communication type to the M204IFAM EXEC:

• IUCVVMCF (the default)
• IUCV
• VMCF
• VMCFIUCV

Note: Regardless of the option specified, Model 204 establishes communications with IUCV. The VMCF facility is not supported as of Version 2, Release 2 of Model 204. To ensure compatibility with existing programs, the VMCF option is still accepted but has no effect. The VMCF option might be dropped in future releases of Model 204. If this occurs, you will need to change your HLI programs to eliminate all references to VMCF.

See HLI: IFAM1 job program examples and HLI: IFAM2/IFAM4 job program examples for examples of a CMS M204IFAM EXEC, which establishes the IUCV link.

Using VM immediate commands

You can use the HX, HT, and RT VM immediate commands described below when an IFAM2 host program is executing.

If one of the following commands is entered after the attention key for the terminal is pressed, VM takes the immediate actions summarized below:

• The HX command abnormally terminates (ABENDs) execution of a program. Control returns to CMS. This is equivalent to cancelling a program under z/OS.
• The HT command halts the display of output on the terminal, but continues execution. Use the RT command to resume output.

Loading and executing an IFAM2 program

To load and execute an IFAM2 application program under CMS, use the following steps as guidelines. The specific procedures for loading and running IFAM2 programs depend upon the particular language in which the program is written.

1. Use the GLOBAL TXTLIB command to specify the list of object libraries (called TXTLIBs) that are used to resolve references by the IFAM2 program to library subroutines.

   Note: The GLOBAL TXTLIB command includes M204IFAM TXTLIB in the list of libraries, which enables the CMS Loader to include the IFAM2 interface in the program.

   Specify the following command in the GLOBAL TXTLIB command:

   GLOBAL TXTLIB M204IFAM

   M204IFAM TXTLIB contains the interface routines necessary for communication with Model 204 using IUCV.

2. Load the application program using the CMS Loader.

   Note: The LOAD command that is normally used to invoke the CMS Loader must specify the Model 204 IFCM module in the list of programs to be loaded. If this is not done, IFCM is not included and an error occurs when the application program attempts to load the module named IGCLM244.

   To load a program named IFAMTEST, for example, specify the following command:

   LOAD IFAMTEST IFCM CLEAR

3. To run the program immediately:
   • Specify START in the command line as follows:

     LOAD IFAMTEST IFCM (START CLEAR

   • Or specify START as a separate command:

     LOAD IFAMTEST IFCM CLEAR START

   • Or use the GENMOD command to create a nonrelocatable program module (with external references resolved).

     For example, for the program named IFAMTEST, specify the following command:

     LOAD IFAMTEST IFCM GENMOD IFAMTEST

     IFAMTEST is the file name assigned to the module (and the file type is MODULE).

     And next, enter the name of the program to run it. For example,

     IFAMTEST

See HLI: IFAM2/IFAM4 job program examples for examples of CMS EXECs to compile and link and to run an IFAM2 application.

For more information about running application programs under CMS, refer to the appropriate IBM User's Guide for your operating system.

IFAM2 jobs: Using an IFDIAL thread under CMS

Specifying the IFDIAL operand in the ONLINE command

Under CMS, an IFAM2 job can start an IFDIAL thread, and this is the only connection that is allowed in the job.

Use the IFDIAL operand in the ONLINE command to specify a single-user IFDIAL connection to be made (saved segment mandatory).

The IFDIAL connection must be made on the main (nonrecovery) step. Execution of the ONLINE command creates a Model 204 Online environment. For more information about this facility, refer to the Rocket Model 204 installation instructions for the IBM z/VM platform.

If you specify IFDIAL, the main (nonrecovery) EXEC must provide only one parameter, the user program name, in the stack. IFDIAL connections require that the user program be placed first on the stack.

When defining subsystems that contain Model 204 calls in the SCT for IFDIAL, do not set the DBASE parameter.

IFAM2 jobs: Running under CICS

IFAM2 pseudo conversational support allows CICS users to include pseudo conversational applications in their IFAM2 programs. This allows the host IFAM2 program to enter a pseudo conversational wait at any time during an IFAM2 session with Model 204. The CICS interfaces are compatible with CICS Release 2.1 and later.

Transaction management

The CICS pseudo conversational programming technique ensures that no resources are held by a task during each conversational iteration with the terminal operator.

Such resources include VSAM strings, file record enqueues, enqueues on Temporary Storage queues or transient data destinations, as well as the storage acquired by the transaction during execution. Note, however, that Model 204 found sets are retained.

The pseudo conversational feature prevents potentially serious bottlenecks between transactions that could cause longer response times and deadlocks.

Using the CICS-resident program (DFHPSF)

For applications running under CICS, the IFIF module along with a CICS-specific appendage called IFPS, are linked as a CICS-resident program, such as DFHPSF, when the CICS interface is installed.

Once the CICS interface is installed using the CICS-resident program, CICS users can submit IFAM2 jobs to run by link-editing to IFENTPS, which is described in the next section.

Note: The CICS-resident program name is site-specific and can be named on the CICFG configuration section of the CICS batch program. Several types of DFHPSF (IFIF/IFPS) CICS-resident programs can be available in the CICS environment. The particular copy can be selected through the configuration name.

For more information about CICS-resident programs, see HLI: IFAM2 CICS processing.

Linking to the IFENTPS module

The IFENTPS module provides the IFAM2 application program interface for pseudo conversational CICS transactions and must be link-edited with the user CICS program.

To use the IFAM2 CICS interface, link-edit your program with the IFENTPS module. No other direct changes to your program are required.

Include the data set or file definition statements for Model 204 files that are accessed by CICS applications in the JCL for the Model 204 region, not the CICS region.

Note: The IFENTPS module can be used with either macro-level or command-level CICS application programs. The configuration copy member, CICFG, contains a conditional assemble switch that determines whether a macro-level or command-level version is generated. The Model 204 system manager must ensure that the correct version of IFENTPS is used with the appropriate application programs.

Using macro or command level program code

The version of IFENTPS that is link-edited with your IFAM2 CICS program must be assembled specifically for either macro or command level program code.

Addressing and storage requirements

Note the following IFAM2 CICS requirements:

• The following CICS areas must be addressable: CSA, TWA, and TCA.
• IFAM2 requires 88 bytes of CICS TWA.
• A temporary storage queue is created for each HLI transaction when the first IFSTRT or IFDIAL call is issued.

First and last calls in the program

The following calls are required in the IFAM2 CICS program:

• Before Version 3.1 of Model 204, the IFCSA call was required and needed to be the first call issued during the IFAM2 session. For Model 204 Version 3.1 and later, the IFCSA call no longer performs any function and is not required. For purposes of upward compatibility, the IFCSA call can remain in your current programs.
• The IFFNSH or IFHNGUP call is necessary as the last call in the program to ensure that all CRAM resources are released at program termination.

Abend handling is required

Using the Model 204 IFAM2 CICS interface successfully depends on correct abend handling to prevent hung CRAM channels.

A program must establish its own abend handler or use the IFABXIT call to establish the IFAM2 abend handler. The program must establish the abend handler or issue IFABXIT after any pseudo conversational waits, that is, after the initial connection is established.

If you run CICS IFAM2 applications written in COBOL II, set the &IFABEND parameter in CICFG to 'NO'. This prevents the abend handler in IFENTPS from causing ASRAs.

If you do this, you might want to include an abend handler routine in your COBOL II applications to prevent hanging threads after an abend. If you do, the abend handler routine must issue an IFFNSH call.

For more information

See HLI: IFAM2 CICS processing for detailed information about abend handling in an IFAM2 CICS program. Also refer to that topic for the following information about IFAM2 CICS programs:

• The IFENTPS link module
• Addressable CICS areas (CSA, TCA, TWA) and coding example
• TWA requirements, using the CICFG copy member
• Temporary storage queue

See the individual wiki pages for a description of the IFCSA, IFFNSH, and IFABXIT calls.

IFAM4 jobs

An IFAM4 job involves a two-step procedure: step one is to link-edit the application program and step two is to execute the IFAM4 batch job which runs Model 204 and the application program.

IFAM4 applications can run under the z/OS operating system. Examples of the IFAM4 job steps showing sample setups are provided in the sections which follow. The following topics are covered:

• Link-editing the application program
• Running the application program

See IFAM4 jobs: Control statements for a description of the control statements that are used with an IFAM4 job.

Running the IFAM4 application and Model 204

IFAM4 is a single-region configuration of Model 204 that supports a single user using a private copy of Model 204.

When you use the IFAM4 interface, your application program and the Model 204 service routines run as separate tasks in a single region or virtual machine.

Note: In order to use the IFAM4 facility, the Model 204 system manager must initially build the IFAM4 load module for your installation site. IFAM4 must be link-edited with the REUS option and must be named IFAM4.

Contact your Model 204 system manager to get the name of the Model 204 load library that is used to run IFAM4 programs at your site. For more information about creating the IFAM4 module, refer to the Rocket Model 204 installation instructions for your operating system.

Using IFSTRT threads

IFAM4 supports an application that uses one or more threads. An IFAM4 application can use only IFSTRT threads.

If your application uses single cursor IFSTRT threads, IFAM4 provides the most efficient way to run a multithreaded batch HLI program. IFAM4 is also useful in certain test and batch production situations.

Running concurrent IFAM4 applications

Ordinarily, two concurrently running HLI programs do not use IFAM4 to interface with a single copy of Model 204. Each IFAM4 application program runs in its own region and must have its own copy of Model 204.

However, the capability to use multiple applications or copies of an application with a single copy of Model 204 exists. To run multiple applications or copies, the host installation must provide a single controlling or monitor program to attach as subtasks each application program that is to communicate with Model 204.

This monitor program is then considered to be the application referred to subsequently in the IFAM4 control statements. Each of these application programs must have its own copy of IFIF4 link-edited to do the Host Language Interface calls and data transfers.

IFAM1 jobs: Compiling under Enterprise PL/I for z/OS

When compiling a PL/I application under the Enterprise PL/I for z/OS compiler, the following compiler parameter is required:

DEFAULT(LINKAGE(SYSTEM))

This causes the parameter list to be built in the same way that it was built by the old compilers (including turning on the high-order bit of the address of the last parameter).

For example:

//PLICMPL EXEC PGM=IBMZPLI,PARM='OBJECT,OPTIONS, // DEFAULT(LINKAGE(SYSTEM))',REGION=512K,...

If this compiler option is not specified, subsequent executions of the application will fail with 0C4 abends.

IFAM4 jobs: Link-editing under z/OS

Link with IFIF4

To link-edit your IFAM4 job running under z/OS, link the IFAM4 application with the Model 204 object module IFIF4 using the INCLUDE OB statement in SYSIN DD.

Example of z/OS JCL to link-edit COBOL application (IFAM4)

The following sample code shows an example of the JCL that might be used to link-edit an IFAM4 application to build the application load module. In this example, COBUCL is a COBOL compile-and-link procedure and the program name is COBOLTST.

//EXECCOBUCL . . . //LKED.SYSLMODDDDISP=(NEW,CATLG), //DSNAME=LOCAL.M204.IFAM4.APPLIC //LKED.OBDDDSN=LOCAL.M204.OBJECT,DISP=SHR //LKED.SYSINDD* INCLUDE OB(IFIF4) NAME COBOLTST(R)

Example of z/OS JCL to link-edit PL/1 application (IFAM4)

The sample code below shows another example of the JCL that might be used to link-edit an IFAM4 application to build the application load module. In this example, PL1LFCL is a PL/1 compile-and-link procedure and the program name is PL1TEST.

//EXECPL1LFCL . . . //LKED.SYSLMODDDDISP=(NEW,CATLG), //DSNAME=LOCAL.M204.IFAM4.APPLIC //LKED.OBDDDSN=LOCAL.M204.OBJECT,DISP=SHR //LKED.SYSINDD* INCLUDE OB(IFIF4) NAME PL1TEST(R)

IFAM4 jobs: Running under z/OS

Execute IFAM4

Once you have link-edited the application program, run the IFAM4 application in z/OS.

Example of z/OS JCL to run application (IFAM4)

The sample code below shows an example excerpt of the JCL that might be used to run an IFAM4 application which was link-edited as shown in the previous example. The sample job stream runs Model 204 and an IFAM4 application program (executing IFAM4) with three IFSTRT threads (IODEV=23). In this example, the program name in IFAM4IN DD is PL1TEST.

//RUN EXEC PGM=IFAM4,REGION=1024K,TIME=10, // PARM='SYSOPT=160,LIBUFF=1024' //STEPLIB DD DSN=LOCAL.M204.IFAM4.APPLIC,DISP=SHR // DD DSN=LOCAL.M204.LOAD,DISP=SHR //CCAAUDIT DD SYSOUT=A //CCAJRNL DD DSN=M204.JRNL,DISP=OLD //CCATEMP DD UNIT=3380,SPACE=(TRK,40), // DISP=(NEW,DELETE) //CCASNAP DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //VEHICLES DD DSN=M204.FILE.VEHICLES,DISP=SHR //CUSTOMER DD DSN=M204.FILE.CUSTOMER,DISP=SHR //EMPLOYEE DSN=M204.FILE.EMPLOYEE,DISP=SHR //CCAPRINT DD SYSOUT=A //CCASERVR DD UNIT=3380,DISP=(NEW,DELETE), // SPACE=(CYL,2) //CCAIN DD * NUSERS=4,NSERVS=3,NFILES=3,NDIR=3 IODEV=23 IODEV=23 IODEV=23 *SLEEP 3600 /* //IFAM4IN DD * PL1TEST P1=149,P2=ANDREW /* //SYSOUT DD SYSOUT=A //INFILE DD DSN=RANDOM.INPUT.DATA,DISP=SHR . . .

See IFAM4 jobs: Job errors and ABENDs for information about IFAM4 job step return codes and job run ABENDs.

Note: The IFAM4 load module must be installed at your site and must be named IFAM4.

IFAM4 jobs: Control statements

Overview of IFAM4 job control statements

The control statements listed in the following table are used in an IFAM4 job.

IFAM4 control statements

Statement	Use
EXEC	Required
STEPLIB	Required
CCAJRNL	Required for roll-forward recovery
CHKPOINT	Required for roll-back recovery
CCAAUDIT	Optional
CCATEMP	Required
CCASNAP, SYSUDUMP	Required for error diagnostics
CCAPRINT	Required
CCAIN	Required
CCASERVR	Required for server swapping
CCASTAT	Required for security
CCAGRP	Required for permanent file groups
IFAM4IN	Required
Model 204 files	Required
Application program files	Optional

See below for information about the EXEC, STEPLIB file, CCAIN, IFAM4IN, Model 204 files, and application program file statements for IFAM4 jobs.

For a detailed description of the Model 204 data sets that are used for HLI jobs, see HLI: Model 204 data sets in HLI jobs.

For additional information about the Model 204 job control statements, see Using HLI and batch configurations.

EXEC statement

You can specify the following parameters in the EXEC statement:

• PGM -- Required; Must specify IFAM4 (and not the name of the application program).
• REGION -- Required; Indicates the size of the memory area to be allocated for both IFAM4 and the application. For information about setting the REGION parameter, see Runtime environment specifications.
• TIME -- Required; Indicates how much time the application program and Model 204 together can use before being cancelled by the operating system.
• PARM -- Optional; Indicates any Model 204 runtime parameters, to be passed to Model 204. Note that user application parameters are not specified in the EXEC statement for IFAM4 and are handled instead by IFAM4IN, which is described below.

  Specify any Model 204 parameters that can be set in the EXEC statement using the following format:

  ,PARM='parameter=value[,parameter=value]...'

  Note that the following guidelines apply for specifying SYSOPT parameter settings:

  • If option 16 is set, a valid LOGIN account must be specified in the IFSTRT call for each application thread that is started by the job.
  • Setting option 32 (print RK lines) provides an audit trail or journal log of each Host Language Interface call made to Model 204. This log is invaluable for debugging the application.

STEPLIB statement

The STEPLIB file points to the load module libraries where the application program and the Model 204 IFAM4 interface program reside.

The STEPLIB file statement must specify the Model 204 load module library or the library that contains IFAM4 and the user's application program. If the Model 204 load module library and application load library are in separate libraries, use concatenated DD data set definition statements.

CCAIN file

The CCAIN input file is required for IFAM4 to specify Model 204 User 0 parameters that apply for the rest of the job run. For IFAM4 the following parameters and statements are required in the CCAIN DD:

• NUSERS -- Required; NUSERS is required on the User 0 parameter line. Set NUSERS equal to the number of threads to be used (that is, the number of IODEV statements) plus one.
• IODEV=23 -- Required; Following the User 0 parameter lines, insert an IODEV=23 statement for each thread to be started in the application program.
• *SLEEP -- Required; You must use the *SLEEP command following the IODEV lines to specify an elapsed time in seconds longer than the time the application program needs to finish processing. *SLEEP suspends processing of the CCAIN input stream but allows the application program threads to continue.

  Notes:
  

  IFAM4 immediately terminates when the application program ends. If *SLEEP times out before the application program completes, IFAM4 ends and, if the application is updating the database, file damage may occur.

  Model 204 expects the CCAIN data set to consist of 80-character lines. Data is in columns 1 through 71. Any nonblank character in column 72 indicates continuation of the line in to the next line. For a complete description of the CCAIN file, see Defining the runtime environment (CCAIN).

IFAM4IN file

Use the IFAM4IN file definition statement to specify a data set that contains the following two control statements:

1. The first statement is required and contains the name of the your application program as specified in the compile-and-link job. It must start in Column 1.
2. The second statement is used to specify parameters to be passed to the application program, as necessary.

   Note: If you are running the application program named APATTACH, omit the entire IFAM4IN data set.

Model 204 files

The control statements must contain a data set or file definition statement for each data set of each Model 204 file to be used in the run.

A disposition of either SHR or OLD can be specified, depending whether the Host Language Interface job runs concurrently with other Model 204 programs which use the file. Usually SHR is the recommended disposition. Model 204 makes use of operating system enqueuing to resolve updating conflicts.

Application program files

The application program may need data set or file definition statements of its own for various data sets. Be careful not to specify file names that are the same as the names of any of the data set or file definition statements needed by the Host Language Interface itself.

IFAM4 jobs: Job errors and ABENDs

Follow the guidelines in the following table for troubleshooting IFAM4 job ABEND codes.

IFAM4 job ABEND codes

Code	Solution
S806	Check that the following items are correctly specified: Verify that IFAM4 is named IFAM4 in the link-edit. Verify that the STEPLIB DD statement points to the library or libraries containing IFAM4 and the application program. Verify that the application program is correctly specified in Column 1 of the first statement of IFAM4IN.
S804 or S80A	Verify that the REUS option was specified in the link-edit of IFAM4. The following conditions indicate that the REUS option was not specified in the link-edit of IFAM4: IFSTRT returns a completion code of 1001. A message appears that monitor requested IFAM4 termination. IBM messages indicate that there is not enough storage for GETMAINS. Follow either step one or two: If the REUS option was not specified, relink IFAM4. If the REUS option was specified, increase REGION by 10K and add 3000 to the SPCORE parameter. Note: The SPCORE parameter defaults to 12288 in IFAM4 and can be set in the PARM field of the EXEC statement or on User 0's parameter line.

Job step return codes

IFAM4 sets the return code for the job step according to the highest completion code from Model 204 and the application program.

IFAM4 returns the job step return codes for the error conditions listed below.

Code	Error condition
999	Model 204 is not initialized properly.
998	Either the application or Model 204 ABENDs.

Note: Option 64 of the SYSOPT parameter can be set to force an ABEND without a dump at termination when the return code is nonzero. The SYSOPT parameter is specified in the EXEC statement.

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