Janus IFDIAL Library: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Created page with "The <var class="product">Janus IFDIAL Library</var> provides client/server streams support over TCP/IP. This support is similar to <var class="product">Model 204</var> <var>BATCH...")
 
mNo edit summary
 
(11 intermediate revisions by the same user not shown)
Line 30: Line 30:
<tr><th>C routine </th>
<tr><th>C routine </th>
<th>Description </th></tr>
<th>Description </th></tr>
<tr><th><var>ifdial</var> </th>
<tr><th><var class="camel">ifdial</var> </th>
<td>Initiate a connection to a <var class="product">Model 204</var> server. </td></tr>
<td>Initiate a connection to a <var class="product">Model 204</var> server. </td></tr>
<tr><th><var>iffinish</var> </th>
<tr><th><var class="camel">iffinish</var> </th>
<td>Terminate (hang up) connections to <var class="product">Model 204</var> servers. </td></tr>
<td>Terminate (hang up) connections to <var class="product">Model 204</var> servers. </td></tr>
<tr><th><var>ifhangup</var> </th>
<tr><th><var class="camel">ifhangup</var> </th>
<td>Terminate a connection to a <var class="product">Model 204</var> server. </td></tr>
<td>Terminate a connection to a <var class="product">Model 204</var> server. </td></tr>
<tr><th><var>ifread</var>* </th>
<tr><th><var class="camel">ifread</var>* </th>
<td>Read data sent from <var class="product">Model 204</var> server. </td></tr>
<td>Read data sent from <var class="product">Model 204</var> server. </td></tr>
<tr><th><var>ifwrite</var>* </th>
<tr><th><var class="camel">ifwrite</var>* </th>
<td>Write data on a connection to a <var class="product">Model 204</var> server. </td></tr></table>
<td>Write data on a connection to a <var class="product">Model 204</var> server. </td></tr></table>
   
   
===ifdial===
===ifdial===
<table class="syntaxTable">
<table>
<tr><th>Name</th>
<tr><th>Name</th>
<td>ifdial &mdash; initiate a connection to a <var class="product">Model 204</var> server. </td></tr>
<td>ifdial &mdash; Initiate a connection to a <var class="product">Model 204</var> server. </td></tr>
<tr><th>Synopsis</th>
<tr><th>Synopsis</th>
<td><p class="code">#include <ifdial.h>
<td>
cnum = ifdial(name, port, ibsize, obsize, maxin)
<p class="code">#include <ifdial.h>
<span class="term">cnum</span> = <span class="literal">ifdial</span>(<span class="term">name, port, ibsize, obsize, maxin</span>)
int cnum;
int cnum;
char *name;
char *name;
Line 58: Line 59:
<td>The parameter <var class="term">name</var> specifies either the TCP/IP address or
<td>The parameter <var class="term">name</var> specifies either the TCP/IP address or
the name of the host running the BATCH2 server.
the name of the host running the BATCH2 server.
The parameter
The parameter <var class="term">port</var> specifies the TCP/IP port providing the <var>BATCH2</var> service.
<var class="term">port</var> specifies the TCP/IP port providing the <var>BATCH2</var> service.
If this parameter is 0, the default port of 204 is used.
If this parameter is 0, the default port of 204 is used.
The parameter <var class="term">ibsize</var> indicates the size of the buffer to be used to
The parameter <var class="term">ibsize</var> indicates the size of the buffer to be used to
Line 65: Line 65:
the size of the buffer to be used to send data to the <var class="product">Model 204</var> server.
the size of the buffer to be used to send data to the <var class="product">Model 204</var> server.
<p>
<p>
The default for <var class="term">ibsize</var> is 1024 and the default for
The default for <var class="term">ibsize</var> is 1024, and the default for
<var class="term">obsize</var> is the same as the value of <var class="term">ibsize</var>.
<var class="term">obsize</var> is the same as the value of <var class="term">ibsize</var>.
Note that values for both <var class="term">ibsize</var> and <var class="term">obsize</var>
Note that values for both <var class="term">ibsize</var> and <var class="term">obsize</var>
Line 77: Line 77:
The default for <var class="term">maxin</var> is 256, and it will be forced
The default for <var class="term">maxin</var> is 256, and it will be forced
into the range 80 to 8192 inclusive if outside this range.</p> </td></tr>
into the range 80 to 8192 inclusive if outside this range.</p> </td></tr>
<tr><th>Return values</th>
<tr><th nowrap>Return values</th>
<td> <table>
<td> <table>
<tr><th>>= 0 </th>
<tr><th nowrap>>= 0 </th>
<td>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 <var>ifread</var> and <var>ifwrite</var> calls. There  is no limit to the number of <var>ifdial</var> 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.
<td>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 <var class="camel">ifread</var> and <var class="camel">ifwrite</var> calls. There  is no limit to the number of <var class="camel">ifdial</var> 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.
</td></tr>
</td></tr>
<tr><th>-100 </th>
<tr><th>-100 </th>
Line 93: Line 93:
<td>local failure (TCP/IP service probably lost). </td></tr>
<td>local failure (TCP/IP service probably lost). </td></tr>
<tr><th>-105 </th>
<tr><th>-105 </th>
<td>Error in initial handshake (probably not a <var class="product">Model 204</var> ifdial server). </td></tr>
<td>Error in initial handshake (probably not a <var class="product">Model 204</var> <var>IFDIAL</var> server). </td></tr>
<tr><th>-106 </th>
<tr><th>-106 </th>
<td>Connected to incompatible <var>IFDIAL</var> server. </td></tr></table>
<td>Connected to incompatible <var>IFDIAL</var> server. </td></tr></table>
</table>
</table>
 
===iffinish===
===iffinish===
<table>
<table>
<tr><th>Name </th>
<tr><th>Name </th>
<td><var>iffinish</var> &mdash; terminate (hang up) all connections to <var class="product">Model 204</var> server(s)
<td><var class="camel">iffinish</var> &mdash; Terminate (hang up) all connections to <var class="product">Model 204</var> server(s)
</td></tr>
</td></tr>
<tr><th>Synopsis </th>
<tr><th>Synopsis </th>
<td><p class="code">#include <ifdial.h>
<td>
rc = iffinish();
<p class="code">#include <ifdial.h>
<span class="term">rc</span> = <span class="literal">iffinish</span>();
int rc;
int rc;
</p> </td></tr>
</p> </td></tr>
<tr><th>Description </th>
<tr><th>Description </th>
<td>No further ''ifread'' or ''ifwrite'' are allowed on any connection after an ''iffinish'' </td></tr>
<td>No further <var class="camel">ifread</var> or <var class="camel">ifwrite</var> are allowed on any connection after an <var class="camel">iffinish</var> </td></tr>
<tr><th>Return values </th>
<tr><th>Return values </th>
<td> <table> <tr><th>0 </th>
<td> <table> <tr><th>0 </th>
<td>All connections terminated. </td></tr></table>
<td>All connections terminated. </td></tr></table>
</td></tr></table>
</td></tr></table>
 
===ifhangup===
===ifhangup===
<table>
<table>
<tr><th>Name </th>
<tr><th>Name </th>
<td><var>ifhangup</var> &mdash; terminate (hang up) a connection to a <var class="product">Model 204</var> server
<td><var class="camel">ifhangup</var> &mdash; Terminate (hang up) a connection to a <var class="product">Model 204</var> server </td></tr>
</td></tr>
<tr><th>Synopsis </th>
<tr><th>Synopsis </th>
<td><p class="code">#include <ifdial.h>
<td>
rc = ifhangup(cnum);
<p class="code">#include <ifdial.h>
int rc;
<span class="term">rc</span> = <span class="literal">ifhangup</span>(<span class="term">cnum</span>);
int rc;  
</p> </td></tr>
</p> </td></tr>
<tr><th>Description </th>
<tr><th>Description </th>
<td>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.
<td>The parameter <var class="term">cnum</var> specifies the connection number returned by a previous <var class="camel">ifdial</var>. No further <var class="camel">ifread</var> or <var class="camel">ifwrite</var> calls are allowed on a connection after an <var class="camel">ifhangup</var> for that connection. </td></tr>
</td></tr>
<tr><th nowrap>Return values </th>
<tr><th>Return values </th>
<td> <table>  
<td> <table> <tr><th>0 </th>
<tr><th>0 </th>
<td>Connection terminated. </td></tr> >
<td>Connection terminated. </td></tr>  
<th>100 </th>
<tr><th>100 </th>
<td>Invalid connection number. </td></tr></table>
<td>Invalid connection number. </td></tr></table>
</td></tr></table>
</td></tr></table>
 
===ifread===
===ifread===
<table>
<table>
<tr><th>Name</th>
<tr><th>Name</th>
<td><var>ifread</var>, <var>ifreadl</var> &mdash; read data sent from a <var class="product">Model 204</var> server
<td><var class="camel">ifread</var>, <var class="camel">ifreadl</var> &mdash; Read data sent from a <var class="product">Model 204</var> server
   
   
<var>ifreadVB</var>, <var>ifreadlVB</var> - Wrappers for using <var>ifread</var>, <var>ifreadl</var> from Visual Basic programs
<var class="camel">ifreadVB</var>, <var class="camel">ifreadlVB</var> &mdash; Wrappers for using <var class="camel">ifread</var>, <var class="camel">ifreadl</var> from Visual Basic programs
<tr><th>Synopsis</th>
<tr><th>Synopsis</th>
<td><p class="code">#include <ifdial.h>
<td>
rc = ifread(cnum, data)
<p class="code">#include &#60;ifdial.h>
<span class="term">rc</span> = <span class="literal">ifread</span>(<span class="term">cnum</span>, <span class="term">data</span>)
int rc;
int rc;
int cnum;
int cnum;
char **data;
char **data;
 
rc = ifreadl(cnum, data, len)
<span class="term">rc</span> = <span class="literal">ifreadl</span>(<span class="term">cnum</span>, <span class="term">data</span>, <span class="term">len</span>)
int rc;
int rc;
int cnum;
int cnum;
Line 154: Line 156:
int *len;
int *len;
</p>
</p>
<tr><th>Description</th>
<tr><th>Description</th>
<td>The parameter <var class="term>cnum</var> specifies the number of a connection
<td>The parameter <var class="term">cnum</var> specifies the number of a connection established with a previous <var class="camel">ifdial</var> call.
established with a previous <var>ifdial</var> call.
<p>
<p>
<var class="term"> data</var> is a pointer to a string pointer to be set to point to a blank delimited
<var class="term"> data</var> 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 <var>IFDIAL</var> server. </p>
character string that contains the next output line from the <var>IFDIAL</var> server. </p>
<p>
<p>
<var class="term"> len</var> (<var>ifreadl</var> and <var>ifreadlVB</var> only) is both an input and an output parameter.
<var class="term"> len</var> (<var class="camel">ifreadl</var> and <var class="camel">ifreadlVB</var> only) is both an input and an output parameter.
On input, it's the maximum length to be returned in <var class="term">data</var>
On input, it's the maximum length to be returned in <var class="term">data</var>
(<b>including</b> a terminating null-byte).
(<b>including</b> a terminating null-byte).
Line 167: Line 169:
output value exceeds the input value, the record was truncated.  </p>
output value exceeds the input value, the record was truncated.  </p>
<p>
<p>
In the case of a C-program calling <var>ifreadl</var>, no data are actually
In the case of a C-program calling <var class="camel">ifreadl</var>, no data are actually
moved (the <var class="term">data</var> parameter is set to point to the record in the
moved (the <var class="term">data</var> parameter is set to point to the record in the
internal buffer), so there is no worry about buffer overflow and the input
internal buffer), so there is no worry about buffer overflow and the input
Line 174: Line 176:
However, since it is possible that the returned data contains embedded nulls,
However, since it is possible that the returned data contains embedded nulls,
the returned value in <var class="term">len</var> is useful when <var class="term">strlen</var> won't work. </p></td></tr>
the returned value in <var class="term">len</var> is useful when <var class="term">strlen</var> won't work. </p></td></tr>
<tr><th> Visual Basic issues</th>
<tr><th> Visual Basic issues</th>
<td>Except for <var>ifread</var> and <var>ifreadl</var>, all the <var>IFDIAL</var>
<td>Except for <var class="camel">ifread</var> and <var class="camel">ifreadl</var>, all the <var>IFDIAL</var> 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 <var class="term">name</var> arg to <var class="camel">ifdial</var> and the <var class="term">data</var> arg to <var class="camel">ifwrite</var> and <var class="camel">ifwriteb</var>) <b>must be</b> null-terminated).
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 <var class="term">name</var> arg
to <var>ifdial</var> and the <var class="term">data</var> arg to <var>ifwrite</var>
and <var>ifwriteb</var>) <b>must be</b> null-terminated).
<p>
<p>
However, because of the way VB passes string args, your VB program must
However, because of the way VB passes string args, your VB program must
use the alternate forms <var>ifreadVB</var> and <var>ifreadlVB</var>:</p>
use the alternate forms <var class="camel">ifreadVB</var> and <var class="camel">ifreadlVB</var>:</p>
<p class="code">Dim cnum As Long
<p class="code">Dim cnum As Long
Dim data As String * 256
Dim data As String * 256
Line 198: Line 195:
in the (General)(Declarations) section of your VB project.
in the (General)(Declarations) section of your VB project.
Since the returned string is actually moved into the <var class="term">data</var>
Since the returned string is actually moved into the <var class="term">data</var>
parameter, buffer overflow is possible with the <var>ifreadVB</var>
parameter, buffer overflow is possible with the <var class="camel">ifreadVB</var>
function, but if the <var class="term">length</var> argument is properly set
function, but if the <var class="term">length</var> argument is properly set
on input, the <var>ifreadlVB</var> function is safe in this regard. </p></td></tr>
on input, the <var class="camel">ifreadlVB</var> function is safe in this regard. </p></td></tr>
<tr><th>Return values</th>
<tr><th nowrap>Return values</th>
<td> <table>
<td> <table>
<tr><th>1 </th>
<tr><th>1 </th>
<td><var>ifwrite</var> required to provide data for <var class="product">Model 204</var>. </td></tr>
<td><var class="camel">ifwrite</var> required to provide data for <var class="product">Model 204</var>. </td></tr>
<tr><th>2 </th>
<tr><th>2 </th>
<td><var>ifread</var> required to receive data from <var class="product">Model 204</var>. </td></tr>
<td><var class="camel">ifread</var> required to receive data from <var class="product">Model 204</var>. </td></tr>
<tr><th>12 </th>
<tr><th>12 </th>
<td>No data to receive. <var>ifwrite</var> required to provide data for <var class="product">Model 204</var>. <var class="term">**data</var> is set to 0 in this case. </td></tr>
<td>No data to receive. <var class="camel">ifwrite</var> required to provide data for <var class="product">Model 204</var>. <var class="term">**data</var> is set to 0 in this case. </td></tr>
<tr><th>100 </th>
<tr><th>100 </th>
<td>Invalid connection number. </td></tr>
<td>Invalid connection number. </td></tr>
Line 218: Line 215:
<table>
<table>
<tr><th>Name</th>
<tr><th>Name</th>
<td><var>ifwrite</var>, <var>ifwriteb</var>, <var>ifwritel</var>, <var>ifwritbl</var> &mdash; write
<td><var class="camel">ifwrite</var>, <var class="camel">ifwriteb</var>, <var class="camel">ifwritel</var>, <var class="camel">ifwritbl</var> &mdash; Write data on a connection to a <var class="product">Model 204</var> server
data on a connection to a <var class="product">Model 204</var> server
<tr><th>Synopsis</th>
<tr><th>Synopsis</th>
<td><p class="code">#include <ifdial.h>
<td>
rc = ifwrite(cnum, data)
<p class="code">#include <ifdial.h>
<span class="term">rc</span> = <span class="literal">ifwrite</span>(<span class="term">cnum</span>, <span class="term">data</span>)
int rc;
int rc;
int cnum;
int cnum;
char *data;
char *data;
   
   
rc = ifwritel(cnum, data, len)
<span class="term">rc</span> = <span class="literal">ifwritel</span>(<span class="term">cnum</span>, <span class="term">data</span>, <span class="term">len</span>)
int rc;
int rc;
int cnum;
int cnum;
Line 233: Line 230:
int len;
int len;
   
   
rc = ifwriteb(cnum, data)
<span class="term">rc</span> = <span class="literal">ifwriteb</span>(<span class="term">cnum</span>, <span class="term">data</span>)
int rc;
int rc;
int cnum;
int cnum;
char *data;
char *data;
   
   
rc = ifwritbl(cnum, data, len)
<span class="term">rc</span> = <span class="literal">ifwritbl</span>(<span class="term">cnum</span>, <span class="term">data</span>, <span class="term">len</span>)
int rc;
int rc;
int cnum;
int cnum;
Line 244: Line 241:
int len;
int len;
</p>
</p>
<tr><th>Description</th>
<tr><th>Description</th>
<td><var>ifwrite</var>, <var>ifwriteb</var>, <var>ifwriteb</var> and
<td><var class="camel">ifwrite</var>, <var class="camel">ifwriteb</var>, <var class="camel">ifwriteb</var> and <var class="camel">ifwritbl</var> are used to send data to a <var class="product">Model 204</var> server.
<var>ifwritbl</var> are used to send data to a <var class="product">Model 204</var> server.
   
   
<var>ifwrite</var> and <var>ifwriteb</var> must be passed a null
<var class="camel">ifwrite</var> and <var class="camel">ifwriteb</var> must be passed a null
terminated string pointer, while <var>ifwritel</var> and
terminated string pointer, while <var class="camel">ifwritel</var> and
<var>ifwritbl</var> must be passed a string pointer and the length of the string.
<var class="camel">ifwritbl</var> must be passed a string pointer and the length of the string.
   
   
<var>ifwrite</var> and <var>ifwritel</var> will force any data in the
<var class="camel">ifwrite</var> and <var class="camel">ifwritel</var> will force any data in the
current <var>ifwrite</var> buffer to be sent immediately to the <var class="product">Model 204</var>.
current <var class="camel">ifwrite</var> buffer to be sent immediately to the <var class="product">Model 204</var>
server, and then wait for either data from the <var class="product">Model 204</var> server or a
server, and then wait for either data from the <var class="product">Model 204</var> server or a
response indicating that more <var>ifwrite</var> data is required.
response indicating that more <var class="camel">ifwrite</var> data is required.
   
   
<var>ifwriteb</var> and <var>ifwritbl</var> will buffer the writes so
<var class="camel">ifwriteb</var> and <var class="camel">ifwritbl</var> will buffer the writes so
that a single TCP/IP send can be used to send multiple lines to the
that a single TCP/IP send can be used to send multiple lines to the
<var class="product">Model 204</var> server, and they will not wait to determine whether an
<var class="product">Model 204</var> server, and they will not wait to determine whether an
<var>ifread</var> or an <var>ifwrite</var> is required next.
<var class="camel">ifread</var> or an <var class="camel">ifwrite</var> is required next.
Use of <var>ifwriteb</var> or <var>ifwritbl</var> can result in a return code
Use of <var class="camel">ifwriteb</var> or <var class="camel">ifwritbl</var> can result in a return code
of 12 indicating that the data to be sent to the <var class="product">Model 204</var> server was
of 12 indicating that the data to be sent to the <var class="product">Model 204</var> server was
not accepted.
not accepted.
   
   
This return code is also possible with <var>ifwrite</var> or
This return code is also possible with <var class="camel">ifwrite</var> or
<var>ifwritel</var> if an <var>ifwrite</var> is issued without waiting
<var class="camel">ifwritel</var> if an <var class="camel">ifwrite</var> is issued without waiting
for a return code of from <var>ifread</var>.
for a return code of from <var class="camel">ifread</var>.
   
   
In either case, some form of <var>ifwrite</var> must be called again
In either case, some form of <var class="camel">ifwrite</var> must be called again
with the original data after one or more <var>ifread</var> calls are
with the original data after one or more <var class="camel">ifread</var> calls are
made whenever a return code of 12 is received from an <var>ifwrite</var> function.
made whenever a return code of 12 is received from an <var class="camel">ifwrite</var> function.
For maximum throughput, issue <var>ifwriteb</var> or <var>ifwritbl</var> calls until a value of 12 is
For maximum throughput, issue <var class="camel">ifwriteb</var> or <var class="camel">ifwritbl</var> calls until a value of 12 is
returned at which point issue an <var>ifread</var> and then retry the <var>ifwrite</var>.
returned at which point issue an <var class="camel">ifread</var> and then retry the <var class="camel">ifwrite</var>.
   
   
The parameter <var class="term">cnum</var> specifies the number of a connection
The parameter <var class="term">cnum</var> specifies the number of a connection
established with a previous <var>ifdial</var> call.
established with a previous <var class="camel">ifdial</var> call.
<var class="term">data</var> is the data to be sent to the <var class="product">Model 204</var> server.
<var class="term">data</var> is the data to be sent to the <var class="product">Model 204</var> server.
<var class="term">len</var> is the length of the data to be sent.
<var class="term">len</var> is the length of the data to be sent.
<tr><th>Return values</th>
<tr><th nowrap>Return values</th>
<td> <table>
<td> <table>
<tr><th>1 </th>
<tr><th>1 </th>
<td><var>ifwrite</var> is required to provide data for <var class="product">Model 204</var>. For buffered ifwrites (<var>ifwriteb</var> and <var>ifwritbl</var>), this return code might be followed by a return code 12 on an immediately following <var>ifwrite</var> is required to provide data for <var class="product">Model 204</var>. </td></tr>
<td><var class="camel">ifwrite</var> is required to provide data for <var class="product">Model 204</var>. For buffered ifwrites (<var class="camel">ifwriteb</var> and <var class="camel">ifwritbl</var>), this return code might be followed by a return code 12 on an immediately following <var class="camel">ifwrite</var>. </td></tr>
<tr><th>2 </th>
<tr><th>2 </th>
<td><var>ifread</var> data is available from <var class="product">Model 204</var>. This will never be returned by <var>ifwriteb</var>. </td></tr>
<td><var class="camel">ifread</var> data is available from <var class="product">Model 204</var>. This will never be returned by <var class="camel">ifwriteb</var>. </td></tr>
<tr><th>12 </th>
<tr><th>12 </th>
<td><var>ifwrite</var> not accepted, data must be received from <var class="product">Model 204</var> with <var>ifread</var>. </td></tr>
<td><var class="camel">ifwrite</var> not accepted, data must be received from <var class="product">Model 204</var> with <var class="camel">ifread</var>. </td></tr>
<tr><th>100 </th>
<tr><th>100 </th>
<td>Invalid Connection number. </td></tr>
<td>Invalid Connection number. </td></tr>
Line 292: Line 289:
<td>Connection lost. </td></tr></table>
<td>Connection lost. </td></tr></table>
</table>
</table>
 
==Workstation utilities==
==Workstation utilities==
Several workstation utilities are provided with the <var class="product">Janus IFDIAL Library</var>
Several workstation utilities are provided with the <var class="product">Janus IFDIAL Library</var>
Line 298: Line 295:
These utilities are ready-to-run, precompiled C programs:
These utilities are ready-to-run, precompiled C programs:
<table>
<table>
<tr><th><var>batch2</var> </th>
<tr><th><var class="camel">batch2</var> </th>
<td>sends data from an input file to a <var class="product">Model 204</var> server and places returned data into an output file. </td></tr>
<td>sends data from an input file to a <var class="product">Model 204</var> server and places returned data into an output file. </td></tr>
<tr><th><var>m204</var> </th>
<tr><th><var class="camel">m204</var> </th>
<td>initiates a conversation with a <var class="product">Model 204</var> server, prompting for input data from the terminal as required and sending the <var class="product">Model 204</var> output to standard output. </td></tr></table>
<td>initiates a conversation with a <var class="product">Model 204</var> server, prompting for input data from the terminal as required and sending the <var class="product">Model 204</var> output to standard output. </td></tr></table>
   
   
Line 306: Line 303:
   
   
===batch2===
===batch2===
The <var>batch2</var> command has the following format:
The <var class="camel">batch2</var> command has the following format:
   
   
==batch2 command syntax==
====batch2 command syntax====
<p class="code">batch2 filename host [ port ]
<p class="syntax"><span class="literal">batch2</span> <span class="term">filename host</span> <span class="squareb">[</span><span class="term">port</span><span class="squareb">]</span>
</p>
</p>
where
where
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>filename </th>
<tr><th>filename </th>
<td>Identifies the name of the input and output files. An <code>.m204</code> string is appended to the filename to identify the input file, and a <code>.lst</code> string is appended to the filename to identify the output file. </td></tr>
<td>Identifies the name of the input and output files. A <code>.m204</code> string is appended to the filename to identify the input file, and a <code>.lst</code> string is appended to the filename to identify the output file. </td></tr>
<tr><th>host </th>
<tr><th>host </th>
<td>The name or IP address of the CMS or MVS system on which the <var class="product">Model 204</var> server is running. </td></tr>
<td>The name or IP address of the CMS or MVS system on which the <var class="product">Model 204</var> server is running. </td></tr>
Line 321: Line 318:
   
   
===m204===
===m204===
The <var>m204</var> command has the following format:
The <var class="camel">m204</var> command has the following format:
   
   
==m204 command syntax==
====m204 command syntax====
<p class="syntax">m204 host [ port ]
<p class="syntax"><span class="literal">m204</span> <span class="term">host</span> <span class="squareb">[</span><span class="term">port</span><span class="squareb">]</span>
</p>
</p>
where
where
Line 334: Line 331:
   
   
The user is prompted for <var class="product">Model 204</var> input with a <code>></code>, and output from <var class="product">Model 204</var> is sent to standard output (normally the user's terminal screen).
The user is prompted for <var class="product">Model 204</var> input with a <code>></code>, and output from <var class="product">Model 204</var> is sent to standard output (normally the user's terminal screen).
[[Category:Janus TCP/IP Base]]

Latest revision as of 15:33, 16 March 2012

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