Difference between revisions of "DosSetPathInfo (OS/2 1.x)"
m |
|||
Line 1: | Line 1: | ||
− | |||
− | |||
− | |||
− | |||
This call sets attribute and extended attribute information for a file or subdirectory. | This call sets attribute and extended attribute information for a file or subdirectory. | ||
Line 60: | Line 56: | ||
==Return Code== | ==Return Code== | ||
− | + | ;rc (USHORT) - return:Return code descriptions are: | |
− | Return code descriptions are: | + | *0 NO_ERROR |
− | * 0 | + | *32 ERROR_SHARING_VIOLATION |
− | * 32 | + | *87 ERROR_INVALID_PARAMETER |
− | * 87 | + | *124 ERROR_INVALID_LEVEL |
− | * 124 | + | *206 ERROR_FILENAME_EXCED_RANGE |
− | * 206 | + | *122 ERROR_INSUFFICIENT_BUFFER |
− | * 122 | + | *254 ERROR_INVALID_EA_NAME |
− | * 254 | + | *255 ERROR_EA_LIST_INCONSISTENT |
− | * 255 | + | |
==Remarks== | ==Remarks== | ||
Line 80: | Line 75: | ||
The last modification date and time will get changed if the extended attributes are modified. | The last modification date and time will get changed if the extended attributes are modified. | ||
− | ===C | + | ==Binding== |
+ | ===C=== | ||
<PRE> | <PRE> | ||
typedef struct _GEA { /* gea */ | typedef struct _GEA { /* gea */ | ||
− | |||
BYTE cbName; /* name length not including NULL */ | BYTE cbName; /* name length not including NULL */ | ||
CHAR szName[1]; /* attribute name */ | CHAR szName[1]; /* attribute name */ | ||
− | |||
} GEA; | } GEA; | ||
typedef struct _GEALIST { /* geal */ | typedef struct _GEALIST { /* geal */ | ||
− | |||
ULONG cbList; /* total bytes of structure including full list */ | ULONG cbList; /* total bytes of structure including full list */ | ||
GEA list[1]; /* variable length GEA structures */ | GEA list[1]; /* variable length GEA structures */ | ||
− | |||
} GEALIST; | } GEALIST; | ||
typedef struct _FEA { /* fea */ | typedef struct _FEA { /* fea */ | ||
− | |||
BYTE fEA; /* flags */ | BYTE fEA; /* flags */ | ||
BYTE cbName; /* name length not including NULL */ | BYTE cbName; /* name length not including NULL */ | ||
USHORT cbValue; /* value length */ | USHORT cbValue; /* value length */ | ||
− | |||
} FEA; | } FEA; | ||
typedef struct _FEALIST { /* feal */ | typedef struct _FEALIST { /* feal */ | ||
− | |||
ULONG cbList; /* total bytes of structure including full list */ | ULONG cbList; /* total bytes of structure including full list */ | ||
FEA list[1]; /* variable length FEA structures */ | FEA list[1]; /* variable length FEA structures */ | ||
− | |||
} FEALIST; | } FEALIST; | ||
typedef struct _EAOP { /* eaop */ | typedef struct _EAOP { /* eaop */ | ||
− | |||
PGEALIST fpGEAList; /* general EA list */ | PGEALIST fpGEAList; /* general EA list */ | ||
PFEALIST fpFEAList; /* full EA list */ | PFEALIST fpFEAList; /* full EA list */ | ||
ULONG oError; | ULONG oError; | ||
− | |||
} EAOP; | } EAOP; | ||
Line 124: | Line 110: | ||
PathInfoBufSize, PathInfoFlags, 0); | PathInfoBufSize, PathInfoFlags, 0); | ||
− | PSZ | + | PSZ PathName; /* File or directory path name string */ |
− | USHORT | + | USHORT PathInfoLevel; /* Info data type */ |
− | PBYTE | + | PBYTE PathInfoBuf; /* Info buffer */ |
− | USHORT | + | USHORT PathInfoBufSize; /* Info buffer size */ |
− | USHORT | + | USHORT PathInfoFlags; /* Path info flags */ |
− | ULONG | + | ULONG 0; /* Reserved (must be zero) */ |
− | USHORT | + | USHORT rc; /* return code */ |
</PRE> | </PRE> | ||
− | ===MASM | + | ===MASM=== |
<PRE> | <PRE> | ||
GEA struc | GEA struc | ||
− | |||
gea_cbName db ? ;name length not including NULL | gea_cbName db ? ;name length not including NULL | ||
gea_szName db 1 dup (?) ;attribute name | gea_szName db 1 dup (?) ;attribute name | ||
− | |||
GEA ends | GEA ends | ||
GEALIST struc | GEALIST struc | ||
− | |||
geal_cbList dd ? ;total bytes of structure including full list | geal_cbList dd ? ;total bytes of structure including full list | ||
geal_list db size GEA * 1 dup (?) ;variable length GEA structures | geal_list db size GEA * 1 dup (?) ;variable length GEA structures | ||
− | |||
GEALIST ends | GEALIST ends | ||
FEA struc | FEA struc | ||
− | |||
fea_fEA db ? ;flags | fea_fEA db ? ;flags | ||
fea_cbName db ? ;name length not including NULL | fea_cbName db ? ;name length not including NULL | ||
fea_cbValue dw ? ;value length | fea_cbValue dw ? ;value length | ||
− | |||
FEA ends | FEA ends | ||
FEALIST struc | FEALIST struc | ||
− | |||
feal_cbList dd ? ;total bytes of structure including full list | feal_cbList dd ? ;total bytes of structure including full list | ||
feal_list db size FEA * 1 dup (?) ;variable length FEA structures | feal_list db size FEA * 1 dup (?) ;variable length FEA structures | ||
− | |||
FEALIST ends | FEALIST ends | ||
EAOP struc | EAOP struc | ||
− | |||
eaop_fpGEAList dd ? ;general EA list | eaop_fpGEAList dd ? ;general EA list | ||
eaop_fpFEAList dd ? ;full EA list | eaop_fpFEAList dd ? ;full EA list | ||
eaop_oError dd ? ; | eaop_oError dd ? ; | ||
− | |||
EAOP ends | EAOP ends | ||
Line 187: | Line 163: | ||
</PRE> | </PRE> | ||
− | [[Category: | + | [[Category:Dos16]] |
Revision as of 05:54, 26 January 2020
This call sets attribute and extended attribute information for a file or subdirectory.
Syntax
DosSetPathInfo (PathName, PathInfoLevel, PathInfoBuf, PathInfoBufSize, PathInfoFlags, Reserved)
Parameters
- 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.
- 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.
- 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.
- Error (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.
- 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.
Return Code
- 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.
Binding
C
typedef struct _GEA { /* gea */ BYTE cbName; /* name length not including NULL */ CHAR szName[1]; /* attribute name */ } GEA; typedef struct _GEALIST { /* geal */ ULONG cbList; /* total bytes of structure including full list */ GEA list[1]; /* variable length GEA structures */ } GEALIST; typedef struct _FEA { /* fea */ BYTE fEA; /* flags */ BYTE cbName; /* name length not including NULL */ USHORT cbValue; /* value length */ } FEA; typedef struct _FEALIST { /* feal */ ULONG cbList; /* total bytes of structure including full list */ FEA list[1]; /* variable length FEA structures */ } FEALIST; typedef struct _EAOP { /* eaop */ PGEALIST fpGEAList; /* general EA list */ PFEALIST fpFEAList; /* full EA list */ ULONG oError; } EAOP; #define INCL_DOSFILEMGR USHORT rc = DosSetPathInfo(PathName, PathInfoLevel, PathInfoBuf, PathInfoBufSize, PathInfoFlags, 0); PSZ PathName; /* File or directory path name string */ USHORT PathInfoLevel; /* Info data type */ PBYTE PathInfoBuf; /* Info buffer */ USHORT PathInfoBufSize; /* Info buffer size */ USHORT PathInfoFlags; /* Path info flags */ ULONG 0; /* Reserved (must be zero) */ USHORT rc; /* return code */
MASM
GEA struc gea_cbName db ? ;name length not including NULL gea_szName db 1 dup (?) ;attribute name GEA ends GEALIST struc geal_cbList dd ? ;total bytes of structure including full list geal_list db size GEA * 1 dup (?) ;variable length GEA structures GEALIST ends FEA struc fea_fEA db ? ;flags fea_cbName db ? ;name length not including NULL fea_cbValue dw ? ;value length FEA ends FEALIST struc feal_cbList dd ? ;total bytes of structure including full list feal_list db size FEA * 1 dup (?) ;variable length FEA structures FEALIST ends EAOP struc eaop_fpGEAList dd ? ;general EA list eaop_fpFEAList dd ? ;full EA list eaop_oError dd ? ; EAOP ends EXTRN DosSetPathInfo:FAR INCL_DOSFILEMGR EQU 1 PUSH@ ASCIIZ PathName ;File or directory path name string PUSH WORD PathInfoLevel ;Info data type PUSH@ OTHER PathInfoBuf ;Info buffer PUSH WORD PathInfoBufSize ;Info buffer size PUSH WORD Flags ;Path info flags PUSH DWORD 0 ;Reserved (must be zero) CALL DosSetPathInfo Returns WORD