Qp0lSetAttr()--Set Attributes

Syntax

 #include <Qp0lstdi.h>
 int Qp0lSetAttr
        (Qlg_Path_Name_T     *Path_Name,
         char                *Buffer_ptr,
         uint                 Buffer_Size,
         uint                 Follow_Symlnk, ...);

  Service Program Name: QP0LLIB3

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

The Qp0lSetAttr() function sets one of a set of defined attributes, on each 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 attribute must be supported by the file system to which the object belongs. When an attribute is not supported by the file system, Qp0lSetAttr() will fail with ENOTSUP. See the Usage Notes for more information.

If the last component of the Path_Name parameter is a symbolic link, the Qp0lSetAttr() either sets the attribute of the symbolic link or sets the attribute of the object that the symbolic link names. This depends on the value of the Follow_Symlnk parameter.

All times that are set by Qp0lSetAttr() are 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 system date is set prior to 1970, all time values will be zero.

Parameters

Path_Name

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

Buffer_ptr

(Input) A pointer to a buffer containing a constant that identifies the attribute and the value for the attribute that Qp0lSetAttr() sets. The number of bytes allocated for this buffer is in the Buffer_Size parameter.

The following table describes the format of the entry in the buffer.

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 value to which the attribute is set.

Attribute identification. The constant identifying the attribute being set. Valid values are:

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

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

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

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.

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.

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.

QP0L_ATTR_PC_ARCHIVE: (CHAR(1)) Whether the object has changed since the last time the file was saved or reset by a PC client.

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

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.

QP0L_ATTR_CODEPAGE: (BINARY(4)) The code page used to derive a coded character set identifier (CCSID) used for the data in the file or the extended attributes of the directory.

QP0L_ATTR_ALWCKPWRT: (CHAR(1)) Whether a stream file (*STMF) can be shared with readers and writers during the save-while-active checkpoint processing. Setting this attribute may cause unexpected results. See the Back up your server topic for details on this attribute.

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.

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

QP0L_ATTR_DISK_STG_OPT (CHAR(1)) Which option should be used to determine how auxiliary storage is allocated by the system for the specified object. The option will take effect immediately and be part of the next auxiliary storage allocation for the object. This option can only be specified for byte 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 accomodate the current space requirement, and anticipated future requirements, while minimizing the number of disk I/O operations. If the QP0L_ATTR_DISK_STG_OPT attribute has not been specified for an object, this value is the default.
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 accomodate 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 byte 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.

QP0L_ATTR_MAIN_STG_OPT: (CHAR(1)) Which option should be used to determine how main storage is allocated and used by the system for the specified object. The option will take effect the next time the specified object is opened. This option can only be specified for byte 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. If the QP0L_ATTR_MAIN_STG_OPT attribute has not been specified for an object, this value is the default.
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 NORMAL. When the object is accessed through a file server, this option has no effect. Instead, its behavior is the same as NORMAL.

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 be 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 *TYPE2 directories 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. If the QP0L_ATTR_CRTOBJSCAN attribute has not been specified for a directory, this value is the default.
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.

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 be specified for stream files in the "root" (/), QOpenSys and user-defined file systems Start of change that are not virtual volumes or network server storage spaces. End of change Even though this attribute can be set for objects in *TYPE1 and *TYPE2 directories, only objects which are in *TYPE2 directories 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. If the QP0L_ATTR_SCAN attribute has not been specified for an object, this value is the default.
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.

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

Note: It is highly recommended that this attribute not be changed for any system created objects.

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. If the QP0L_ATTR_ALWSAV attribute has not been specified for an object, this value is the default.

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. In addition, this attribute can only be specified for objects within the Network File System (NFS), QFileSvr.400, "root" (/), QOpenSys, or user-defined file systems. Both the NFS and QFileSvr.400 file systems support this attribute by passing it to the server and surfacing it to the caller. This attribute is also 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.

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. This attribute can only be specified for directories in the "root" (/), QOpenSys, QSYS.LIB, independent ASP QSYS.LIB, QFileSvr.400 and user-defined file systems.

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.

200

QP0L_ATTR_RESET_DATE: (UNSIGNED (BINARY(2)) The count of the number of days an object has been used. Usage has different meanings according to the 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. This attribute can be set to zero only. An attempt to set to any other value will result in errno [EINVAL].

When this attribute is set, the date use count reset for the object is set to the current date.

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.

Offset to next attribute entry. (Output) This field is not used by the Qp0lSetAttr() function. It is provided for alignment so that the same buffer format returned from the Qp0lGetAttr() function can be used as input to the Qp0lSetAttr() function.

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

Size of attribute data. The exact size of the data for this attribute. If this size does not match the size that the system stores for this attribute, [EINVAL] is returned.

Buffer_Size

(Input) The size in bytes of the buffer pointed to by the Buffer_ptr parameter.

Follow_Symlnk

(Input) If the last component in the *Path_Name is a symbolic link, Qp0lSetAttr() either acts upon the symbolic link or the path contained in the symbolic link. This depends on the value of the Follow_Symlnk parameter. 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 set.
1	QP0L_FOLLOW_SYMLNK: A symbolic link in the last component is followed. The attributes of the object contained in the symbolic link are set.

Authorities

Note: Adopted authority is not used.

Authorization Required for Qp0lSetAttr() (excluding QSYS.LIB, independent ASP QSYS.LIB, and QDLS)
Object Referred to	Authority Required	errno
Each directory, preceding the last component, in the path name except when setting the QP0L_ATTR_CRTOBJAUD attribute.	*X	EACCES
Object, when setting the QP0L_ATTR_RESET_DATE, QP0L_ATTR_ALWCKPWRT, QP0L_ATTR_ALWSAV, QP0L_ATTR_DISK_STG_OPT or QP0L_ATTR_MAIN_STG_OPT attribute	*OBJMGT	EACCES
Object, when setting the QP0L_ATTR_CREATE_TIME, QP0L_ATTR_ACCESS_TIME, or QP0L_ATTR_MODIFY_TIME attribute to the current time	Owner or W (See Note*)	EACCES
Object, when setting the QP0L_ATTR_RSTDRNMUNL, QP0L_ATTR_SUID, or QP0l_ATTR_SGID values	Owner (See Note)	EPERM
Object, when setting the QP0L_ATTR_CREATE_TIME, QP0L_ATTR_ACCESS_TIME, or QP0L_ATTR_MODIFY_TIME attribute to a specific time	*W	EPERM
User, when setting the QP0L_ATTR_CRTOBJSCAN or QP0L_ATTR_SCAN attribute	ALLOBJ, SECADM	EPERM
User, when setting the QP0L_ATTR_CRTOBJAUD attribute	*AUDIT	EPERM
Object, when setting any other attribute	*W	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 Qp0lSetAttr() 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 setting the QP0L_ATTR_CRTOBJAUD attribute.	*X	EACCES
Object, when setting the QP0L_ATTR_RESET_DATE attribute and the object type is *FILE	OBJOPR and OBJMGT	EACCES or EPERM
Object, when setting the QP0L_ATTR_RESET_DATE attribute and the object is a database file member	X and OBJMGT	EACCES or EPERM
Object, when setting the QP0L_ATTR_RESET_DATE attribute and the object is neither a *FILE object type nor a database file member	*OBJMGT	EACCES or EPERM
User, when setting the QP0L_ATTR_CRTOBJAUD attribute	*AUDIT	EPERM

Authorization Required for Qp0lSetAttr() in the QDLS File System
Object Referred to	Authority Required	errno
Each directory, preceding the last component, in the path name	*X	EACCES
Object, when setting the QP0L_ATTR_RESET_DATE attribute	W, OBJMGT (See Note)	EACCES
Object, when setting any other attribute	W (See Note*)	EACCES
Note: If you have *ALLOBJ special authority, you do not need the listed object authority.

Return Value

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

Error Conditions

If the Qp0lSetAttr() API 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]
[EJRNDAMAGE]
[EJRNENTTOOLONG]
[EJRNINACTIVE]
[EJRNRCVSPC]
[ELOOP]
[ENAMETOOLONG]
[ENEWJRN]
[ENEWJRNRCV]
[ENOENT]
[ENOMEM]
[ENOSPC]
[ENOTAVAIL]
[ENOTDIR]
[ENOTSAFE]
[ENOTSUP]
[EOFFLINE]
[EPERM]
[EROOBJ]
[ESCANFAILURE]	You have attempted to modify an object that has been marked as a scan failure due to processing by an exit program associated with the scan-related integrated file system exit points.
[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
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.
CPE3418 E	Possible APAR condition or hardware failure.

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_CREATE_TIME and QP0L_ATTR_RESET_DATE attributes are supported for objects of type *STMF only. Attempts to set them on other objects will result in the operation failing with errno set to [ENOTSUP].

The QP0L_ALWSAV_YES value cannot be specified for the QP0L_ATTR_ALWSAV attribute for /dev/null, /dev/zero or objects of type *SOCKET. Attempts to set it on these objects will result in the operation failing with errno set to [ENOTSUP].

The QP0L_ATTR_SGID attribute of the directory affects what the group ID (GID) is for objects that are created in the directory. If the QP0L_ATTR_SGID attribute of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the object. If the QP0L_ATTR_SGID attribute of the parent directory is on, the group ID (GID) of the new object is set to the GID of the parent directory. For all other file systems, the GID of the new object is set to the GID of the parent directory.

When setting the QP0L_ATTR_RSTDRNMUNL, QP0L_ATTR_SUID, or QP0L_ATTR_SGID attributes on an object that has a primary group, it must match the primary group ID or one of the supplemental group IDs of the caller of this API; otherwise, the QP0L_ATTR_SGID attribute is set to QP0L_SGID_OFF.
QSYS.LIB and Independent ASP QSYS.LIB File System Differences
The following attributes may be set on objects in these file systems:
- QP0L_ATTR_CRTOBJAUD
- QP0L_ATTR_RESET_DATE
  When you set the QP0L_ATTR_RESET_DATE attribute of a database file, all members in that file will have their days used count reset to 0 also.
Attempting to set any other attribute other than QP0L_ATTR_SUID or QP0L_ATTR_SGID will result in the operation failing with errno set to [ENOTSUP].

QSYS.LIB and Independent ASP QSYS.LIB do not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.
Network File System Differences
When you set the following attributes on objects in the Network File System, the operation will fail with the errno set to [ENOTSUP] if the attribute is not set to the following attribute value.
- If set, QP0L_ATTR_PC_READ_ONLY must be set to an attribute value of QP0L_PC_NOT_READ_ONLY.
- If set, QP0L_ATTR_PC_HIDDEN must be set to an attribute value of QP0L_PC_NOT_HIDDEN.
- If set, QP0L_ATTR_PC_SYSTEM must be set to an attribute value of QP0L_PC_NOT_SYSTEM.
- If set, QP0L_ATTR_PC_ARCHIVE must be set to an attribute value of QP0L_PC_NOT_CHANGED; however, if the object is of type *STMF, the attribute value must be QP0L_PC_CHANGED.
- If set, QP0L_ATTR_SYSTEM_ARCHIVE must be set to an attribute value of QP0L_SYSTEM_NOT_CHANGED.
The QP0L_ATTR_CREATE_TIME, QP0L_ATTR_RESET_DATE, QP0L_ATTR_CODEPAGE, QP0L_ATTR_CCSID, QP0L_ATTR_ALWSAV, QP0L_ATTR_ALWCKPWRT, QP0L_ATTR_DISK_STG_OPT, QP0L_ATTR_MAIN_STG_OPT and QP0L_ATTR_CRTOBJAUD attributes cannot be set on objects within the Network File System or they will result in the operation failing with errno set to [ENOTSUP].

The NFS client supports the QP0L_ATTR_SUID, QP0L_ATTR_SGID, and QP0L_ATTR_RSTDRNMUNL attributes by passing them to the server over the network and surfacing them to the caller. Whether a particular network file system supports the setting of these attributes depends on the server. Most servers have the capability of masking off the QP0L_ATTR_SUID and QP0L_ATTR_SGID attributes if the NOSUID option is specified on the export. The default, however, is to support these attributes.
QNetWare File System Differences
The QNetWare File System does not support setting the QP0L_ATTR_RSTDRNMUNL, QP0L_ATTR_SYSTEM_ARCHIVE, QP0L_ATTR_RESET_DATE, QP0L_ATTR_CRTOBJAUD attributes. If you set any attribute on a NetWare Directory Services (NDS) object, the operation will fail with errno set to [ENOTSUP].

QNetWare supports the QP0L_ATTR_SUID and QP0L_ATTR_SGID attributes by passing them to the server and surfacing them to the caller. Some versions of NetWare may support the attributes and others may not.
QDLS File System Differences
The following attributes may be set on objects in this file system:
- QP0L_ATTR_ACCESS_TIME
- QP0L_ATTR_CCSID
- QP0L_ATTR_CODEPAGE
- QP0L_ATTR_MODIFY_TIME
- QP0L_ATTR_PC_ARCHIVE
- QP0L_ATTR_PC_HIDDEN
- QP0L_ATTR_PC_READ_ONLY
- QP0L_ATTR_PC_SYSTEM
- QP0L_ATTR_RESET_DATE (for documents only)
Attempting to set any other than the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes will result in the operation failing with errno set to [ENOTSUP].

QDLS does not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.
QOPT File System Differences
If you set the QP0L_ALWSAV_YES value for the QP0L_ATTR_ALWSAV attribute, the operation will fail with errno set to [ENOTSUP].

QOPT does not support setting the QP0L_ATTR_SUID, QP0L_ATTR_SGID, QP0L_ATTR_RSTDRNMUNL, or QP0L_ATTR_CRTOBJAUD attributes for any optical media format. If any attribute is specified, the operation will fail with errno set to [ENOTSUP].
QFileSvr.400 File System Differences
QFileSvr.400 supports the QP0L_ATTR_SUID, QP0L_ATTR_SGID, and QP0L_ATTR_RSTDRNMUNL attributes by passing them to the server and surfacing them to the caller.

QFileSvr.400 does not support setting the QP0L_ATTR_ALWSAV attribute. The operation will fail if this attribute is specified.

QFileSvr.400 supports setting the QP0L_ATTR_CRTOBJAUD attribute. However, the QSECOFR user profiles on the source and target system must be enabled, and their passwords must match for the operation to succeed.
QNTC File System Differences
The following attributes may be set on objects in this file system:
- QP0L_ATTR_PC_ARCHIVE
- QP0L_ATTR_PC_HIDDEN
- QP0L_ATTR_PC_READ_ONLY
- QP0L_ATTR_PC_SYSTEM
Attempting to set any other than the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes will result in the operation failing with errno set to [ENOTSUP].

QNTC does not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.

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.
QlgSetAttr()--Set Attributes (using NLS-enabled path name)
Qp0lGetAttr()--Get Attributes
Retrieve System Values (QWCRSVAL) API

Example

See Code disclaimer information for information pertaining to code examples.

The following is an example showing a call to the Qp0lSetAttr() and the Qp0lGetAttr() APIs.

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


 int GetAttrObject(
                   Qlg_Path_Name_T *Pathname_ptr,
                   char            *Buffer_ptr,
                   unsigned int    Buffer_size)
 {
  /**************************************************************/
  /*   Local variables                                          */
  /**************************************************************/
   struct attrStruct
   {
     Qp0l_AttrTypes_List_t  attr_struct;
     uint                   AttrTypes[10];
   };
   struct attrStruct  Attr_types_ptr;

   unsigned int buff_size_needed;
   unsigned int num_bytes_returned;
   unsigned int follow_sym;        
   int          rc;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Get Attributes Parameters                       */
  /**************************************************************/
   memset((void *)&Attr_types_ptr, 0x00,sizeof(struct attrStruct));
   Attr_types_ptr.attr_struct.Number_Of_ReqAttrs = 3;
   Attr_types_ptr.AttrTypes[0] = QP0L_ATTR_PC_READ_ONLY;
   Attr_types_ptr.AttrTypes[1] = QP0L_ATTR_PC_HIDDEN;
   Attr_types_ptr.AttrTypes[2] = QP0L_ATTR_CODEPAGE;
   buff_size_needed = 0;
   follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Call Qp0lGetAttr() to retrieve attributes.                 */
  /**************************************************************/
   rc = Qp0lGetAttr(Pathname_ptr,
                    (Qp0l_AttrTypes_List_t *)&Attr_types_ptr,
                    Buffer_ptr,
                    Buffer_size,
                    &buff_size_needed,
                    &num_bytes_returned,
                    follow_sym);

   if((rc == 0) &&              /* If successful, but           */
      (num_bytes_returned <= 0)) /* Incorrect bytes returned    */
     rc = EUNKNOWN;             /* Unknown error                */

   return(rc);
 }                              /* End GetAttrObject()          */


 int SetAttrObject(
                   Qlg_Path_Name_T *Pathname_ptr,
                   char            *Buffer_ptr,
                   unsigned int    Buffer_size)
 {

  /**************************************************************/
  /*   Local variables                                          */
  /**************************************************************/

   unsigned int       follow_sym;           
   int                rc;
   int                done = 0;
   unsigned int       attrSize;
   Qp0l_Attr_Header_t *attrPtr;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Set Attributes Parameters                       */
  /**************************************************************/
   follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Qp0lSetAttr() only sets one attribute at a time.  The      */
  /* buffer from Qp0lGetAttr may contain more than one          */
  /* attribute to set.  We may have to call Qp0lSetAttr()       */
  /* multiple times.  The Next_Attr_Offset value is the key.    */
  /* If it is greater than zero, then there is another          */
  /* attribute in the buffer.  Also, it is important to note    */
  /* that the value stored there is the offset from the start   */
  /* of the buffer, not the offset from the start of the        */
  /* current entry.                                             */
  /**************************************************************/
   attrPtr = (Qp0l_Attr_Header_t *)Buffer_ptr;
   while(!done)
   {
       attrSize = attrPtr->Attr_Size +
         sizeof(Qp0l_Attr_Header_t);  /* Calculate attr size    */
       /*********************************************************/
       /* Call Qp0lSetAttr() to set the attribute               */
       /*********************************************************/
       rc=Qp0lSetAttr(Pathname_ptr,
                      (char *)attrPtr,
                      attrSize,
                      follow_sym);
       if(rc != 0)              /* If the function failed       */
         done = 1;              /* End the loop                 */
       else if(attrPtr->Next_Attr_Offset > 0) /* If more data   */
         attrPtr = (Qp0l_Attr_Header_t *) /* Set attribute      */
           (Buffer_ptr + attrPtr->Next_Attr_Offset); /* pointer */
       else                     /* No more data                 */
         done = 1;              /* End the loop                 */
   }
   return(rc);
 }                              /* End SetAttrObject()          */


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

   typedef struct pnstruct
   {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[sizeof(MYPN)];
   } ;

   typedef struct pnstruct2
   {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[sizeof(MYPN2)];
   } ;

   struct pnstruct pns;
   struct pnstruct2 pns2;
   int rc;

   char  BufferArea[250];
   unsigned int buffer_size = 250;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Pathname for original object                    */
  /**************************************************************/
   memset((void *)&pns, 0, 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));

  /**************************************************************/
  /* Call GetAttrObject to retrieve attributes from the source  */
  /* object.                                                    */
  /**************************************************************/
   rc = GetAttrObject((Qlg_Path_Name_T *)&pns,
                      BufferArea,
                      buffer_size);
   if (rc == 0)                  /* If GetAttr succeeded        */
   {  
    /************************************************************/
    /* Initialize Pathname for target object                    */
    /************************************************************/
     memset((void *)&pns2, 0, sizeof(struct pnstruct2));
     pns2.qlg_struct.CCSID = 37;
     memcpy(pns2.qlg_struct.Country_ID,US_const,2);
     memcpy(pns2.qlg_struct.Language_ID,Language_const,3);;
     pns2.qlg_struct.Path_Type = 0;
     pns2.qlg_struct.Path_Length = sizeof(MYPN2)-1;
     memcpy(pns2.qlg_struct.Path_Name_Delimiter,Path_Name_Del_const,1);
     memcpy(pns2.pn,MYPN2,sizeof(MYPN2));

    /************************************************************/
    /* Call SetAttrObject to set attributes on the target       */
    /* object.                                                  */
    /************************************************************/
     rc=SetAttrObject((Qlg_Path_Name_T *)&pns2,
                       BufferArea,
                       buffer_size);
     if (rc != 0)
     {
       rc = errno;              /* return errno from SetAttrObject */
       printf("Qp0lSetAttr() for %s failed with %i.\n",pns2.pn,rc);
     }
   }                            /* end check GetAttrObject rc      */
   else                         /* GetAttrObject failed            */
   {
     rc = errno;                /* return errno from GetAttrObject */
     printf("Qp0lGetAttr() for %s failed with %s.\n",pns.pn,rc);
   }
   return(rc);
 }                              /* end main                        */

API introduced: V4R4

Top | UNIX-Type APIs | APIs by category