Retrieve Referenced Objects (QP0LRRO) API

  Syntax

 
 #include <qp0lrro.h>
 void QP0LRRO(
              void *            Receiver_Variable,
              unsigned int      Length_Of_Receiver_Variable,
              char *            Receiver_Format_Name,
              void *            Job_Identification,
              char *            Job_Identification_Format,
              void *            Error_Code
             );

   Default Public Authority: *USE

  Threadsafe: No

The QP0LRRO() API is used to retrieve information about integrated file system objects that are currently referenced by a specific job.

A reference is an individual type of access or lock obtained on the object when using integrated file system interfaces. An object may have multiple references concurrently held, provided that the reference types do not conflict with one another.

This API will not return information about byte range locks that may currently be held on an object.

Parameters

Receiver_Variable

(Output)

The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API will return only complete records that the area can hold. A complete record is defined as the object list output structure (Qp0l_PObj_List_Output_T) along with the extended reference types, the Qlg_Path_Name_T structure and path of the object if it can be returned.

The format of the output is described by the RROO0100 output format. See RROO0100 Output Format Description for a detailed description of these output formats.

Length_Of_Receiver_Variable

(Input)

The length of the receiver variable. If the length specified is larger than the size allocated for the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

Receiver_Format_Name

(Input)

Pointer to an 8-byte character string that identifies the desired output format. It must be one of the following values.

RROO0100

The reference type output will be formatted in the RROO0100 output format. See RROO0100 Output Format Description for a detailed description of this output format.

Job_Identification

(Input)

Pointer to the structure that is used to identify the job or thread for which the integrated file system objects are referenced. See the various job formats available in the Retrieve Job Locks (QWCRJBLK) API for a detailed description of this input format.

Job_Identification_Format

(Input)

Pointer to an 8-byte character string that is used to identify the format of the job or thread identification information. The format name must be one of the following values.

JIDF0100	This format is used to retrieve the references that a job and threads are holding. See JIDF0100 Format in Retrieve Job Locks (QWCRJBLK) API for more information.
JIDF0200	This format is used to retrieve the references that a specific thread is holding. See JIDF0200 Format in Retrieve Job Locks (QWCRJBLK) API for more information.

Note: The Internal Job Identifier within job formats JIDF0100 and JIDF0200 is not supported by QP0LRRO at this time. If the internal job identifier is specified, CPE3440 (Operation not supported) will be returned in the error code structure.

This API is thread independent. This means QP0LRRO returns references for integrated file system objects for all threads within a specified job. Therefore the thread indicator fields in the job format structures will be ignored.

Error_Code

(Input/Output)

Pointer to an error code structure to receive error information. See Error code parameter for more information.

Authorities and Locks

Job Authority

The job authority must be one of the following:

1. The API must be called from within the job for which the information is being retrieved.
2. The caller of the API must be running under a user profile that is the same as the job user identity of the job for which the information is being retrieved.
3. The caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work Management topic.

Input Structure Formats

The input structure formats are used to input job or thread information. for a detailed description of this input format. See JIDF0100 Format and JIDF0200 Format in Retrieve Job Locks (QWCRJBLK) API.

Output Structure Formats

RROO0100 Output Format Description (Qp0l_RROO0100_Output_T)

This output format is used to return integrated file system objects that have been referenced by a specific job.

Objects List Output Structure Description (Qp0l_Obj_List_Output_T)

This structure is embedded within the RROO0100 format. It is used to return the list of integrated file system objects that have been referenced by a specific job. This structure is repeated for each integrated file system object referenced by the job.

Qlg Path Name Structure Description (Qlg_Path_Name_T)

This structure is embedded within the RROO0100 format. It is an NLS-enabled Qlg_Path_Name_T format structure that contains a path name or pointer to a path name of an integrated file system object that is referenced by the job. For more information on the Qlg_Path_Name_T structure, see Path name format.

Some integrated file system objects may have multiple links. In this case the QP0LRRO API will only return a single path name to the object.

If the last element of the path is a symbolic link, QP0LRRO does not resolve the contents of the symbolic link. The reference information will be obtained for the symbolic link itself.

The Qlg_Path_Name_T structure will have a path length of zero (0) if no path name was available to be returned. A path name may not be returned under the following conditions:

• The object is in the "root" (/), QOpenSys or a user-defined file system and is not linked to a directory path.
• The object is in a remote file system or the optical file system (QOPT).

Extended Object Reference Types Structure Description (Qp0l_Ext_Ref_Types_Output)

This structure is embedded within the RROO0100 format. It is used to return object reference type information.

The Qp0l_Ext_Ref_Types_Output contains the references for the returned object contained in the Qlg_Path_Name_T structure. For more information on the Qp0l_Ext_Ref_Types_Output_T structure see Extended object reference types structure description in Retrieve Object References (QP0LROR) API.

Field Descriptions for RROO0100 Output Structure and the embedded structures

Bytes available. Number of bytes of output data that was available to be returned.

Bytes returned. Number of bytes returned in the output buffer.

Displacement to extended reference types. Displacement from the beginning of the Objects list output structure containing this field to the beginning of the Extended reference types structure.

Displacement to next Object list output structure. Displacement from the beginning of Object list output structure to the beginning of the next Object list output structure. If this field is 0, then there are no more Object list output structures available to be returned, or not enough space was provided to complete the next Object list output structure.

Displacement to Qlg_Path_Name_T structure. Displacement from the beginning of the Object list output structure containing this field to the beginning of the Qlg_Path_Name_T structure.

Extended reference types structure. This is a Qp0l_Ext_Ref_Types_Output_T structure containing fields that indicate different types of references that may be held on an object. For more information on the Qp0l_Ext_Ref_Types_Output_T structure see Extended object reference types structure description in Retrieve Object References (QP0LROR) API.

File identifier. An identifier associated with the referred to object. A file ID can be used with Qp0lGetPathFromFileID() to retrieve an object's path name from some file systems. The file identifier is defined in header file Qp0lstdi.h as data type Qp0lFID_t.

File identifier number. The file identifier number of the object. This number uniquely identifies the object within a file system. When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system.

File system identifier. The file system ID to which the object belongs. This number uniquely identifies the file system to which the object belongs. When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system.

File system type. An integer representation of the file system the object belongs. The file system type may be one of the following values.

Generation identifier. The generation identifier associated with the object. When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system.

Length of extended reference types. Length of the Extended reference types information.

Length of Qlg_Path_Name structure. Length of the Qlg_Path_Name structure.

Objects returned count. The number of integrated file system objects that are returned in the Objects list output structure. The number of objects returned is limited by the amount of space allocated to receive the list of objects.

Objects available count. The number of integrated file system objects that are available to be returned in the Objects list output structure. This value may be larger than the value in the Objects returned count.

Offset to objects list output structure. Offset from the beginning of the Receiver_Variable to the beginning of the Objects list output structure. If this field is 0, then no integrated file system objects were available to be returned, or not enough space was provided to complete an Objects list output structure.

Qlg Path Name structure. An NLS enabled Qlg_Path_Name_T format structure that contains a path name of an integrated file system object that is referenced by the job.

Reference count. Current number of references on the object for the specified job.

Retrieve referenced object status. An integer space to return potential error conditions back to the caller that may have been ignored by the QP0LRRO() API. The following feedback conditions may be returned (NOTE: If non-zero, this condition value may indicate more than one error condition):

Error Messages

Usage Notes

1. The QP0LRRO API will return references for the file systems whose types are listed above in the file system type definition.
   
   
2. The list of objects returned in the RROO0100 output format may be incomplete for objects residing in file systems other than the "root" (/), QOpenSys, and user-defined file systems. Objects in some of the other file systems can be locked with interfaces that do not use the integrated file system. Therefore, objects referenced by a job will only have references that were obtained as part of an integrated file system operation, or an operation that causes an integrated file system operation to occur.
   
   
3. Jobs using file systems that access remote objects, such as Network File System (NFS) and the QFileSvr.400 file systems, will only be returning object references that are locally obtained. Any remote object references held by the job are not returned by this API.
   
   
4. Since the output format is variable length, the following is recommended for obtaining a minimum output buffer size to receive the information:
   
   
   • RROO0100: Programs may consider first calling QP0LRRO and specifying the minimum eight bytes for the input Length_Of_Receiver_Variable and assigning a space of at least eight bytes to the output Receiver_Variable. QP0LRRO will then return the number of bytes required for this operation in the bytes available field in output structure RROO0100. The program could then allocate a buffer equal in size to the returned value in bytes available.

     The number of referenced objects for a particular job may change between multiple calls to this API. Therefore, the output buffer size for a RROO0100 format may not be enough space under all conditions.

   • If not enough is space provided to receive a complete list of object information, then only those object entries that completely fit in the buffer will be returned. The RROO0100 output structure contains a field called Object available count that will always contain the total number of integrated file system objects that were available for returning to the caller at that instance in time.
     
     
5. This API will only capture the object references at an instant in time. By the time this API has completed and returns to the caller, the reference information may already be out of date. This behavior is characteristic of this type of interface.
   
   
6. There are some reference types that are obtained on an object without incrementing the object's reference count. This could result in an object not being returned by this API for a job even though that job is holding a lock on that object.

   For example: At some instances during the save or restore of an integrated file system object, the job may have references on an object even though its reference count is zero.

7. Under some circumstances, the list of objects that are referenced by a job may be incomplete. Some system programs obtain object references directly on an object without obtaining an open descriptor for the object.
   
   
8. This type of reference information can also be viewed through the iSeries Navigator application. The terminology, however, differs in that iSeries Navigator refers to this type of information as "Usage" information instead of "Reference" information.

Related Information

• The <qp0lrro.h> file (see Header Files for UNIX-Type Functions)
• The <qp0lror.h> file (see Header Files for UNIX-Type Functions)
• The <qlg.h> file (see Header Files for UNIX-Type Functions)
• Retrieve Job Locks API (QWCRJBLK) API
• Retrieve Object References (QP0LROR) API

Example

The following is an example use of this API.

See Code disclaimer information for information pertaining to code examples.

#include <qp0lrro.h>
#include <qp0wpid.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <iconv.h>
#include <qtqiconv.h>
#include <errno.h>

 /* Function convertData for converting a National Language Support */
 /* path name                                                       */
int convertData(int  in_ccsid,
		int   out_ccsid,
		char   *in_buf,
		char   *out_buf,
		size_t *in_bytes_left,
		size_t *out_bytes_left)
{

    QtqCode_T from_code =
    {
        0,                           /* input CCSID.                */
        0,                           /* (conversion alternative)
                                      IBM default conversion.     */
        0,                           /* (substitution alternative)
                                      do not return substitution
                                      count.                      */
        0,                           /* (shift-state alternative)
                                      conv descriptor is not
                                      returned to initial shift
                                      state.                      */
        0,                           /* (input length option) valid
                                      inbytesleft required.
                                      (input/output are NOT
                                      null-terminated)            */
        0                            /* (error option for mixed data)
                                      No mixed byte errors.       */
    };

    QtqCode_T to_code =
    {
        0,                           /* output CCSID.               */
        0,                           /* ignored on output           */
        0,                           /* ignored on output           */
        0,                           /* ignored on output           */
        0,                           /* ignored on output           */
        0                            /* ignored on output           */
    };

    iconv_t cd;                      /* conversion descriptor.      */

    /* Set the to and from ccsids. */
    from_code.CCSID = in_ccsid;
    to_code.CCSID = out_ccsid;

    errno = 0;

    /* Call code conversion allocation API to get a conversion      */
    /* descriptor.                                                  */
    cd = QtqIconvOpen(&to_code, &from_code);

    /* verify conversion descriptor */
    if ( cd.return_value == -1 )
    {
        printf("ERROR: iconv_open failed (errno=%d).",
             errno);
        return(-1);
    }

    /* Do the conversion. */
    if ( iconv(cd,
               &in_buf,
               in_bytes_left,
               &out_buf,
               out_bytes_left) == -1 )
    {
        printf("ERROR: iconv failed (errno=%d).",
             errno);
        printf("The input ccsid=%d, and the output ccsid=%d.",
             in_ccsid, out_ccsid);
        printf("The input data=%s.\n", in_buf);
        return(-1);
    }

    /* Close the conversion descriptor. */
    if ( iconv_close(cd) == -1 )
    {
        printf("ERROR: iconv_close failed (errno=%d).",
             errno);
        return(-1);
    }

    return(0);

} /* end convertData */

  /*************************/
  /* Start of main program */
  /*************************/
void main()
{

      /* Define a Path name structure */
    struct PathNameStruct
    {
      Qlg_Path_Name_T pn_header;
      char pn[500];
    };

    struct PathNameStruct *pathP;

    char path_buffer[500]; /* buffer to receive a converted
			      path name                       */
    size_t out_bytes;      /* path buffer size                */

    Qus_EC_t errorCode;

      /* Define an input job structure */
    struct myjob100_struct
    {
	char Job_Name[10];
	char User_Name[10];
	char Job_Number[6];
	char Int_Job_ID[16];
	char Reserved[2];
	int  Thread_Indicator;
	char Thread_Id[8];
    }myjob100_struct_t;

    char output_format[8];    /* declare an output format variable */

    unsigned outputBufSize;   /* Declare an output buffer size
                                 variable                      */

    /* declare a pointer fro retrieving the Object list output */
    Qp0l_Obj_List_Output_T *Obj_ListP;

    /* Declare a pointer for retrieving the RROO0100 format.  */
    Qp0l_RROO0100_Output_T *output100P;

    /* Declare a job pointer.                    */
    struct QP0W_Job_ID_T jobP;
    struct myjob100_struct Job_ID;

    char job_format[8];      /* declare a job format variable. */

    /* Declare a process ID */
    pid_t Process_ID = 0;    /* zero = current process */

    /*********************************************************/
    /* Define a constant for the number of output buffer     */
    /* bytes provided for the RROO0100 format.               */
    /*********************************************************/
     outputBufSize =                                  \
             (sizeof(Qp0l_RROO0100_Output_T) +        \
	      sizeof(Qp0l_Obj_List_Output_T) +        \
              sizeof(Qlg_Path_Name_T) +               \
              sizeof(Qp0l_Ext_Ref_Types_Output_T) +   \
              5000);      /* Pad space for the returned path 
                            name                             */

    /*************************************/
    /* Get the job ID of the current job */
    /*************************************/
    int rv = Qp0wGetJobID(Process_ID, &jobP);
     if(rv != 0)
     {
	 printf("Error occurred for Qp0lGetJobID.\n");
	 return;
     }

   /*********************************************************/
   /* Set the Qp0l_RROI0100 information from the Process_ID */
   /*********************************************************/
    memset(&Job_ID, 0x00, sizeof(Job_ID));
    memcpy(Job_ID.Job_Name, jobP.jobname, sizeof(Job_ID.Job_Name));
    memcpy(Job_ID.User_Name, jobP.username, sizeof(Job_ID.User_Name));
    memcpy(Job_ID.Job_Number, jobP.jobnumber, sizeof(Job_ID.Job_Number));
    memset(Job_ID.Int_Job_ID, 0x40, sizeof(Job_ID.Int_Job_ID));
	 
    /*********************************************************/
    /* Setup the error code structure to cause the error to  */
    /* be returned within the error structure.               */
    /*********************************************************/
    errorCode.Bytes_Provided = sizeof(errorCode);
    errorCode.Bytes_Available = 0;

    /****************************************************/
    /* Allocate space to receive output from QP0LRRO    */
    /****************************************************/
     if (NULL == (output100P = (Qp0l_RROO0100_Output_T *)
		 malloc(outputBufSize)))
    {
	printf("No space available.\n");
	return;
    }

    /****************************************************/
    /* Clear the allocated space                        */
    /****************************************************/
     memset(output100P, 0x00, outputBufSize);

    /****************************************************/
    /* set output format  and job format                */
    /****************************************************/
    memcpy(output_format,
	   QP0LRRO_RROO0100_FORMAT,
	   sizeof(output_format));
    memcpy(job_format,
	   QP0LRRO_RROI0100_FORMAT,
	   sizeof(job_format));
    
    /*********************************************************/
    /* Call QP0LRRO.  We will compare the number of bytes    */
    /* to the number of bytes available to allocate more     */  
    /* space if required                                     */
    /*********************************************************/
    QP0LRRO(output100P,
     outputBufSize,
     output_format,
     &Job_ID,
     job_format,
     &errorCode);

    /* Check if an error occurred.                            */
    if (errorCode.Bytes_Available != 0)
    {
	printf("Error occurred for RROO0100.\n");
        free(output100P);   /* free space */
	return;
    }

    /************************************************************/
    /* If there was more information available than we had      */
    /* provided receiver space for, then we will allocate a     */
    /* larger buffer and try once again.  This could potentially*/
    /* keep re-occurring, but this example will stop after this */
    /* second retry.                                            */
    /************************************************************/
    if (output100P->BytesReturned < output100P->BytesAvailable)
    {
        /*********************************************************/
	/* Use the bytes available value to determine how much   */
	/* more buffer size is needed.  We will pad it with an   */
	/* extra 1000 bytes to try and handle more jobs obtaining*/ 
	/* references between calls to QP0LRRO.                  */
        /*********************************************************/
	outputBufSize = output100P->BytesAvailable + 1000;

         /* reallocate more space to output100P */
        output100P = (Qp0l_RROO0100_Output_T *)(realloc((void *)output100P,
          outputBufSize));

	if (output100P ==NULL)
	{
	    printf("No space available.\n");
            free(output100P);   /* free space */
	    return;
	}

	QP0LRRO(output100P,
		 outputBufSize,
		 output_format,
		 &Job_ID,
		 job_format,
		 &errorCode);

	/* Check if an error occurred.                        */
	if (errorCode.Bytes_Available != 0)
	{
	    free(output100P);
	    printf("Error occurred for RROO0100 (2nd call).\n");
	    return;
	}
    }

   /***************************************************/
   /* Check if we received any objects that might be  */
   /* associated with a job.  If not, return.         */
   /***************************************************/
    if (output100P->ObjectsReturned == 0)
    {
	printf("QP0LRRO returned an object count of: %d\n",
	       output100P->ObjectsReturned);
	printf("Number of objects available: %d\n",
	       output100P->ObjectsAvailable);
	free(output100P);
	return;
    }

    printf("Number of objects referenced by the job: %d\n",
	   output100P->ObjectsReturned);
    printf("Number of objects available: %d\n",
	   output100P->ObjectsAvailable);
    printf("Paths referenced by the current job:\n");

    /* Get a pointer to the object list structure */
    Obj_ListP = (Qp0l_Obj_List_Output_T *)((char *)output100P + output100P->ObjListOffset);

    /* Loop through the output buffer and return the path names */
    for(int i = 0; i < output100P->ObjectsReturned; i++)
    {
	  /* Get a pointer to the Qlg_Path_Name structure */
	pathP = (PathNameStruct *)((char *)Obj_ListP + Obj_ListP->PathDisp);

	 /* clear the returned path buffer */
	memset(path_buffer, 0x00, sizeof(path_buffer));
	out_bytes = sizeof(path_buffer); /* get size of path buffer */

	/**********************************************/
	/* convert the returned object from the ccsid */
        /* in the Qlg path structure to the jobccsid  */
	/**********************************************/
	convertData(pathP->pn_header.CCSID,
		    0,            
		    pathP->pn,
		    path_buffer,
		    (size_t *)&pathP->pn_header.Path_Length,
		    (size_t *)&out_bytes);

	/* print the path name */
	printf(" %s\n",path_buffer);

	/* increment to next list entry */
	Obj_ListP = (Qp0l_Obj_List_Output_T *)((char *)Obj_ListP + Obj_ListP->NextListEntryDisp);
    }

    free(output100P);

    return;
}

Example Output:

Number of objects referenced by the job: 3
Number of objects available: 3
Paths referenced by the current job:
/
/home/myprofile
/mydir/mystmf1