View source for IFREAD (HLI function)

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

==Summary==
<dl>
<dt>Description</dt>
<dd>The IFREAD call (READ) obtains a line of output from Model 204.</dd>
<dt>Thread type</dt>
<dd>IFDIAL</dd>
<dt>IFCALL function number</dt>
<dd>9</dd>
</dl>

==Syntax==
<p class="syntax">IFREAD(RETCODE,LINE_AREA,MSG_DESC,LINE_LEN)</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 output parameter. The code is a binary integer value.</td>
</tr>
<tr>
<td>LINE_AREA</td>
<td>[O,c,r] The line area is a required output parameter that is set to the output line from Model 204.

<p class="note"><b>Note:</b> If Model 204 generates a logical line of output that is longer than a connection's line size, the logical line is broken into two or more physical lines that do not exceed the connection's line size. A hyphen (-) is placed in the continuation character position of each continued line and a completion code of 2 is returned until the entire logical line has been transmitted.</p>
<p>
For example, suppose that the line size was set to 4 and Model 204 is to print the string ABCDEFGH. Three calls to IFREAD are required, as summarized below:</p>
<p>
Programs using a language indicator of 2, for example, COBOL and FORTRAN, must blank out the line area before each call to IFREAD. </p>
</td>
</tr>
<tr>
<td>MSG_DESC</td>
<td>[O,i,o] The message descriptor is an optional output parameter. Model 204 returns the descriptor as an integer value in the following format:
<table>
<tr>
<td nowrap>Bytes 0 and 1</td>
<td>Contain the message length +4, in binary.</td>
</tr>
<tr>
<td>Byte 2</td>
<td>Is a bit string that describes the message returned in LINE_AREA.</td>
</tr>
<tr>
<td>Byte 3</td>
<td>Reserved</td>
</tr>
<tr>
<td colspan="2">
<p class="note"><b>Note:</b> Since the bits can be used in combination, host language programs should test the bits individually. The bits for byte 2 are summarized below.</p>
</td>
</tr>
<tr>
<td>Bit 0 (X'80')</td>
<td>If one, output is a class E message.</td>
</tr>
<tr>
<td>Bit 1 (X'40')</td>
<td>If one, output begins a new page.</td>
</tr>
<tr>
<td>Bit 2 (X'20')</td>
<td>If one, user is being restarted.</td>
</tr>
<tr>
<td>Bit 3 (X'10')</td>
<td>If one, output is a nondisplay input prompt.</td>
</tr>
<tr>
<td>Bit 4 (X'08')</td>
<td>If one, output is a $READ prompt.</td>
</tr>
<tr>
<td>Bit 5 (X'04')</td>
<td>If one, output is a class I message or any other special message such as a broadcast or file open message.</td>
</tr>
<tr>
<td>Bits 6 and 7</td>
<td>Reserved</td>
</tr>
</table>
</td>
</tr>
<div id="LINE_LEN"></div>
<tr>
<td>LINE_LEN</td>
<td>[I,i,o] The line length is an optional input parameter that specifies the transfer length for IFREAD.
<p>
This parameter determines the maximum line length for the IFREAD call. If this parameter is present, it overrides any value specified on IFDIAL or IFDIALN. For PL/1, the length is the minimum of this value plus the string length. See [[#Transfer length for output from Model 204|Transfer length for output from Model 204]] for more information about the IFREAD line length.</p>
</td>
</tr>
</table>

==Usage notes==
<p>
Use the IFREAD call only with an IFDIAL connection to receive data from Model 204.</p>
<p>
See [[HLI: IFDIAL processing#Sample subroutine to convert IFREAD flags|Sample subroutine to convert IFREAD flags]] for a coding example of a subroutine that translates the message descriptor (MSG_DESC) values returned by Model 204.</p>
<p>
You can specify a different buffer length with each call by specifying the line length in IFREAD. See the next page for detailed information about the IFREAD line length. </p>

==Completion return code (RETCODE)==
<p>
Code your IFDIAL application to check the return code for the following values: </p>
<table>
<tr class="head">
<th>Code</th>
<th>Required action</th>
</tr>
<tr>
<td>1</td>
<td>Call IFWRITE next to provide Model 204 with input.</td>
</tr>
<tr>
<td>2</td>
<td>Call IFREAD next to get more output from Model 204.</td>
</tr>
</table>

See [[HLI: IFDIAL processing|IFDIAL processing]] for more information about coding IFDIAL applications.
<p>
If the IFREAD call is unsuccessful, Model 204 returns an error code for either of the following error conditions: </p>
<table>
<tr class="head">
<th>Code</th>
<th>Condition</th>
</tr>
<tr>
<td>12</td>
<td>No output ready from Model 204 call IFWRITE to provide more input. In this case, the answer area is not altered. IFREAD call not accepted (IFWRITE call expected).</td>
</tr>
<tr>
<td>100</td>
<td>No current Model 204 connection exists or the connection is lost.</td>
</tr>
</table>

==Transfer length for output from Model 204==
<p>
The parameters in effect during the execution of the IFREAD call determine the length of data transferred from Model 204 and the actions taken when the receiving area is a different size than the Model 204 output line. </p>
<p>
The following factors determine the length: </p>
<p>
The first factor is PL/1 string length; for PL/1 compilers (F-level, Optimizer and Checkout) use a dope vector when passing character string arguments. This dope vector contains the maximum length of the string and its address. For strings declared as VARYING, it also contains the current length.</p>
<p>
Additionally, the transfer length for output from Model 204; this value is based on the following order of precedence, from highest to lowest: </p>
<ol>
<li>
The optional length parameter in the IFREAD call. The HLI application program may optionally specify a buffer length in the IFREAD call (see the [[#LINE_LEN|LINE_LEN parameter]]) which is different from the CRAM buffer size returned by the IFDIAL or IFDIALN call.
<p>
For PL/1, if this length is greater than the maximum string length, the maximum string length is used. </p>

<p class="note"><b>Note:</b> This value is in effect only for this specific IFREAD call.</p>
</li>
<li>
The optional default length parameter in the IFDIAL call; this new default remains in effect until IFHNGUP is called.
<p>
For PL/1, if this length is greater than the maximum string length, the string length is used.</p> </li>
<li>
The standard default length, which is set relative to the host language (that is, the language indicator parameter specified in the IFDIAL or IFDIALN call); Model 204 uses either of the following lengths:
<ul>
<li>252 for COBOL, FORTRAN, and Assembler </li>
<li>PL/1 maximum string length (dope vector) </li>
</ul>
</ol>
<p class="note"><b>Note:</b> The maximum length of a data area that can be transferred over an IFDIAL thread is 32763 bytes. For more information about buffer size parameters, see [[Defining the runtime environment (CCAIN)]].</p>

==When transfer length differs from output line size==
<p>
The maximum length of data that can be transferred is a result of the transfer length. If this value is different than the actual Model 204 output line size, truncation or padding may occur. </p>

<p class="note"><b>Note:</b> For all languages, when the output transfer length is less than the Model 204 output line size, Model 204 truncates the data.</p>
<p>
However, if the transfer length is greater than the output line size, Model 204 performs either of the following actions: </p>
<ul>
<li>
For COBOL, FORTRAN, and PL/1 fixed string areas, pads the remaining area with spaces. </li>
<li>
For PL/1, Model 204 sets the current string length to the output line size. The remaining answer area is unchanged. </li>
</ul>

==Overview of IFREAD data transfer==
<p>
The following table summarizes the relationship between the parameters that determine the IFREAD data transfer length and the actions taken by Model 204.</p>
<p>
The table uses the following codes: </p>
<ul>
<li>Lang=<var class="term">n</var>, which is the language indicator specified in the IFDIAL or IFDIALN call. </li>
<li>LENGTH1, which is the default length parameter in the IFDIAL call. </li>
<li>LENGTH2, which is the length parameter in the IFREAD call. </li>
<li>FIXED, which is a PL/1 string argument that is declared as fixed. </li>
<li>VARYING, which is a PL/1 string argument that is declared as varying.</li>
<li>MAXLEN, which is the maximum length of the PL/1 string. </li>
<li>Pad, which indicates that Model 204 pads the remaining answer area with spaces.</li>
<li>Set length, which indicates that PL/1 string length field (CURRLEN) is set to the Model 204 output line size, and the remaining answer area is unchanged. </li>
</ul>
<table>
<p class="caption">IFREAD data transfer length</p>
<tr class="head">
<th rowspan="1" colspan="4">Parameters in effect</th>
<th rowspan="2" colspan="1">Transfer length</th>
<th rowspan="2" colspan="1">Action</th>
</tr>
<tr class="head">
<th rowspan="1" colspan="2">IFDIAL</th>
<th rowspan="1" colspan="2">IFREAD</th>
</tr>
<tr>
<td>Lang=1</td>
<td>LENGTH1 <br />
LENGTH1 <br />
&#172;LENGTH1 <br />
&#172;LENGTH1</td>
<td colspan="2">LENGTH2 <br />
&#172;LENGTH2 <br />
LENGTH2 <br />
&#172;LENGTH2</td>
<td>min(LENGTH2,MAXLEN) <br />
min(LENGTH1,MAXLEN) <br />
min(LENGTH2,MAXLEN) <br />
MAXLEN</td>
<td>Set length</td>
</tr>
<tr>
<td>Lang=2</td>
<td>LENGTH1 <br />
LENGTH1 <br />
&#172;LENGTH1 <br />
&#172;LENGTH1</td>
<td colspan="2">LENGTH2 <br />
&#172;LENGTH2 <br />
LENGTH2 <br />
&#172;LENGTH2</td>
<td>LENGTH2 <br />
LENGTH1 <br />
LENGTH2 <br />
252</td>
<td>Pad</td>
</tr>
<tr>
<td>Lang=3</td>
<td>LENGTH1 <br />
LENGTH1 <br />
&#172;LENGTH1 <br />
&#172;LENGTH1</td>
<td>LENGTH2, <br />
&#172;LENGTH2, <br />
LENGTH2, <br />
&#172;LENGTH2</td>
<td>FIXED <br />
FIXED <br />
FIXED <br />
FIXED</td>
<td>min(LENGTH2,MAXLEN) <br />
min(LENGTH1,MAXLEN) <br />
min(LENGTH2,MAXLEN) <br />
MAXLEN</td>
<td>Pad</td>
</tr>
<tr>
<td>Lang=3</td>
<td>LENGTH1 <br />
LENGTH1 <br />
&#172;LENGTH1 <br />
&#172;LENGTH1</td>

<td>LENGTH2, <br />	
&#172;LENGTH2, <br />	
LENGTH2, <br />	
&#172;LENGTH2,</td>

<td>VARYING <br />
VARYING <br />
VARYING <br />
VARYING</td>
<td>min(LENGTH2,MAXLEN) <br />
min(LENGTH1,MAXLEN) <br />
min(LENGTH2,MAXLEN) <br />
MAXLEN</td>
<td>Set length</td>
</tr>
</table>
<p>Legend: </p>
<table>
<tr>
<td>LENGTH<var class="term">n</var></td>
<td>Parameter was specified</td>
</tr>
<tr>
<td>&#172;LENGTH<var class="term">n</var></td>
<td>Parameter was not specified</td>
</tr>
<tr>
<td>min(<var class="term">l</var>,<var class="term">m</var>)</td>
<td>Transfer length is determined to be the minimum value of <var class="term">l</var> and <var class="term">m</var></td>
</tr>
</table>

==Coding example (Assembler)==
<p class="code"><nowiki>.
.
.
  CALL IFDIAL...
.
.
.
  CALL IFWRITE...
.
.
.
  MVC     RLEN(4),=F'30'
  CALL    IFREAD,(RETCODE,INPUT,MDF,RLEN),VL
  CLI     MDF+2,X'14'  DO WE NEED A PASSWORD
.
.
.
RETCODE    DC   F'0'
INPUT      DC   CL30' '
MDF        DS   0F
MDFLEN     DS   H
MDFTYPE    DS   BL2      X'80'=CLASS E ERROR MESSAGE
*                        X'40'=NEW PAGE
*                        X'20'=RESTART
*                        X'10'=PASSWORD PROMPT
*                        X'08'=$READ PROMPT
*                        X'04'=CLASS I MESSAGE
RLEN        DC  F'0'
  END  </nowiki></p>

[[Category: HLI functions]]