View source for IFSTRTN (IFAM2) (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 IFSTRTN call (START THREAD) starts an IFAM2 thread connection to Model 204 with a specified Host Language Interface Model 204 service program through the named channel.</dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT, single cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>4</dd>
</dl>

==Syntax==
<p class="syntax">IFSTRTN|IFSTRN (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID,[SSNX:]CHAN)</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&nbsp;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&nbsp;204. </p>
<p>
<var class="term">password</var> is a character string that allows the specified user to access Model&nbsp;204.</p>
<p>As of Model 204 version 7.7: <br />Either a blank or a semicolon is accepted as the password delimiter. You can set the <var>[[CUSTOM parameter|CUSTOM]]=24</var> option to allow embedded blanks within passwords. If you are using embedded blanks, you must indicate the end of the password with a semicolon.</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&nbsp;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) interface|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 single cursor IFSTRT threads and can be used for a 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.</p>
<p>
File updating by passing data from a retrieval-only Host Language Interface thread to an update thread can lead to logical inconsistencies to the updated file during a roll forward. 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 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>
<tr>
<td>THRD_ID</td>
<td>[O,i,r] The thread identifier is a required output parameter. Specify an integer variable. Model&nbsp;204 returns a value that may be referenced using the IFDTHRD and IFSTHRD calls for thread switching in multithreaded applications.</td>
</tr>
<tr>
<td nowrap>[SSNX:]CHAN</td>
<td>[I,c,r] The channel (CHAN) name (the value of the [[IFAMCHNL parameter]]) is a required input parameter that specifies the CRAM, IUCV, or VMCF communications channel name for a particular service program. Specify the name as an eight-character string.
<p>
The four-character, secondary subsystem name, SSNX, is optional.  If present, the colon is a required delimiter.  You can use it when you want to override the default value stored in IGCLM244. See [[HLI: Job requirements#Subsystem names, channel names, and IODEV settings|Subsystem names, channel names, and IODEV settings]] for defaults.
</p>
<p class="note"><b>Note:</b> Do <i>not</i> append a semicolon.</p>
<p>
If the host language is PL/1, pass the address of the string using a based variable that overlays the original parameter. </p>
</td>
</tr>
</table>

==Usage notes==
<p>
Use the <var>IFSTRTN</var> call to establish an IFAM2 connection using a specific Host Language Interface Model&nbsp;204 service program. <var>IFSTRTN</var> performs the same function as <var>[[IFSTRT (IFAM2/IFAM4) (HLI function)|IFSTRT]]</var>. The <var>IFSTRTN</var> call includes a sixth parameter, which is not available with <var>IFSTRT</var> that is used to specify the communications channel name for the service program.</p>
<p>
For more information about CRAM (Cross Region Access Method) and Host Language Interface Model&nbsp;204 service programs, see [[HLI: Job requirements#Communications facilities (CRAM or IUCV)|Communications facilities (CRAM or IUCV)]] and [[HLI: IFAM2 CICS processing#CICS abend handling|IFAM2 CICS abend handling]].
</p>
<p class="note"><b>Note:</b> An IFAM2 job can be multithreaded. You can call <var>IFSTRTN</var> more than once in a job to establish multiple threads, but only one thread is currently active and, for single cursor <var>IFSTRT</var> threads, each thread has its own current file or group, current record set, and current record. </p>
<p>
<var>IFSTRTN</var> uses <var>IFSTRT</var> protocols, and allows applications written in a host language to process against the Model&nbsp;204 database using a the same class of HLI calls that are available with <var>IFSTRT</var>. You can start a single cursor or multiple cursor <var>IFSTRT</var> thread using the <var>IFSTRTN</var> call. </p>
<p>
<var>IFSTRT</var>, together with <var>IFFNSH</var>, initiates [[HLI: Recovery and checkpoints#Automatic checkpointing: CPSORT|CPSORT checkpointing]].</p>

===Changing a login password===
<p>
Changing a login password by specifying <var class="term">password</var>:<var class="term">new password</var> is supported in Model&nbsp;204 version 7.5 or earlier, and in Model&nbsp;204 version 7.6 if the <var>PWDCOLON</var> parameter is not set (see <var>[[PWDCOLON parameter|PWDCOLON]]</var> for details). 
</p>
<p class="note"><b>Note:</b> Since colons are allowed in login passwords as of Model&nbsp;204 version 7.7, 
the <var class="term">password</var>:<var class="term">new password</var> syntax is no longer valid because the colon is not recognized as a delimiter. Instead, use the <var>[[LOGINCP or LOGONCP command|LOGINCP]]</var> command to change your password. </p>

==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>
<li>Channel name M204CHNB </li>
</ul>
<p class="code"><nowiki>WORKING-STORAGE SECTION.
01  LOGIN-INFO.
    05 LOGIN      PIC X(12) VALUE 'USERABC;ECP;'.
01  CALL-ARGS.    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).
    05 CHAN-NAME  PIC X(13) VALUE "SSN1:IFAMCHNL".
*   05 CHAN-NAME  PIC X(8) VALUE "IFAMCHNL".
.
.
.
PROCEDURE DIVISION.
INITIALIZATION.
    OPEN OUTPUT...
    CALL "IFSTRTN" USING RETCODE, LANG-IND, LOGIN, MODE, 
    THRD-NO, CHAN-NAME.
    IF RETCODE IS NOT EQUAL TO ZERO
    GO TO ERROR-ROUTINE.
.
.
.</nowiki></p>

[[Category: HLI functions]]