IFDIAL (HLI function)

From m204wiki
Revision as of 20:53, 6 July 2016 by ELowell (talk | contribs)
Jump to navigation Jump to search

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.

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