friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qxdaconn.htm

1066 lines
33 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>Connect to EDRS Server (QxdaConnectEDRS) API</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. -->
<!-- File SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- This file has undergone html cleanup on 9/20/01 by JET -->
<!-- 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Connect to EDRS Server (QxdaConnectEDRS) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Input structure</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Input structure format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Receiver variable</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Receiver variable format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Service Program: QXDAEDRS<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usage_notes">Usage
Notes</a><br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Connect to EDRS Server (QxdaConnectEDRS) API is used to initiate a
connection between the local system (requesting system), and a server system.
The connection can be local, where the server system is the local system. For
non-local connections, a corresponding <strong>shadow</strong> job is started
on the server system. If the input structure format used is the basic input
structure (CDBI0100), then the shadow job is swapped to run under the same user
profile, using the same job description, coded character set identifier
(CCSID), and job priority as the client system job. The user profile, user
password, and job description must be identical on both systems for a
successful connection. If the input structure format used is CDBI0200, then the
shadow job will run under the specified user profile name. It will use the
specified user profile's associated job description and job priority. The CCSID
will be set to the CCSID of the server job field in the input structure.</p>
<p>For TCP/IP or UNIX domain sockets connections, a controller job must be
started on the server system before calling the QxdaConnectEDRS API on the
client system. The controller job can be started by using the STRTCPSVR
command, specifying the *EDRSQL server.</p>
<p>If a TCP/IP or UNIX domain socket connection is being requested, the
password level (QPWDLVL system value) of the server system must be compatible
with the requesting server. If the password level is 0 or 1, or is a pre-V5R1
system, then the requesting system should be 0 or 1. Likewise, if the V5R1
server system's password level is 2 or 3, the V5R1 requesting system should
also be set to 2 or 3. Failure to coordinate the password level in this fashion
will prevent a successful connection, resulting in the CPI2A5A message.</p>
<p>Note that the CDBI0200 format cannot be used when the connection type is 'O'
(Opticonnect). CDBI0200 is intended for use only with TCP/IP and UNIX socket
connections. For additional restrictions that apply to OptiConnect connections,
see the <a href="comm7.htm">OptiConnect API</a> documentation.</p>
<p>The connection handle returned by this API is valid only in the same job and
activation group in which it was generated. A connection cannot span multiple
jobs or activation groups.</p>
<p>If a relational database (RDB)
name is specified for either the CDBI0100 or CDBI0200 format, it must be blank
padded to 18 characters, the maximum length of an RDB name. If the server
system does not have any active independent ASPs, the only RDB that can be
connected is the *LOCAL RDB. All other RDB names will cause the CPFB752 message
to be sent to the caller. The *LOCAL RDB can be determined by viewing the
'remote location' column when executing the WRKRDBDIRE command.</p>
<p>If XA commitment control is specified for either the CDBI0100 or CDBI0200 format, the Transaction Manager Information field must be blank padded to 10 characters, the maximum length, and a Lock Timeout Value should be given. Specifying a *LOCAL connection type along with a *XA commit scope value will cause the CPFB754 with reason code 2 message to be sent to the caller. Likewise, specifying a N commitment control value along with a *XA commit scope value will cause the CPFB754 with reason code 3 message to be sent to the caller. XA commitment control can only be specified over TCP/IP, UNIX domain sockets, or OPTI-CONNECT. The QxdaXA* API's use the <em>connection</em> as the XA thread of control, opposed to the XA API's, which use the <em>thread</em> as the XA thread of control.</p>
<p><img src="delta.gif" alt="Start of change">If thread safety has been specified, prior to the CONNECT (via the QxdaSetOptions API),
all threads must specify connection type U or connection type T.<img src="deltaend.gif" alt="End of change"> </p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Input structure</strong></dt>
<dd>INPUT; CHAR(*)
<p>The structure in which to pass information about the connection. For the
format of this parameter, see the <a href="#HDRI0100">CDBI0100 Format</a> or the <a href="#HDRI0200">CDBI0200 Format</a>.</p>
</dd>
<dt><strong>Input structure format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the input structure template being used. The possible value
is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CDBI0100</em></td>
<td align="left" valign="top">Basic input structure</td>
</tr>
<tr>
<td align="left" valign="top"><em>CDBI0200</em></td>
<td align="left" valign="top">Basic input structure with user profile and
password fields</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The structure in which to return information about the connection. For the
format of this parameter, see <a href="#HDRO0100">CDBO0100 Format</a>.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of bytes that the calling program provides for the receiver
variable data.</p>
</dd>
<dt><strong>Receiver variable format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the receiver variable template being used. The possible value
is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CDBO0100</em></td>
<td align="left" valign="top">Basic receiver variable</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRI0100">CDBI0100 Format</a></h3>
<p>The following table shows the information to pass in the CDBI0100 format.
For more details about the fields in this table, see <a href="#HDRFIELD3">Field
Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Connection type</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Commitment control</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Commit scope</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow job suspension</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="center" valign="top">D</td>
<td align="left" valign="top">CHAR(256)</td>
<td align="left" valign="top">Server system name</td>
</tr>
<tr>
<td align="center" valign="top">269</td>
<td align="center" valign="top">10D</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Relational database (RDB) specified</td>
</tr>
<tr>
<td align="center" valign="top">270</td>
<td align="center" valign="top">10E</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">SQL hexadecimal constants</td>
</tr>
<tr>
<td align="center" valign="top">271</td>
<td align="center" valign="top">10F</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">272</td>
<td align="center" valign="top">110</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">SQLDA cache size</td>
</tr>
<tr>
<td align="center" valign="top">276</td>
<td align="center" valign="top">114</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">280</td>
<td align="center" valign="top">118</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">284</td>
<td align="center" valign="top">11C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to job-suspension user data</td>
</tr>
<tr>
<td align="center" valign="top">288</td>
<td align="center" valign="top">120</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of job-suspension user data</td>
</tr>
<tr>
<td align="center" valign="top">292</td>
<td align="center" valign="top">124</td>
<td align="left" valign="top">CHAR(18)</td>
<td align="left" valign="top">Relational database (RDB) name</td>
</tr>
<tr>
<td align="center" valign="top">310</td>
<td align="center" valign="top">136</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Transaction manager information</td>
</tr>
<tr>
<td align="center" valign="top">320</td>
<td align="center" valign="top">140</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Lock timeout value</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Job-suspension user data</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRI0200">CDBI0200 Format</a></h3>
<p>The following table shows the information to pass in the CDBI0200 format.
For more details about the fields in this table, see <a href="#HDRFIELD3">Field
Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Connection type</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Commitment control</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Commit scope</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow job suspension</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="center" valign="top">D</td>
<td align="left" valign="top">CHAR(256)</td>
<td align="left" valign="top">Server system name</td>
</tr>
<tr>
<td align="center" valign="top">269</td>
<td align="center" valign="top">10D</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Convert Endian Data</td>
</tr>
<tr>
<td align="center" valign="top">270</td>
<td align="center" valign="top">10E</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Relational database (RDB) specified</td>
</tr>
<tr>
<td align="center" valign="top">271</td>
<td align="center" valign="top">10F</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">SQL hexadecimal constants</td>
</tr>
<tr>
<td align="center" valign="top">272</td>
<td align="center" valign="top">110</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">SQLDA cache size</td>
</tr>
<tr>
<td align="center" valign="top">276</td>
<td align="center" valign="top">114</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">280</td>
<td align="center" valign="top">118</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">284</td>
<td align="center" valign="top">11C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to job-suspension user data</td>
</tr>
<tr>
<td align="center" valign="top">288</td>
<td align="center" valign="top">120</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of job-suspension user data</td>
</tr>
<tr>
<td align="center" valign="top">292</td>
<td align="center" valign="top">124</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to user profile data</td>
</tr>
<tr>
<td align="center" valign="top">296</td>
<td align="center" valign="top">128</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of user profile data</td>
</tr>
<tr>
<td align="center" valign="top">300</td>
<td align="center" valign="top">12C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to password associated with user
profile</td>
</tr>
<tr>
<td align="center" valign="top">304</td>
<td align="center" valign="top">130</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of password associated with user
profile</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID of the server job</td>
</tr>
<tr>
<td align="center" valign="top">312</td>
<td align="center" valign="top">138</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID of the password</td>
</tr>
<tr>
<td align="center" valign="top">316</td>
<td align="center" valign="top">13C</td>
<td align="left" valign="top">CHAR(18)</td>
<td align="left" valign="top">Relational database (RDB) name</td>
</tr>
<tr>
<td align="center" valign="top">334</td>
<td align="center" valign="top">14E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Transaction manager information</td>
</tr>
<tr>
<td align="center" valign="top">344</td>
<td align="center" valign="top">158</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Lock timeout value</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Job-associated user data</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Job-suspension user data</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">User profile data</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Password associated with user profile data</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRO0100">CDBO0100 Format</a></h3>
<p>The following table shows the information returned in the CDBO0100 format.
For more details about the fields in the following table, see <a href=
"#HDRFIELD3">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Connection handle</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Server job name</td>
</tr>
<tr>
<td align="center" valign="top">22</td>
<td align="center" valign="top">16</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Server job user name</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Server job number</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Connection type used</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRFIELD3">Field Descriptions</a></h3>
<p><strong>Allow job suspension.</strong> Whether or not to allow this job to
be suspended or switched to run to a backup server if there is a server system
failure or backup. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">This job may be suspended or switched for server
system failures or backups. If this option is specified with a remote
connection type and the server system has been switched to a backup by the
QxdaBlockEDRS API, the connection will be made to the backup system.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">This job should not be suspended or
switched.</td>
</tr>
</table>
<p><strong>Bytes available.</strong> The length of the information available to
the API to return, in bytes.</p>
<p><strong>Bytes returned.</strong> The actual length of information returned
to the caller of the API.</p>
<p><strong>CCSID of password.</strong> The CCSID of the password. The possible
values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the default CCSID for the current
process.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1 - 65533</em></td>
<td align="left" valign="top">Valid range of CCSID values.</td>
</tr>
</table>
<p><strong>CCSID of server job</strong> The CCSID of the job on the server
system. The possible values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the default CCSID for the current
process.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1 - 65533</em></td>
<td align="left" valign="top">Valid range of CCSID values.</td>
</tr>
</table>
<p><strong>Commit scope.</strong> The commitment definition scope.
<img src="delta.gif" alt="Start of change">A value must be specified regardless of the commit level.<img src="deltaend.gif" alt="End of change">
The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*JOB</em></td>
<td align="left" valign="top">The job-level commitment definition is started
for the job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ACTGRP</em></td>
<td align="left" valign="top">An activation-group-level commitment definition
is started for the activation group associated with the program issuing the
command. This value is allowed for connection type L only. To simulate
activation group commit scope in a remote environment, multiple remote
connections must be used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*XA</em></td>
<td align="left" valign="top">The XA-level commitment definition is started
for the job. This value is not allowed with connection type L and/or commitment control N.</td>
</tr>
</table>
<p><strong>Commitment control.</strong> The commit level to be used. The
possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>C</em></td>
<td align="left" valign="top">*CHG: Every record read for update (for a file
opened under commitment control) is locked. If a record is changed, added, or
deleted, that record remains locked until the transaction is committed or
rolled back. Records that are accessed for update operations, but are released
without being changed, are unlocked.</td>
</tr>
<tr>
<td align="left" valign="top"><em>S</em></td>
<td align="left" valign="top">*CS: Every record accessed for files opened under
commitment control is locked. A record that is read, but not changed or
deleted, is unlocked when a different record is read. Records that are changed,
added, or deleted are locked until the transaction is committed or rolled
back.</td>
</tr>
<tr>
<td align="left" valign="top"><em>A</em></td>
<td align="left" valign="top">*ALL: Every record accessed for files opened
under commitment control is locked until the transaction is committed or rolled
back.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">*NONE: Commitment control should not be
started.</td>
</tr>
</table>
<p><strong>Connection type.</strong> The communications type to use for the
connection. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>L</em></td>
<td align="left" valign="top">Local connection: Only one local connection per
job may be open at a time. If a second local connection is attempted in the
job, the connection actually will be made over UNIX domain sockets.</td>
</tr>
<tr>
<td align="left" valign="top"><em>O</em></td>
<td align="left" valign="top">OptiConnect</td>
</tr>
<tr>
<td align="left" valign="top"><em>T</em></td>
<td align="left" valign="top">TCP/IP sockets</td>
</tr>
<tr>
<td align="left" valign="top"><em>U</em></td>
<td align="left" valign="top">UNIX domain sockets. <img src="delta.gif" alt="Start of change">If thread safety is on, each thread
must use connection type U or connection type T.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<p><strong>Connection type used.</strong> The connection type that was actually
used for the connection.</p>
<p><strong>Connection handle.</strong> A unique handle number for the
connection. The maximum number of connections per job that may be open at one
time is 30.</p>
<p><strong>Convert endian data.</strong> Whether integer data should be
converted from i5/OS big-endian format to Windows PC little-endian format. The
field is only used by the Client Access Express version of this API when
returning data into the SQL Descriptor Area (SQLDA). The possible values
are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not convert endian data. If the API is called
from an i5/OS application, you must code '0' for this field.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Convert endian integer data from big-endian to
little-endian.</td>
</tr>
</table>
<p><strong>Job-associated user data.</strong> Data to associate with the server
job that allows the job to be found using the QxdaFindJob API.</p>
<p><strong>Job-suspension user data.</strong> Data associated with the current
job to allow the job to be suspended independent of an entire system
suspension.</p>
<p><strong>Length of job-associated user data.</strong> The length of the
job-associated data passed.</p>
<p><strong>Length of job-suspension user data.</strong> The length of the
job-suspension user data passed. This parameter must be set to 0 if the allow
job suspension parameter is N.</p>
<p><strong>Length of password associated with user profile.</strong> The length
of the user profile password passed. The maximum length for the password is 512
bytes. Passwords can have a maximum of 128 characters. 512 bytes can
accommodate 128 double bytes characters with a shift-in, shift-out pairing.</p>
<p><strong>Length of user profile data.</strong> The length of the user profile
data passed.</p>
<p><strong>Lock timeout value.</strong> Timeout value for locks in seconds.</p>
<p><strong>Offset to job-associated user data.</strong> The offset from the
beginning of the input structure to the job-associated user data in the input
structure, in bytes.</p>
<p><strong>Offset to job-suspension user data.</strong> The offset from the
beginning of the input structure to the job-suspension user data in the input
structure, in bytes. This value must be 0 if the allow job suspension parameter
is set to N.</p>
<p><strong>Offset to password associated with user profile.</strong> The offset
from the beginning of the input structure to the password associated with the
user profile in the input structure, in bytes.</p>
<p><strong>Offset to user profile data.</strong> The offset from the beginning
of the input structure to the user profile data in the input structure, in
bytes.</p>
<p><strong>Password associated with user profile data.</strong> The password to
be used in conjunction with the user profile to connect to the server
system.</p>
<p><strong>Relational database (RDB)
name</strong>The relational database on the server system to which the
connection should be made. This field should be blank padded to 18 characters
or unpredictable results may occur. If the field is set to all blanks, the
connection will be made to the *LOCAL (SYSBAS) RDB on the server system. If the
server system does not have any active independent ASPs, an error will be
signaled for any RDB that is not defined as the the *LOCAL RDB.</p>
<p><strong>Relational database (RDB) specified</strong>Specifies whether the
relational database (RDB) name field was provided. Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The relational database (RDB) name field was not
specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The relational database (RDB) name was
specified.</td>
</tr>
</table>
<p><strong>Reserved.</strong> Reserved field; it must be initialized to
0x00.</p>
<p><strong>Server job name.</strong> The job name of the database server job.
If this is a local connection, this will be the current job name.</p>
<p><strong>Server job number.</strong> The job number of the database server
job. If this is a local connection, this will be the current job number.</p>
<p><strong>Server job user name.</strong> The user name of the database server
job's initial user. If this is a local connection, this will be the current
job's initial user.</p>
<p><strong>Server system name.</strong> <img src="delta.gif" alt="Start of change">The null-terminated name of the system to which to
connect.<img src="deltaend.gif" alt="End of change"> For connection type O, this is the current system name as displayed on
the Display Network Attributes (DSPNETA) display on the server system. For
connection type T, this is the server system name as displayed in the TCP/IP
host table. It must be initialized to blanks for all other connection types. If
the server system name is the local system, the connection actually will be
made locally.</p>
<p><strong>SQL hexadecimal constants.</strong> This corresponds to the SET OPTION SQLCURRULE option and
controls how hexadecimal constants are treated within SQL statements.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Corresponds to a SQL CURRULE value of *DB2 where hexadecimal constants are treated
as character data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Corresponds to a SQL SQLCURRULE value of *STD where hexadecimal constants are
treated as binary data.</td>
</tr>
</table>
<p><strong>SQLDA cache size.</strong> The number of SQL descriptor areas to
store for later reuse. An improvement in performance will be seen if an SQL
descriptor area can be reused.</p>
<p><strong>Transaction manager information.</strong> Transaction manager name. </p>
<p><strong>User profile data.</strong> The name of the user profile to use to
connect to the server system.</p>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<p>This function may be called from the initial thread of a job only.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF180C E</td>
<td align="left" valign="top">Function &amp;1 not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFAE14 E</td>
<td align="left" valign="top">Cannot allocate &amp;1 bytes.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB751 E</td>
<td align="left" valign="top">Parameter &amp;1 passed not correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB752 E</td>
<td align="left" valign="top">Internal error in &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB753 E</td>
<td align="left" valign="top">Required OptiConnect support not installed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB754 E</td>
<td align="left" valign="top">Unable to open connection. Reason code &1. </td>
</tr>
<tr>
<td align="left" valign="top">CPFB757 E</td>
<td align="left" valign="top">The connection is suspended.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB758 E</td>
<td align="left" valign="top">The EDRS server system has been switched.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R4
<hr>
<table align="center" cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center">
<a href="#top_Of_Page">Top</a> |
<a href="file1.htm">Database and File APIs</a> |
<a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</body>
</html>
Reference in New Issue Copy Permalink