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