Qp0lCvtPathToQSYSObjName()-- Resolve Integrated File System Path Name into QSYS Object Name

 #include <qp0lstdi.h>

 void Qp0lCvtPathToQSYSObjName(
                               Qlg_Path_Name_T *path_name,
                               void            *qsys_info,
                               char             format_name[8],
                               uint             bytes_provided,
                               uint             desired_CCSID,
                               void            *error_code);  

The Qp0lCvtPathToQSYSObjName() 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 error_code structure. Note that the API does not verify that the object exists.

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:

/qsys.lib/test*.file/*.*

the API will return:

• Library name: QSYS
• Library type: *LIB
• Object name: TEST*
• Object type: *FILE
• Member name: *ALL
• Member type: *ALL
• ASP name: *SYSBAS

Note that path name components that follow one containing a wildcard character are ignored.

If less than 8 bytes are supplied for the error_code structure, errors will cause an exception to be returned to the caller.

Parameters

path_name

(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 Path name format. If the path_name parameter is NULL or points to invalid storage, a CPFA0CE error message is returned.

qsys_info

(Output) A pointer of type void * that refers to a structure that contains the object name. The format of the data returned is specified by the format_name parameter. If the qsys_info parameter is NULL or points to invalid storage, a CPF24B4 error message is returned.

format_name

(Input) An 8-byte character array that indicates how the data will be formatted in the qsys_info parameter that is returned. The format is as follows:

QSYS0100

For the format of this structure, see the section Returned Data Format.

If the format_name parameter is NULL or points to invalid storage, a CPF24B4 error message is returned.

bytes_provided

(Input) The number of bytes of data provided in the structure referred to by the qsys_info parameter. This value must be at least 8, or a CPF3C24 error message will be returned.

desired_CCSID

(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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Authorities

Note: Adopted authority is not used.

Returned Data Format

The following table describes the format of the data returned in the qsys_info parameter if the QSYS0100 format is specified. For details on the fields of the structure, see the section Field Descriptions.

Field Descriptions

ASP Name. 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.

Bytes_Available. The total number of bytes required to hold all of the data available in the qsys_info parameter.

Bytes_Returned. The number of bytes actually returned in the caller's buffer for the qsys_info parameter.

CCSID_Out. The CCSID that the returned text is in. This may be different than the desired_CCSID 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.

Lib_Name. The name of the library that the path name refers to. This field is NULL terminated.

Lib_Type. The type of the object, beginning with an * (asterisk). This field will return either *LIB or *ALL. This field is NULL terminated.

Mbr_Name. The name of the member that the path name refers to. This field is NULL terminated, and could be all NULL (all x'00').

Mbr_Type. 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').

Obj_Name. The name of the object that the path name refers to. This field is NULL terminated, and could be all NULL (all x'00').

Obj_Type. 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').

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.

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').

If the object name is not an *FILE object with members, then the Mbr_Name field is NULL (all x'00').

If the object name contains quoted strings, the characters within the strings will not be converted to uppercase.

Error Conditions

None.

Error Messages

Usage Notes

1. This API will fail and return the error message CPFA0A8 when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • 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:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined file system
     • QSYS.LIB
     • Independent ASP QSYS.LIB
   
   
2. This API ignores trailing blank spaces at the end of a path name.

   For example, if the path name is

   "/qsys.lib/fred.lib/foo.file/abc.mbr      "
   

   the trailing blank spaces will be ignored. Thus, the above path name is equivalent to

   "/qsys.lib/fred.lib/foo.file/abc.mbr"
   

Related Information

• The <qp0lstdi.h> file (see Header Files for UNIX-Type Functions)
• QlgQp0lCvtPathToQSYSObjName()-- Resolve Integrated File System Path Name into QSYS Object Name

Example

See Code disclaimer information for information pertaining to code examples.

The following example program gets the three-part QSYS name from an integrated file system path name passed to it.

#include <qp0lstdi.h>        /* For Qp0lCvtPathToQSYSObjName        */
                             /*     type Qp0l_QSYS_Info_t           */
                             /*     type Qlg_Path_Name_T            */
#include <qusec.h>           /* For type Qus_EC_T                   */
#include <stdlib.h>
#include <stdio.h>

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->CCSID = 37;
    memcpy(path_name->Country_ID, US_const, 2);
    memcpy(path_name->Language_ID, Language_const, 3);
    path_name->Path_Type = 0;
    path_name->Path_Length = strlen(fname);
    memcpy(path_name->Path_Name_Delimiter, Path_Name_Del_const, 1);
    memcpy( &(((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(&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,
                            &error_code);

    if (error_code.Bytes_Available > 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);
}

Output:

Library name: JEROLD
Library type: *LIB
Object name:  QCSRC
Object type:  *FILE
Member name:  TESTCONV
Member type:  *MBR
Asp name:     *SYSBAS