View source for IFSTRT (IFAM2/IFAM4) (HLI function)

The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions|Function call notation conventions]].

==Summary==
<dl>
<dt>Description</dt>
<dd>The form of the IFSTRT call (START THREAD) that starts an IFAM2 or IFAM4 thread connection to Model 204 performs the following actions:
<ul>
<li>Allocates a thread, making it currently active in the job</li>
<li>Returns the thread identifier for use by IFDTHRD or IFSTHRD</li>
<li>Specifies the calling protocol to be used for the host language </li>
<li>Performs a user login</li>
<li>Establishes either a single cursor or a multiple cursor type thread</li>
<li>For a single cursor thread, determines whether retrieval or updating privileges are allowed </li>
</ul></dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT, single cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>1</dd>
</dl>

==Syntax==
<p class="code">IFSTRT(RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID)</p>

<dl>
<dt>Compile-only form</dt>
<dd>Not available</dd>
<dt>Execute-only form</dt>
<dd>Not available</dd>
</dl>

<p>Specify the parameters in the syntax order shown above.</p>
<table>
<tr class="head">
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>RETCODE</td>
<td>[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.</td>
</tr>
<tr>
<td>LANG_IND</td>
<td>[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.
<p>
Specify one of the following integer values:</p>
<p>
1 = PL/1 F-level, and BAL languages <br />
2 = COBOL, FORTRAN, and BAL languages <br />
3 = PL/1 with +Optimizer/Checkout compilers, VS/FORTRAN, and BAL languages</p>
<p class="note"><b>Note:</b> 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.</p>
</td>
</tr>
<tr>
<td>LOGIN</td>
<td>
[I,c,r] The login information is a required parameter that supplies a valid Model 204 user ID and password that permit entry to the system. Specify the login as a character string using the following format:
<p class="syntax"><span class="term">userid</span> [<span class="term">account</span>];
<span class="term">password</span>[:<span class="term">new password</span>]; (This method of changing a password is supported in version 7.6 and earlier)</p>
<p>where:</p>
<p><var class="term">userid</var> is a character string that identifies the user who is logging into Model 204.</p>
<p>
<var class="term">account</var> is an optional character string that supplies an account under which the user is logging into Model 204. </p>
<p>
<var class="term">password</var> is a character string that allows the specified user to access Model 204.</p>
<p>
<var class="term">new password</var> is an optional character string that changes the login password for the specified user, for future logins. (Supported in Model 204 version 7.6 and earlier; see [[#Changing a login password|Changing a login password]] for details.)</p>
<p>
Certain restrictions apply to login entries when using a security subsystem, such as Security Server (formerly RACF), to perform login validation. For details, see the topic for your [[:Category:Security interfaces|security interface]]. </p>
<p>For a description of the login command, see [[LOGIN or LOGON command]].</p>
</td>
</tr>
<tr>
<td>THRD_TYP</td>
<td>[I,i,r] The thread type indicator is a required parameter that specifies the type of IFSTRT thread to be allocated. Specify one of the following integer values:
<p>0 = Single cursor thread with read-only privileges <br />
1 = Single cursor thread with update privileges <br />
2 = Multiple cursor thread</p>
<p class="note"><b>Note:</b> The 0(read) and 1 (update) settings are valid for a single cursor IFSTRT thread which can be used in an multithreaded application. </p>
<p>
A thread type indicator of 0 allows a single cursor IFSTRT thread to be used only for retrieval, regardless of the file or group password that is used in a particular call. File updating by passing data from a retrieval-only Host Language Interface thread to an update thread can lead to logical inconsistencies.</p> 
<p>To prevent inconsistencies, start the thread as an update thread (1) and use a retrieval-only password to open a file. This provides share-mode (SHR) enqueuing and prevents updating from the thread. Files that are opened this way are also prevented from being marked physically inconsistent with a user restart or system crash. </p>
</td>
</tr>
<div id="THRD_ID"></div>
<tr>
<td>THRD_ID</td>
<td>[O,i,r] The thread identifier is a required output parameter. Specify an integer variable. Model 204 returns a value that may be referenced using the IFDTHRD and IFSTHRD calls for thread switching in multithreaded applications.</td>
</tr>
</table>

==Usage notes==
<p>
Use the IFSTRT call to establish a connection to the Host Language Interface Model 204 service program. For an IFAM2 connection, IFSTRT assumes a default channel name of IFAMPROD. </p>
<p>
Note that an IFAM2 or IFAM4 job can be multithreaded. You can call IFSTRT more than once in a job to establish multiple threads, but only one IFSTRT thread is currently active and, for single cursor IFSTRT threads, each thread has its own current file or group, current record set, and current record. You can start single cursor and multiple cursor IFSTRT threads in the same job. </p>
<p>
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. </p>
<p>
On a single cursor IFSTRT thread, IFSTRT together with IFFNSH initiates [[HLI: Recovery and checkpoints#Automatic checkpointing: CPSORT|CPSORT checkpointing]].</p>

===Changing a login password===
Changing a login password by specifying <var class="term">password</var>:<var class="term">new password</var> is supported in Model 204 version 7.5 or earlier, and in Model 204 version 7.6 if the PWDCOLON parameter is not set (see <var>[[PWDCOLON parameter|PWDCOLON]]</var> for details).
<p>As of Model 204 version 7.7, colons are always allowed in login passwords, so a colon is not recognized as a delimiter between passwords. Use the <var>[[LOGINCP or LOGONCP command|LOGINCP]]</var> command to change your password.</p>

==Completion return code (RETCODE)==
<p>
If the IFSTRT call is unsuccessful, Model 204 returns an error code for any of the following error conditions:</p>
<table>
<tr class="head">
<th>Code</th>
<th>Error condition</th>
</tr>
<tr>
<td>4</td>
<td>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.</td>
</tr>
<tr>
<td>90</td>
<td>A Model 204 is not yet available for user processing. Recovery might still be in progress. (Action: Call IFSTRT again.)</td>
</tr>
<tr>
<td>100</td>
<td>LOGIN failed.</td>
</tr>
<tr>
<td>400</td>
<td>Invalid language code (LANG_IND).</td>
</tr>
</table>

==Coding example (COBOL)==
<p>
This COBOL coding example specifies the following IFSTRT parameters: </p>
<ul>
<li>COBOL calling convention (language indicator is 2) </li>
<li>Login account name USERABC </li>
<li>Login password ECP </li>
<li>Single cursor thread with read-only access (thread type is 0) </li>
</ul>
<p class="code">WORKING-STORAGE SECTION.
01  LOGIN-INFO.
    05 LOGIN       PIC X(12) VALUE 'USERABC;ECP;'.
01  CALL-PARMS  COMP SYNC.
    05 RETCODE     PIC 9(5).
    05 LANG-IND    PIC 9(5) VALUE 2.
    05 MODE        PIC 9(5) VALUE 0.
    05 THRD-NO     PIC 9(5).
.
.
.
PROCEDURE DIVISION.
INITIALIZATION.
  OPEN OUTPUT...
  CALL "IFSTRT" USING RETCODE, LANG-IND, LOGIN, MODE, THRD-NO.
  IF RETCODE IS NOT EQUAL TO ZERO
     GO TO ERROR-ROUTINE.
.
.
.</p>

[[Category: HLI functions]]