HLI: Coding conventions

Overview

This topic provides the application programmer with general guidelines for coding HLI call parameters and conventions to follow when using particular programming languages.

See HLI functions for descriptions of all of the HLI calls and their parameter lists. See HLI: IFAM1 job program examples and HLI: IFAM2/IFAM4 job program examples for examples of HLI programs written in different programming languages.

General coding guidelines

Using the host language call protocol (the CALL verb)

Host Language Interface functions are called by the host language program according to the host language subroutine call protocol. Each HLI function is an external subroutine and is called with a CALL verb of the host language.

The following table shows examples.

Language	Example using call verb
COBOL	CALL "IFOPEN" USING RET-CODE, FILE-NAME
FORTRAN	CALL IFOPEN(RETCD,FILEN)
PL/I	CALL IFOPEN (RET_CODE,FILE_NAME)
Assembler	CALL IFOPEN,(RETCD,FILEN),VL

Note: If you are using COBOL, your COBOL compiler determines whether or not you use double quotes.

Using function names and aliases

All Host Language Interface function names begin with the letters IF and are seven characters or less in length, for example, IFFIND and IFCOUNT.

Function names that are seven characters in length also have an alias (six characters or less in length) that is used in FORTRAN programming.

The alias name, if available, is provided in the Syntax description of a call. The full name is first, followed by a vertical bar separator, followed by the alias. For example, IFFINDC | IFFDC, where IFFDC is the alias.

See HLI: Function summary for a complete listing of HLI calls by name.

Using function numbers

All Host Language Interface functions except IFCALL, IFLOG, and IFSTRT (in IFAM1) have an associated function number. You can use IFCALL to call functions that have numbers only if you are running an IFAM2 or IFAM4 job.

The function number, where available, is provided in the Syntax description of the individual call.

See HLI: Function summary for a complete listing of HLI calls and their numbers.

Specifying HLI call parameters

The following guidelines apply for specifying HLI call parameters:

The same set of parameters for each call is required with all languages.
The order of the parameters in each call is important. Follow the syntax that is specified for each call.
Except where noted, you cannot omit a parameter. If you do not want to specify a value for a parameter, supply a null placeholder parameter. If, for example, parameters 3 and 4 are optional and you select one, you include both.
Note: A missing parameter is not a null parameter.

Defining HLI call parameter data types

With the exception of one parameter of IFCHKPT that is in packed format, all parameters are defined as one of the following types:

Fullword aligned binary integers in COBOL
Fullword integer in FORTRAN
Fullword fixed binary integer in PL/I
Short character string whose maximum length is 32 bytes
Full length character string whose maximum length is the buffer size; the input buffer size is determined by the LIBUFF User 0 parameter; the output buffer size is determined by the LOBUFF User 0 parameter.
The following table shows examples.

Language Example of integer variable

COBOL 05 INTEGER-ARG PIC 9(5) COMP SYNC.

FORTRAN INTEGER*4 INTARG

PL/I DECLARE INTEGER_ARG FIXED BIN(31):

Assembler INTARG DC F'O'

Length restrictions on character string parameters in HLI calls

Character string parameters are passed to Model 204, but Model 204 does not always know the length. For example, length is known with PL/I dope vectors, but length is not known with COBOL. Length is language-dependent.

The mechanism that governs the maximum length that an HLI call may pass in a single parameter is determined by the setting of the language indicator that is specified (in the IFSTRT, IFSTRTN, IFDIAL, or IFDIALN call) in the HLI application.

For a language indicator equal to 2 (that is, COBOL, FORTRAN, and Assembler), the Model 204 User 0 parameter LIBUFF determines the maximum length of a character string that may be passed by the HLI program in an individual parameter; the Model 204 User 0 parameter LOBUFF determines the maximum character string length to return.

For a language indicator equal to 1 or 3 (that is, PL/I), the length of each argument is supplied as part of the parameter. PL/I passes dope vectors in parameter lists which contain the exact length of the parameters.

In the examples of character string variable definitions below, the actual length of the input parameter is specified for COBOL and FORTRAN, and a maximum length of 255 is specified for PL/I.

The following table shows examples.

Language	Example of character string variable
COBOL	05 STRING-ARG	PIC X(6) VALUE 'value;'
FORTRAN	LOGICAL*1 STRING(5)/'value'/
PL/I	DECLARE STRING_ARG	CHAR(255) VAR INIT ('value')
Assembler	STRING DC C'value'

Note: Except where noted, it is important to indicate the end of a character string passed as an parameter with a semicolon (;).

See HLI: Model 204 parameters for more information about character string variables used in HLI call parameters.

Using the completion return code (RETCODE)

Except for IFABXIT, IFCALL, and IFCSA, the first parameter of each call is a completion return code (RETCODE). In some cases RETCODE is the only parameter that is specified for a call.

Your application program must check return codes because they indicate success or failure or informative messages.

Note: Nonzero codes do not always mean failure and vice versa.

Completion codes corresponding to particular error conditions are described in the "Notes and Tips" section for individual calls to aid you in coding.

See HLI: Model 204 completion and ABEND codes for a list of completion return codes. See HLI: Model 204 completion return codes for more information about using completion return codes.

COBOL coding guidelines

Use the following coding conventions when COBOL is the host language:

Call Host Language Interface functions by using a CALL in the PROCEDURE DIVISION. For example:
CALL 'IFOPEN' USING ERROR FILE-NAME.
Declare all parameters in the WORKING STORAGE or LINKAGE SECTION of the DATA DIVISION.
- You must define integer parameters as fullword, aligned, binary numbers. For example:
  1 ERROR PIC 9(5) COMP SYNC.
- Define character parameters as alphanumeric. You must end input of a parameter string with a semicolon (;). For example:
  FILE-NAME PIC X(14) VALUE 'TESTFILE;PASS;'.
Model 204 ignores extra embedded blanks within input parameters.
The maximum character string length that can be passed to a Host Language Interface function in a single parameter is determined by the value of the LIBUFF parameter, which defaults to 255.
Note: LIBUFF is a Model 204 User 0 parameter that cannot be changed once the Host Language Interface/Model 204 service program is initialized.
The maximum character string length that a Host Language Interface function returns to the application program is determined by LOBUFF.
Note: LOBUFF is a Model 204 User 0 parameter that cannot be changed once the Host Language Interface/Model 204 service program is initialized.
The Host Language Interface function cannot determine the actual length of a COBOL data area parameter.
Model 204 moves values into the data area, beginning with the first character in the area and continuing until the function has finished processing or until the maximum of LIBUFF character positions has been filled.

Note: If the data area is longer than the returned values, the remaining data area characters are not filled. If the data area is shorter than the returned values, the characters following the data area are overwritten.
Some character string parameters are specially designated as short strings. Short strings can be used for input or output.
The maximum length of a short string in IFAM2 is 32 bytes. In IFAM1 or IFAM4, the maximum length is set by LIBUFF.
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.

See CICS abend handling for detailed information about abend handling in an IFAM2 CICS program.

FORTRAN coding guidelines

Use the following coding conventions when FORTRAN is the host language:

Call Host Language Interface functions by using the CALL statement. For example:
CALL IFOPEN (ERROR, FILENAME)
Define integer arguments as fullword integers. For example:
INTEGER*4 ERROR
End character string arguments with a semicolon. For example:
INTEGER*4 FILENAME(4) DATA FILENAME/'TEST','FILE',';PAS','S; '/
The conventions concerning the lengths of string arguments passed to or returned from Host Language Interface functions are the same as those for COBOL (see COBOL coding guidelines).
For FORTRAN 77, the language indicator is 2 in releases prior to Release 1.3. Add the following @PROCESS command listing all functions:
@PROCESS SC (IFSTRT,IFFIND, ...)

This compiles the FORTRAN program without dope vectors, which are not supported.

PL/I coding guidelines

Coding conventions

Use the following coding conventions when PL/I is the host language:

Call Host Language Interface functions by using the CALL statement. For example:
CALL IFOPEN (ERROR, FILENAME);
Declare all Host Language Interface functions called in a PL/I application program in that program as external entry points.
Describe integer parameters as fullword, fixed, binary; describe string parameters as character strings. For example:

DCL IFOPEN EXT ENTRY (FIXED BIN(31), CHAR(*));
Declare integer arguments as fixed, binary, fullword. For example:
DCL ERROR FIXED BIN (31);
Declare string arguments as character strings, either FIXED or VARYING. For example:
DCL FINDSPEC CHAR(8) INITIAL ('STATE=MA'); DCL OUTDATA CHAR(256) VARYING;

Note: In PL/I application programs, character string arguments do not need to end with semicolons.
All types of PL/I, that is, PL/I F-level (IFSTRT language indicator = 1) or PL/I Optimizer or Checkout (language indicator = 3), pass to Model 204 a dope vector that contains the value length along with the value string itself. A semicolon delimiter at the end of each string argument is not needed.

However, semicolons within argument strings are still required where appropriate. For example:

L FILEARGS CHAR(10) INITIAL ('CEN1;PASSW');
The maximum lengths for string arguments that are passed to or returned from Host Language Interface functions are governed by the value of the LIBUFF parameter.
A string returned from a Host Language Interface function is truncated if the area in the PL/I program to which it is being returned is shorter than the returned value. If the returned value is shorter than the return data area, the unused portion of the data area remains unchanged for FIXED strings, and a string's length is set for VARYING strings.
The special argument designation of short string does not apply to PL/I.

Passing a channel name as a string in IFSTRTN or IFDIALN

When an IFSTRTN or IFDIALN call is made (in IFAM2) with a language indicator of 1 or 3, Model 204 expects the channel name to be a string and not a PL/I dope vector.

To force the compiler to pass the address of the string instead of the dope vector, you can use a data type that does not use dope vectors, such as FIXED BIN. Either a based or defined variable of this type can overlay the original argument. The variable is passed to the call. A based variable, unlike a defined variable, does not produce any compiler error messages.

The following example passes the address of the string independent of the PL/I compiler in use:

DCL IFSTRTN EXTERNAL ENTRY(FIXED BIN(31), /* completion code */ FIXED BIN(31), /* language ind */ CHAR(*), /* login info */ FIXED BIN(31), /* update indicator */ FIXED BIN(31), /* thread id */ FIXED BIN(31)); /* CRAM [subsysname:]channelname */ DCL RETURN_CODE FIXED BIN(31), LANGUAGE_INDICATOR FIXED BIN(31), LOGIN_INFO CHAR(15), UPDATE_INDICATOR FIXED BIN(31), THREAD_ID FIXED BIN(31), CRAM_CHANNEL CHAR(13) INIT('SSN1:MYCHAN'), CRAM_CHANNEL_ARG FIXED BIN(31) BASED(P); /* THE FOLLOWING STATEMENT SETS THE POINTER P TO THE */ /* ADDRESS OF CRAM_CHANNEL. P IS ALSO THE ADDRESS OF */ /* CRAM_CHANNEL_ARG. */ P = ADDR(CRAM_CHANNEL); CALL IFSTRTN(RETURN_CODE,LANGUAGE_INDICATOR,LOGIN_INFO, THREAD_ID,CRAM_CHANNEL_ARG);

The following call is for IFDIALN:

CALL IFDIALN(RETURN_CODE,LANGUAGE_INDICATOR, CRAM_CHANNEL_ARG)

Assembler language coding guidelines

Assembler language programs usually adhere to the standard calling sequence used by COBOL and FORTRAN and are subject to the same conventions that govern parameter formats and lengths.

Note: However, when starting an IFSTRT, IFSTRTN, IFDIAL, or IFDIALN thread, any of the three language indicator values (1, 2, or 3) can be used with an Assembler language application program.
Accordingly, the calling sequences and data structures that correspond to the particular language specified in the thread call must be used in the Assembler application program.

Regardless of the language indicator specified, use the following coding conventions when Assembler is the host language:

The IFFIND call must have the following format:
CALL IFFIND,(ERR,QUAL1),VL
Under z/OS, all calls must end with the VL parameter.

Pascal/VS coding guidelines

Use the following conventions when Pascal/VS is the host language:

Declare integer arguments as type INTEGER. For example:
VAR I:INTEGER;
Declare character string parameters as PACKED ARRAY OF CHAR, and end their values with a semicolon. For example:
TYPE M204.STR = PACKED ARRAY (.1..255.) OF CHAR; VAR FILENAME: M204.STR; FILENAME:='TESTFILE;PASS;';
Declare HLI functions as external FORTRAN procedures and pass all arguments by REFERENCE, using the VAR keyword. For example:
PROCEDURE IFOPEN (VAR ERROR:INTEGER;VARFILENAME:M204.STR); FORTRAN;
Use language indicator 2 in the IFSTRT call.

Coding guidelines for other languages

You can use Host Language Interface functions for languages other than COBOL, FORTRAN, PL/I, Assembler, and Pascal.

Follow the conventions below for passing parameters, depending on the language indicator specified in the IFSTRT, IFSTRTN, IFDIAL, or IFDIALN call that establishes the thread:

For language indicator 1, you can call a Host Language Interface function if the compiler can generate parameter lists that adhere to standard register usage.
Note: Register 1 must point to the parameter list and consist of a list of memory addresses.
For language indicator 2, the addresses point directly to the parameter values. The last valid parameter is flagged by setting the high-order byte of the parameter address.
Many language compilers that do not ordinarily follow the parameter passing conventions listed above have special options for calling external FORTRAN and Assembler language routines. For example, Pascal/VS passes parameters by value in some cases.
These special options allow Host Language Interface functions to be invoked using language indicator 2.