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 i5/OS 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.

Attribute array pointer
Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Number of requested attributes
4	4	ARRAY(*) of BINARY(4)	Array of attribute constants

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 Control Language (CL) information in the iSeries Information center for descriptions of all iSeries 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]. Refer to 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]. Refer to 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:

x'00'	QP0L_SYS_NOT_STG_FREE: The object's data is not offline.
x'01'	QP0L_SYS_STG_FREE: The object's data is offline.

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.

Checkout Format
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(1)	Flag indicating whether an object is checked out
1	1	CHAR(10)	User to whom checked out
11	B	CHAR(1)	Reserved
12	C	BINARY(4)	Time checked out

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

x'00'	QP0L_NOT_CHECKED_OUT: The object is not checked out.
x'01'	QP0L_CHECKED_OUT: The object is checked out.

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:

x'01'	QP0L_LOCAL_OBJ: The object's data is stored locally.
x'02'	QP0L_REMOTE_OBJ: The object's data is on a remote system.

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.

General Authority Format
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(10)	Object owner
10	0A	CHAR(10)	Primary group
20	14	CHAR(10)	Authorization list name
30	1E	CHAR(10)	Reserved
40	28	BINARY(4)	Offset to array of users
44	2C	BINARY(4)	Number of users
48	30	BINARY(4)	Size of user entry field entry
52	34	CHAR(12)	Reserved
		ARRAY(*)	Array of users

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:

*NOUSRPRF

This special value is used by the Network File System to indicate that there is no user profile on the local iSeries server with a user ID (UID) matching the UID of the remote object.

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:

*NONE	The object does not have a primary group.
*NOUSRPRF	This special value is used by the Network File System to indicate that there is no user profile on the local server with a group ID (GID) matching the GID of the remote object.

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.

Data and Object Authority Format
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(10)	User name
10	0A	CHAR(10)	User data authority
Object rights
20	14	CHAR(1)	Object management
21	15	CHAR(1)	Object existence
22	16	CHAR(1)	Object alter
23	17	CHAR(1)	Object reference
24	18	CHAR(10)	Reserved
Data rights
34	22	CHAR(1)	Object operational
35	23	CHAR(1)	Read
36	24	CHAR(1)	Add
37	25	CHAR(1)	Update
38	26	CHAR(1)	Delete
39	27	CHAR(1)	Execute
40	28	CHAR(1)	Exclude
41	29	CHAR(7)	Reserved

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

0	The user does not have add data rights.
1	The user does have add data rights.

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

0	The user does not have delete data rights.
1	The user does have delete data rights.

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

0	The user does not have execute data rights.
1	The user does have execute data rights.

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

0	The user does not have exclude data rights.
1	The user does have exclude data rights.

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

0	The user does not have alter object rights.
1	The user does have alter object rights.

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

0	The user does not have object existence rights.
1	The user does have object existence rights.

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:

0	The user does not have object management rights.
1	The user does have object management rights.

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:

0	The user does not have object operational rights.
1	The user does have object operational rights.

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

0	The user does not have object reference rights.
1	The user does have object reference rights.

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

0	The user does not have read data rights.
1	The user does have read data rights.

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:

0	The user does not have update data rights.
1	The user does have update data rights.

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

*RWX	Allows all operations on the object except those that are limited to the owner or controlled by the object rights.
*RW	Allows access to the object attributes and allows the object to be changed. The user cannot use the object.
*WX	Allows use of the object and allows the object to be changed. The user cannot access the object attributes.
*R	Allows access to the object attributes.
*W	Allows the object to be changed.
*X	Allows the use of the object.
*EXCLUDE	All operations on the object are prohibited.
*NONE	Displayed by the system when the user does not have any data authorities.
USER DEF	Displayed by the system when the specific data authorities do not match any of the predefined data authority levels above.

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:

*NOUSRPRF	The authorities of either the owner or the primary group of the object for which the profile name could not be determined. This value is used by the Network File System only. It indicates that the user ID (UID) or the group ID (GID) for the remote object does not match any profile on the local iSeries server with that UID or GID.
*NTWIRF	The authorities of the NetWare Inherited Rights Filter for the object. This value is only used by the QNetWare file system.
*NTWEFF	The NetWare effective rights to the object. This value is only used by the QNetWare file system.
*PUBLIC	The authorities of users who are not specifically named and who are not in the object's authorization list.

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

Qp0l_Usage_t
Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Reset date
4	4	BINARY(4)	Last used date
8	8	BINARY(4)	Days used count
12	C	CHAR(4)	Reserved

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 i5/OS 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:

x'00'	QP0L_PC_NOT_READONLY: The object can be changed.
x'01'	QP0L_PC_READONLY: The object cannot be changed.

18

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

x'00'	QP0L_PC_NOT_HIDDEN: The object is not hidden.
x'01'	QP0L_PC_HIDDEN: The object is hidden.

19

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

x'00'	QP0L_PC_NOT_SYSTEM: The object is not a system file.
x'01'	QP0L_PC_SYSTEM: The object is a system file.

20

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

x'00'	QP0L_PC_NOT_CHANGED: The object has not changed.
x'01'	QP0L_PC_CHANGED: The object has changed.

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.

x'00'	QP0L_SYSTEM_NOT_CHANGED: The object has not changed and does not need to be saved.
x'01'	QP0L_SYSTEM_CHANGED: The object has changed and does need to be 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:

x'00'

QP0L_FILE_FORMAT_TYPE1: The object has the same format as *STMF objects created on releases prior to Version 4 Release 4. It has a minimum object size of 4096 bytes and a maximum object size of approximately Start of change

128

gigabytes.

x'01'

QP0L_FILE_FORMAT_TYPE2: A QP0L_FILE_FORMAT_TYPE2 (*TYPE2) *STMF has high performance file access and was new in Version 4 Release 4 of i5/OS (OS/400). It has a minimum object size of 4096 bytes and a maximum object size of approximately one terabyte in the "root" (/), QOpenSys and user-defined file systems. Otherwise, the maximum is approximately 256 gigabytes. A *TYPE2 *STMF is capable of memory mapping as well as the ability to specify an attribute to optimize disk storage allocation.

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:

x'00'

QP0L_UDFS_DEFAULT_TYPE1: The stream file (*STMF) has the same format as *STMFs created on releases prior to Version 4 Release 4 of i5/OS (OS/400). It has a minimum object size of 4096 bytes and a maximum object size of approximately 256 gigabytes.

x'01'

QP0L_UDFS_DEFAULT_TYPE2: A *TYPE2 *STMF has high performance file access and was new in Version 4 Release 4 of i5/OS (OS/400). It has a minimum object size of 4096 bytes and a maximum object size of approximately one terabyte in the "root" (/), QOpenSys and user-defined file systems. Otherwise, the maximum is approximately 256 gigabytes. A *TYPE2 *STMF is capable of memory mapping as well as the ability to specify an attribute to optimize disk storage allocation.

25

QP0L_ATTR_JOURNAL_INFORMATION: Basic Journaling information for this object. 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:

Qp0l_Journal_Info_t
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(1)	Journaling status
1	1	CHAR(1)	Options
2	2	CHAR(10)	Journal identifier (JID)
12	0C	CHAR(10)	Current or last journal name
22	16	CHAR(10)	Current or last journal library name
32	20	BINARY(4), UNSIGNED	Last journaling start time

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:

x'00'	QP0L_NOT_JOURNALED: The object is currently not being journaled.
x'01'	QP0L_JOURNALED: The object is currently being journaled.

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:

x'80'	QP0L_JOURNAL_SUBTREE: When this flag is returned, this object is a directory with IFS journaling subtree semantics. New objects created within this directory's subtree will inherit the journaling attributes and options from this directory.
x'08'	QP0L_JOURNAL_OPTIONAL_ENTRIES: When journaling is active, entries that are considered optional are journaled. The list of optional journal entries varies for each object type. See the Integrated file system information in the Files and file systems topic for information regarding these optional entries for various objects.
x'20'	QP0L_JOURNAL_AFTER_IMAGES: When journaling is active, the image of the object after a change is journaled.
x'40'	QP0L_JOURNAL_BEFORE_IMAGES: When journaling is active, the image of the object prior to a change is journaled.

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:

x'00'	QP0L_NOT_ALWCKPWRT: The object can be shared with readers only.
x'01'	QP0L_ALWCKPWRT: The object can be shared with readers and writers.

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 i5/OS digital signature. This attribute is only returned for *STMF objects. Valid values are:

x'00'	QP0L_NOT_SIGNED: The object does not have an i5/OS digital signature.
x'01'	QP0L_SIGNED: The object does have an i5/OS digital signature.

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:

x'00'	QP0L_SYSTEM_SIGNED_NO: (CHAR(1)) None of the signatures came from a source that is trusted by the system.
x'01'	QP0L_SYSTEM_SIGNED_YES: The object was signed by a source that is trusted by the system. If the object has multiple signatures, at least one of the signatures came from a source that is trusted by the system.

30

QP0L_ATTR_MULT_SIGS: (CHAR(1)) Whether an object has more than one i5/OS 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:

x'00'	QP0L_MULT_SIGS_NO: The object has only one digital signature.
x'01'	QP0L_MULT_SIGS_YES: The object has more than one digital signature. If the QP0L_ATTR_SYS_SIGNED attribute has the value QP0L_SYS_SIGNED, at least one of the signatures is from a source trusted by the system.

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 byte stream files. Valid values are:

x'00'	QP0L_STG_NORMAL: The auxiliary storage will be allocated normally. That is, as additional auxiliary storage is required, it will be allocated in logically sized extents to accommodate the current space requirement, and anticipated future requirements, while minimizing the number of disk I/O operations.
x'01'	QP0L_STG_MINIMIZE: The auxiliary storage will be allocated to minimize the space used by the object. That is, as additional auxiliary storage is required, it will be allocated in small sized extents to accommodate the current space requirement. Accessing an object composed of many small extents may increase the number of disk I/O operations for that object.
x'02'	QP0L_STG_DYNAMIC: The system will dynamically determine the optimum auxiliary storage allocation for the object, balancing space used versus disk I/O operations. For example, if a file has many small extents, yet is frequently being read and written, then future auxiliary storage allocations will be larger extents to minimize the number of disk I/O operations. Or, if a file is frequently truncated, then future auxiliary storage allocations will be small extents to minimize the space used. Additionally, information will be maintained on the stream file sizes for this system and its activity. This file size information will also be used to help determine the optimum auxiliary storage allocations for this object as it relates to the other objects sizes.

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:

x'00'	QP0L_STG_NORMAL: The main storage will be allocated normally. That is, as much main storage as possible will be allocated and used. This minimizes the number of disk I/O operations since the information is cached in main storage.
x'01'	QP0L_STG_MINIMIZE: The main storage will be allocated to minimize the space used by the object. That is, as little main storage as possible will be allocated and used. This minimizes main storage usage while increasing the number of disk I/O operations since less information is cached in main storage.
x'02'	QP0L_STG_DYNAMIC: The system will dynamically determine the optimum main storage allocation for the object depending on other system activity and main storage contention. That is, when there is little main storage contention, as much storage as possible will be allocated and used to minimize the number of disk I/O operations. And when there is significant main storage contention, less main storage will be allocated and used to minimize the main storage contention. This option only has an effect when the storage pool's paging option is CALC. When the storage pool's paging option is FIXED, the behavior is the same as QP0L_STG_NORMAL. When the object is accessed through a file server, this option has no effect. Instead, its behavior is the same as QP0L_STG_NORMAL.

33

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

x'00'	QP0L_DIR_FORMAT_TYPE1: The directory of type DIR has the original directory format. The Convert Directory (CVTDIR) command may be used to convert from the TYPE1 format to the *TYPE2 format.
x'01'	QP0L_DIR_FORMAT_TYPE2: The directory of type DIR is optimized for performance, size, and reliability compared to directories having the TYPE1 format.

34

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

Valid values are:

*NONE	QP0L_AUD_NONE: No auditing occurs for this object when it is read or changed regardless of the user who is accessing the object.
*USRPRF	QP0L_AUD_USRPRF: Audit this object only if the current user is being audited. The current user is tested to determine if auditing should be done for this object. The user profile can specify if only change access is audited or if both read and change accesses are audited for this object. The OBJAUD parameter of the Change User Auditing (CHGUSRAUD) command is used to change the auditing for a specific user.
*CHANGE	QP0L_AUD_CHANGE: Audit all change access to this object by all users on the system.
*ALL	QP0L_AUD_ALL: Audit all access to this object by all users on the system. All access is defined as a read or change operation.
*NOTAVL	QP0L_AUD_NOTAVL: The user performing the operation is not allowed to retrieve the current auditing value. Note: The user must have all object (ALLOBJ) or audit (AUDIT) special authority to retrieve the auditing value.

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 Start of change file systems that have completely converted to the *TYPE2 directory format End of change will actually be scanned, no matter what value is set for this attribute.

Valid values are:

x'00'	QP0L_SCANNING_NO: After an object is created in the directory, the object will not be scanned according to the rules described in the scan-related exit programs. Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
x'01'	QP0L_SCANNING_YES: After an object is created in the directory, the object will be scanned according to the rules described in the scan-related exit programs if the object has been modified or if the scanning software has been updated since the last time the object was scanned.
x'02'	QP0L_SCANNING_CHGONLY: After an object is created in the directory, the object will be scanned according to the rules described in the scan-related exit programs only if the object has been modified since the last time the object was scanned. It will not be scanned if the scanning software has been updated. This attribute only takes effect if the Scan file systems control (QSCANFSCTL) system value has USEOCOATR specified. Otherwise, it will be treated as if the attribute is QP0L_SCANNING_YES. Note:* If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

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 Start of change file systems that have completely converted to the *TYPE2 directory format End of change will actually be scanned, no matter what value is set for this attribute.

Valid values are:

x'00'	QP0L_SCANNING_NO: The object will not be scanned according to the rules described in the scan-related exit programs. Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
x'01'	QP0L_SCANNING_YES: The object will be scanned according to the rules described in the scan-related exit programs if the object has been modified or if the scanning software has been updated since the last time the object was scanned.
x'02'	QP0L_SCANNING_CHGONLY: The object will be scanned according to the rules described in the scan-related exit programs only if the object has been modified since the last time the object was scanned. It will not be scanned if the scanning software has been updated. This attribute only takes effect if the Scan file systems control (QSCANFSCTL) system value has USEOCOATR specified. Otherwise, it will be treated as if the attribute is QP0L_SCANNING_YES. Note:* If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

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:

Qp0l_Scan_Info_t
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(1)	Scan status
1	1	CHAR(1)	Scan signatures different
2	2	CHAR(1)	Binary scan
3	3	CHAR(1)	Reserved
4	4	BINARY(4), UNSIGNED	CCSID 1
8	8	BINARY(4), UNSIGNED	CCSID 2

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:

x'00'	QP0L_SCAN_NO: The object was not scanned in binary mode.
x'01'	QP0L_SCAN_YES: The object was scanned in binary mode. If the object scan status is QP0L_SCAN_SUCCESS, then the object was successfully scanned in binary. If the object scan status is QP0L_SCAN_FAILURE, then the object failed the scan in binary.

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:

x'00'	QP0L_SCAN_NO: The compared signatures are not different.
x'01'	QP0L_SCAN_YES: The compared signatures are different.

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

x'00'	QP0L_SCAN_REQUIRED: A scan is required for the object either because it has not yet been scanned by the scan-related exit programs, or because the objects data or CCSID has been modified since it was last scanned. Examples of object data or CCSID modifications are: writing to the object, directly or through memory mapping; truncating the object; clearing the object; and changing the objects CCSID attribute etc..
x'01'	QP0L_SCAN_SUCCESS: The object has been scanned by a scan-related exit program, and at the time of that last scan request, the object did not fail the scan.
x'02'	QP0L_SCAN_FAILURE: The object has been scanned by a scan-related exit program, and at the time of that last scan request, the object failed the scan and the operation did not complete. Once an object has been marked as a failure, it will not be scanned again until the object's scan signature is different than the global scan key signature or independent ASP group scan key signature as appropriate. Therefore, subsequent requests to work with the object will fail with a scan failure indication if that access meets the criteria for when an object is to be scanned. Examples of requests which will fail are opening the object with more than write-only access, changing the CCSID of the object, copying the object etc.. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for the criteria for when an object is to be scanned. Note: If scanning has been turned off using the QSCANFS system value, or if no exit programs are registered for a specific exit point, then any requests which trigger that specific exit point will return a scan failure indication. If the scan attribute is set to not scan the object , then requests to work with the object will not fail with a scan failure indication.
x'05'	QP0L_SCAN_PENDING_CVN: The object is in a file system that has not completely converted to the TYPE2 directory format, and therefore will not be scanned until the file system is completely converted. For information on the TYPE2 directory format, see the Convert Directory (CVTDIR) command and the Integrated file system information in the Files and file systems topic.
x'06'	QP0L_SCAN_NOT_REQUIRED: The object does not require any scanning because the object is marked to not be scanned.

38

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

x'00'

QP0L_ALWSAV_NO: This object will not be saved when using the Save Object (SAV) command or the QsrSave() API.

Additionally, if this object is a directory, none of the objects in the directory's subtree will be saved unless they were explicitly specified as an object to be saved. The subtree includes all subdirectories and the objects within those subdirectories.

Note: If this attribute is chosen for an object that has private authorities associated with it, or is chosen for the directory of an object that has private authorities associated with it, then the following consideration applies. When the private authorities are saved, the fact that an object has the QP0L_ALWSAV_NO attribute is not taken into consideration. (Private authorities can be saved using either the Save System (SAVSYS) or Save Security Data (SAVSECDTA) command or the Save Object List (QSRSAVO) API.) Therefore, when a private authority is restored using the Restore Authority (RSTAUT) command, message CPD3776 will be seen for each object that was not saved either because it had the QP0L_ALWSAV_NO attribute specified, or because the object was not specified on the save and it was in a directory that had the QP0L_ALWSAV_NO attribute specified.

x'01'

QP0L_ALWSAV_YES: This object will be saved when using the Save Object (SAV) command or the QsrSave() API.

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:

x'00'	QP0L_RSTDRNMUNL_OFF: No additional restrictions for rename and unlink operations.
x'01'	QP0L_RSTDRNMUNL_ON: Additional restrictions for rename and unlink operations.

40

QP0L_ATTR_JOURNAL_EXTENDED_INFORMATION: Extended Journaling information for this object. 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:

Qp0l_Journal_Extended_Info_t
Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(1)	Journaling status
1	1	CHAR(1)	Options
2	2	CHAR(10)	Journal identifier (JID)
12	0C	CHAR(10)	Current or last journal name
22	16	CHAR(10)	Current or last journal library name
32	20	BINARY(4), UNSIGNED	Last journaling start time
36	24	CHAR(10)	Starting journal receiver for apply
46	2E	CHAR(10)	Starting journal receiver library name
56	38	CHAR(10)	Starting journal receiver ASP device
66	42	CHAR(1)	Apply journaled changes required
67	43	CHAR(1)	Rollback was ended
68	44	CHAR(12)	Reserved

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:

x'00'	QP0L_APYJRNCHG_REQ_NO: The object does not have partial transactions.
x'01'	QP0L_APYJRNCHG_REQ_YES: The object was restored with partial transactions. This object can not be used until the Apply Journaled Changes (APYJRNCHG) or Remove Journaled Changes (RMVJRNCHG) command is used to complete or rollback the partial transactions.

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:

x'00'	QP0L_NOT_JOURNALED: The object is currently not being journaled.
x'01'	QP0L_JOURNALED: The object is currently being 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:

x'80'	QP0L_JOURNAL_SUBTREE: When this flag is returned, this object is a directory with IFS journaling subtree semantics. New objects created within this directory's subtree will inherit the journaling attributes and options from this directory.
x'08'	QP0L_JOURNAL_OPTIONAL_ENTRIES: When journaling is active, entries that are considered optional are journaled. The list of optional journal entries varies for each object type. See the Integrated file system information in the Files and file systems topic for information regarding these optional entries for various objects.
x'20'	QP0L_JOURNAL_AFTER_IMAGES: When journaling is active, the image of the object after a change is journaled.
x'40'	QP0L_JOURNAL_BEFORE_IMAGES: When journaling is active, the image of the object prior to a change is journaled.

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:

x'00'

QP0L_ROLLBACK_END_NO: The object did not have a rollback operation ended prior to completion of a request to roll back a transaction.

x'01'

QP0L_ROLLBACK_END_YES: The object had a rollback operation ended using the "End Rollback" option on the Work with Commitment Definition (WRKCMTDFN) screnn. It is recommended that the object be restored as it can not be used. As a last resort, the Change Journaled Object (CHGJRNOBJ) command can be used to allow the object to be used. Doing this, however, may leave the object in an inconsistent state.

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:

*SYSBAS	The journal receiver library resides in the system or user ASPs
ASP device	The journal receiver library resides in this ASP.

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:

*SYSVAL	QP0L_AUD_SYSVAL: The object auditing value for the objects created in the directory is determined by the system auditing value (QCRTOBJAUD).
*NONE	QP0L_AUD_NONE: No auditing occurs for this object when it is read or changed regardless of the user who is accessing the object.
*USRPRF	QP0L_AUD_USRPRF: Audit this object only if the current user is being audited. The current user is tested to determine if auditing should be done for this object. The user profile can specify if only change access is audited or if both read and change accesses are audited for this object. The OBJAUD parameter of the Change User Auditing (CHGUSRAUD) command is used to change the auditing for a specific user.
*CHANGE	QP0L_AUD_CHANGE: Audit all change access to this object by all users on the system.
*ALL	QP0L_AUD_ALL: Audit all access to this object by all users on the system. All access is defined as a read or change operation.
*NOTAVL	QP0L_AUD_NOTAVL: The user performing the operation is not allowed to retrieve the current create object auditing value. Note: The user must have all object (ALLOBJ) or audit (AUDIT) special authority to retrieve the create object auditing value.

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:

x'00'	QP0L_SYSUSE_NONE: The file is a generic stream file.
x'01'	QP0L_SYSUSE_VRTVOL: The file is a virtual volume. Examples include tape and optical virtual volumes.
x'02'	QP0L_SYSUSE_NWSSTG: The file is a network server storage space.

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:

x'00'	QP0L_SUID_OFF: The user ID (UID) is not set at execution time.
x'01'	QP0L_SUID_ON: The object owner is the effective user ID (UID) at execution time.

301

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

x'00'	QP0L_SGID_OFF: If the object is a file, the group ID (GID) is not set at execution time. If the object is a directory in the "root" (/), QOpenSys, and user-defined file systems, the group ID (GID) of objects created in the directory is set to the effective GID of the thread creating the object. This value cannot be set for other file systems.
x'01'	QP0L_SGID_ON: If the object is a file, the group ID (GID) is set at execution time. If the object is a directory, the group ID (GID) of objects created in the directory is set to the GID of the parent directory.

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:

Buffer Pointer
Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Offset to next attribute entry
4	4	BINARY(4)	Attribute identification
8	8	BINARY(4)	Size of attribute data
12	C	CHAR(4)	Reserved
16	10	CHAR(*)	Attribute data

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.

0	QP0L_ATTR_OBJTYPE
1	QP0L_ATTR_DATA_SIZE
2	QP0L_ATTR_ALLOC_SIZE
3	QP0L_ATTR_EXTENDED_ATTR_SIZE
4	QP0L_ATTR_CREATE_TIME
5	QP0L_ATTR_ACCESS_TIME
6	QP0L_ATTR_CHANGE_TIME
7	QP0L_ATTR_MODIFY_TIME
8	QP0L_ATTR_STG_FREE
9	QP0L_ATTR_CHECKED_OUT
10	QP0L_ATTR_LOCAL_REMOTE
11	QP0L_ATTR_AUTH
12	QP0L_ATTR_FILE_ID
13	QP0L_ATTR_ASP
14	QP0L_ATTR_DATA_SIZE_64
15	QP0L_ATTR_ALLOC_SIZE_64
16	QP0L_ATTR_USAGE_INFORMATION
17	QP0L_ATTR_PC_READ_ONLY
18	QP0L_ATTR_PC_HIDDEN
19	QP0L_ATTR_PC_SYSTEM
20	QP0L_ATTR_PC_ARCHIVE
21	QP0L_ATTR_SYSTEM_ARCHIVE
22	QP0L_ATTR_CODEPAGE
23	QP0L_ATTR_FILE_FORMAT
24	QP0L_ATTR_UDFS_DEFAULT_FORMAT
25	QP0L_ATTR_JOURNAL_INFORMATION
26	QP0L_ATTR_ALWCKPWRT
27	QP0L_ATTR_CCSID
28	QP0L_ATTR_SIGNED
29	QP0L_ATTR_SYS_SIGNED
30	QP0L_ATTR_MULT_SIGS
31	QP0L_ATTR_DISK_STG_OPT
32	QP0L_ATTR_MAIN_STG_OPT
33	QP0L_ATTR_DIR_FORMAT
34	QP0L_ATTR_AUDIT
35	QP0L_ATTR_CRTOBJSCAN
36	QP0L_ATTR_SCAN
37	QP0L_ATTR_SCAN_INFO
38	QP0L_ATTR_ALWSAV
39	QP0L_ATTR_RSTDRNMUNL
40	QP0L_ATTR_JOURNAL_EXTENDED_INFORMATION
41	QP0L_ATTR_CRTOBJAUD
42	QP0L_ATTR_SYSTEM_USE
300	QP0L_ATTR_SUID
301	QP0L_ATTR_SGID

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:

0	QP0L_DONOT_FOLLOW_SYMLNK: A symbolic link in the last component is not followed. Attributes of the symbolic link object are returned.
1	QP0L_FOLLOW_SYMLNK: A symbolic link in the last component is followed. The attributes of the object contained in the symbolic link are returned.

Authorities

Note: Adopted authority is not used.

Authorization Required for Qp0lGetAttr()
Object Referred to	Authority Required	errno
Each directory, preceding the last component, in the Path_Name (except when only QP0L_ATTR_AUDIT and/or QP0L_ATTR_CRTOBJAUD are requested)	*X	EACCES
Object, when retrieving the QP0L_ATTR_AUTH attribute	*OBJMGT	EACCES
Note: If the file system supports ALLOBJ special authority and if you have ALLOBJ special authority, you do not need the listed object authority.

Return Value

0	Qp0lGetAttr() was successful.
-1	Qp0lGetAttr() was not successful. The errno global variable is set to indicate the error.

Error Conditions

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

Error condition	Additional information
[EACCES]	If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.
[EAGAIN]
[EBADFID]
[EBADNAME]
[EBUSY]
[ECANCEL]
[ECONVERT]
[EDAMAGE]
[EFAULT]
[EINTR]
[EINVAL]
[EIO]
[ELOOP]
[ENAMETOOLONG]
[ENOENT]
[ENOMEM]
[ENOSPC]
[ENOTAVAIL]
[ENOTDIR]
[ENOTSAFE]
[ENOTSUP]
[EOFFLINE]
[EOVERFLOW]
[EPERM]
[EROOBJ]
[EUNKNOWN]

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

Error condition	Additional information
[EADDRNOTAVAIL]
[ECONNABORTED]
[ECONNREFUSED]
[ECONNRESET]
[EHOSTDOWN]
[EHOSTUNREACH]
[ENETDOWN]
[ENETRESET]
[ENETUNREACH]
[ESTALE]	If you are accessing a remote file through the Network File System, the file may have been deleted at the server.
[ETIMEDOUT]
[EUNATCH]

Error Messages

The following messages may be sent from this function:

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPFA0D4 E	File system error occurred. Error number &1
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

Usage Notes

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

Refer to 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.
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.
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.

Related Information

The <Qp0lstdi.h> file (see Header Files for UNIX-Type Functions)
The <qlg.h> file (see Header Files for UNIX-Type Functions)
chmod()--Change File Authorizations
Integrated File System Scan on Close Exit Programs
Integrated File System Scan on Open Exit Programs.
fstat()--Get File Information by Descriptor
lstat()--Get File or Link Information
QlgGetAttr()--Get Attributes (using NLS-enabled path name)
QlgStat()--Get File Information (using NLS-enabled path name)
QlgLstat()--Get File or Link Information (using NLS-enabled path name)
Qp0lSetAttr()--Set Attributes
Retrieve System Values (QWCRSVAL) API
stat()--Get File Information

Example

See Code disclaimer information for information pertaining to code examples.

Following is an example showing a call to Qp0lGetAttr(). The example also shows a call to Qp0lSaveStgFree().

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

Top | UNIX-Type APIs | APIs by category