Qp0lGetAttr()--Get Attributes


  Syntax
 #include <Qp0lstdi.h>
 int Qp0lGetAttr
   (Qlg_Path_Name_T         *Path_Name,
    Qp0l_AttrTypes_List_t   *Attr_Array_ptr,
    char                    *Buffer_ptr,
    uint                     Buffer_Size_Provided,
    uint                    *Buffer_Size_Needed_ptr,    
    uint                    *Num_Bytes_Returned_ptr,
    uint                     Follow_Symlnk, ...);

  Service Program Name: QP0LLIB2

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

The Qp0lGetAttr() function gets one or more attributes, on a single call, for the object that is referred to by the input Path_Name. The object must exist, the user must have authority to it, and the requested attributes must be supported by the specific file system or object type. For each requested attribute that is not supported by the file system or object type, Qp0lGetAttr() returns zero in the Size of attribute data field, pointed to by the Buffer_ptr parameter, for that attribute.

Qp0lGetAttr() either returns the attributes of the symbolic link, or returns the attributes of the object that the symbolic link names. This depends upon the value of the Follow_Symlnk parameter.

Qp0lGetAttr() returns all times in seconds since the Epoch so that they are consistent with UNIX®-type APIs. The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If the IBM® i date is set prior to 1970, all time values are zero.


Parameters

Path_Name
(Input) The path name of the object for which attribute information is returned. This path name is in the Qlg_Path_Name_T format. For more information on this structure, see Path name format.

Attr_Array_ptr
(Input) A pointer to a structure listing the requested attributes returned for the object identified by the Path_Name parameter. Each entry in the array identifies an attribute, by a constant value, that Qp0lGetAttr() returns. The number of requested attributes field must equal the total number of constants. If the Attr_Array_ptr is NULL or if the Number of requested attributes field is zero, Qp0lGetAttr() returns all the attributes that the API supports that are available for the object. The format of this parameter follows.

Array of attribute constants. A list of predefined constants, each identifying a requested attribute. Qp0lGetattr() also returns one of these constants in the Attribute identification field, pointed to by the Buffer_ptr parameter. The constant must be used to identify the returned attribute because the attributes are returned in any order. Note that the Size of attribute data field, pointed to by the Buffer_ptr parameter, contains the total size of data that Qp0lGetattr() returns for the constants in this array. Valid values, and sizes of the returned attributes, follow:

0
QP0L_ATTR_OBJTYPE: (CHAR(10)) The object type. See the Control language topic collection for descriptions of all object types.

1
QP0L_ATTR_DATA_SIZE: (UNSIGNED BINARY(4)) The size in bytes of the data in this object. The size varies by object type and file system. This size does not include object headers or the size of extended attributes associated with the object. If this attribute is requested and the size cannot be represented in a BINARY(4) data type, Qp0lGetAttr() fails with errno [EOVERFLOW]. See QP0L_ATTR_DATA_SIZE_64 for objects whose data sizes are greater than BINARY(4).

2
QP0L_ATTR_ALLOC_SIZE: (UNSIGNED BINARY(4)) The number of bytes that have been allocated for this object. The allocated size varies by object type and file system. For example, the allocated size includes the object data size as shown in QP0L_ATTR_DATA_SIZE or QP0L_ATTR_DATA_SIZE_64 as well as any logically sized extents to accommodate anticipated future requirements for the object data. It may or may not include additional bytes for attribute information. If this size cannot be represented in a BINARY(4) data type, Qp0lGetAttr() fails with errno [EOVERFLOW]. See QP0L_ATTR_ALLOC_SIZE_64 for objects whose allocated sizes are greater than BINARY(4).

3
QP0L_ATTR_EXTENDED_ATTR_SIZE: (UNSIGNED BINARY(4)) The total number of extended attribute bytes.

4
QP0L_ATTR_CREATE_TIME: (UNSIGNED BINARY(4)) The time the object was created.

5
QP0L_ATTR_ACCESS_TIME: (UNSIGNED BINARY(4)) The time that the object's data was last accessed.

6
QP0L_ATTR_CHANGE_TIME: (UNSIGNED BINARY(4)) The time that the object's data or attributes were last changed.

7
QP0L_ATTR_MODIFY_TIME: (UNSIGNED BINARY(4)) The time that the object's data was last changed.

8
QP0L_ATTR_STG_FREE: (CHAR(1)) Whether the object's data has been moved offline, freeing its online storage. Valid values are:
9
QP0L_ATTR_CHECKED_OUT: Whether an object is checked out or not. When an object is checked out, other users can read and copy the object. Only the user who has the object checked out can change the object. The checkout format is defined in the Qp0lstdi.h header file as data type Qp0l_Checkout_t, and is described in the following table.

Flag. An indicator as to whether an object is checked out. Valid values are:

Reserved. A reserved field. This field must be set to binary zero.

Time checked out. The time the object was checked out. This field represents the number of seconds since the Epoch.

User to whom checked out. The user who has the object checked out. This field is blank if it is not checked out.

10
QP0L_ATTR_LOCAL_REMOTE: (CHAR(1)) Whether an object is stored locally or stored on a remote system. The decision of whether a file is local or remote varies according to the respective file system rules. Objects in file systems that do not carry either a local or remote indicator are treated as remote. Valid values are:

11
QP0L_ATTR_AUTH: The public and private authorities associated with the object.

When the QP0L_ATTR_AUTH attribute is requested, the attribute data is returned in the buffer in the following format. This format is defined in header file Qp0lstdi.h as data type Qp0l_Authority_General_t.

Array of users. The names and authorities of the users who are authorized to use the object.

Authorization list name. The name of the authorization list that is used to secure the named object. The value *NONE indicates that no authorization list is used in determining authority to the object.

Number of users. The number of users that are authorized to the object. This is the number of users returned in the array of users.

The QFileSvr.400 file system returns zero for the Number of users and zero for the Offset to array of users. If a primary group is specified, the Network File System (NFS) returns one for the Number of users.

Object owner. The name of the user profile that is the owner of the object or the following special value:

Offset to array of users. The offset to the names and authorities of the users who are authorized to use the object. This offset is relative to the start of the buffer pointed to by the Buffer_ptr parameter.

Primary group. The name of the user profile that is the primary group of the object or the following special values:

Reserved. A reserved field. This field must be set to binary zero.

Size of user entry field entry. The number of bytes returned for each user.

When the QP0L_ATTR_AUTH attribute is requested, the array of users is returned in the buffer in the following format. This format is defined in header file Qp0lstdi.h as data type Qp0l_Authority_Users_t.

Add (*ADD). Authority to add entries to the object. Valid values are:

Delete (*DELETE). Authority to remove entries from the object. Valid values are:

Execute (*EXECUTE). Authority to run a program or search a library or directory. Valid values are:

Exclude (*EXCLUDE). The user is prevented from accessing the object. Valid values are:

Object alter (*OBJALTER). Authority to change the attributes of an object, such as adding or removing triggers for a database file. Valid values are:

Object existence (*OBJEXIST). Authority to control the object's existence and ownership. Valid values are:

Object management (*OBJMGT). Authority to specify security, to move or rename the object, and to add members if the object is a database file. Valid values are:

Object operational (*OBJOPR). Authority to look at the object's attributes and to use the object as specified by the data authorities that the user has to the object. Valid values are:

Object reference (*OBJREF). Authority to specify the object as the first level in a referential constraint. Valid values are:

Read (*READ). Authority to access the contents of the object. Valid values are:

Reserved. A reserved field. This field must be set to binary zero.

Update (*UPDATE). Authority to change the content of existing entries in the object. Valid values are:

User data authority. The operation, use, or access that the user has to an object. Valid values follow:

User name. The name of a user authorized to use the object. This may be the name of the user profile or one of the following special values:



12
QP0L_ATTR_FILE_ID: (CHAR(16)) An identifier associated with the referred to object. A file ID can be used with Qp0lGetPathFromFileID() to retrieve an object's path name. The file ID is defined in header file Qp0lstdi.h as data type Qp0lFID_t.
13
QP0L_ATTR_ASP: (BINARY(2)) The auxiliary storage pool (ASP) in which the object is stored.

14
QP0L_ATTR_DATA_SIZE_64: (UNSIGNED BINARY(8)) The size in bytes of the data in this object. The size varies by object type and file system. This size does not include object headers or the size of extended attributes associated with the object. QP0L_ATTR_DATA_SIZE may be used for objects whose data size can be represented in a BINARY(4) data type.
15
QP0L_ATTR_ALLOC_SIZE_64: (UNSIGNED BINARY(8)) The number of bytes that have been allocated for this object. The allocated size varies by object type and file system. For example, the allocated size includes the object data size as shown in QP0L_ATTR_DATA_SIZE or QP0L_ATTR_DATA_SIZE_64 as well as any logically sized extents to accommodate anticipated future requirements for the object data. It may or may not include additional bytes for attribute information. QP0L_ATTR_ALLOC_SIZE may be used for objects whose allocated size can be represented in a BINARY(4) data type.
16
QP0L_ATTR_USAGE_INFORMATION: Fields indicating how often an object is used. Usage has different meanings according to the specific file system and according to the individual object types supported within a file system. Usage can indicate the opening or closing of a file or can refer to adding links, renaming, restoring, or checking out an object. The usage information format is defined in the Qp0lstdi.h header file as data type Qp0l_Usage_t and is shown in the following table.

Days used count. The number of days an object has been used. Usage has different meanings according to the specific file system and according to the individual object types supported within a file system. Usage can indicate the opening or closing of a file or can refer to adding links, renaming, restoring, or checking out an object. This count is incremented once each day that an object is used and is reset to zero by calling the Qp0lSetAttr() API.

Last used date. The number of seconds since the Epoch that corresponds to the date the object was last used. This field is zero when the object is created. If usage data is not maintained for the IBM i type or the file system to which an object belongs, this field is zero.

Reserved. A reserved field set to binary zeros.

Reset date. The number of seconds since the Epoch that corresponds to the date the days used count was last reset to zero (0). This date is set to the current date when the Qp0lSetAttr() API is called to reset the Days used count to zero.



17
QP0L_ATTR_PC_READ_ONLY: (CHAR(1)) Whether the object can be written to or deleted, have its extended attributes changed or deleted, or have its size changed. Valid values are:

18
QP0L_ATTR_PC_HIDDEN: (CHAR(1)) Whether the object can be displayed using an ordinary directory listing.

19
QP0L_ATTR_PC_SYSTEM: (CHAR(1)) Whether the object is a system file and is excluded from normal directory searches.

20
QP0L_ATTR_PC_ARCHIVE: (CHAR(1)) Whether the object has changed since the last time the file was examined.

21
QP0L_ATTR_SYSTEM_ARCHIVE: (CHAR(1)) Whether the object has changed and needs to be saved. It is set on when an object's change time is updated, and set off when the object has been saved.

22
QP0L_ATTR_CODEPAGE: (BINARY(4)) The code page derived from the coded character set identifier (CCSID) used for the data in the file or the extended attributes of the directory. If the returned value of this field is zero (0), there is more than one code page associated with the st_ccsid. If the st_ccsid is not a supported system CCSID, the st_codepage is set equal to the st_ccsid.

23
QP0L_ATTR_FILE_FORMAT: (CHAR(1)) The format of the stream file (*STMF). Valid values are:

24
QP0L_ATTR_UDFS_DEFAULT_FORMAT: (CHAR(1)) The default file format of stream files (*STMF) created in the user-defined file system. Valid values are:

25
QP0L_ATTR_JOURNAL_INFORMATION: Basic Journaling information for this object.

Note: This attribute is only returned if the object has ever been journaled.

The journaling information format is defined in the Qp0lstdi.h header file as data type Qp0l_Journal_Info_t and is shown in the following table:

For extended journaling information see QP0L_ATTR_JOURNAL_EXTENDED_INFORMATION.

Current or last journal library name. If the value of the journaling status is QP0L_JOURNALED, then this field contains the name of the library containing the currently used journal. If the value of the journaling status is QP0L_NOT_JOURNALED, then this field contains the name of the library containing the last used journal. All bytes in this field will be set to binary zero if this object has never been journaled.

Current or last journal name. If the value of the journaling status is QP0L_JOURNALED, then this field contains the name of the journal currently being used. If the value of the journaling status is QP0L_NOT_JOURNALED, then this field contains the name of the journal last used for this object. All bytes in this field will be set to binary zero if this object has never been journaled.

Journal identifier (JID). This field associates the object being journaled with an identifier that can be used on various journaling-related commands and APIs.

Journaling status. Current journaling status of the object. This field will be one of the following values:

Last journaling start time. The number of seconds since the Epoch that corresponds to the last date and time for which the object had journaling started for it. This field will be set to binary zero if this object has never been journaled.

Options. This field describes the current journaling options. This field is composed of several bit flags and contains one or more of the following bit values:



26
QP0L_ATTR_ALWCKPWRT: (CHAR(1)) Whether a stream file (*STMF) can be shared with readers and writers during the save-while-active checkpoint processing. Valid values are:

27
QP0L_ATTR_CCSID: (BINARY(4)) The CCSID of the data and extended attributes of the object.

28
QP0L_ATTR_SIGNED: (CHAR(1)) Whether an object has an IBM i digital signature. This attribute is only returned for *STMF objects. Valid values are:

29
QP0L_ATTR_SYS_SIGNED: (CHAR(1)) Whether the object was signed by a source that is trusted by the system. This attribute is only returned for *STMF objects. Note: this attribute is not returned if the QP0L_ATTR_SIGNED attribute has the value QP0L_NOT_SIGNED. Valid values are:

30
QP0L_ATTR_MULT_SIGS: (CHAR(1)) Whether an object has more than one IBM i digital signature. This attribute is only returned for *STMF objects. Note: this attribute is not returned if the QP0L_ATTR_SIGNED attribute has the value QP0L_NOT_SIGNED. Valid values are:

31
QP0L_ATTR_DISK_STG_OPT (CHAR(1)) This option should be used to determine how auxiliary storage is allocated by the system for the specified object. This option can only be specified for stream files in the "root" (/), QOpenSys and user-defined file systems. This option will be ignored for *TYPE1 stream files. Valid values are:

32
QP0L_ATTR_MAIN_STG_OPT: (CHAR(1)) This option should be used to determine how main storage is allocated and used by the system for the specified object. This option can only be specified for stream files in the "root" (/), QOpenSys and user-defined file systems. Valid values are:

33
QP0L_ATTR_DIR_FORMAT: (CHAR(1)) The format of the specified directory object. Valid values are:

34
QP0L_ATTR_AUDIT: (CHAR(10)) The auditing value associated with the object.

Valid values are:



35
QP0L_ATTR_CRTOBJSCAN: (CHAR(1)) Whether the objects created in a directory will be scanned when exit programs are registered with any of the integrated file system scan-related exit points.

The integrated file system scan-related exit points are:

This attribute can only have been specified for directories in the "root" (/), QOpenSys and user-defined file systems. Even though this attribute can be set for *TYPE1 and *TYPE2 directories, only objects which are in file systems that have completely converted to the *TYPE2 directory format will actually be scanned, no matter what value is set for this attribute.

Valid values are:



36
QP0L_ATTR_SCAN: (CHAR(1)) Whether the object will be scanned when exit programs are registered with any of the integrated file system scan-related exit points.

The integrated file system scan-related exit points are:

This attribute can only have been specified for stream files in the "root" (/), QOpenSys and user-defined file systems. Even though this attribute can be set for objects in *TYPE1 and *TYPE2 directories, only objects which are in file systems that have completely converted to the *TYPE2 directory format will actually be scanned, no matter what value is set for this attribute.

Valid values are:



37
QP0L_ATTR_SCAN_INFO: Scan information for this object. The scan information format is defined in the qp0lstdi.h header file as data type Qp0l_Scan_Info_t and is shown in the following table:

Note: Historical information is only kept for the last two CCSIDs which have been scanned, as well as the binary scan indication.

Binary scan. This indicates if the object has been scanned in binary mode when it was previously scanned. This field will be one of the following values:

CCSID 1. A CCSID value that the object has been scanned in if it was previously scanned in a CCSID. If the object scan status is QP0L_SCAN_SUCCESS, then the object was successfully scanned in this CCSID. If the object scan status is QP0L_SCAN_FAILURE, then the object failed the scan in this CCSID. A value of 0 means this field does not apply.

CCSID 2. A CCSID value that the object has been scanned in if it was previously scanned in a CCSID. If the object scan status is QP0L_SCAN_SUCCESS, then the object was successfully scanned in this CCSID. If the object scan status is QP0L_SCAN_FAILURE, then this field will be 0. A value of 0 means this field does not apply.

Reserved. A reserved field. This field will be set to binary zero.

Scan signatures different. The scan signatures give an indication of the level of the scanning software support. For more information, see Scan Key List and Scan Key Signatures in Integrated File System Scan on Open Exit Program.

When an object is in an independent ASP group, the object scan signature is compared to the associated independent ASP group scan signature. When an object is not in an independent ASP group, the object scan signature is compared to the global scan signature value. This field will be one of the following values:

Scan status. The scan status associated with this object. This field will be one of the following values:



38
QP0L_ATTR_ALWSAV: (CHAR(1)) Whether the object can be saved or not. Valid values are:

39
QP0L_ATTR_RSTDRNMUNL: (CHAR(1)) Restricted renames and unlinks for objects within a directory. Objects can be linked into a directory that has this attribute set on, but cannot be renamed or unlinked from it unless one or more of the following are true for the user performing the operation:
  • The user is the owner of the object.
  • The user is the owner of the directory.
  • The user has *ALLOBJ special authority.
This restriction only applies to directories. Other types of object can have this attribute on, however, it will be ignored. This attribute is equivalent to the S_ISVTX mode bit for an object. Valid values are:

40
QP0L_ATTR_JOURNAL_EXTENDED_INFORMATION: Extended Journaling information for this object.

Note: This attribute is only returned if the object has ever been journaled.

The journaling information format is defined in the Qp0lstdi.h header file as data type Qp0l_Journal_Extended_Info_t and is shown in the following table:

Apply journaled changes required. Whether the object was restored with partial transactions which would require an Apply Journaled Changes (APYJRNCHG) command to complete the transaction. A partial transaction can occur if an object was saved using save-while-active requesting that transactions with pending record changes do not have to reach a commit boundary before the object is saved. The valid values are:

Current or last journal library name. If the value of the journaling status is QP0L_JOURNALED, then this field contains the name of the library containing the currently used journal. If the value of the journaling status is QP0L_NOT_JOURNALED, then this field contains the name of the library containing the last used journal. All bytes in this field will be set to binary zero if this object has never been journaled.

Current or last journal name. If the value of the journaling status is QP0L_JOURNALED, then this field contains the name of the journal currently being used. If the value of the journaling status is QP0L_NOT_JOURNALED, then this field contains the name of the journal last used for this object. All bytes in this field will be set to binary zero if this object has never been journaled.

Journal identifier (JID). This field associates the object being journaled with an identifier that can be used on various journaling-related commands and APIs.

Journaling status. Current journaling status of the object. This field will be one of the following values:

Last journaling start time. The number of seconds since the Epoch that corresponds to the last date and time for which the object had journaling started for it. This field will be set to binary zero if this object has never been journaled.

Options. This field describes the current journaling options. This field is composed of several bit flags and contains one or more of the following bit values:

Reserved. A reserved field. This field will be set to binary zero.

Rollback was ended. Whether the object had rollback ended prior to completion of a request to roll back a transaction. The valid values are:

Starting journal receiver ASP device. The name of the ASP for the library that contains the starting journal receiver. This field will be blank if no information is available. The valid values are:

Starting journal receiver for apply. The oldest journal receiver needed to successfully Apply Journaled Changes (APYJRNCHG). When the Apply journaled Changes required field is set to QP0L_APYJRNCHG_REQ_YES the journal receiver contains the journal entries representing the start of the partial transaction. Otherwise; the journal receiver contains the journal entries representing the start-of-the-save operation. This field will be blank if no information is available.

Starting journal receiver library name. The name of the library that contains the journal receiver. This field will be blank if no information is available.

41
QP0L_ATTR_CRTOBJAUD: (CHAR(10)) The create object auditing value associated with the directory. This is the auditing value given to any objects created in the directory. Valid values are:

42
QP0L_ATTR_SYSTEM_USE: (CHAR(1)) Whether the file has a special use by the system. This attribute is valid only for stream files. Possible values are:


43
QP0L_ATTR_TEMPORARY: (CHAR(1)) Whether the object is a temporary object. Possible values are:


44
QP0L_ATTR_UDFS_TEMPORARY: (CHAR(1)) Whether the objects in the UDFS are temporary objects. Possible values are:


Start of change 45
QP0L_ATTR_UDFS_PREFERRED_STORAGE_UNIT: (CHAR(1)) The preferred storage media for the objects in the UDFS. Possible values are:


46
QP0L_ATTR_INHERIT_ALWCKPWRT: (CHAR(1)) Whether new objects created within a directory should inherit the save-while-active checkpoint processing options of its parent. Possible values are:


47
QP0L_ATTR_SYS_RESTRICTS_SAVE: (CHAR(1)) Whether the system prevents the object from being saved. Possible values are:


300
QP0L_ATTR_SUID: (CHAR(1)) Set effective user ID (UID) at execution time. This value is ignored if the specified object is a directory. Valid values are:

301
QP0L_ATTR_SGID: (CHAR(1)) Set effective group ID (GID) at execution time. Valid values are:

Number of requested attributes. The total number of requested attributes that Qp0lGetAttr() returns. This field is required when the Attr_Array_ptr parameter is not NULL and must equal the number of constants in the array to which it points. When this field is zero, Qp0lGetAttr() returns all the attributes that are supported by the API and that are available for the object.

Buffer_ptr
(Input) A pointer to a buffer that the caller allocates for Qp0lGetAttr() to return the requested data. The caller also sets the Buffer_Size_Provided parameter to the number of bytes that are allocated for this buffer.

If the buffer provided is not large enough to hold all of the requested data, Qp0lGetAttr() fills the buffer with as much data as possible and sets the value pointed to by the Buffer_Size_Needed_ptr parameter equal to the number of bytes required for all of the requested data to be returned.

When the Buffer_ptr is NULL, Qp0lGetAttr() returns the total number of bytes needed to hold all of the requested attributes and sets the Buffer_Size_Needed_ptr parameter to point to this value.

Qp0lGetAttr() identifies each entry that it returns in the buffer with the constant that the user supplied in the input structure pointed to by the Attr_Array_ptr parameter. Qp0lGetAttr() returns this constant in the Attribute identification field. The constant must be used to identify the returned attribute because the attributes are returned in any order.

Qp0lGetAttr() fills the buffer with an entry for each requested attribute in the following format:

Attribute data. The attribute data that was requested.

Attribute identification. The constant that identifies the returned attribute. Valid values follow and are the same constants as provided by the caller of Qp0lGetAttr(), pointed to by the Attr_Array_ptr parameter.

See the Attr_Array_ptr parameter for descriptions of each of these attribute values.

Offset to next attribute entry. The offset to the next attribute entry in the buffer. This offset is relative to the start of the buffer. An offset of zero means that no more attribute entries follow.

Reserved. A reserved field set to binary zero.

Size of attribute data. The total size of all the data for this attribute. The special value of 0 in this field indicates that the attribute is not supported by the file system in which the object is stored. The attribute data is padded with hexadecimal zeros. The size indicated in this field does not include the padding bytes.

Buffer_Size_Provided
(Input) The number of bytes the caller allocates in a buffer for the return of requested data. The buffer is pointed to by the Buffer_ptr parameter.

If this size is set to zero or is not large enough to hold all of the requested data, Qp0lGetAttr() fills the buffer with as much data as possible and sets the value pointed to by the Buffer_Size_Needed_ptr parameter equal to the number of bytes required for all of the requested data to be returned.

When determining the appropriate allocation, the caller should assume that the returned attribute data will be aligned on a minimum of an 8-byte boundary.

Buffer_Size_Needed_ptr
(Output) A pointer to the number of bytes that the caller needs to allocate for Qp0lGetAttr() to return all of the requested data.

Num_Bytes_Returned_ptr
(Output) A pointer to the actual number of bytes of data returned in the user buffer. This field is zero if the Buffer_ptr parameter is NULL.

Follow_Symlnk
(Input) If the last component in the Path_Name is a symbolic link, this parameter determines if the symbolic link or the path contained in the symbolic link is acted upon: Valid values are:

Authorities

Note: Adopted authority is not used.





Return Value



Error Conditions

If Qp0lGetAttr() is not successful, errno indicates one of the following errors:

Additionally, if interaction with a file server is required to access the object, errno could also indicate one of the following errors:


Error Messages

The following messages may be sent from this function:



Usage Notes

  1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:

    • Where multiple threads exist in the job.

    • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
      • "Root" (/)
      • QOpenSys
      • User-defined
      • QNTC
      • QSYS.LIB
      • Independent ASP QSYS.LIB
      • QOPT
      • Network File System
      • QFileSvr.400

  2. "Root" (/), QOpenSys, and User-Defined File System Differences

    The QP0L_ATTR_ALLOC_SIZE and QP0L_ATTR_ALLOC_SIZE_64 values can be influenced by the setting of the disk storage option attribute. See QP0L_ATTR_DISK_STG_OPT for more information.

  3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

    Qp0lGetAttr() could return zero for the QP0L_ATTR_ACCESS_TIME value (in the buffer area) under some conditions.

    See the CL programming topic for more information regarding which object types maintain usage information that is returned for the QP0L_ATTR_USAGE_INFORMATION attribute.

    When Qp0lGetAttr() is performed on a physical file member, the QP0L_ATTR_JOURNAL_INFORMATION or QP0L_ATTR_JOURNAL_EXTEND_INFORMATION attribute will contain journaling information applicable to the physical file that contains the member.

  4. QFileSvr.400 File System Differences

    If only the QP0L_ATTR_AUDIT or QP0L_ATTR_CRTOBJAUD attributes are requested, the QSECOFR user profiles on the source and target system must be enabled, and their passwords must match for the operation to succeed.

  5. Network File System Differences

    If the user has the appropriate authority when requesting the QP0L_ATTR_AUDIT attribute for objects in the Network File System, the value QP0L_AUD_NONE will always be returned.

  6. To work with any of the times which are returned from this interface in seconds since the Epoch, there are various interfaces in the ILE C/C++ Runtime Library FunctionsLink to PDF that can be used; for example, localtime(), ctime(), gmtime() etc.

Related Information


Example

The following example shows a call to Qp0lGetAttr(). The example also shows a call to Qp0lSaveStgFree().

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

/*****************************************************************/
#include "Qp0lstdi.h"
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <sys/types.h>
#include <qusec.h>
#include <time.h>

int Save(Qp0l_Pathnames_t *Path_name_ptr)
{
  /**************************************************************/
  /* No function here in the example                            */
  /**************************************************************/
};

void SaveAnObject(Qp0l_Pathnames_t *Path_name_ptr,
                  int              *Return_code_ptr,
                  int              *Return_value_ptr,
                  void             *Function_CtlBlk_ptr)
{
  /**************************************************************/
  /* This function saves a file and its hard links to tape.     */
  /**************************************************************/
  int rc;

  if ((Path_name_ptr == (Qp0l_Pathnames_t *)NULL) ||
      (Path_name_ptr->Number_Of_Names == 0))
  {
    printf("In User Exit Program with null Path \n");
  }
  else
  {
    /* This example calls a function (Save) that could call the  */
    /* Save Object (QsrSave) API.  The QsrSave API is designed to */
    /* save a copy of one or more objects that can be used in the */
    /* integrated file system.  For details on using QsrSave, see  */
    /* the Backup and Recovery API part.                          */

    rc = (Save(Path_name_ptr));
    
    *Return_code_ptr = rc;
    *Return_value_ptr = errno;
    
    if (rc == 0)
    {
      /* Other processing for a successfully saved object. */
    }
    else
    {
      /* Optional processing such as storing information   */
      /* to be returned to the caller in the function      */
      /* control block area, or building a list of the     */
      /* files whose save attempts failed, or other.       */
    }
  }
  return;
}                               /* end SaveAnObject exit program */

int main (int argc, char *argv[])
{
#define MYPN "ADIR/ASTMF"
  const char US_const[3]= "US";
  const char Language_const[4]="ENU";
  const char Path_Name_Del_const[2] = "/";

  struct pnstruct
  {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[1];
  };
  struct pnstruct pns;
  struct pnstruct *pns_ptr = NULL;

  struct attrStruct
  {
    Qp0l_AttrTypes_List_t  attr_struct;
    uint AttrTypes[10];
  };
  struct attrStruct Attr_types_ptr;
  Qp0l_Attr_Header_t *attrPtr;
  char *attrValp;

  Qp0l_StgFree_Function_t  User_function;

  struct
  {
    uint    AnyData_to_the_exitprogram;
    uint    AnyData_not_processed_by_the_API;
  } CtlBlkAreaName;

  time_t mytime;
  char BufferArea[250];
  unsigned int buff_size_provided;
  unsigned int buff_size_needed = 0;
  unsigned int num_bytes_returned = 0;
  unsigned int follow_sym;
  int done=0;
  int rc;
  int returned_data_index = 0;

  /**************************************************************/
  /* Initialize Get Attributes Parameters                       */
  /**************************************************************/
  memset((void*)&pns, 0x00, sizeof(struct pnstruct));
  pns.qlg_struct.CCSID = 37;
  memcpy(pns.qlg_struct.Country_ID,US_const,2);
  memcpy(pns.qlg_struct.Language_ID,Language_const,3);
  pns.qlg_struct.Path_Type = 0;
  pns.qlg_struct.Path_Length = sizeof(MYPN)-1;
  memcpy(pns.qlg_struct.Path_Name_Delimiter,Path_Name_Del_const,1);
  memcpy(pns.pn,MYPN,sizeof(MYPN));
  memset((void *)&Attr_types_ptr, 0x00,sizeof(struct attrStruct));
  pns_ptr = &pns;

  Attr_types_ptr.attr_struct.Number_Of_ReqAttrs = 2;
  Attr_types_ptr.AttrTypes[0] = QP0L_ATTR_ACCESS_TIME;
  Attr_types_ptr.AttrTypes[1] = QP0L_ATTR_STG_FREE;

  buff_size_provided = 250;

  follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Call the Qp0lGetAttr() API to retrieve attributes to       */
  /* determine if selection criteria can be met for calling     */
  /* the Qp0lSaveStgFree() API.                                 */
  /**************************************************************/
  rc = Qp0lGetAttr((Qlg_Path_Name_T *)&pns,
                   (Qp0l_AttrTypes_List_t *)&Attr_types_ptr,
                   BufferArea,
                   buff_size_provided,
                   &buff_size_needed,
                   &num_bytes_returned,
                   follow_sym);
  if (rc == 0)                      /* check API return code */
  {
    /* Must first check if any data was returned. */
    if (num_bytes_returned > 0)
    {
      attrPtr = (Qp0l_Attr_Header_t *)BufferArea;
      while(!done)
      {
        attrValp = (char *)attrPtr +
          sizeof(Qp0l_Attr_Header_t);  /* Point to attr value   */
        /******************************************************/
        /* The following code prints the two attributes that  */
        /* were returned.  Add more code here, for example,   */
        /* to determine if the returned attributes meet       */
        /* the criteria or policies for storage freeing.      */
        /******************************************************/
        printf ("******************************************\n");
        printf ("Attr ID #%d = %d - ",
                returned_data_index,
                attrPtr->Attr_ID);
        if(attrPtr->Attr_Size > 0)
        {
          switch (attrPtr->Attr_ID)
          {
            case QP0L_ATTR_ACCESS_TIME:
                printf("QP0L_ATTR_ACCESS_TIME\n");
                memcpy((void *)&mytime,
                       (void *)attrValp,
                       attrPtr->Attr_Size);
                printf ("%s", ctime(&mytime));
                break;
            case QP0L_ATTR_STG_FREE:
                printf ("QP0L_ATTR_STG_FREE\n");
                switch (attrValp[0])
                {
                  case QP0L_SYS_STG_FREE:
                      printf ("--Is storage freed--\n");
                      break;
                  case QP0L_SYS_NOT_STG_FREE:
                      printf ("--Is not storage freed--\n");
                      break;
                  default:
                      printf ("Invalid data: %d.\n",
                              attrValp[0]);
                      break;
                }
                break;
            default:
                printf ("Undefined return type (attr id unknown.)\n");
                break;
          }                      /* end switch                   */
        }
        else
          printf("Attribute has no value\n");
        printf("***Size of this attr's data: %d\n",
               attrPtr->Attr_Size);
        printf("***Offset to next attr: %d\n",
               attrPtr->Next_Attr_Offset);
        ++returned_data_index;
        if(attrPtr->Next_Attr_Offset > 0) /* If more data        */
          attrPtr = (Qp0l_Attr_Header_t *) /* Set attribute      */
            &(BufferArea[attrPtr->Next_Attr_Offset]); /* pointer */
        else                    /* No more data                  */
          done = 1;             /* End the loop                  */
      }

    /**********************************************************/
    /* Initialize Save Storage Free Parameters.  The path     */
    /* name parameter was already initialized as part of the  */
    /* call to Qp0lGetAttr() API and is assumed, in this      */
    /* example, to be the same pathname.  Both APIs require   */
    /* the same path name format.                             */
    /**********************************************************/
      memset((void *)&User_function,0x00,sizeof(Qp0l_StgFree_Function_t));
      User_function.Mltthdacn[0] = QP0L_MLTTHDACN_NOMSG;
      User_function.Function_Type = QP0L_USER_FUNCTION_PTR;
      User_function.Procedure = &SaveAnObject;
      
      rc = Qp0lSaveStgFree((Qlg_Path_Name_T *)&pns,
                           &User_function,
                           &CtlBlkAreaName);
      if(rc == 0)
        printf("Qp0lSaveStgFree() Successful!");
      else
      {/* Unsuccessful return from Qp0lSaveStgFree() API.  */
      /* The following code prints the errno value message.  */
        rc = errno;
        printf("ERROR on Qp0lSaveStgFree(): error = %d\n", rc);
        perror("Error message");
      }
    }                           /* if (num_bytes_returned > 0)   */
    else
      rc = EUNKNOWN;
  }                 /* end rcGA == 0, Qp0lGetAttr() was successful */
  else
  {
    rc = errno;
    printf("ERROR on Qp0lGetAttr(): error = %d\n", rc);
    perror("Error message");
  }
  return(rc);
} /* end main */

API introduced: V4R3