DosSetPathInfo

Bindings:  C, MASM 

This call sets attribute and extended attribute information for a file or 
subdirectory. 

 DosSetPathInfo     (PathName, PathInfoLevel, PathInfoBuf, 
                    PathInfoBufSize, PathInfoFlags, Reserved) 
 

 PathName (PSZ) - input 
    Address of the ASCIIZ full path name of the file or subdirectory. 
    Global file name characters are not permitted. 

    DosQSysInfo is called by an application during initialization to 
    determine the maximum path length allowed by OS/2. 

 PathInfoLevel (USHORT) - input 
    Level of file object information being defined. A value of 1 or 2 can 
    be specified. The structures described in PathInfoBuf indicate the 
    information being set for each of these levels. 

 PathInfoBuf (PBYTE) - input 
    Address of the storage area containing the file information being set. 
    

    Level 1 Information 
       PathInfoBuf contains the following structure, to which information 
       is specified in the following format: 

       filedate (FDATE) 
          Structure containing the date of creation. 

          Bit       Description 
          15-9      Year, in binary, of creation 
          8-5       Month, in binary, of creation 
          4-0       Day, in binary, of creation. 

       filetime (FTIME) 
          Structure containing the time of creation. 

          Bit       Description 
          15-11     Hours, in binary, of creation 
          10-5      Minutes, in binary, of creation 
          4-0       Seconds, in binary number of two-second increments, of 
                    creation. 

       fileaccessdate (FDATE) 
          Structure containing the date of last access. See FDATE in 
          filedate. 

       fileaccesstime (FTIME) 
          Structure containing the time of last access. See FTIME in 
          filetime. 

       writeaccessdate (FDATE) 
          Structure containing the date of last write. See FDATE in 
          filedate. 

       writeaccesstime (FTIME) 
          Structure containing the time of last write. See FTIME in 
          filetime. 

    Level 2 Information 
       PathInfoBuf contains an EAOP structure, which has the following 
       format: 

       fpGEAList (PGEALIST) 
          Address of GEAList. GEAList is a packed array of variable length 
          "get EA" structures, each containing an EA name and the length 
          of the name. 

       fpFEAList (PFEALIST) 
          Address of FEAList. FEAList is a packed array of variable length 
          "full EA" structures, each containing an EA name and its 
          corresponding value, as well as the lengths of the name and the 
          value. 

       oError (ULONG) 
          Offset into structure where error has occurred. 

          Level 2 sets a series of EA name/value pairs. On input, 
          FileInfoBuf is an EAOP structure above.  fpGEAList is ignored. 
          fpFEAList points to a data area where the relevant FEA list is 
          to be found.  oError is ignored. Following is the format of the 
          FEAList structure: 

       cbList (ULONG) 
          Length of the FEA list, including the length itself. 

       list (FEA) 
          List of FEA structures.  An FEA structure has the following 
          format: 

          Flags (BYTE) 
             Bit indicator describing the characteristics of the EA being 
             defined. 

             Bit       Description 
             7         Critical EA. 
             6-0       Reserved and must be set to zero. 

            
             If bit 7 is set to 1, this indicates a critical EA.  If bit 7 
             is 0, this means the EA is noncritical; that is, the EA is 
             not essential to the intended use by an application of the 
             file with which it is associated. 

          cbName (BYTE) 
             Length of EA ASCIIZ name, which does not include the null 
             character. 

          cbValue (USHORT) 
             Length of EA value, which cannot exceed 64KB. 

          szName (PSZ) 
             Address of the ASCIIZ name of EA. 

          aValue (PSZ) 
             Address of the free-format value of EA. 

       Note: 
          The szName and aValue fields are not included as part of header 
          or include files.  Because of their variable lengths, these 
          entries must be built manually. 

      
       On output, fpGEAList is unchanged.  fpFEAList is unchanged as is 
       the area pointed to by fpFEAList.  If an error occurred during the 
       set, oError is the offset of the FEA where the error occurred.  The 
       API return code is the error code corresponding to the condition 
       generating the error.  If no error occurred, oError is undefined. 

 PathInfoBufSize (USHORT) - input 
    Length of PathInfoBuf. 

 PathInfoFlags (USHORT) - input 
    PathInfoFlags contain information on how the set operation is 
    performed.  Only one bit is defined.  If PathInfoFlags = 0010H, then 
    the information being set must be written out to disk before returning 
     to the application. This guarantees that the EAs have been written to 
    disk. All other bits are reserved and must be zero. 

 Reserved (ULONG) - input 
    Reserved, must be set to zero. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    32        ERROR_SHARING_VIOLATION 
    87        ERROR_INVALID_PARAMETER 
    124       ERROR_INVALID_LEVEL 
    206       ERROR_FILENAME_EXCED_RANGE 
    122       ERROR_INSUFFICIENT_BUFFER 
    254       ERROR_INVALID_EA_NAME 
    255       ERROR_EA_LIST_INCONSISTENT 
 
 Remarks 

 To set any level of file information for a file or subdirectory with 
 DosSetPathInfo, a process must have exclusive write access to the closed 
 file object. Thus, if the file object is already accessed by another 
 process, a call to DosSetPathInfo fails. 

 A zero (0) value in both the date and time components of a field cause 
 that field to be left unchanged.  For example, if both "Last write date" 
 and "Last write time" are specified as zero in the Level 0001H 
 information structure, then both attributes of the file are left 
 unchanged. If either "Last write date" or "Last write time" are specified 
 as non-zero, then both attributes of the file are set to the new values. 

 The write-through bit in PathInfo Flags should be used only in cases 
 where it is necessary, for data integrity purposes, to write the EAs out 
 to disk immediately, instead of caching them and writing them out later. 
 Setting the write-through bit all the time may degrade the performance. 

 The last modification date and time will get changed if the extended 
 attributes are modified.