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.
Attribute array pointer Offset Type Field Dec Hex 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 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:
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 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 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 server on the System i® platform 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 on the System i platform 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 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 server on the System i platform 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 which is no longer supported. *NTWEFF The NetWare effective rights to the object. This value is only used by the QNetWare file system which is no longer supported. *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 (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.
Qp0l_Usage_t Offset Type Field Dec Hex 0 0 BINARY(4), UNSIGNED Reset date 4 4 BINARY(4), UNSIGNED Last used date 8 8 BINARY(2), UNSIGNED Days used count 10 A CHAR(6) 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 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:
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 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 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 IBM i (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 IBM i (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.
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:
Qp0l_Journal_Info_t Offset Type Field Dec Hex 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 or library with inherit journal semantics. If this object is a directory, new objects created or linked within this directory will inherit the journal options and state from this directory. If this object is a library, new objects created or linked within this library will inherit the journal options and state from this library according to the journal inherit rules for this library. 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 topic collection 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 IBM i digital signature. This attribute is only returned for *STMF objects.
Valid values are:
x'00' QP0L_NOT_SIGNED: The object does not have an IBM i digital signature. x'01' QP0L_SIGNED: The object does have an IBM i 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 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:
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 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 optimal 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 optimal 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 optimal 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. 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:
- Integrated File System Scan on Close Exit Programs
- Integrated File System Scan on Open Exit Programs.
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:
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:
- Integrated File System Scan on Close Exit Programs
- Integrated File System Scan on Open Exit Programs.
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:
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 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 about 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.
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.
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:
Qp0l_Journal_Extended_Info_t Offset Type Field Dec Hex 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. 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 or library with inherit journal semantics. If this object is a directory, new objects created or linked within this directory will inherit the journal options and state from this directory. If this object is a library, new objects created or linked within this library will inherit the journal options and state from this library according to the journal inherit rules for this library. 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.
- 43
- QP0L_ATTR_TEMPORARY: (CHAR(1)) Whether the object is a temporary object. Possible values are:
x'00' QP0L_TEMPORARY_NO: The object is a permanent object. x'01' QP0L_TEMPORARY_YES: The object is a temporary object.
- 44
- QP0L_ATTR_UDFS_TEMPORARY: (CHAR(1)) Whether the objects in the UDFS are temporary objects. Possible values are:
x'00' QP0L_UDFS_TEMPORARY_NO: The objects in the UDFS are permanent objects. x'01' QP0L_UDFS_TEMPORARY_YES: The objects in the UDFS are temporary objects.
- 45
- QP0L_ATTR_UDFS_PREFERRED_STORAGE_UNIT: (CHAR(1)) The preferred storage media for the objects
in the UDFS. Possible values are:
x'00' QP0L_UDFS_PREFERRED_STORAGE_ANY: No storage media is preferred. Storage will be allocated from any available storage media. x'01' QP0L_UDFS_PREFERRED_STORAGE_UNIT_SSD: Solid state drive storage media is preferred. Storage should be allocated from solid state drive storage media, if available.
- 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:
x'00' QP0L_INHERIT_ALWCKPWRT_NO: New directory objects created within this directory will have the QP0L_ATTR_INHERIT_ALWCKPWRT attribute set to QP0L_INHERIT_ALWCKPWRT_NO.
New stream file objects created within this directory will have the QP0L_ATTR_ALWCKPWRT attribute set to QP0L_NOT_ALWCKPWRT.x'01' QP0L_INHERIT_ALWCKPWRT_YES: New directory objects created within this directory will have the QP0L_ATTR_INHERIT_ALWCKPWRT attribute set to QP0L_INHERIT_ALWCKPWRT_YES.
New stream file objects created within this directory will have the QP0L_ATTR_ALWCKPWRT attribute set to QP0L_ALWCKPWRT.
- 47
- QP0L_ATTR_SYS_RESTRICTS_SAVE: (CHAR(1)) Whether the system prevents the object from
being saved. Possible values are:
x'00' QP0L_SYS_RESTRICTS_SAVE_NO: The system does not prevent the object from being saved. x'01' QP0L_SYS_RESTRICTS_SAVE_YES: The system has determined that the object cannot be saved because of system restrictions.
- 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 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 43 QP0L_ATTR_TEMPORARY 44 QP0L_ATTR_UDFS_TEMPORARY 45 QP0L_ATTR_UDFS_PREFERRED_STORAGE_UNIT 46 QP0L_ATTR_INHERIT_ALWCKPWRT 47 QP0L_ATTR_SYS_RESTRICTS_SAVE 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() (excluding QSYS.LIB and independent ASP QSYS.LIB) | ||
---|---|---|
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. |
Authorization Required for Qp0lGetAttr() in the QSYS.LIB and independent ASP QSYS.LIB File Systems | ||
---|---|---|
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 |
*MBR object, when retrieving the QP0L_ATTR_STG_FREE, QP0L_ATTR_JOURNAL_INFORMATION or QP0L_ATTR_JOURNAL_EXTENDED_INFORMATION attribute | *RX | EACCES |
*MBR object when retrieving the QP0L_ATTR_AUTH attribute | *RX, *OBJMGT | EACCES |
Objects other than *MBR, when retrieving the QP0L_ATTR_AUTH attribute | *OBJMGT | EACCES |
All other object types for retrieving any other attribute (except when only QP0L_ATTR_AUDIT and/or QP0L_ATTR_CRTOBJAUD are requested) | *X | EACCES |
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
- Where multiple threads exist in the job.
-
"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.
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.
-
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.
- 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 Functions that can be used; for example, localtime(), ctime(), gmtime() etc.
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
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
Top | UNIX-Type APIs | APIs by category |