ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qsygeteimconnectinfo.htm

561 lines
21 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>QsyGetEIMConnectInfo()--Get EIM Connect Information</title>
<!-- Begin header records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Created by Carol Budnik on 17 July 2001 -->
<!-- End header records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!--Java sync-link-->
<script type="text/javascript" language="javascript" src="../rzahg/synch.js">
</script>
<!-- ============================================================== -->
<!-- -->
<!-- -->
<!-- ============================================================== -->
<h2>QsyGetEIMConnectInfo()--Get EIM
Connect Information</h2>
<!-- ============================================================== -->
<!-- -->
<!-- S Y N T A X / P A R M T A B L E -->
<!-- -->
<!-- ============================================================== -->
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;qsyeimapi.h&gt;
#include &lt;eim.h&gt;
int QsyGetEIMConnectInfo(int <em>lengthOfConnectInfo</em>,
EimList * <em>connectInfo</em>,
EimRc * <em>eimrc</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSYEIMAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<p>The <strong>QsyGetEIMConnectInfo()</strong> function returns the connection
information that will be used by the operating system when it needs to
connect to the EIM domain that is configured for this system or for the master
system.</p>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== -->
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
<!-- Instead, use the commented out coding below to indicate NONE. -->
<h3>Authorities and Locks</h3>
<!-- Use this if there are no authorities and locks. -->
<p>None.</p>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<h3>Parameters</h3>
<dl><!-- ============================================================== -->
<!-- lengthOfConnectInfo -->
<!-- ============================================================== -->
<dt><strong>lengthOfConnectInfo</strong></dt>
<dd>(Input)
<p>The number of bytes provided by the caller for the connection information
parameter. The minimum size required is 20 bytes. The API will return the
number of bytes available for all of the connection information and as much
data as space has been provided.</p>
<!-- ============================================================== -->
<!-- connectInfo -->
<!-- ============================================================== -->
</dd>
<dt><strong>connectInfo</strong></dt>
<dd>(Output)
<p>A pointer to the data to be returned.</p>
<p>The EimList structure contains information about the returned data. The data
returned is a linked list of QsyEimConnectInfo structures. firstEntry is used
to get to the first QsyEimConnectInfo structure in the linked list.</p>
<!-- ============================================================== -->
<!-- -->
<!-- EimList -->
<!-- ============================================================== -->
<p>EimList structure:</p>
<pre>
typedef struct EimList
{
unsigned int bytesReturned; /* Number of bytes actually returned
by the API */
unsigned int bytesAvailable; /* Number of bytes of available data
that could have been returned by
the API */
unsigned int entriesReturned; /* Number of entries actually
returned by the API */
unsigned int entriesAvailable; /* Number of entries available to be
returned by the API */
unsigned int firstEntry; /* Displacement to the first linked
list entry. This byte offset is
relative to the start of the
EimList structure. */
} EimList;
</pre>
<!-- ============================================================== -->
<!-- QsyEimConnectInfo -->
<!-- ============================================================== -->
<p>QsyEimConnectInfo structure:</p>
<pre>
#pragma enumsize(4)
typedef struct QsyEimConnectInfo
{
unsigned int nextEntry;
/* Displacement to next entry.
This byte offset is relative
to the start of this structure. */
enum QsyEimConnectSystem connectSystem;
/* System connection info is for -
configured (0) or master (1). */
enum QsyEimConnectType connectType;
/* Connection type - simple (0),
kerberos with keytab file (1), or
kerberos with password (2) */
union {
struct {
enum EimPasswordProtect protect;
/* Protect value - no protect (0),
cram_md5 (1), or optional
cram_md5 (2) */
EimListData bindDN;
} simpleConnect; /* Protect value and bind DN, if
connectType=QSY_EIM_SIMPLE (0) */
struct {
EimListData kerberosPrincipal;
EimListData kerberosRealm;
} kerberosPwd; /* Kerberos information, if
connectType=QSY_KERBEROS_PWD (1) */
struct {
EimListData kerberosKeyTab;
EimListData kerberosPrincipal;
EimListData kerberosRealm;
} kerberosKeyTab; /* Kerberos information, if
connectType=
QSY_KERBEROS_KEYTAB (2) */
} connectInfo;
} QsyEimConnectInfo;
</pre>
<!-- ============================================================== -->
<!-- EimListData -->
<!-- ============================================================== -->
<p>EimListData structure:</p>
<pre>
typedef struct EimListData
{
unsigned int length; /* Length of data */
unsigned int disp; /* Displacement to data. This byte
offset is relative to the start of
the parent structure; that is, the
structure containing this
structure */
} EimListData;
</pre>
</dd>
<!-- ============================================================== -->
<!-- eimrc -->
<!-- ============================================================== -->
<dt><strong>eimrc</strong></dt>
<dd>(Input/Output)
<p>The structure in which to return error code information. If the return value
is not 0, eimrc is set with additional information. This parameter may be NULL.
For the format of the structure, see <a href="eimrc.htm">EimRC--EIM Return Code
Parameter</a>.</p>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- R E T U R N V A L U E -->
<!-- -->
<!-- ============================================================== -->
<h3>Return Value</h3>
<p>The return value from the API. Following each return value is the list of
possible values for the messageCatalogMessageID field in the eimrc parameter
for that value.</p>
<dl><!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<dt><strong>0</strong></dt>
<dd>Request was successful.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA (3028)</strong></dt>
<dd>eimrc is not valid.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBUSY -->
<!-- ============================================================== -->
<dt><strong>EBUSY (3029)</strong></dt>
<dd>Unable to allocate internal system object.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOLOCK (26)</em></td>
<td align="left" valign="top">Unable to allocate internal system object.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ECONVERT -->
<!-- ============================================================== -->
<dt><strong>ECONVERT (3490)</strong></dt>
<dd>Data conversion error.<br>
<br>
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em>EIMERR_DATA_CONVERSION (13)</em></td>
<td align="left" valign="top">Error occurred when converting data between code
pages.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EINVAL -->
<!-- ============================================================== -->
<dt><strong>EINVAL (3021)</strong></dt>
<dd>Input parameter was not valid.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_EIMLIST_SIZE (16)</em></td>
<td align="left" valign="top">Length of EimList is not valid. EimList must be
at least 20 bytes in length.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PARM_REQ (34)</em></td>
<td align="left" valign="top">Missing required parameter. Please check API
documentation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PTR_INVAL (35)</em></td>
<td align="left" valign="top">Pointer parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_SPACE (41)</em></td>
<td align="left" valign="top">Unexpected error accessing parameter.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOMEM -->
<!-- ============================================================== -->
<dt><strong>ENOMEM (3460)</strong></dt>
<dd>Unable to allocate required space.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOMEM (27)</em></td>
<td align="left" valign="top">No memory available. Unable to allocate required
space.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN (3474)</strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_UNKNOWN (44)</em></td>
<td align="left" valign="top">Unknown error or unknown system state.</td>
</tr>
</table>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- U S A G E N O T E S -->
<!-- -->
<!-- ============================================================== -->
<!-- ============================================================== -->
<!-- -->
<!-- R E L A T E D I N F O R M A T I O N -->
<!-- -->
<!-- ============================================================== -->
<h3>Related Information</h3>
<ul>
<li><a href="qsyseteimconnectinfo.htm">QsySetEIMConnectInfo()</a>--Set EIM
Connect Information<br>
<br>
</li>
</ul>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example will get connection information used by the operating
system.</p>
<pre>
#include &lt;eim.h&gt;
#include &lt;qsyeimapi.h&gt;
void printListResults(EimList * list)
{
int i;
QsyEimConnectInfo * entry;
char * data;
int dataLength;
printf("\n___________");
printf("\nBytes Returned = %d", list-&gt;bytesReturned);
printf("\nBytes Available = %d", list-&gt;bytesAvailable);
printf("\nEntries Returned = %d", list-&gt;entriesReturned);
printf("\nEntries Available = %d", list-&gt;entriesAvailable);
entry = (QsyEimConnectInfo *)((char *)list + list-&gt;firstEntry);
for (i = 0; i &lt; list-&gt;entriesReturned; i++)
{
printf("\n");
printf("\n***** Entry %d ***** ",i+1);
printf("\nConnect system : %d ",entry-&gt;connectSystem );
printf("\nConnect type : %d ",entry-&gt;connectType );
switch (entry-&gt;connectType) /* Determine connect type. */
{
case QSY_EIM_SIMPLE:
{
printf("\nProtect type : %d ",
entry-&gt;connectInfo.simpleConnect.protect );
data = ((char *)entry +
entry-&gt;connectInfo.simpleConnect.bindDN.disp );
dataLength =
entry-&gt;connectInfo.simpleConnect.bindDN.length;
printf("\n%s : ","Bind DN");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
break;
}
case QSY_EIM_KERBEROS_KEYTAB:
{
/* Print out the keytab file name */
data = ((char *)entry + entry-&gt;
connectInfo.kerberosKeyTab.kerberosKeyTab.disp );
dataLength =
entry-&gt;connectInfo.kerberosKeyTab.kerberosKeyTab.length;
printf("\n%s : ","Keytab file name");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
/* Print out the principal */
data = ((char *)entry + entry-&gt;
connectInfo.kerberosKeyTab.kerberosPrincipal.disp );
dataLength =
entry-&gt;connectInfo.kerberosKeyTab.kerberosPrincipal.length;
printf("\n%s : ","Kerberos principal");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
/* Print out the realm */
data = ((char *)entry + entry-&gt;
connectInfo.kerberosKeyTab.kerberosRealm.disp );
dataLength =
entry-&gt;connectInfo.kerberosKeyTab.kerberosRealm.length;
printf("\n%s : ","Kerberos realm");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
break;
}
case QSY_EIM_KERBEROS_PWD:
{
/* Print out the principal */
data = ((char *)entry + entry-&gt;
connectInfo.kerberosPwd.kerberosPrincipal.disp );
dataLength =
entry-&gt;connectInfo.kerberosPwd.kerberosPrincipal.length;
printf("\n%s : ","Kerberos principal");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
/* Print out the realm */
data = ((char *)entry + entry-&gt;
connectInfo.kerberosPwd.kerberosRealm.disp );
dataLength =
entry-&gt;connectInfo.kerberosPwd.kerberosRealm.length;
printf("\n%s : ","Kerberos realm");
if (dataLength &gt; 0)
printf("%.*s",dataLength, data);
else
printf("Not found.");
break;
}
} /* end determine connect type. */
/* advance to next entry */
entry = (QsyEimConnectInfo *)((char *)entry + entry-&gt;nextEntry);
}
printf("\n");
}
int main(int argc, char *argv[])
{
int rc;
char eimerr[100];
EimRC *err;
char listData[5000];
EimList * list = (EimList * ) listData;
err = (EimRC *)eimerr;
err-&gt;memoryProvidedByCaller = 100;
if (0 != (rc = QsyGetEIMConnectInfo(5000,
list,
err)))
{
printf("Get connection information error = %d", rc);
return -1;
}
printListResults(list);
return 0;
}
</pre>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- F O O T E R -->
<!-- -->
<!-- ============================================================== -->
<hr>
API introduced: V5R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>