IFSTRT (IFAM1) (HLI function)

From m204wiki
Revision as of 23:00, 11 July 2016 by ELowell (talk | contribs)
Jump to navigation Jump to search

The conventions used on this page are described in Function call notation conventions.

Summary

Description

The form of the IFSTRT call (START THREAD) that starts an IFAM1 thread connection to Model 204 performs the following actions:

  • Allocates a single active thread
  • Specifies the calling protocol to be used for the host language
  • Sets certain Model 204 job parameters
  • Establishes either a single or a multiple cursor type thread
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
Not applicable

Syntax

IFSTRT(RETCODE,LANG_IND,PARM_LIST,PRO_LIST,THRD_TYP)

Compile-only form
Not available
Execute-only form
Not available

Specify the parameters in the syntax order shown above.

Parameter Description
RETCODE [O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.
LANG_IND [I,i,r] The language indicator is a required input parameter that establishes the calling sequence convention to be used corresponding to the host language. The indicator specifies the format of parameters that are passed in subsequent calls. Specify one of the following integer values:

1 = PL/1 F-level, and BAL languages
2 = COBOL, FORTRAN, and BAL languages
3 = PL/1 with +Optimizer/Checkout compilers, VS/FORTRAN, and BAL languages

Note: Any convention may be specified for use with the BAL language, and the BAL programmer must adhere to the convention that is specified when coding parameters.

PARM_LIST [I,c,r] The parameter list is a required input parameter that specifies PARM entries that are set on the EXEC statement for the IFAM1 job. Specify a character string and append a semicolon (;), or specify a semicolon if no parameters are to be set. See List of Model 204 parameters for a description of the Model 204 parameters.

Note: If the LIBUFF and LOBUFF parameters are to be set, include them in the parameter list. Do not specify the following parameters in the PARM list: ALTIODEV, NUSERS, and NSERVS.

PRO_LIST [I,c,r] The prologue list is a required input parameter that specifies Model 204 User 0 parameters, such as page size and lengths of various work areas. Specify a character string and append a semicolon (;), or specify a semicolon if no parameters are to be set. (This entry corresponds to the first line of the SYSIN data set in a BATCH204 run.)

See "Notes and tips" in the following section for restrictions that apply to User 0 login entries. For a description of the Model 204 User 0 parameters, see User 0 parameters.

THRD_TYP [I,i,o] The thread type indicator is an optional parameter that indicates either a single cursor or a multiple cursor IFSTRT thread. Specify either of the following integer values:

0 = Single cursor thread (default)
2 = Multiple cursor thread

Note: If not specified, the thread indicator defaults to 0; you must specify a value of 2 to use a multiple cursor IFSTRT thread.

Usage notes

Use the IFSTRT call to establish a connection to the Host Language Interface Model 204 service program.

Note that an IFAM1 job is single-threaded, and only one IFSTRT thread can be started in the job. You can specify a multiple cursor IFSTRT thread or use the default single cursor IFSTRT thread.

The IFSTRT protocol allows applications written in a host language to process against the Model 204 database using a particular class of HLI calls. See HLI: Function summary for an overview of IFSTRT calls.

User 0 login restrictions

Certain restrictions apply for specifying User 0 login parameters (the PRO_LIST parameter). Rocket recommends the following actions when using a security subsystem, such as Security Server (formerly RACF), that performs login validation:

  • Do not specify a user ID in the login for User 0. Note that if you do supply a user ID in the login, it must match the user ID of the owner of the address space; otherwise, the login fails.
  • When the IFSTRT call processes the login parameter, do not code the password in the host language program. Model 204 interprets a password that is passed in the IFSTRT call as an invalid command.

Completion return code (RETCODE)

If the IFSTRT call is unsuccessful, Model 204 returns an error code for either of the following error conditions:

Code Error condition
4 No IFSTRT thread was started; do not attempt to issue any other HLI calls. The HLI program code should check the return code from IFSTRT and continue processing only if the call was successful; for a return code of 4, either reissue IFSTRT until it is successful or stop job processing and give an error message.
80 No current thread. (Action: Call IFSTRT.)
90 An illegal IFSTRT call was made when a thread already exists.

Coding example (PL/1 Optimizer)

. . . DCL NERR FIXED BIN (31) INIT (0); DCL PARM CHAR (80) INIT('SYSOPT=144,LIBUFF=500,LOBUFF=500;'); DCL IFSTRT ENTRY(FIXED BIN(31), FIXED BIN(31),CHAR(*),CHAR(*)); . . . CALL IFSTRT (NERR,3,PARM,'PAGESZ=6184,SPCORE=5000;'); . . .