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

787 lines
24 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>
<!-- Begin Header Records ========================================== -->
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Qp0lCvtPathToQSYSObjName()-- Resolve Integrated File System Path Name
into QSYS Object Name</title>
<!-- 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 -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 011008 RTHEIS P9953491, v5r2a Update usage notes. -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 050418 JTROUS V5r4 API review updated, no change flag -->
<!-- This file has undergone html cleanup June 2002 by JET -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>Qp0lCvtPathToQSYSObjName()-- Resolve Integrated File System Path Name into
QSYS Object Name</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qp0lstdi.h&gt;
void Qp0lCvtPathToQSYSObjName(
Qlg_Path_Name_T *path_name,
void *qsys_info,
char format_name[8],
uint bytes_provided,
uint desired_CCSID,
void *error_code);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB2<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usage">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>Qp0lCvtPathToQSYSObjName()</strong> function resolves a given
integrated file system path name into the four-part QSYS.LIB or independent ASP
QSYS.LIB file system name. The primary three parts of the path name are the
following components: library, object, and member. The fourth part of the path
name is a character representation of the ASP associated with the object, or
the independent ASP name. This depends on whether the path refers to an object
in the QSYS.LIB file system or an object in an independent ASP QSYS.LIB file
system. If the path contains symbolic links, they will be resolved. If, after
symbolic links have been resolved, the path does not refer to an object that
could be in either the QSYS.LIB file system or an independent ASP QSYS.LIB file
system, the API will return with the error message CPFA0DB indicated in the
<em>error_code</em> structure. Note that the API does not verify that the
object exists.</p>
<p>The API also handles wildcard (*) characters in the path name. If the name
or type of a library, object, or member is just an asterisk, *ALL is returned
as the name or the type. If an asterisk is part of a library, object, or member
name, a name containing an asterisk is returned. For example if the following
path name is passed in:</p>
<p>/qsys.lib/test*.file/*.*</p>
<p>the API will return:</p>
<ul>
<li>Library name: QSYS</li>
<li>Library type: *LIB</li>
<li>Object name: TEST*</li>
<li>Object type: *FILE</li>
<li>Member name: *ALL</li>
<li>Member type: *ALL</li>
<li>ASP name: *SYSBAS</li>
</ul>
<p>Note that path name components that follow one containing a wildcard
character are ignored.</p>
<p>If less than 8 bytes are supplied for the <em>error_code</em> structure,
errors will cause an exception to be returned to the caller.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>path_name</em></strong></dt>
<dd>(Input) The path name that refers to the QSYS.LIB or independent ASP
QSYS.LIB file system object. The path name must refer to an object on the local
file system; this API does not recognize file system objects accessed remotely.
This path name is in the Qlg_Path_Name_T format. For more information on this
structure, see <a href="../apiref/pns.htm">Path name format</a>. If the path_name
parameter is NULL or points to invalid storage, a CPFA0CE error message is
returned.<br>
</dd>
<dt><strong><em>qsys_info</em></strong></dt>
<dd>(Output) A pointer of type <samp>void *</samp> that refers to a structure
that contains the object name. The format of the data returned is specified by
the <em>format_name</em> parameter. If the qsys_info parameter is NULL or
points to invalid storage, a CPF24B4 error message is returned.<br>
</dd>
<dt><strong><em>format_name</em></strong></dt>
<dd>(Input) An 8-byte character array that indicates how the data will be
formatted in the <em>qsys_info</em> parameter that is returned. The format is
as follows:
<dl compact>
<dt><em><strong>QSYS0100</strong></em></dt>
<dd>For the format of this structure, see the section <a href="#HDRFMTQSYS">
Returned Data Format</a>.</dd>
</dl>
If the format_name parameter is NULL or points to invalid storage, a CPF24B4
error message is returned.<br>
</dd>
<dt><strong><em>bytes_provided</em></strong></dt>
<dd>(Input) The number of bytes of data provided in the structure referred to
by the <em>qsys_info</em> parameter. This value must be at least 8, or a
CPF3C24 error message will be returned.<br>
</dd>
<dt><strong><em>desired_CCSID</em></strong></dt>
<dd>(Input) The CCSID the returned object names and types should be converted
to. If the value of this parameter is 0, the object names and types will be
returned in the job CCSID.<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>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<strong><a name="TBLASWP1Q">Authorization Required for the
Qp0lCvtPathToQSYSObjName() API</a></strong>
<table border>
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority<br>
Required</th>
<th align="left" valign="bottom">Message ID</th>
</tr>
<tr>
<td align="left" valign="top">Each directory, preceding the last component, in
the path name.</td>
<td align="center" valign="top">*X</td>
<td align="left" valign="top">CPFA09C</td>
</tr>
<tr>
<td align="left" valign="top">Object in the QSYS.LIB or independent ASP
QSYS.LIB file system that the path name refers to.</td>
<td align="center" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<br>
<h3><a name="HDRFMTQSYS">Returned Data Format</a></h3>
<p>The following table describes the format of the data returned in the <em>
qsys_info</em> parameter if the QSYS0100 format is specified. For details on
the fields of the structure, see the section <a href="#HDRCNQSYSF">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">CCSID_Out</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(28)</td>
<td align="left" valign="top">Lib_Name</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Lib_Type</td>
</tr>
<tr>
<td align="center" valign="top">60</td>
<td align="center" valign="top">3C</td>
<td align="left" valign="top">CHAR(28)</td>
<td align="left" valign="top">Obj_Name</td>
</tr>
<tr>
<td align="center" valign="top">88</td>
<td align="center" valign="top">58</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Obj_Type</td>
</tr>
<tr>
<td align="center" valign="top">108</td>
<td align="center" valign="top">6C</td>
<td align="left" valign="top">CHAR(28)</td>
<td align="left" valign="top">Mbr_Name</td>
</tr>
<tr>
<td align="center" valign="top">136</td>
<td align="center" valign="top">88</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Mbr_Type</td>
</tr>
<tr>
<td align="center" valign="top">156</td>
<td align="center" valign="top">9C</td>
<td align="left" valign="top">CHAR(28)</td>
<td align="left" valign="top">Asp_Name</td>
</tr>
</table>
<br>
<h3><a name="HDRCNQSYSF">Field Descriptions</a></h3>
<p><strong>ASP Name.</strong> The path name component that represents the ASP
name, if part of the path, or the ASP that the path is associated with. For
paths that refer to objects in independent ASP QSYS.LIB file systems, this will
be the name of the ASP device description object. For paths that refer to
objects in the QSYS.LIB file system, the value of ASP Name will be *SYSBAS.</p>
<p><strong>Bytes_Available.</strong> The total number of bytes required to hold
all of the data available in the <em>qsys_info</em> parameter.</p>
<p><strong>Bytes_Returned.</strong> The number of bytes actually returned in
the caller's buffer for the <em>qsys_info</em> parameter.</p>
<p><strong>CCSID_Out.</strong> The CCSID that the returned text is in. This may
be different than the <em>desired_CCSID</em> if conversion failed. The text is
internally normalized, then converted to the desired CCSID. If this conversion
from the normalized form does not succeed, the text will be returned in the
CCSID of the normalized form.</p>
<p><strong>Lib_Name.</strong> The name of the library that the path name refers
to. This field is NULL terminated.</p>
<p><strong>Lib_Type.</strong> The type of the object, beginning with an *
(asterisk). This field will return either *LIB or *ALL. This field is NULL
terminated.</p>
<p><strong>Mbr_Name.</strong> The name of the member that the path name refers
to. This field is NULL terminated, and could be all NULL (all x'00').</p>
<p><strong>Mbr_Type.</strong> The type of the member that the path name refers
to. This field is NULL terminated. This field will contain *MBR, *ALL, or all
NULL (all x'00').</p>
<p><strong>Obj_Name.</strong> The name of the object that the path name refers
to. This field is NULL terminated, and could be all NULL (all x'00').</p>
<p><strong>Obj_Type.</strong> The type of the object that the path name refers
to. This field is NULL terminated. This field could contain an object type (for
example *FILE), *ALL, or be NULL (all x'00').</p>
<p>The Lib_Name, Lib_Type, Obj_Name, Obj_Type, Mbr_Name, and Mbr_Type fields of
the Qp0l_QSYS_Info_t structure will be filled in as appropriate.</p>
<p>If the object that the path name refers to is a library (*LIB), then the
lib_name and lib_type fields will contain that library name and *LIB,
respectively, and the Obj_Name and Mbr_Name fields will be NULL (all
x'00').</p>
<p>If the object name is not an *FILE object with members, then the Mbr_Name
field is NULL (all x'00').</p>
<p>If the object name contains quoted strings, the characters within the
strings will not be converted to uppercase.</p>
<br>
<h3>Error Conditions</h3>
<p>None.</p>
<br>
<h3>Error Messages</h3>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3101 E</td>
<td width="85%" valign="top">I/O exception non-recoverable error.</td>
</tr>
<tr>
<td valign="top">CPE3101 E</td>
<td valign="top">I/O exception non-recoverable error.</td>
</tr>
<tr>
<td valign="top">CPE3418 E</td>
<td valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPE3474 E</td>
<td valign="top">Unknown system state.</td>
</tr>
<tr>
<td valign="top">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF3BF6 E</td>
<td valign="top">Path type value not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C24 E</td>
<td valign="top">Length of the receiver variable is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program &amp;1 in library &amp;2 ended. Reason code is
&amp;3.</td>
</tr>
<tr>
<td valign="top">CPFA092 E</td>
<td valign="top">Path name not converted.</td>
</tr>
<tr>
<td valign="top">CPFA09C E</td>
<td valign="top">Not authorized to object. Object is &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA09E E</td>
<td valign="top">Object in use. Object is &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA09F E</td>
<td valign="top">Object damaged. Object is &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA0A1 E</td>
<td valign="top">An input or output error occurred.</td>
</tr>
<tr>
<td valign="top">CPFA0A2 E</td>
<td valign="top">Information passed to this operation was not valid.</td>
</tr>
<tr>
<td valign="top">CPFA0A3 E</td>
<td valign="top">Path name resolution causes looping.</td>
</tr>
<tr>
<td valign="top">CPFA0A7 E</td>
<td valign="top">Path name too long.</td>
</tr>
<tr>
<td valign="top">CPFA0A8 E</td>
<td valign="top">Operation not allowed in a job running multiple threads.</td>
</tr>
<tr>
<td valign="top">CPFA0A9 E</td>
<td valign="top">Object not found. Object is &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA0AA E</td>
<td valign="top">Error occurred while attempting to obtain space.</td>
</tr>
<tr>
<td valign="top">CPFA0AD E</td>
<td valign="top">Function not supported by file system.</td>
</tr>
<tr>
<td valign="top">CPFA0B1 E</td>
<td valign="top">Requested operation not allowed. Access problem.</td>
</tr>
<tr>
<td valign="top">CPFA0C0 E</td>
<td valign="top">Buffer overflow occurred.</td>
</tr>
<tr>
<td valign="top">CPFA0C1 E</td>
<td valign="top">CCSID &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPFA0CE E</td>
<td valign="top">Error occurred with path name parameter specified.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA0D9 E</td>
<td valign="top">Character string not converted.</td>
</tr>
<tr>
<td valign="top">CPFA0DB E</td>
<td valign="top">Object not a QSYS.LIB object. Object is &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA0DD E</td>
<td valign="top">Function was interrupted.</td>
</tr>
<tr>
<td valign="top">CPFA0E0 E</td>
<td valign="top">File ID conversion of a directory failed.</td>
</tr>
<tr>
<td valign="top">CPFA0E1 E</td>
<td valign="top">The file ID table is damaged.</td>
</tr>
<tr>
<td valign="top">CPFA0E2 E</td>
<td valign="top">System unable to establish a communications connection to a
file server.</td>
</tr>
<tr>
<td valign="top">CPFA0E4 E</td>
<td valign="top">The communications connection with the file server was
abnormally ended.</td>
</tr>
<tr>
<td valign="top">CPFA0E5 E</td>
<td valign="top">The communications connection with the file server was
abnormally ended.</td>
</tr>
<tr>
<td valign="top">CPFA0E6 E</td>
<td valign="top">Object handle rejected by file server.</td>
</tr>
<tr>
<td valign="top">CPFA0E7 E</td>
<td valign="top">System cannot establish a communications connection with a
file server.</td>
</tr>
<tr>
<td valign="top">CPFA1C5 E</td>
<td valign="top">Object is a read only object. Object is &amp;1.</td>
</tr>
</table>
<br>
<br>
<h3><a name="usage">Usage Notes</a></h3>
<ol type="1">
<li>This API will fail and return the error message CPFA0A8 when all the
following conditions are true:
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined file system</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
</ul>
</li>
</ul>
<br>
</li>
<li>This API ignores trailing blank spaces at the end of a path name.
<p>For example, if the path name is</p>
<pre>
"/qsys.lib/fred.lib/foo.file/abc.mbr "
</pre>
the trailing blank spaces will be ignored. Thus, the above path name is
equivalent to
<pre>
"/qsys.lib/fred.lib/foo.file/abc.mbr"
</pre>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>qp0lstdi.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)
</li>
<li><a href="conqsysnu.htm">QlgQp0lCvtPathToQSYSObjName()</a>-- Resolve
Integrated File System Path Name into QSYS Object Name</li>
</ul>
<br>
<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 program gets the three-part QSYS name from an
integrated file system path name passed to it.</p>
<pre>
#include &lt;qp0lstdi.h&gt; /* For Qp0lCvtPathToQSYSObjName */
/* type Qp0l_QSYS_Info_t */
/* type Qlg_Path_Name_T */
#include &lt;qusec.h&gt; /* For type Qus_EC_T */
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
int main ()
{
/***************************************************************/
/* Declaration of path_name parameter */
/***************************************************************/
char path_info_array[500];
Qlg_Path_Name_T *path_name;
const char fname[] =
"/qsys.lib/jerold.lib/qcsrc.file/testconv.mbr";
const char US_const[] = "US";
const char Language_const[] = "ENU";
const char Path_Name_Del_const[] = "/";
/***************************************************************/
/* Declaration of qsys_info parameter */
/***************************************************************/
Qp0l_QSYS_Info_t qsys_info;
/***************************************************************/
/* Declaration of format_name parameter */
/***************************************************************/
char format_name[8] = "QSYS0100";
/***************************************************************/
/* Declaration of bytes_provided parameter */
/***************************************************************/
uint bytes_provided;
/***************************************************************/
/* Declaration of desired_CCSID parameter. */
/***************************************************************/
uint desired_CCSID;
/***************************************************************/
/* Declarations for error_code parameter */
/***************************************************************/
Qus_EC_t error_code;
char error_string[8];
/***************************************************************/
/* Initialize path_name parameter */
/***************************************************************/
memset(path_info_array, 0, sizeof(path_info_array));
path_name = (Qlg_Path_Name_T *) path_info_array;
path_name-&gt;CCSID = 37;
memcpy(path_name-&gt;Country_ID, US_const, 2);
memcpy(path_name-&gt;Language_ID, Language_const, 3);
path_name-&gt;Path_Type = 0;
path_name-&gt;Path_Length = strlen(fname);
memcpy(path_name-&gt;Path_Name_Delimiter, Path_Name_Del_const, 1);
memcpy( &amp;(((char *) path_name)[sizeof(Qlg_Path_Name_T)]),
fname,
strlen(fname));
/***************************************************************/
/* Initialize qsys_info parameter */
/***************************************************************/
/* No initialization requirements for this parameter. */
/***************************************************************/
/* Initialize format_name parameter */
/***************************************************************/
/* No additional initialization required. */
/***************************************************************/
/* Initialize bytes_provided parameter. */
/***************************************************************/
bytes_provided = sizeof(Qp0l_QSYS_Info_t);
/***************************************************************/
/* Initialize desired_CCSID parameter. */
/***************************************************************/
desired_CCSID = 37;
/***************************************************************/
/* Initialize error_code param */
/***************************************************************/
memset(&amp;error_code, 0, sizeof(error_code));
error_code.Bytes_Provided = sizeof(error_code);
/***************************************************************/
/* Call API */
/***************************************************************/
Qp0lCvtPathToQSYSObjName(path_name,
QSYS.LIB_info,
format_name,
bytes_provided,
desired_CCSID,
&amp;error_code);
if (error_code.Bytes_Available &gt; 0)
{
/***********************************************************/
/* Error occurred. */
/***********************************************************/
printf ("Error occurred: ");
memcpy (error_string, error_code.Exception_Id, 7);
error_string[7] = '\0';
printf ("%s\n", error_string);
printf ("Bytes available in error code structure: %d.\n",
error_code.Bytes_Available);
exit(1);
}
/***************************************************************/
/* API returned successfully. */
/***************************************************************/
printf ("Library name: %s\n", qsys_info.Lib_Name);
printf ("Library type: %s\n", qsys_info.Lib_Type);
printf ("Object name: %s\n", qsys_info.Obj_Name);
printf ("Object type: %s\n", qsys_info.Obj_Type);
printf ("Member name: %s\n", qsys_info.Mbr_Name);
printf ("Member type: %s\n", qsys_info.Mbr_Type);
printf ("Asp name: %s\n", qsys_info.Asp_Name);
exit(0);
}
</pre>
<p>Output:</p>
<pre>
Library name: JEROLD
Library type: *LIB
Object name: QCSRC
Object type: *FILE
Member name: TESTCONV
Member type: *MBR
Asp name: *SYSBAS
</pre>
<br>
<hr>
API introduced: V4R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue Copy Permalink