IFSTRTN (IFAM2) (HLI function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with " ==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 se...")
 
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions|Function call notation conventions]].


==Summary==
==Summary==
Line 11: Line 12:


==Syntax==
==Syntax==
<p class="syntax">IFSTRTN | IFSTRN (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID,[SBSN:]CHAN)</p>
<p class="syntax">IFSTRTN|IFSTRN (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID,[SSNX:]CHAN)</p>


<dl>
<dl>
Line 46: Line 47:
<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:
<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>];
<p class="syntax"><span class="term">userid</span> [<span class="term">account</span>];
<span class="term">password</span>[:<span class="term">new password</span>];</p>
<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>
<p>
where:</p>
Where:</p>
<p>
<p>
<var class="term">userid</var> is a character string that identifies the user who is logging into Model 204.</p>
<var class="term">userid</var> is a character string that identifies the user who is logging into Model&nbsp;204.</p>
<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>
<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>
<p>
<var class="term">password</var> is a character string that allows the specified user to access Model 204.</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>
<p>
<var class="term">new password</var> is an optional character string that changes the login password for the specified user, for future logins.</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>
<p>
See [[#Login restrictions|Login restrictions]] for the restrictions that apply to login entries when using a security subsystem, such as Security Server, to perform login validation. For a description of the login command, see [[LOGIN or LOGON command]].</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>
</td>
</tr>
</tr>
Line 77: Line 81:
<tr>
<tr>
<td>THRD_ID</td>
<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>
<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>
<tr>
<tr>
<td nowrap>[SBSN:]CHAN</td>
<td nowrap>[SSNX:]CHAN</td>
<td>[I,c,r] The channel (CHAN) name 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.
<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>
<p>
The subsystem name (SBSN:) is optional. You can use it when you want to override the default. Specify the name as a four-character string, plus colon (:).</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 class="note"><b>Note:</b> Do <i>not</i> append a semicolon.</p>
<p>
<p>
Line 93: Line 98:
==Usage notes==
==Usage notes==
<p>
<p>
Use the IFSTRTN call to establish an IFAM2 connection using a specific Host Language Interface Model 204 service program. IFSTRTN performs the same function as IFSTRT. The IFSTRTN call includes a sixth parameter, which is not available with IFSTRT that is used to specify the communications channel name for the service program.</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>
<p>
For more information about CRAM (Cross Region Access Method) and Host Language Interface Model 204 service programs, see [[HLI: Job requirements]] and [[HLI: IFAM2 CICS processing]].</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 class="note"><b>Note:</b> An IFAM2 job can be multithreaded. You can call IFSTRTN more than once in a job to establish multiple threads, but only one 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. </p>
</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>
<p>
IFSTRTN uses IFSTRT protocols, and allows applications written in a host language to process against the Model 204 database using a the same class of HLI calls that are available with IFSTRT. You can start a single cursor or multiple cursor IFSTRT thread using the IFSTRTN call. </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>
<p>
IFSTRT, together with IFFNSH, initiates [[HLI: Recovery and checkpoints#Automatic checkpointing: CPSORT|CPSORT checkpointing]].</p>
<var>IFSTRT</var>, together with <var>IFFNSH</var>, initiates [[HLI: Recovery and checkpoints#Automatic checkpointing: CPSORT|CPSORT checkpointing]].</p>


===Login restrictions===
===Changing a login password===
<p>
<p>
Certain restrictions apply for specifying login information (the LOGIN parameter). Rocket recommends the following actions when using a security subsystem, such as Security Server, that performs login validation: </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).  
<ul>
</p>
<li>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. </li>
<p class="note"><b>Note:</b> Since colons are allowed in login passwords as of Model&nbsp;204 version 7.7,  
<li>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. </li>
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>
</ul>


==Coding example (COBOL)==
==Coding example (COBOL)==

Latest revision as of 16:33, 23 January 2018

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

Summary

Description
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.
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
4

Syntax

IFSTRTN|IFSTRN (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID,[SSNX:]CHAN)

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.

LOGIN [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:

userid [account]; password[:new password]; (This method of changing a password is supported in version 7.6 and earlier)

Where:

userid is a character string that identifies the user who is logging into Model 204.

account is an optional character string that supplies an account under which the user is logging into Model 204.

password is a character string that allows the specified user to access Model 204.

As of Model 204 version 7.7:
Either a blank or a semicolon is accepted as the password delimiter. You can set the CUSTOM=24 option to allow embedded blanks within passwords. If you are using embedded blanks, you must indicate the end of the password with a semicolon.

new password 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 for details.)

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 security interface.

For a description of the login command, see LOGIN or LOGON command.

THRD_TYP [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:

0 = Single cursor thread with read-only privileges
1 = Single cursor thread with update privileges
2 = Multiple cursor thread

Note: The 0 (read) and 1 (update) settings are valid for single cursor IFSTRT threads and can be used for a multithreaded application.

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 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.

THRD_ID [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.
[SSNX:]CHAN [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.

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 Subsystem names, channel names, and IODEV settings for defaults.

Note: Do not append a semicolon.

If the host language is PL/1, pass the address of the string using a based variable that overlays the original parameter.

Usage notes

Use the IFSTRTN call to establish an IFAM2 connection using a specific Host Language Interface Model 204 service program. IFSTRTN performs the same function as IFSTRT. The IFSTRTN call includes a sixth parameter, which is not available with IFSTRT that is used to specify the communications channel name for the service program.

For more information about CRAM (Cross Region Access Method) and Host Language Interface Model 204 service programs, see Communications facilities (CRAM or IUCV) and IFAM2 CICS abend handling.

Note: An IFAM2 job can be multithreaded. You can call IFSTRTN more than once in a job to establish multiple threads, but only one 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.

IFSTRTN uses IFSTRT protocols, and allows applications written in a host language to process against the Model 204 database using a the same class of HLI calls that are available with IFSTRT. You can start a single cursor or multiple cursor IFSTRT thread using the IFSTRTN call.

IFSTRT, together with IFFNSH, initiates CPSORT checkpointing.

Changing a login password

Changing a login password by specifying password:new password 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 PWDCOLON for details).

Note: Since colons are allowed in login passwords as of Model 204 version 7.7, the password:new password syntax is no longer valid because the colon is not recognized as a delimiter. Instead, use the LOGINCP command to change your password.

Coding example (COBOL)

This COBOL coding example specifies the following IFSTRT parameters:

  • COBOL calling convention (language indicator is 2)
  • Login account name USERABC
  • Login password ECP
  • Single cursor thread with read-only access (thread type is 0)
  • Channel name M204CHNB

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. . . .