Using HLI and batch configurations

Overview

The configurations described in this topic use the Model 204 Host Language Interface (HLI), which allows a user to invoke most of the system functions from application languages such as Assembler, COBOL, PL/I, and FORTRAN.

This page summarizes the Inverted Files Access Methods, IFAM1, IFAM2, and IFAM4, which are used as interfaces between application languages and Model 204; the BATCH204 configuration, which supports a single user without a terminal; and the BATCH2 utility, which establishes a remote connection with a Model 204 Online running in a separate region.

For additional information, see the following sections on other pages:

• Multiple jobs running on one CPU
• Setting user parameters
• File groups
• IFAM2 control

For complete information about HLI, refer to Host Language Interface (HLI).

IFAM1

IFAM1 is a batch configuration of Model 204 that supports Host Language Interface calls in Assembler, COBOL, FORTRAN, or PL/I to the Inverted File Access Method (IFAM).

Linking Model 204 modules with a user's host language program is similar to linking with function subroutines. At runtime, the host language program is loaded dynamically with Model 204.

An IFAM1 application runs in its own region, which is always separate from the Online region. The program and Model 204 execute together in a single virtual machine or address space.

Because each IFAM1 application is linked to its own copy of the HLI/Model 204 routines, all IFAM1 programs must be relinked each time an HLI/Model 204 routine changes. By specifying the DYNAM compiler option, application developers can dynamically link the HLI/Model 204 portion of their application at runtime and obtain gains in efficiency of application maintenance and storage space.

For more information about IFAM1 jobs, see HLI: Job design factors.

z/OS and IFAM1

The following considerations apply to the z/OS JCL required to run IFAM1:

• Required JCL DD statements for IFAM1 are:
  • CCAPRINT
  • CCATEMP
  • STEPLIB
  • CCAGRP, if permanent file groups are used
  • CCASTAT, if security features are used
  • Host language program statements
• Optional DD statements are:
  • CCAAUDIT
  • CCAJLOG
  • CCAJRNL
  • CCASNAP
  • SYSUDUMP

  CCASNAP or SYSUDUMP is required if you want error diagnostics.

  Note: CCAIN statements are not valid.

• EXEC statement parameters do not refer to Model 204 directly. Model 204 parameter settings and User 0 parameters are passed to Model 204 by the IFSTRT call, or by the IFSETUP call if using an IFDIAL thread.
• PGM parameter (required) specifies the name of the user program that is being run, not IFAM1.
• REGION parameter is optional. Calculate REGION size by determining the amount of memory that the application program requires and adding that to a minimum of 260K (buffers and other overhead). The Model 204 modules in IFAM1 occupy approximately 704K.
• PARM field (used to set application runtime parameters) is optional. Model 204 parameters cannot be specified in the PARM field.
• TIME parameter is optional.

z/VSE partition usage

An IFAM1 configuration uses the storage area between the end of the IFAM1 configuration and the beginning of the partition GETVIS area, unless the user-written host language program is PL/I or large enough for Model 204 to allocate some buffers from it. In the case of PL/I programs, some storage must be left between the end of the IFAM1 configuration and the beginning of the GETVIS area.

To enable Model 204 to take dynamic storage for the GETVIS area, set the SIZE parameter on the EXEC statement as follows:

SIZE=AUTO,nK

where n is the number of bytes to be left. The IFAM1 dynamic link load module that is loaded needs a large GETVIS area.

"IFAM partition usage" illustrates the partition storage division:

IFAM partition usage

	PARTITION
Low end		User-Written Host Language Program	Program area
		IFIF1DOS
SIZE parameter	IFAM1	Unused space reserved for dynamic storage allocation	GETVIS area
High end	Phase

Running IFAM1 under z/VSE

The following considerations apply to running IFAM 1 under z/VSE:

• Do not specify Model 204 parameters on User 0's parameter line. These parameters are included in the IFSTRT call to HLI, or in IFSETUP.
• Specify a value for the SYSOPT parameter in this call in decimal format (for example, SYSOPT=16).
• Do not use the UPSI Job Control statement to specify bit settings for SYSOPT.
• You must catalog IFAM1 programs into a sublibrary before you can execute them.
• You must include label information for the CCATEMP, CCASTAT, CCAUDIT, and all user database files referenced by the IFAM1 program in the job stream:
  • EXEC statement refers to the phase name under which the IFAM1 program is cataloged.
  • Partition storage requirements must be met.

IFAM2

IFAM2 is a multi thread configuration of Model 204 that supports host language calls to HLI from one or more user programs. IFAM2 programs run as separate jobs in other regions or partitions and share a single copy of the database management system software. Each user program:

• Can have only one IFDIAL thread, although each program can have multiple IFSTRT threads.
• Must be linked to a small interface module in its region. The linked interface provides communication between the batch region (user program) and the IFAM region via a special inter-region supervisor call.

The IFAM2 feature can handle calls from several users at once, similar to the Model 204 ONLINE configuration. The ONLINE load module can be link-edited in such a way that it supports HLI user programs as well as terminals that run SOUL requests (see the Rocket Model 204 Installation pages).

Host Language applications can run in 31-bit addressing mode and move data to and from Model 204 in 31-bit addressing mode.

CRAM requirements for z/OS and z/VSE

The Cross-Region Access Method (CRAM) is required for z/OS and z/VSE systems.

If the host language program has been compiled with a z/VSE compile, or requires z/VSE SVC simulation, the z/VM/z/VSE environment (SET DOS ON) is also supported.

IUCV channels can be available in the same run under z/OS and z/VSE (prior to Release 1.4.0).

Length of HLI functions

The maximum length of an HLI function argument depends on the HLI application's language indicator:

• For PL/I, supply the length of each argument as part of the argument in a dope vector.
• For Assembler, COBOL, or FORTRAN, set the maximum length of an input argument using the LIBUFF parameter set on the user's parameter line.

  The maximum length of an output parameter is the maximum value of LOBUFF.

IFAM buffer size (IFAMBS)

The value required for the IFAMBS (IFAM2 buffer size) parameter set on User 0's parameter line depends on the maximum string length and the highest number of string arguments used by a single HLI call.

IFAMBS is the maximum size of a block of data that can be transferred between the application and Model 204. The block contains a fixed header of 284 bytes, plus all the input and output arguments for a single function call. Four bytes are required for each integer argument. The maximum string length is required for each output string argument:

• For PL/I input strings, use the string's actual length.
• For COBOL and FORTRAN input strings, use the maximum length (LIBUFF). IFAMBS defaults to 2048 and can be set on User 0's parameter line.

To calculate IFAMBS, use the following formula:

IFAMBS = (n * LIBUFF) + 284

where n is the number of arguments used on a function call in your HLI program. The minimum value of n is 2.

Setting the IFAM2 channel name

Set the IFAM2 channel name on User 0's parameter line. For IFAM2 communication using:

• Cross-Region Access Method, set the IFAM2 channel name using the IFAMCHNL parameter.
• IUCV interface, set the channel name using the VMIFCHNL parameter.

Additional modules (IFAM, CRIO,IFFII, IFIF)

To support IFDIAL threads, link-edit the CRIO module into the ONLINE configuration.

To generate an ONLINE load module that supports normal IFAM2 processing, CRIO processing, and provides z/OS support for CICS, link the following additional modules with ONLINE:

Module	Contains...
IFAM	Basic IFAM routines
IFII	Code to interface to Host Language programs
CRIO	Code to interface to User Language programs

If you need a special version of IFAM2, you can create the interface module IFIF without using the default channel names. Consult Technical Support for instructions.

Multiple IFAM2 versions

Multiple IFAM2 versions must use different names for each CRAM channel:

• If a second job is brought up without a unique name, you can initiate recovery with the following sequence of commands, if the second IFAM2 is initialized with SOUL connections:

  LOGIN system-manager-id password IFAMSTAT -1 IFAMDRAIN IFAMSTAT IFAMFORCE IFAMCLOSE IFAMOPEN newname IFAMSTAT -1 IFAMSTART

• To terminate IFAM2 processing on a version of IFAM2 that has SOUL connections, use the following sequence of commands, if no application jobs are active:

  IFAMSTAT -1 IFAMDRAIN IFAMSTAT IFAMFORCE IFAMCLOSE LOGWHO

  At this point, you can forceably terminate active IFAM2 applications with the IFAMFORCE command, or allow normal completion by issuing the IFAMCLOSE command after you verify that the IFAM facility is drained (IFAMSTAT command).

Terminating IFAM2 processing

To terminate IFAM2 processing on a version of IFAM2 that does not have any IFDIAL connections, you must quiesce active IFAM2 applications (by canceling them or allowing them to complete).

If none of the applications are updating, or if broken files are acceptable, you can simply terminate IFAM.

Operational considerations when using the CICS system interface are described in HLI: IFAM2 CICS processing.

z/VSE and IFAM2

When using IFAM2 with ONLINE, Model 204 allocates data buffers in contiguous space. Model 204 attempts to allocate buffers between the end of the ONLINE program and the beginning of the partition GETVIS area first. If this storage area is not sufficient for a minimum amount of buffer space, it is left unused. You can keep the amount of storage in the unused area to a minimum by specifying SIZE=AUTO on the EXEC statement.

A situation might arise in which sufficient contiguous space is not found in either the reserved area or the area above it. In this case, specify either a very large or a very small SIZE VALUE. "ONLINE partition usage with IFAM2," below, illustrates ONLINE partition usage with IFAM2.

In z/VSE, the partition in which IFAM2 application programs are run must have access to a core image library containing the phases IGCLM244 and CRAMSWT.

Label information is not needed for database files in the JCL for the IFAM2 application.

Label information for database files accessed by the IFAM2 application must be provided in the JCL of the ONLINE program that is communicating with the IFAM2 program.

ONLINE partition usage with IFAM2

	PARTITION 1					PARTITION 2
Low		ONLINE				IFAM2 Program			Prob Prog Area
		Unused space (unless SIZE = AUTO)
		IGCLM244	CRAMZWT			IGCLM244	CRAMSWT		GETVIS Area
High		Reserved for dynamic storage allocation

z/VM and IFAM2

In z/VM, Model 204 files accessed by the host language programs are defined to the service machine:

• Define application program files in the user's z/VM virtual machine.
• You can use z/VSE macros within IFAM2 programs.
• You can run the copy of Model 204 communicating with the IFAM2 program under any operating system.
• IFAM2 permits user-written programs that use HLI and Model 204 to run in separate virtual machines. IUCV is the communications protocol.

IFAM4 for z/OS

IFAM4 is a multi thread configuration of Model 204 that supports host language (Assembler, PL/I, COBOL, FORTRAN) calls to HLI without the use of CRAM. Model 204 and the user.s application program are run as separate subtasks of a single batch job.

Note: IFAM4 is not applicable for z/VM or z/VSE. You must compile and link-edit IFAM4 before executing it. You must compile IFAM4 programs with the NODYNAM option.

Link-editing requirements

You must link IFAM4 with the REUS option:

• Name the resulting link IFAM4. (See the Rocket Model 204 installation pages for operating system instructions.)
• Link application programs into a load module library that is used by the IFAM4 run.

Examples

The COBOL compile and link procedure is:

// EXEC COBUCL . . . //LKED.SYSLMOD DD DISP=(NEW,CATLG), // DSN=M204.PROGMS.IFAM4 //LKED.OB DD DSN=M204.OBJECT,DISP=SHR //LKED.SYSIN DD * INCLUDE OB(IFIF4) NAME programname(R)

The PL/I compile and link procedure is:

// EXEC PLILFCL . . . //LKED.SYSLMOD DD DISP=(NEW,CATLG), // DSN=M204.PROGMS.IFAM4 //LKED.OB DD DSN=M204.OBJECT,DISP=SHR //LKED.SYSIN DD * INCLUDE OB (IFIF4) NAME programname (R)

Converting an IFAM2 application to an IFAM4 application

Only a link-edit, without recompiling the IFAM2 application, is required to convert an IFAM2 IFSTRT application program into an IFAM4 application. For example:

// EXEC LKED . . //LKED.SYSLMOD DD DISP=(NEW,CATLG), // DSN=M204.PROGMS.IFAM4 //LKED.OB DD DSN=M204.OBJECT,DISP=SHR //LKED.IFAM2LIB DD DSN=M204.PROGMS.IFAM2,DISP=SHR //LKED.SYSIN DD * INCLUDE OB (IFIF4) INCLUDE IFAM2LIB (oldprogram) ENTRY entryname NAME newprogram (R)

• Only the interface module (IFIF) for IFAM2 is changed.
• ENTRY statement is required.
• entryname must be the same as in the IFAM2 load module.

IFAM4 running JCL

IFAM4 requires essentially the same JCL as that described for ONLINE in ONLINE data streams with CCAIN.

• Use an IFAM4IN DD statement to specify a control data set.
• Your application program might require additional DD statements
• You must set the PGM parameter to IFAM4, not the name of the application program.
• REGION parameter must provide a region size large enough for both IFAM4 and the application program.
• PARM parameter must specify any parameters that are passed to Model 204.
• STEPLIB DD statement must specify the load module library or the library that contains the IFAM4 and the HLI application program. If you use separate libraries, concatenated DD statements are required.
• Set the NUSERS parameter on User 0's parameter line to the maximum number of HLI threads needed by the application program plus one.
• Set NSERVS, if server swapping is required to save memory.
• An IODEV=23 statement, following User 0's parameter line, is required for each HLI thread.
• Follow user parameter lines with a *SLEEP command that specifies a longer elapsed time (in seconds) than the application program needs to finish.
• Your application program might need SYSOUT or INFILE data sets. Avoid names that conflict with ddnames used for IFAM4 processing.
• IFAM4IN handles user application program parameters.

  The IFAM4IN data set contains control statements used during IFAM4 initialization:

• The first statement (started in column one) contains the name of the application program as it was specified in the compile-and-link job.
• The second statement contains parameters that are passed to the application program. (These are the parameters normally specified in the PARM field of the EXEC statement, if the application program is executed independently.)
• The second statement of IFAM4IN is omitted if the application program requires no parameters.
• The entire IFAM4IN data set is omitted if the application program is named APATTACH.

Common IFAM4 problems

The following table lists common IFAM4 problems and suggested solutions:

Common IFAM4 problems

Problem	Solution
S806 ABEND	Verify that IFAM4 has been named in the link-edit. Verify that the STEPLIB DD statement points to the libraries containing IFAM4 and the application program. Verify that the application program name was correctly specified in column one of the first statement of IFAM4IN.
S804 or S80A ABEND	Verify that REUS (RENT for VS1) is specified in the link-edit of IFAM4. If REUS is not specified, relink IFAM4. If REUS is specified, increase REGION by 10K and add 3000 to the SPCORE parameter. SPCORE defaults to 12288 in IFAM4. Specify a setting (on the EXEC PARM field or on User 0's parameter line) high enough to accommodate all the dynamic storage requirements of Model 204, the application program, and dynamically loaded subroutines used by the application.

BATCH204

BATCH204 is a Model 204 configuration that supports a single user without the use of terminals (batch configuration). Input to BATCH204 is sequential, consisting of system control commands and SOUL or FLOD statements. Output is a printed listing.

The BATCH204 interface is similar to the support offered to the HLI Interface in IFAM1 for IFSTRT. In the IFAM1 environment, the IFAM module is the interface between the application program and Model 204. In the BATCH204 environment, the IFID module is the interface between the application program and Model 204.

When using BATCH204, the JCL EXEC parameter is not available to Model 204. CCAIN and CCAPRINT files are used. The dynamic loading of Model 204 routines, such as the BATCH204 module, during initialization is the responsibility of the IFIF1OS, IFIF1DOS, and IFIF1CMS modules. One of these operating-system-dependent modules must be linked with the application program.

BATCH2 utility

The BATCH2 utility provides the capacity to access a Model 204 Online running in a separate region. BATCH2 establishes a remote connection, emulates a line-at-a-time terminal, reads a specified input data stream, and transmits the input to the Online region. The resulting output generated by the Online region is read by BATCH2 and written to the specified output data stream.

In the z/OS and z/VSE environments, BATCH2 uses the CRAM thread defined by IODEV=29 (SOUL line-at-a-time thread). In the z/VM environment, BATCH2 uses the IUCV line-at-a-time thread defined by IODEV=39.

A complete discussion, JCL requirements, and runtime parameters for the BATCH2 utility are given in the BATCH2 facility.