com.ibm.as400.access

Class UDFS

  • java.lang.Object
    • com.ibm.as400.access.UDFS

  • public class UDFS
extends java.lang.Object
    Represents a user-defined file system on the IBM i system.

    • Constructor Summary

      Constructors 
      Constructor and Description
      UDFS(AS400 system, java.lang.String path)
      Constructs a UDFS object.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void create()
      Creates a file system that can be made visible to the rest of the integrated file system name space through the mount() method.
      void create(java.lang.String publicDataAuthority, java.lang.String[] publicObjectAuthority, java.lang.String auditingValue, java.lang.String scanningOption, boolean specialRestrictions, java.lang.String defaultDiskStorageOption, java.lang.String defaultMainStorageOption, java.lang.String caseSensitivity, java.lang.String defaultFileFormat, java.lang.String description)
      Creates a file system that can be made visible to the rest of the integrated file system name space through the mount() method.
      void delete()
      Deletes an existing and unmounted user-defined file system (UDFS) and all of the objects within it.
      UDFS.MountedFsInformationStructure getMountedFsInformationStructure()
      Returns information about a mounted file system.
      UDFS.UdfsInformationStructure getUdfsInformationStructure()
      Returns information about a UDFS.
      void mount(java.lang.String mountPoint)
      Makes the objects in a file system accessible to the integrated file system name space.
      void mount(java.lang.String mountPoint, boolean rwOption, boolean suidOption)
      Makes the objects in a file system accessible to the integrated file system name space.
      void setPreferredStorageUnit(java.lang.String storageUnit)
      Specifies the preferred storage media of objects created in this user-defined file system.
      void unmount()
      Makes a previously mounted file system inaccessible within the integrated file system name space.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • UDFS

        public UDFS(AS400 system,
    java.lang.String path)
        Constructs a UDFS object.
        Parameters:
        system - The system object representing the system on which the UDFS exists.
        path - The path name of the file system. It must be in one of the following two forms:
        1. /dev/qaspXX/udfsname.udfs, where XX is one of the valid system or basic user auxiliary storage pool (ASP) numbers on the system, and udfsname is the name of the user-defined file system. All other parts of the name must appear as in the example above.
        2. /dev/aspname/udfsname.udfs, where aspname is one of the valid independent ASP names on the system, and udfsname is the name of the user-defined file system. All other parts of the name must appear as in the example above.

        The name part of the path must be unique within the specified qaspXX or aspname directory.

        Wildcard characters such as '*' and '?' are not allowed in this parameter.

    • Method Detail

      • create

        public void create()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException
        Creates a file system that can be made visible to the rest of the integrated file system name space through the mount() method.

        A UDFS is represented by the object type *BLKSF, or block special file.

        The public data authority and public object authority will be *INDIR, the auditing value will be *SYSVAL, the scanning option will be *PARENT, rename and unlink will not be restricted, the default disk storage option and the default main storage option will be *NORMAL, the case sensitivity will be *MONO, the default file format will be *TYPE2, and the description will be *BLANK.

        Restrictions:

        1. The user must have input/output (I/O) system configuration (*IOSYSCFG) special authority.
        2. A maximum of approximately 4,000 user-defined file systems can be created on an independent auxiliary storage pool (ASP).
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        See Also:
        setPreferredStorageUnit(java.lang.String)

      • create

        public void create(java.lang.String publicDataAuthority,
          java.lang.String[] publicObjectAuthority,
          java.lang.String auditingValue,
          java.lang.String scanningOption,
          boolean specialRestrictions,
          java.lang.String defaultDiskStorageOption,
          java.lang.String defaultMainStorageOption,
          java.lang.String caseSensitivity,
          java.lang.String defaultFileFormat,
          java.lang.String description)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException
        Creates a file system that can be made visible to the rest of the integrated file system name space through the mount() method.

        A UDFS is represented by the object type *BLKSF, or block special file.

        Restrictions:

        1. The user must have input/output (I/O) system configuration (*IOSYSCFG) special authority.
        2. The audit (*AUDIT) special authority is required when specifying a value other than *SYSVAL on the auditingValue parameter.
        3. The user must have all object (*ALLOBJ) and security administrator (*SECADM) special authorities to specify a value for the scanningOption parameter other than *PARENT.
        4. A maximum of approximately 4,000 user-defined file systems can be created on an independent auxiliary storage pool (ASP).
        To retrieve attribute values, use the 'get' methods of FileAttributes.
        Parameters:
        publicDataAuthority - Specifies the public data authority given to the user for the new user-defined file system (UDFS), or specifies that all authorities are inherited from the directory it is to be created in. Possible values are:
        • "*INDIR" - The authority for the UDFS to be created is determined by the directory it is to be created in. This means the new UDFS will inherit its primary group, authorization list, and its public, private and primary group authorities from the /dev/qaspXX or /dev/aspname directory. If the value *INDIR is specified for either the publicObjectAuthority parameter or the publicDataAuthority parameter, then *INDIR must be specified for both parameters.
        • "*RWX" - The user can change the object and perform basic functions on the object except those limited to the owner or controlled by object existence (*OBJEXIST), object management (*OBJMGT), object alter (*OBJALTER) and object reference (*OBJREF) authority. Read, write, execute (*RWX) provides object operational (*OBJOPR) and all data authorities.
        • "*RW" - The user can view and change the contents of an object. Read, write (*RW) authority provides *OBJOPR and data read (*READ), add (*ADD), update (*UPD) and delete (*DLT) authorities.
        • "*RX" - The user can perform basic operations on the object, such as run a program or display the contents of a file. The user is prevented from changing the object. Read, execute (*RX) authority provides *OBJOPR and data *READ and *EXECUTE authorities.
        • "*WX" - The user can change the contents of an object and run a program or search a library or directory. Write, execute (*WX) authority provides *OBJOPR and data *READ, *UPD, *DLT, and *EXECUTE authorities.
        • "*R" - The user can view the contents of an object. Read (*R) authority provides *OBJOPR and data *READ authorities.
        • "*W" - The user can change the contents of an object. Write (*W) authority provides *OBJOPR and data *READ, *UPD, and *DLT authorities.
        • "*X" - The user can run a program or search a library or directory. Execute (*X) authority provides *OBJOPR and data *EXECUTE authorities.
        • "*EXCLUDE" - The user cannot access the object. The publicObjectAuthority parameter value must be *NONE, if this special value is used.
        • "*NONE" - The user is given no data authorities to the object. This value cannot be used with publicObjectAuthority parameter value of *NONE.
        • authorization-list-name - The format of the authorization list name remains the current ten-character format. The publicObjectAuthority parameter value must be *NONE, if this special value is used.
        publicObjectAuthority - Specifies the public object authority given to users for the user-defined file system, or specifies that all authorities are inherited from the directory it is to be created in. Possible values for the elements of this array are:
        • "*INDIR" - The object authority for the UDFS to be created is determined by the directory it is to be created in. This means the new UDFS will inherit its primary group, authorization list, and its public, private and primary group authorities from the /dev/qaspXX or /dev/aspname directory. If the value *INDIR is specified for either the publicObjectAuthority parameter or the publicDataAuthority parameter, then *INDIR must be specified for both parameters. This value must be the only element of the array.
        • "*NONE" - None of the other object authorities (*OBJEXIST, *OBJMGT, *OBJALTER or *OBJREF) are given to the users. If *EXCLUDE or an authorization list is specified for the publicDataAuthority parameter, *NONE must be specified. This value cannot be used with the publicDataAuthority parameter value of *NONE. This value must be the only element of the array.
        • "*ALL" - All of the other object authorities (*OBJEXIST, *OBJMGT, *OBJALTER or *OBJREF) are given to the users. This value must be the only element of the array.
        • "*OBJEXIST" - The user is given object existence (*OBJEXIST) authority to the object. The user can delete the object, free storage of the object, perform save and restore operations for the object, and transfer ownership of the object.
        • "*OBJMGT" - The user is given object management (*OBJMGT) authority to the object. With this authority the user can specify security for the object, move or rename the object and add members to database files.
        • "*OBJALTER" - The user is given object alter (*OBJALTER) authority to the object. The user is able to alter the attributes of the objects. On a database file, the user can add and remove triggers, add and remove referential and unique constraints, and change the attributes of the database file. With this authority on an SQL package, the user can change the attributes of the SQL package. Currently, this authority is used only for database files and SQL packages.
        • "*OBJREF" - The user is given object reference (*OBJREF) authority to objects. Used only for database files, the user can reference an object from another object such that operations on that object may be restricted by the other object. On a physical file, the user can add a referential constraint in which the physical file is the parent.
        auditingValue - Specifies the auditing value of root directory objects created in this user-defined file system. Possible values are:
        • "*SYSVAL" - The object auditing value for the objects in the UDFS is determined by the Create object auditing (QCRTOBJAUD) system value.
        • "*NONE" - Using or changing this object does not cause an audit entry to be sent to the security journal.
        • "*USRPRF" - The user profile of the user accessing this object is used to determine if an audit record is sent for this access. The OBJAUD parameter of the Change User Auditing (CHGUSRAUD) command is used to turn on auditing for a specific user.
        • "*CHANGE" - All change accesses to this object by all users are logged.
        • "*ALL" - All change or read accesses to this object by all users are logged.
        scanningOption - Specifies whether the root directory objects created in the user-defined file system 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:

        • QIBM_QP0L_SCAN_OPEN - Integrated File System Scan on Open Exit Program
        • QIBM_QP0L_SCAN_CLOSE - Integrated File System Scan on Close Exit Program

        For details on these exit points, see the System API Reference information in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter.

        Even though this attribute can be set for user-defined file systems, only objects which are in *TYPE2 directories in that user-defined file system will actually be scanned, no matter what value is set for this attribute.

        Possible values are:

        • "*PARENT" - The create object scanning attribute value for this user-defined file system is copied from the create object scanning attribute value of the parent directory.
        • "*YES" - After an object is created in the user-defined file system, 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.
        • "*NO" - After an object is created in the user-defined file system, the object will not be scanned by 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.

        • "*CHGONLY" - After an object is created in the user-defined file system, 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 *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.

        This parameter is ignored on Version 5 Release 2 and earlier of IBM i.

        specialRestrictions - Specifies whether special restrictions apply for rename and unlink operations performed on objects within the root directory of the user-defined file system. This attribute is equivalent to the S_ISVTX mode bit for this directory. true if objects within the root directory of the user-defined file system may be renamed or unlinked only if 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 all object (*ALLOBJ) special authority.

        false if no additional restrictions for renaming or unlinking objects from the root directory of the user-defined file system. This parameter is ignored on Version 5 Release 2 and earlier of IBM i.

        defaultDiskStorageOption - Specifies how auxiliary storage will be allocated by the system for the stream files (*STMF) created in this user-defined file system. This option will be ignored for *TYPE1 stream files. Possible values are:
        • "*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.
        • "*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.
        • "*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.

        This parameter is ignored on Version 5 Release 4 and earlier of IBM i.

        defaultMainStorageOption - Specifies how main storage is allocated and used by the system for the stream files (*STMF) created in this user-defined file system. Possible values are:
        • "*NORMAL" - The main storage will be allocated normally. That is, as 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.
        • "*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.
        • "*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 *NORMAL. When the object is accessed through a file server, this option has no effect. Instead, its behavior is the same as *NORMAL.

        This parameter is ignored on Version 5 Release 4 and earlier of IBM i.

        caseSensitivity - Specifies the case sensitivity of this file system. Possible values are:
        • "*MONO" - The file system will not be case sensitive. For example, the names FileA and filea refer to the same object.
        • "*MIXED" - The file system will be case sensitive. For example, the names FileA and filea do NOT refer to the same object.
        defaultFileFormat - Specifies the format of stream files (*STMF) created in this user-defined file system. Possible values are:
        • "*TYPE2" - A *TYPE2 *STMF has high performance file access and was new in Version 4 Release 4 of IBM i. It has a minimum object size of 4096 bytes and a maximum object size of approximately 1 terabyte. A *TYPE2 stream file is capable of memory mapping as well as the ability to specify an attribute to optimize disk storage allocation.
        • "*TYPE1" - A *TYPE1 *STMF has the same format as *STMF objects created on releases prior to Version 4 Release 4 of IBM i. It has a minimum size of 4096 bytes and a maximum object size of approximately 256 gigabytes.
        description - Text description for the user-defined file system. Possible values are:
        • "*BLANK" - Text is not specified.
        • description - Specify no more than 50 characters.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        See Also:
        setPreferredStorageUnit(java.lang.String)

      • delete

        public void delete()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException
        Deletes an existing and unmounted user-defined file system (UDFS) and all of the objects within it. The command will fail if the UDFS is mounted.

        Restrictions:

        1. The UDFS to be deleted must not be mounted.
        2. Only a user with input/output (I/O) system configuration (*IOSYSCFG) special authority can specify this command.
        3. The user must have object existence (*OBJEXIST) authority to all of the objects in the UDFS.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.

      • mount

        public void mount(java.lang.String mountPoint)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException
        Makes the objects in a file system accessible to the integrated file system name space. The directory that is the destination for the mount, the mountPoint parameter, must exist. The mount will be performed with default options, read-write and setuid execution allowed.

        Restrictions:

        1. The user must have input/output (I/O) system configuration (*IOSYSCFG) special authority to use this command.
        2. The user must have write (*W) authority to the directory to be mounted over.
        3. The user must have execute (*X) authority to each directory in the path.
        Parameters:
        mountPoint - Specifies the path name of the existing directory that the file system will be mounted over. This directory gets 'covered' by the mounted file system. This directory must exist.

        Multiple file systems can be mounted over the same directory, one on top of the other. However, only the topmost mounted file system is accessible, and the file systems must later be unmounted in the opposite order from which they were mounted (last-in first-out order).

        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.

      • mount

        public void mount(java.lang.String mountPoint,
         boolean rwOption,
         boolean suidOption)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException
        Makes the objects in a file system accessible to the integrated file system name space. The directory that is the destination for the mount, the mountPoint parameter, must exist.

        Restrictions:

        1. The user must have input/output (I/O) system configuration (*IOSYSCFG) special authority to use this command.
        2. The user must have write (*W) authority to the directory to be mounted over.
        3. The user must have execute (*X) authority to each directory in the path.
        Parameters:
        mountPoint - Specifies the path name of the existing directory that the file system will be mounted over. This directory gets 'covered' by the mounted file system. This directory must exist.

        Multiple file systems can be mounted over the same directory, one on top of the other. However, only the topmost mounted file system is accessible, and the file systems must later be unmounted in the opposite order from which they were mounted (last-in first-out order).

        rwOption - This option specifies the protection for the mounted file system. true if read-write, false if read-only.
        suidOption - This option specifies whether setuid execution is allowed. true if suid is specified and setuid execution is allowed. This means that bits other than the permission bits may be set. false if nosuid is specified, setuid execution is not allowed. This parameter is ignored on Version 5 Release 2 and earlier of IBM i.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.

      • unmount

        public void unmount()
             throws AS400SecurityException,
                    ErrorCompletingRequestException,
                    java.lang.InterruptedException,
                    java.io.IOException
        Makes a previously mounted file system inaccessible within the integrated file system name space. If any of the objects in the file system are in use, the command will return an error message to the user. Note that if any part of the file system has itself been mounted over, then this file system cannot be unmounted until it is uncovered.

        Restrictions:

        • The user must have input/output (I/O) system configuration (*IOSYSCFG) special authority to use this command.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.

      • setPreferredStorageUnit

        public void setPreferredStorageUnit(java.lang.String storageUnit)
        Specifies the preferred storage media of objects created in this user-defined file system. In order to be effective, this method must be called prior to create().

        Note: This method is supported only on IBM i version 7.1 and higher. On IBM i version 7.1 it is supported only if IBM i 7.1 PTF SI39439 is installed. If *SSD is specified for a system at IBM i 7.1, and PTF SI39439 is not installed, then the create() methods will throw an AS400Exception indicating "Keyword UNIT not valid for this command".

        To retrieve the in-effect value of the "preferred storage unit" attribute, call FileAttributes.getUdfsPreferredStorageUnit().

        Parameters:
        storageUnit - Preferred storage unit. Possible values are:
        • "*ANY" - No storage media is preferred. Storage will be allocated from any available storage media.
        • "*SSD" - Solid state drive disk storage media is preferred. Storage should be allocated from solid state drive storage media, if available.
        The default is "*ANY". null is interpreted as "*ANY".
JTOpen 11.2