IFDIAL (HLI function): Difference between revisions
Jump to navigation
Jump to search
No edit summary |
m (add <var>'s) |
||
| (2 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
The conventions used on this page are described in [[HLI: Function | The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions|Function call notation conventions]]. | ||
==Summary== | ==Summary== | ||
<dl> | <dl> | ||
<dt>Description</dt> | <dt>Description</dt> | ||
<dd>The IFDIAL call (DIAL) starts an IFDIAL thread that establishes a direct connection to the Model 204 SOUL facility through the default CRAM communications channel. </dd> | <dd>The <var>IFDIAL</var> call (DIAL) starts an <var>IFDIAL</var> thread that establishes a direct connection to the Model 204 SOUL facility through the default CRAM communications channel. </dd> | ||
<dt>Thread type</dt> | <dt>Thread type</dt> | ||
<dd>IFDIAL</dd> | <dd>IFDIAL</dd> | ||
| Line 20: | Line 20: | ||
</dl> | </dl> | ||
<p>Specify the parameters in the syntax order shown above. </p> | <p> | ||
Specify the parameters in the syntax order shown above. </p> | |||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
| Line 26: | Line 27: | ||
<th>Description</th> | <th>Description</th> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>RETCODE</td> | <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> | <td>[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>LANG_IND</td> | <td>LANG_IND</td> | ||
| Line 40: | Line 43: | ||
</td> | </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>BUFFER</td> | <td>BUFFER</td> | ||
<td>[O,i,o] The buffer size is an optional output parameter that specifies the size of the CRAM buffer which is the maximum buffer length for I/O to Model 204. Model 204 returns the size of the buffer as an integer value. | <td>[O,i,o] The buffer size is an optional output parameter that specifies the size of the CRAM buffer which is the maximum buffer length for I/O to Model 204. Model 204 returns the size of the buffer as an integer value. | ||
<p> | <p> | ||
BUFFER is required if IO_LEN is specified. </p> | <var>BUFFER</var> is required if <var>IO_LEN</var> is specified. </p> | ||
</td> | </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>IO_LEN</td> | <td>IO_LEN</td> | ||
<td>[I,i,o] The I/O length is an optional input parameter that specifies the default length for I/O to Model 204. This is the length that is used if a length parameter is not specified in an IFREAD or IFWRITE call. See the LINE_LEN parameter for [[IFREAD (HLI function)|IFREAD]] for details.</td> | <td>[I,i,o] The I/O length is an optional input parameter that specifies the default length for I/O to Model 204. This is the length that is used if a length parameter is not specified in an <var>IFREAD</var> or <var>IFWRITE</var> call. See the <var>LINE_LEN</var> parameter for [[IFREAD (HLI function)|IFREAD]] for details.</td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
< | <ul> | ||
Use the IFDIAL call to establish an IFDIAL connection through the default CRAM channel M204PROD. </ | <li>Use the <var>IFDIAL</var> call to establish an <var>IFDIAL</var> connection through the default CRAM channel <var>M204PROD</var>. If necessary, use <var>[[IFDIALN (HLI function)|IFDIALN]]</var> to connect through an alternate channel name.</li> | ||
< | |||
An HLI job can start both IFDIAL and IFSTRT threads. Note, however, that any single HLI job can have only one active IFDIAL thread. </ | <li>An HLI job can start both <var>IFDIAL</var> and <var>IFSTRT</var> threads. Note, however, that any single HLI job can have only one active <var>IFDIAL</var> thread. </li> | ||
</ul> | |||
===Releasing an IFDIAL thread=== | ===Releasing an IFDIAL thread=== | ||
<p> | <p> | ||
To release an IFDIAL thread, use either one of the following HLI functions:</p> | To release an <var>IFDIAL</var> thread, use either one of the following HLI functions:</p> | ||
<ul> | <ul> | ||
<li>IFHNGUP, which disconnects the IFDIAL thread. </li> | <li><var>IFHNGUP</var>, which disconnects the <var>IFDIAL</var> thread. </li> | ||
<li>IFFNSH, which deletes all outstanding threads, including the IFDIAL connection. </li> | <li><var>IFFNSH</var>, which deletes all outstanding threads, including the <var>IFDIAL</var> connection. </li> | ||
</ul> | </ul> | ||
<p class="note"><b>Note:</b> If your job started both IFSTRT and IFDIAL threads and you use the IFDTHRD call to detach threads, IFDTHRD releases an IFSTRT thread without disconnecting the IFDIAL thread. </p> | <p class="note"><b>Note:</b> If your job started both <var>IFSTRT</var> and <var>IFDIAL</var> threads and you use the <var>IFDTHRD</var> call to detach threads, <var>IFDTHRD</var> releases an <var>IFSTRT</var> thread without disconnecting the <var>IFDIAL</var> thread. </p> | ||
===Using the image feature to transmit data=== | ===Using the image feature to transmit data=== | ||
<p> | <p> | ||
The image feature of SOUL allows a request to process terminal input and output, such as an IFDIAL connection. Large blocks of data can thus be transferred from a host language program to Model 204. </p> | The image feature of SOUL allows a request to process terminal input and output, such as an <var>IFDIAL</var> connection. Large blocks of data can thus be transferred from a host language program to Model 204. </p> | ||
<p> | <p> | ||
For more information about READ IMAGE and WRITE IMAGE, see [[Images]].</p> | For more information about <var>READ IMAGE</var> and <var>WRITE IMAGE</var>, see [[Images]].</p> | ||
==Completion return code (RETCODE)== | ==Completion return code (RETCODE)== | ||
<p> | <p> | ||
If the IFDIAL call is unsuccessful, Model 204 returns one of the following error codes:</p> | If the <var>IFDIAL</var> call is unsuccessful, Model 204 returns one of the following error codes:</p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
| Line 83: | Line 89: | ||
<th>Error condition</th> | <th>Error condition</th> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>80</td> | <td>80</td> | ||
<td>No current thread. (Action: Call IFSETUP.)</td> | <td>No current thread. (Action: Call IFSETUP.)</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>90</td> | <td>90</td> | ||
<td>An IFDIAL connection already exists for this application program. The attempt to establish more than one simultaneous connection for this application is ignored.</td> | <td>An <var>IFDIAL</var> connection already exists for this application program. The attempt to establish more than one simultaneous connection for this application is ignored.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>101</td> | <td>101</td> | ||
<td>Invalid module load. (Action: Check STEPLIB for correct release.)</td> | <td>Invalid module load. (Action: Check STEPLIB for correct release.)</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>500</td> | <td>500</td> | ||
<td>Invalid function called.</td> | <td>Invalid function called.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>800</td> | <td>800</td> | ||
<td>All Model 204 IFDIAL connections are busy. (Action: Check to see that the proper number of IODEV 29 initialization statements were included in the HLI Model 204 service program.)</td> | <td>All Model 204 IFDIAL connections are busy. (Action: Check to see that the proper number of IODEV 29 initialization statements were included in the HLI Model 204 service program.)</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>1001</td> | <td>1001</td> | ||
<td>HLI Model 204 service program is not up, the HLI is halted or drained, or no host language threads were defined in Model 204. (This might indicate that the IFAM4 load module was link-edited without the REUS option.)</td> | <td>HLI Model 204 service program is not up, the HLI is halted or drained, or no host language threads were defined in Model 204. (This might indicate that the IFAM4 load module was link-edited without the REUS option.)</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>1003</td> | <td>1003</td> | ||
| Line 112: | Line 125: | ||
</tr> | </tr> | ||
</table> | </table> | ||
==Coding examples== | ==Coding examples== | ||
===COBOL=== | ===COBOL=== | ||
<p class="code">WORKING-STORAGE SECTION. | <p class="code">WORKING-STORAGE SECTION. | ||
Latest revision as of 18:32, 6 April 2017
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFDIAL call (DIAL) starts an IFDIAL thread that establishes a direct connection to the Model 204 SOUL facility through the default CRAM communications channel.
- Thread type
- IFDIAL
- IFCALL function number
- 6
Syntax
IFDIAL(RETCODE,LANG_IND,BUFFER,IO_LEN)
- 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 can be specified for use with the BAL language, and the BAL programmer must adhere to the convention that is specified when coding parameters. |
| BUFFER | [O,i,o] The buffer size is an optional output parameter that specifies the size of the CRAM buffer which is the maximum buffer length for I/O to Model 204. Model 204 returns the size of the buffer as an integer value.
BUFFER is required if IO_LEN is specified. |
| IO_LEN | [I,i,o] The I/O length is an optional input parameter that specifies the default length for I/O to Model 204. This is the length that is used if a length parameter is not specified in an IFREAD or IFWRITE call. See the LINE_LEN parameter for IFREAD for details. |
Usage notes
- Use the IFDIAL call to establish an IFDIAL connection through the default CRAM channel M204PROD. If necessary, use IFDIALN to connect through an alternate channel name.
- An HLI job can start both IFDIAL and IFSTRT threads. Note, however, that any single HLI job can have only one active IFDIAL thread.
Releasing an IFDIAL thread
To release an IFDIAL thread, use either one of the following HLI functions:
- IFHNGUP, which disconnects the IFDIAL thread.
- IFFNSH, which deletes all outstanding threads, including the IFDIAL connection.
Note: If your job started both IFSTRT and IFDIAL threads and you use the IFDTHRD call to detach threads, IFDTHRD releases an IFSTRT thread without disconnecting the IFDIAL thread.
Using the image feature to transmit data
The image feature of SOUL allows a request to process terminal input and output, such as an IFDIAL connection. Large blocks of data can thus be transferred from a host language program to Model 204.
For more information about READ IMAGE and WRITE IMAGE, see Images.
Completion return code (RETCODE)
If the IFDIAL call is unsuccessful, Model 204 returns one of the following error codes:
| Code | Error condition |
|---|---|
| 80 | No current thread. (Action: Call IFSETUP.) |
| 90 | An IFDIAL connection already exists for this application program. The attempt to establish more than one simultaneous connection for this application is ignored. |
| 101 | Invalid module load. (Action: Check STEPLIB for correct release.) |
| 500 | Invalid function called. |
| 800 | All Model 204 IFDIAL connections are busy. (Action: Check to see that the proper number of IODEV 29 initialization statements were included in the HLI Model 204 service program.) |
| 1001 | HLI Model 204 service program is not up, the HLI is halted or drained, or no host language threads were defined in Model 204. (This might indicate that the IFAM4 load module was link-edited without the REUS option.) |
| 1003 | Not enough memory for CRAM. |
Coding examples
COBOL
WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 COBOL-IND PIC 9(5) VALUE 2. . . . PROCEDURE DIVISION. OPEN INPUT... CALL "IFDIAL" USING RETCODE, COBOL-IND. . . .
Assembler
. . . CALL IFDIAL,(RETCODE,LANGID),VL . . . RETCODE DC F'0' LANGID DC F'2' END