Janus IFDIAL Library

The Janus IFDIAL Library provides client/server streams support over TCP/IP. This support is similar to Model 204 BATCH2/IFDIAL support with the difference that the client programs run on workstations and the communication protocol is TCP/IP. This approach has several advantages:

• It makes it easy to access existing BATCH2 applications from a workstation.
• It makes it easy to write new Model 204 applications that communicate with a workstation since they can be written using well-understood technology (Write Image and Print statements) rather than complex communications functions.
• It makes it possible to write "self-contained" workstation applications that include both client and server (User Language code).
• It provides a mechanism for uploading and downloading Model 204 procedures from/to a workstation.

C routines

Workstation programs written in C have access to the Model 204 server through the functions described in this chapter. There are no limits to the number of IFDIAL connections an application can have at a given time or the number of different Model 204 servers an application can be connected to simultaneously other than the limits imposed by storage capacity on the client machine and the number of IFDIAL threads defined on the host Model 204 Onlines.

Following are the C routines that comprise the Janus IFDIAL Library:

C routine	Description
ifdial	Initiate a connection to a Model 204 server.
iffinish	Terminate (hang up) connections to Model 204 servers.
ifhangup	Terminate a connection to a Model 204 server.
ifread*	Read data sent from Model 204 server.
ifwrite*	Write data on a connection to a Model 204 server.

ifdial

Name	ifdial — Initiate a connection to a Model 204 server.
Synopsis	#include <ifdial.h> cnum = ifdial(name, port, ibsize, obsize, maxin) int cnum; char *name; int port; int ibsize; int obsize; int maxin;
Description	The parameter name specifies either the TCP/IP address or the name of the host running the BATCH2 server. The parameter port specifies the TCP/IP port providing the BATCH2 service. If this parameter is 0, the default port of 204 is used. The parameter ibsize indicates the size of the buffer to be used to receive data from the Model 204 server, and obsize indicates the size of the buffer to be used to send data to the Model 204 server. The default for ibsize is 1024, and the default for obsize is the same as the value of ibsize. Note that values for both ibsize and obsize must be between 512 and 8192 inclusive; values outside that range will be forced to the nearest proper value. The parameter maxin sets the maximum length record that the client will accept from the Model 204 server. The Model 204 server is informed of this limit and will not send any records longer than maxin bytes. The default for maxin is 256, and it will be forced into the range 80 to 8192 inclusive if outside this range.
Return values	>= 0 If the connection succeeds, a value of 0 or greater is returned. This number indicates the connection number and is to be used in future ifread and ifwrite calls. There is no limit to the number of ifdial connections an application can have active at a time. If the connection fails, a value less than 0 is returned indicating the nature of the error. -100 Passed name could not be resolved. -101 Insufficient storage. -102 Socket failure (TCP/IP service not available). -103 Connection failure (server not available). -104 local failure (TCP/IP service probably lost). -105 Error in initial handshake (probably not a Model 204 IFDIAL server). -106 Connected to incompatible IFDIAL server.

iffinish

Name	iffinish — Terminate (hang up) all connections to Model 204 server(s)
Synopsis	#include <ifdial.h> rc = iffinish(); int rc;
Description	No further ifread or ifwrite are allowed on any connection after an iffinish
Return values	0 All connections terminated.

ifhangup

Name	ifhangup — Terminate (hang up) a connection to a Model 204 server
Synopsis	#include <ifdial.h> rc = ifhangup(cnum); int rc;
Description	The parameter cnum specifies the connection number returned by a previous ifdial. No further ifread or ifwrite calls are allowed on a connection after an ifhangup for that connection.
Return values	0 Connection terminated. 100 Invalid connection number.

ifread

Name	ifread, ifreadl — Read data sent from a Model 204 server ifreadVB, ifreadlVB — Wrappers for using ifread, ifreadl from Visual Basic programs
Synopsis	#include <ifdial.h> rc = ifread(cnum, data) int rc; int cnum; char **data; rc = ifreadl(cnum, data, len) int rc; int cnum; char **data; int *len;
Description	The parameter cnum specifies the number of a connection established with a previous ifdial call. data is a pointer to a string pointer to be set to point to a blank delimited character string that contains the next output line from the IFDIAL server. len (ifreadl and ifreadlVB only) is both an input and an output parameter. On input, it's the maximum length to be returned in data (including a terminating null-byte). On output, it is set to the full length of the record, and if the output value exceeds the input value, the record was truncated. In the case of a C-program calling ifreadl, no data are actually moved (the data parameter is set to point to the record in the internal buffer), so there is no worry about buffer overflow and the input value of len isn't very useful (this is not the case with the VB versions; see below). However, since it is possible that the returned data contains embedded nulls, the returned value in len is useful when strlen won't work.
Visual Basic issues	Except for ifread and ifreadl, all the IFDIAL functions can be called from Visual Basic programs, using the Windows build of ifdial.dll and the declarations provided in the ifdial.vb file (note carefully that ints in C must be Longs in VB, and that strings for which a length is not provided (the name arg to ifdial and the data arg to ifwrite and ifwriteb) must be null-terminated). However, because of the way VB passes string args, your VB program must use the alternate forms ifreadVB and ifreadlVB: Dim cnum As Long Dim data As String * 256 Dim rc As Long Dim length As Long rc = ifreadVB (cnum, data) length = 256 ' Length of the data buffer rc = ifreadlVB (cnum, data, length) You must include the declarations provided in the ifdial.vb file in the (General)(Declarations) section of your VB project. Since the returned string is actually moved into the data parameter, buffer overflow is possible with the ifreadVB function, but if the length argument is properly set on input, the ifreadlVB function is safe in this regard.
Return values	1 ifwrite required to provide data for Model 204. 2 ifread required to receive data from Model 204. 12 No data to receive. ifwrite required to provide data for Model 204. **data is set to 0 in this case. 100 Invalid connection number. 200 Connection lost.

ifwrite

Name	ifwrite, ifwriteb, ifwritel, ifwritbl — Write data on a connection to a Model 204 server
Synopsis	#include <ifdial.h> rc = ifwrite(cnum, data) int rc; int cnum; char *data; rc = ifwritel(cnum, data, len) int rc; int cnum; char *data; int len; rc = ifwriteb(cnum, data) int rc; int cnum; char *data; rc = ifwritbl(cnum, data, len) int rc; int cnum; char *data; int len;
Description	ifwrite, ifwriteb, ifwriteb and ifwritbl are used to send data to a Model 204 server. ifwrite and ifwriteb must be passed a null terminated string pointer, while ifwritel and ifwritbl must be passed a string pointer and the length of the string. ifwrite and ifwritel will force any data in the current ifwrite buffer to be sent immediately to the Model 204 server, and then wait for either data from the Model 204 server or a response indicating that more ifwrite data is required. ifwriteb and ifwritbl will buffer the writes so that a single TCP/IP send can be used to send multiple lines to the Model 204 server, and they will not wait to determine whether an ifread or an ifwrite is required next. Use of ifwriteb or ifwritbl can result in a return code of 12 indicating that the data to be sent to the Model 204 server was not accepted. This return code is also possible with ifwrite or ifwritel if an ifwrite is issued without waiting for a return code of from ifread. In either case, some form of ifwrite must be called again with the original data after one or more ifread calls are made whenever a return code of 12 is received from an ifwrite function. For maximum throughput, issue ifwriteb or ifwritbl calls until a value of 12 is returned at which point issue an ifread and then retry the ifwrite. The parameter cnum specifies the number of a connection established with a previous ifdial call. data is the data to be sent to the Model 204 server. len is the length of the data to be sent.
Return values	1 ifwrite is required to provide data for Model 204. For buffered ifwrites (ifwriteb and ifwritbl), this return code might be followed by a return code 12 on an immediately following ifwrite. 2 ifread data is available from Model 204. This will never be returned by ifwriteb. 12 ifwrite not accepted, data must be received from Model 204 with ifread. 100 Invalid Connection number. 200 Connection lost.

Workstation utilities

Several workstation utilities are provided with the Janus IFDIAL Library that provide access to Model 204. These utilities are ready-to-run, precompiled C programs:

batch2	sends data from an input file to a Model 204 server and places returned data into an output file.
m204	initiates a conversation with a Model 204 server, prompting for input data from the terminal as required and sending the Model 204 output to standard output.

These utilities and their options are described in the following section.

batch2

The batch2 command has the following format:

batch2 command syntax

batch2 filename host [port]

where

filename	Identifies the name of the input and output files. A .m204 string is appended to the filename to identify the input file, and a .lst string is appended to the filename to identify the output file.
host	The name or IP address of the CMS or MVS system on which the Model 204 server is running.
port	The port number for the Model 204 server. If this is not specified, the default port, 204, is used.

m204

The m204 command has the following format:

m204 command syntax

m204 host [port]

where

host	The name or IP address of the CMS or MVS system on which the Model 204 server is running.
port	Tu7 port number for the Model 204 server. If this is not specified, the default port, 204, is used.

The user is prompted for Model 204 input with a >, and output from Model 204 is sent to standard output (normally the user's terminal screen).