Retrieve Object References (QP0LROR) API


  Syntax
 #include <qp0lror.h>
 void QP0LROR(
               void *            Receiver_Ptr,
               unsigned int      Receiver_Length,
               char *            Format_Ptr,
               Qlg_Path_Name_T * Path_Ptr,
               void *            Error_Code_Ptr


              );
  Default Public Authority: *USE

  Threadsafe: No

The QP0LROR() API is used to retrieve information about integrated file system references on an object.

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_Ptr
(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 returns only the data that the area can hold.

The format of the output is described by either the RORO0100 output format or the RORO0200 output format. See RORO0100 Output Format Description or the RORO0200 Output Format Description for a detailed description of these output formats.

Receiver_Length
(Input)

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

Format_Ptr
(Input)

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

RORO0100
The reference type output will be formatted in a RORO0100 format. See RORO0100 Output Format Description. This format gives the caller a quick view of the object's references.
RORO0200
The reference type output will be formatted in a RORO0200 format. See RORO0200 Output Format Description. Specifying this format may cause QP0LROR to be a long running operation. The length of time it will take to complete depends on the number of jobs active on the system, and the number of jobs currently using objects through integrated file system interfaces.

Path_Ptr
(Input)

Pointer to the path name to the object whose reference information is to be obtained. The path name must be specified in an NLS-enabled format specified by the Qlg_Path_Name structure. For more information about the Qlg_Path_Name_T structure, see Path name format.



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

Error_Code_Ptr
(Input/Output)

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


Authorities and Locks

Directory Authority
The user must have execute (*X) data authority to each directory preceding the object whose references are to be obtained.

Object Authority
The user must have read (*R) data authority to the object whose references are to be obtained.

Output Structure Formats

RORO0100 Output Format Description (Qp0l_RORO0100_Output)

This structure is used to return object reference information.


RORO0200 Output Format Description (Qp0l_RORO0200_Output)

This output format is used to return object reference information, including a list of jobs known to be referencing the object. This includes everything from the RORO0100 structure plus additional information.


Job Using Object Structure Description (Qp0l_Job_Using_Object)

This structure is imbedded within the RORO0200 format. It is used to return information about a job that is known to be holding a reference on the object.



Simple Object Reference Types Structure Description (Qp0l_Sim_Ref_Types_Output)

This structure is imbedded within the RORO0100 and RORO0200 formats. It is used to return object reference type information.

Each binary field reference type will be set to either 0 or a positive value that represents the number of references for that type. This number will have different meanings depending on the structure it is imbedded within. When this structure is imbedded within a RORO0100 output, or imbedded within the header portion of the RORO0200 output, then these values represent the number of known references of this type. When this structure is imbedded within a specific job list entry, then these values represent the number of references for that specific type within that specific job itself.



Extended Object Reference Types Structure Description (Qp0l_Ext_Ref_Types_Output)

This structure is imbedded in multiple places within the RORO0200 format of the QP0LROR API. It is also imbedded within the RROO0100 format of the QP0LRRO API. It is used to return object reference type information.

Each binary field reference type will be set to either 0 or a positive value that represents the number of references for that type. This number will have different meanings depending on the structure it is imbedded within.

When this structure is imbedded within the header portion of the RORO0200 output, then these values represent the number of jobs in the job list that contains a reference of this type.

When this structure is imbedded within a specific job list entry in the RORO0200 format or within a specific object list entry in the RROO0100 format, then these values represent the number of references for that specific type within that specific job itself. Only reference types that can be associated with a specific job will be represented in this usage of this structure.



i5/OS NetServer Session Using Object Structure Description ( Qp0l_Session_Using_Object Structure)

This structure is imbedded within the RORO0200 format. It is used to return information for sessions having a reference.

Note:i5/OS NetServer refers to IBM i Support for Windows® Network Neighborhood.


Field Descriptions for RORO0100 and RORO0200 Output Structures and their Imbedded Structures

Attribute Lock. Attribute changes are prevented.

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

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

Checked Out. Indicates whether the object is currently checked out. If it is checked out, then the Checked Out User Name contains the name of the user who has it checked out. This field is not scoped to a specific job. Therefore, it will not contain the object's checked out information when it is within a specific job list entry in the RORO0200 format or within a specific object list entry in the RROO0100 format.

Checked Out User Name. Contains the name of the user who has the object checked out, when the Checked Out field indicates that it is currently checked out. This field is set to blanks (x'40) if the object is not checked out. This field is not scoped to a specific job. Therefore, it will not contain the object's checked out information when it is within a specific job list entry in the RORO0200 format or within a specific object list entry in the RROO0100 format.

Current Directory. The object is a directory that is being used as the current directory of the job.

Displacement to Extended Reference Types. Displacement from the beginning of the structure containing this field to the beginning of the Extended Reference Types structure. If this field is 0, then no extended reference types were available to be returned, or not enough space was provided to include any portion of the Extended Reference Types structure.

Displacement to i5/OS NetServer Session List. Displacement from the beginning of the structure containing this field to the first i5/OS NetServer Session Using Object structure. If this field is 0, then there are no sessions in the list. If the File Server Reference and the File Server Working Directory fields are set to 0, then this field will be set to 0.

Displacement to Next i5/OS NetServer Session Entry. Displacement from the beginning of the structure containing this field to the beginning of the next i5/OS NetServer Session Using Object structure. If this field is 0, then there are no more sessions in the list.

Displacement to Next Job Entry. Displacement from the beginning of the structure containing this field to the beginning of the next Job Using Object structure. If this field is 0, then there are no more jobs in the list, or not enough space was provided to include any more Job Using Object structures.

Displacement to Simple Reference Types. Displacement from the beginning of the structure containing this field to the beginning of the Simple Reference Type structure. If this field is 0, then no simple reference types were available to be returned, or not enough space was provided to include any portion of the Simple Reference Types structure.

Execute. Execute only access.

Execute, Share with Readers Only. Execute only access. The sharing mode allows sharing with read and execute access intents only.

Execute, Share with Readers and Writers. Execute only access. The sharing mode allows sharing with read, execute, and write access intents.

Execute, Share with Writers Only. Execute only access. The sharing mode allows sharing with write access intents only.

Execute, Share with neither Readers nor Writers. Execute only access. The sharing mode allows sharing with no other access intents.

Execute/Read, Share with Readers Only. Execute and read access. The sharing mode allows sharing with read and execute access intents only.

Execute/Read, Share with Readers and Writers. Execute and read access. The sharing mode allows sharing with read, execute, and write access intents.

Execute/Read, Share with Writers Only. Execute and read access. The sharing mode allows sharing with write access intents only.

Execute/Read, Share with neither Readers nor Writers. Execute and read access. The sharing mode allows sharing with no other access intents.

Extended Reference Types Structure. This is a Qp0l_Ext_Ref_Types_Output structure containing fields that indicate different types of references that may be held on an object. Some of these are actually a grouping of multiple Simple Reference Types that were known to have been specified by the referring instance. These are not additional references; they are a redefinition of the same references described in the Simple Reference Types structure.

File Server Reference. The File Server is holding a generic reference on the object on behalf of a client. If this field is not 0, then i5/OS NetServer session information may have been returned.

File Server Working Directory. The object is a directory, and the File Server is holding a working directory reference on it on behalf of a client. If this field is not 0, then i5/OS NetServer session information may have been returned.

In-Use Indicator The object is currently in-use. This indicator will be set to one of the following values:

Internal Save Lock. The object is being referenced internally during a save operation on a different object.

i5/OS NetServer Sessions Returned. The number of i5/OS NetServer Session Using Object structures returned for the job.

Job Name. Name of the job.

Job Number. Number associated with the job.

Job User. User profile associated with the job.

Jobs Available. Number of referencing jobs available. This may be greater than the Jobs Returned field when the caller did not provide enough space to receive all of the job information.

Jobs Returned. Number of referencing jobs returned in the job list.

Length of Extended Reference Types. Length of the Extended Reference Types information.

Length of Simple Reference Types. Length of the Simple Reference Types information.

Link Changes Lock. Changes to links in the directory are prevented.

NFS Version 4 Server Reference. The Network File System (NFS) Version 4 server job is holding a generic reference on the object on behalf of a client.

Offset to Extended Reference Types. Offset from the beginning of the Receiver_Ptr to the beginning of the Extended Reference Types structure. If this field is 0, then no extended reference types were available to be returned, or not enough space was provided to include any portion of the Extended Reference Types structure.

Offset to Job List. Offset from the beginning of the Receiver_Ptr to the beginning of the first Job Using Object structure. If this field is 0, then there are no jobs in the list.

Offset to Simple Reference Types. Offset from the beginning of the Receiver_Ptr to the beginning of the Simple Reference Type structure. If this field is 0, then no simple reference types were available to be returned, or not enough space was provided to include any portion of the Simple Reference Types structure.

Read Only. Read only access.

Read Only, Share with Readers Only. Read only access. The sharing mode allows sharing with read and execute access intents only.

Read Only, Share with Readers and Writers. Read only access. The sharing mode allows sharing with read, execute, and write access intents.

Read Only, Share with Writers Only. Read only access. The sharing mode allows sharing with write access intents only.

Read Only, Share with neither Readers nor Writers. Read only access. The sharing mode allows sharing with no other access intents.

Read/Write. Read and write access.

Read/Write, Share with Readers Only. Read and write access. The sharing mode allows sharing with read and execute access intents only.

Read/Write, Share with Readers and Writers. Read and write access. The sharing mode allows sharing with read, execute, and write access intents.

Read/Write, Share with Writers Only. Read and write access. The sharing mode allows sharing with write access intents only.

Read/Write, Share with neither Readers nor Writers. Read and write access. The sharing mode allows sharing with no other access intents.

Reference Count. Current number of references on the object. NOTE: This may be 0 even though the In-Use Indicator indicates that the object is in use.

Referencing Job List. Variable length list of Qp0l_Job_Using_Object structures for jobs that are currently referencing the object.

Root Directory. The object is a directory that is being used as the root directory of the job.

Save Lock. The object is being referenced by an object save operation.

Session identifier. Unique identifier for the i5/OS NetServer session.

Share with Readers Only. The sharing mode allows sharing with read and execute access intents only.

Share with Readers and Writers. The sharing mode allows sharing with read, execute, and write access intents.

Share with Writers Only. The sharing mode allows sharing with write access intents only.

Share with neither Readers nor Writers. The sharing mode allows sharing with no other access intents.

Simple Reference Types Structure. This is a Qp0l_Sim_Ref_Types_Output structure containing fields that indicate different types of references that may be held on an object.

User name. The name of the user that is associated with the i5/OS NetServer session.

Workstation address. The IP address of the workstation from which the i5/OS NetServer session to the server was established. If this information is not available, this field will be set to blanks.

Workstation name. The name of the workstation from which the i5/OS NetServer session to the server was established. If this information is not available, this field will be set to blanks.

Write Only. Write only access.

Write Only, Share with Readers Only. Write only access. The sharing mode allows sharing with read and execute access intents only.

Write Only, Share with Readers and Writers. Write only access. The sharing mode allows sharing with read, execute, and write access intents.

Write Only, Share with Writers Only. Write only access. The sharing mode allows sharing with write access intents only.

Write Only, Share with neither Readers nor Writers. Write only access. The sharing mode allows sharing with no other access intents.


Error Messages



Usage Notes

  1. Since both available formats are variable length, following are the recommended minimum lengths pertaining to their corresponding formats:
    • RORO0100: The size of a RORO0100 Output structure plus the size of a Simple Reference Types structure.
    • RORO0200: This structure varies dynamically, and therefore there is no formula that can yield a size large enough to always retrieve all of the available information. However, programs may consider first calling QP0LROR with the RORO0100 format. This will quickly return the number of references currently on the object. Then the program could allocate a buffer equal in size to: size of a Job Using Object structure (including the size of the Simple and Extended Reference Type structures and the i5/OS NetServer Session Using Object structure) multiplied by the number of references, and then add the sizes of a RORO0100 output, RORO0200 output, and Simple Reference Types structures. Now the program could call QP0LROR with the RORO0200 format requested and the computed size.

      If the RORO0200 format was specified, but there was not enough space provided to receive a complete list of job information, then only those job entries that completely fit in the buffer will be returned. The RORO0200 output structure contains a field called JobsAvailable that will always contain the total number of referencing jobs that were available for returning to the caller at that instance in time.

    Notes

    • There are no locks obtained on the object while this API is running. Therefore, when this API is used on an object that is actively in use (e.g., its lock and reference state is changing while this API is running), some fields in the returned information may be inconsistent with other fields returned on the same invocation of QP0LROR.
    • The number of references on the object may change between multiple calls to this API. Therefore, the above formula for calculating output buffer size for a RORO0200 format may not be enough space under all conditions.
    • There are some reference types that are obtained on the object without incrementing the object's reference count. This could result in a reference count of zero while the object contains reference types. In this instance, the above formula for calculating output buffer size for a RORO0200 format may not be enough space.
  2. The list of simple object reference types in the base portions of the RORO0100 and RORO0200 output structures may not contain complete information for objects residing in file systems other than the "root" (/), QOpenSys, and user-defined file systems. The simple reference types will, however, be set in the job array elements in the RORO0200 output structure for any file system.
  3. The list of object reference types in the RORO0200 output formats may be an incomplete list of references 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, references returned by this API will only be references that were obtained as part of an integrated file system operation, or an operation that cause the integrated file system operation to occur.
  4. Under some circumstances, the list of jobs that are referencing the object may be incomplete. However, jobs not listed in the job list may still have their references listed in the RORO0100 output. This occurs when system programs obtain references directly on an object without obtaining an open descriptor for the object.
  5. At some instances during the save or restore of an integrated file system object, the object may have references held by the job even though its reference count is 0.
  6. Network File System (NFS) Version 2 and Version 3 will only return references that are locally obtained on the object. Any references that the remote system may have on the remote object from NFS Version 2 and Version 3 are not returned by this API.
  7. Use of this API on an object accessed via the QFileSvr.400 file system will not return any job references, even if the object was opened using the QFileSvr.400 client.
  8. This type of reference information is also viewable through the System i® Navigator application. The terminology, however, differs in that System i Navigator refers to this type of information as "Usage" information instead of "Reference" information.


Related Information


Example

The following is an example use of this API.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <qp0lror.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

void main()
{
    struct PathNameStruct
    {
 Qlg_Path_Name_T header;
 char p[50];
    };

    struct PathNameStruct path;

    char pathName[] = "/CustomerData";

    Qus_EC_t errorCode;

    /* Define a constant for the number of output buffer bytes
       provided for the RORO0100 format.                      */
#define OUTPUT_BYTES_RORO0100                                  \
             (sizeof(Qp0l_RORO0100_Output_T) +                 \
              sizeof(Qp0l_Sim_Ref_Types_Output_T) +   \
              100)       /* Pad space for potential gap between
                            the 2 structures.                 */

    /* Declare some space for the RORO0100 output.            */
    char output100Buf[OUTPUT_BYTES_RORO0100];

    /* Declare a pointer for retrieving the RORO0100 format.  */
    Qp0l_RORO0100_Output_T *output100P;

    /* Declare a pointer to retrieve the RORO0200 format.     */
    Qp0l_RORO0200_Output_T *output200P;

    /* Declare a job using object pointer.                    */
    Qp0l_Job_Using_Object_T *jobP;

    unsigned outputBufSize;

    /* Set output buffer pointer and length for retrieving the
       RORO0100 format.                                       */
    output100P = (Qp0l_RORO0100_Output_T *)output100Buf;

    /* Setup the object's path name structure.                */
    memset(&path, 0, sizeof(path));      
    path.header.CCSID = 37;                               
    memcpy(path.header.Country_ID,"US",2);            
    memcpy(path.header.Language_ID,"ENU",3);    
    path.header.Path_Type = QLG_CHAR_SINGLE;                            
    path.header.Path_Length = strlen(pathName);             
    path.header.Path_Name_Delimiter[0] = '/';   
    memcpy(path.p, pathName, path.header.Path_Length);

    /* 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;

    /* First call QP0LROR to get the short format.  We will
       use that information about references to conditionally
       allocate more space and then get the longer
       running format's information.                          */
    QP0LROR(output100P,
     OUTPUT_BYTES_RORO0100,
     QP0LROR_RORO0100_FORMAT,
     (Qlg_Path_Name_T *) &path,
     &errorCode);

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

    /* Check if we received any references that might be
       associated with a job.  If not, return.                */
    if (output100P->Count == 0)
    {
 printf("QP0LROR returned a reference count of %d\n",
        output100P->Count);
 return;
    }

    /* If we get here, then we have at least 1 reference that
       may be identifiable to a job.  We will call the
       QP0LROR API to get the RORO0200 format.  First we
       compute a buffer size to use.  Note:  this calculation
       sums up the sizes of all structures contained within
       the RORO0200 format, but doesn't consider gaps between
       each of the structure.  To attempt to cover potential
       gaps between structures, an extra 1000 bytes is being
       allocated and room for 10 additional jobs.             */
    outputBufSize =
      sizeof(Qp0l_RORO0200_Output_T) +
      sizeof(Qp0l_Sim_Ref_Types_Output_T) +
      sizeof(Qp0l_Ext_Ref_Types_Output_T) +
      ((output100P->Count + 10) *
       (sizeof(Qp0l_Job_Using_Object_T) +
 sizeof(Qp0l_Sim_Ref_Types_Output_T) +
 sizeof(Qp0l_Ext_Ref_Types_Output_T)
 ) + 1000
       );

    if (NULL == (output200P =
   (Qp0l_RORO0200_Output_T *)malloc(outputBufSize)))
    {
 printf("No space available.\n");
 return;
    }

    /* Retrieve object references.                            */ 
    QP0LROR(output200P,
     outputBufSize,
     QP0LROR_RORO0200_FORMAT,
     (Qlg_Path_Name_T *) &path,
     &errorCode);

    /* Check if an error occurred.                            */
    if (errorCode.Bytes_Available != 0)
    {
 free(output200P);
 printf("Error occurred for RORO0200.\n");
 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 reoccurring, but this example will stop after this
       second retry.                                          */
    if (output200P->BytesReturned < output200P->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 QP0LROR.               */
        outputBufSize = output200P->BytesAvailable + 1000;

 if (NULL == (output200P = (Qp0l_RORO0200_Output_T *)
       realloc((void *)output200P,
        outputBufSize)))
 {
     printf("No space available.\n");
     return;
 }

 QP0LROR(output200P,
  outputBufSize,
  QP0LROR_RORO0200_FORMAT,
  (Qlg_Path_Name_T *) &path,
  &errorCode);

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

    /* Print some output.                                     */
    printf("Reference count:  %d\n",output200P->Count);
    printf("Jobs returned:    %d\n",output200P->JobsReturned);

    if (output200P->JobsReturned > 0)
    {
 jobP = (Qp0l_Job_Using_Object_T *)
   ((char *)output200P + output200P->JobsOffset);
 printf("First job's name: %10.10s %10.10s %6.6s",
        jobP->Name,
        jobP->User,
        jobP->Number);
    }

    free(output200P);

    return;
}

Example Output:

Reference count:  1
Jobs returned:    1
First job's name: JOBNAME123 JOBUSER123 123456
API introduced: V5R2

[ Back to top | UNIX-Type APIs | APIs by category ]