<!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>takedescriptor()--Receive Socket Access from Another Job</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. --> <!-- Begin Header Records ========================================== --> <!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- Change History: --> <!-- 021023 JTROUS Changes for scan processing, V5R3, DCR 98680 --> <!-- 031006 JTROUS Add usage note about binary read of taken desc, v5r3--> <!--End Header Records --> <!-- Edited by Kersten Feb 02 --> <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>takedescriptor()--Receive Socket Access from Another Job</h2> <div class="box" style="width: 60%;"> <br> Syntax<br> <pre> #include <sys/types.h> #include <sys/socket.h> int takedescriptor(char *<em>source_job</em>) </pre> <br> Service Program Name: QSOSRV1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The <em>takedescriptor()</em> function is used to obtain a descriptor in one i5/OS job which was passed from another i5/OS job by a <em>givedescriptor()</em>.</p> <br> <h3>Parameters</h3> <dl> <dt><strong>source_job</strong></dt> <dd>(Input) A pointer to the internal job identifier that identifies the source job from which to receive a passed descriptor.</dd> </dl> <br> <h3>Authorities</h3> <p>No authorization is required.</p> <br> <h3>Return Value</h3> <p><em>takedescriptor()</em> returns an integer. Possible values are:</p> <ul> <li>-1 (unsuccessful) <br> <br> </li> <li>n (successful), where n is a descriptor.</li> </ul> <br> <h3>Error Conditions</h3> <p>When <em>takedescriptor()</em> fails, <em>errno</em> can be set to one of the following:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>[EFAULT]</em> </td> <td align="left" valign="top">Bad address. <p>The system detected an address which was not valid while attempting to access the <em>source_job</em> parameter.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EINVAL]</em> </td> <td align="left" valign="top">Parameter not valid. <p>The <em>source_job</em> parameter points to data that is not valid.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EMFILE]</em> </td> <td align="left" valign="top">Too many descriptions for this process. <br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EIO]</em> </td> <td align="left" valign="top">Input/output error.<br><br> </td> </tr> <tr> <td align="left" valign="top"><em>[EUNKNOWN]</em> </td> <td align="left" valign="top">Unknown system state. </td> </tr> </table> <br><br> <h3>Error Messages</h3> <table width="100%" cellpadding="5"> <!-- cols="15 85" --> <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">CPE3418 E </td> <td width="85%" valign="top">Possible APAR condition or hardware failure. </td> </tr> <tr> <td align="left" valign="top">CPF9872 E </td> <td align="left" valign="top">Program or service program &1 in library &2 ended. Reason code &3. </td> </tr> <tr> <td align="left" valign="top">CPFA081 E </td> <td align="left" valign="top">Unable to set return value or error code. </td> </tr> </table><br><br> <h3>Usage Notes</h3> <ol> <li>This function can only obtain a descriptor if the sender of the descriptor referenced the job that this <em>takedescriptor()</em> is issued in by explicitly specifying this job's identification on the <em>target_job</em> parameter of the <em>givedescriptor()</em>. <br> <br> </li> <li>If the <em>source_job</em> parameter is a NULL pointer, then a descriptor can be received from any job which issues a <em>givedescriptor()</em> that references the job in which <em>takedescriptor()</em> is issued. <br> <br> </li> <li>If no descriptor is available to be received, the <em>takedescriptor()</em> is blocked. <br> <br> </li> <li>If both the job in which the <em>givedescriptor()</em> is issued and the job specified by the <em>target_job</em> parameter end while a descriptor is in transit, the descriptor is reclaimed by the system, and the resource that it represents is closed. <br> <br> </li> <li>The information to specify in the <em>target_job</em> parameter of the <em>givedescriptor()</em> and in the <em>source_job</em> parameter of the <em>takedescriptor()</em> can be obtained in the actual target job by using a work management API (for example, <strong>QUSRJOBI</strong>) to retrieve the <em>internal job identifier</em>. <br> <br> </li> <li>For files and directories, <em>takedescriptor()</em> is only supported for objects in the Root, QOpenSys, User-defined file systems (UDFS), and Network File System (NFS). <br> <br></li> <li>If this function is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ENOTSUP]. See <a href= "ifsopenexit.htm">Integrated File System Scan on Open Exit Programs</a> and <a href="ifscloseexit.htm">Integrated File System Scan on Close Exit Programs</a> for more information.<br> <br> </li> <li>When the descriptor is obtained using <em>takedescriptor()</em>, any information accessed using that descriptor with the various read and write interfaces will be in binary, even if the original descriptor's accesses would have had text conversions occur. See <a href="open.htm#HDRIFSCCSD">Using CCSIDs and code pages</a> in the <a href="open.htm">open--Open file</a> documentation for more information on text conversion. <br> <br> </li> </ol> <br> <h3>Related Information</h3> <ul> <li><a href="gvsoc.htm">givedescriptor()</a>--Pass Descriptor Access to Another Job <br> <br> </li> <li><a href="sendms.htm">sendmsg()</a>--Send Data or Descriptors or Both <br> <br> </li> <li><a href="recvms.htm">recvmsg()</a>--Receive Data or Descriptors or Both</li> </ul> <br> <hr> API introduced: V3R1 <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>