CPGuide - Extended Attributes

From EDM2
Jump to: navigation, search

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Control Program Programming Guide and Reference
  1. Introduction to the Control Program
  2. Control Program Functions
  3. Keyboard Functions
  4. Mouse Functions
  5. Video Functions
  6. Data Types
  7. Errors
  8. Debugging
  9. Kernel Debugger Communications Protocol
  10. Device I/O
  11. Dynamic Linking
  12. Error Management
  13. Exception Management
  14. Extended Attributes
  15. File Management
  16. File Names
  17. File Systems
  18. Generic IOCtl Commands
  19. Memory Management
  20. Message Management
  21. National Language Support
  22. Pipes
  23. Program Execution Control
  24. Queues
  25. Semaphores
  26. Timers
  27. Notices
  28. Glossary

OS/2 file systems maintain a standard set of information on file objects. This standard set of information is referred to as Level 1 file information. Level 1 file information includes the name and size of the file object, and the date and time the file object was created, last accessed, and last written to.

Applications can attach additional information to a file object in the form of an extended attribute (EA). There can be many EAs associated with a file object and, because of their flexibility, almost any information about the file can be stored in one.

The following topics are related to the information in this chapter:

  • File Systems
  • File Names
  • File Management

About Extended Attributes

Level 1 file information is the basic information describing files that is stored by the file system. Level 1 file information includes the size of the file, and the date and time it was created, last written, and last accessed. A subset of this information is typically displayed by entering the DIR command on the OS/2 command line. Applications can obtain Level 1 file information by calling DosQueryPathInfo and DosQueryFileInfo. Applications can set Level 1 File Information by calling DosSetPathInfo and DosSetFileInfo.

Applications can attach additional information to a file object in the form of an extended attribute (EA). Extended attributes can be used to describe the file object to another application, to OS/2, and to the file system that is managing that object.

This information can be used to:

  • Store notes on file objects (for example, the name of the file creator)
  • Categorize file objects (for example, source, samples, icons, bit maps)
  • Describe the format of data contained in the file object (for example, a data record)
  • Append additional data to the file object.

An application uses extended attributes to provide a description of a file or directory but the application does not place the description in the file or directory itself. Extended attributes associated with a file object are not part of the file object or its data. They are stored separately from the file they are linked to and the file system manages the storage and maintenance of the EA.

Each extended attribute has two parts, a name and a value. The name is a NULL-terminated string; any convenient name can be chosen. EA names are restricted to the same character set as file names.

The value of the EA can be text, a bit map, binary data, anything at all. OS/2 does not check data that is associated with an EA. The application that creates the extended attributes and the applications that read them must recognize the format and meaning of the data associated with a given EA name.

Applications can examine, add, and replace extended attributes at any time. Any application can read the extended attributes by using the DosQueryFileInfo or DosQueryPathInfo function. Applications can use DosFindFirst and DosFindNext to search for files that have specific extended attributes.

A file can have any number of extended attributes. Each extended attribute can be up to 64KB in size. The sum of all extended attributes for a file must not exceed 64KB.

So that extended attribute data can be understood by other applications, conventions have been established for naming EAs and indicating the type of data they contain.

In addition, a set of Standard Extended Attributes (SEAs) have been defined. SEAs define a common set of information that can be associated with most files (for example, file type and file purpose). Through SEAs, many applications can access the same, useful information associated with files.

Applications are not limited to using SEAs to associate information with files. They can define their own application-specific extended attributes.

Extended attributes associated with a file object are not part of the file object or its data.

Extended attributes are supported by the OS/2 High Performance File System (HPFS) and by the OS/2 FAT file system.

Applications define and associate extended attributes with a file object through file system functions. The file system functions that use and manipulate EAs are:

Extended Attribute Data Type Conventions

Extended attributes (EAs) can contain any type of data. So that applications can understand the type of information stored in an EA, the first WORD of EA data must specify one of the following data types:

Extended Attribute Data Types
Data Type Value Description
EAT_BINARY FFFE Binary (non-text) data; the first WORD following the data type specifies the length of the data.
EAT_ASCII FFFD ASCII text; the first WORD following the data type specifies the length of the data.
EAT_BITMAP FFFB Bit map data; the first WORD following the data type specifies the length of the data.
EAT_METAFILE FFFA Metafile data; the first WORD following the data type specifies the length of the data.
EAT_ICON FFF9 Icon data; the first WORD following the data type specifies the length of the data.
EAT_EA FFEE ASCII name of another EA that is associated with the file. The contents of that EA are to be included into the current EA. The first WORD following the data type specifies the length of the data.
EAT_MVMT FFDF Multi-Valued, Multi-Typed data-two or more consecutive extended attribute values. Each value has an explicitly specified type.
EAT_MVST FFDE Multi-Valued, Single-Typed data-two or more consecutive extended attribute values. All values have the same type.
EAT_ASN1 FFDD ASN.1 field data; an ISO standard for describing multivalue data streams.

Values of hex 8000 and up are reserved. Values between hex 0000 and hex 7FFF can be defined by the user.

Symbolic constants are defined in BSEDOS.H and BSEDOS.INC.

In all cases, the length specifies the number of bytes of data. Other values for data types, in the range hex 0000 through hex 7FFF, can be used for user-defined extended attributes.

All user-defined data types should be length-preceded, meaning that a WORD indicating the length of the data (in bytes) precedes the data.

For example, here is how to represent the string "Hello":

   EAT_ASCII    0005    Hello

Multi-Value Data Type Fields

In many cases, it is desirable for extended attributes (EAs) to store more than a single piece of information. For example, an extended attribute can store a list of names to which a document was sent. The multi-value formats specify how individual pieces of data are stored.

Data entries are length-preceded, making it easy to traverse a multi-valued list.

In order to allow EAs of different code pages, multi-valued EAs include a field in which the EA's code page is specified. For example, the code page field could be used to indicate that the comments for a Kanji file are written in Spanish. If this value is 0, the file default is assumed. (Code page data is for use by applications. OS/2 does not examine or use EA code page information.)

When the concept of a default applies to a multi-valued EA, the first entry in the list is assumed to be the default. For example, suppose an EA entry contains the strings "Text" and "C Code". "Text" is considered the default type. If "C Code" were the first entry in the list ("C Code" then "Text"), then "C Code" would be considered the default type.

There are three multi-valued EA data types:

  • Multi-Valued, Multi-Typed Data
  • Multi-Valued, Single-Type Data
  • ASN.1 Data

Multi-Valued, Multi-Typed Data Type

This data type indicates that the value of a single extended attribute (EA) contains several pieces of information, each of a different data type. It is formatted as follows:

   EAT_MVMT  Codepage  NumEntries  [DataType Data] ...
   WORD      WORD      WORD         WORD

The first word indicates that the EA value is multi-valued, multi-typed. The second word indicates the code page associated with the language in which the EA value is written. The third word indicates the number of entries contained in this EA value. The next word indicates the data type for the first entry in this EA value, followed by the data for the first entry. The next word, if any, indicates the data type for the second entry in this EA value, followed by the data for the second entry. The pattern repeats- data type, followed by data-for any remaining entries.

For example, an extended attribute can have the following value:

   EAT_MVMT  0000  0002  EAT_ASCII   000A Hello John
                         EAT_BINARY  0003 0x12 0x21 0x34

This is a multi-valued extended attribute with two entries, using the default code page. The first entry is the string "Hello John", and the second is the binary data 0x12 0x21 0x34.

Whether or not the data is length-preceded is a function of the data type.

Multi-Valued, Single-Type Data Type

This data type indicates that the value of a single extended attribute (EA) contains several pieces of information, each of the same data type. For example:

   EAT_MVST  Codepage  NumEntries  Data_Type  [data] ...
   WORD      WORD      WORD        WORD

The first word indicates that the EA value is multi-valued, single-typed. The second word indicates the code page associated with the language in which the EA value is written. The third word indicates the number of entries contained in this EA value. The next word indicates the data type of all the entries contained in this EA value, followed by the data for all entries.

For example, the following EA value contains three ASCII names:

   EAT_MVST 0000 0003 EAT_ASCII 0004 Mark
                                0005 Ellen
                                0003 Liz

Each name string is preceded by the length of the string. Whether or not the data is length-preceded is a function of the data type.

ASN.1 Data Type

This data type indicates that the extended attribute uses the ASN.1 ISO standard to describe a multi-valued data stream.

Including One Extended Attribute in Another

Extended attributes (EA) can contain pointers to data stored in other places.

This data type indicates that the data contained in another EA associated with the file object should be included into the current EA.

For example, the following EA value contains the string "Hello", followed by the data in the EA named AB.STUFF, followed by the string "Bye".

   EA_MVMT 0000 0003 EAT_ASCII 0005  Hello
                     EAT_EA    0008  AB.STUFF
                     EAT_ASCII 0003  Bye

Extended Attribute Naming Conventions

Because many applications use text, bit maps, and other binary data in extended attributes, standard names have been adopted to help identify these formats. An application is not limited to these Standard Extended Attributes but should use them when many applications will be accessing the same data.

Standard Extended Attributes (SEAs) have a dot (.) as a prefix. This identifies the extended attribute as a SEA. The leading dot is reserved, so applications should not define extended attributes that start with a dot. Also, extended attributes that start with the characters $, @, &, or + are reserved for system use.

To ensure that its extended attributes are unique, an application should use the name of the company and the name of the application (or suitable abbreviations of each) as a prefix for application-specific extended attributes.

For example, Company A has an OS/2 Application, B, that defines extended attributes STUFF, MORE_STUFF, and STILL_MORE_STUFF for its file objects. The names of these extended attributes could be represented by the following entry:

   AB.STUFF   AB.MORE_STUFF   AB.STILL_MORE_STUFF

Standard Extended Attributes

The name of a SEA has a dot (.) as a prefix. This identifies the extended attribute as a SEA.

The values of Standard Extended Attributes can be multi- or single-valued, with formats following the data type conventions discussed previously.

Where entries for Standard EAs consist of ASCII characters, case is important.

The Standard EAs that have been defined are:

.ASSOCTABLE
.CLASSINFO
.CODEPAGE
.COMMENTS
.HISTORY
.ICON
.ICON1
.ICONPOS
.KEYPHRASES
.LONGNAME
.PREVNAME
.SUBJECT
.TYPE
.VERSION

Any extended attribute that is defined by the system starts with a period. This allows our software vendors to freely define new extended attributes without conflicting with ours, as long as they follow the convention that non-system extended attributes don't start with a period.

The .TYPE and .ASSOCTABLE extended attributes (EA) are two of the most useful SEAs.

The .TYPE extended attribute indicates what type of data is in a file. It also implies what programs can edit the file, and what icon is to be used for the file. OS/2 can use the .TYPE EA to determine a default application to run and a default icon for a file of a particular type (if there is a .ICON EA, it will be used instead of the icon associated with a particular data type).

The .ASSOCTABLE extended attribute allows an application to indicate the type, extension, and icon for data files that it recognizes. It also contains an ownership flag. This data can be automatically installed by OS/2. When your program recognizes files created by other programs, you might want to install .ASSOCTABLE EA entries for those other programs.

The .ASSOCTABLE Standard Extended Attribute

The .ASSOCTABLE extended attribute (EA) contains information that associates data files with the applications that create them or that know how to use them. The .ASSOCTABLE extended attribute enables an application to indicate the type, extension, and icon for the data files it recognizes. The .ASSOCTABLE EA also contains an ownership flag. This tells OS/2 which application to run when the user double-clicks the mouse on a given data file.

Because programs can understand and reference data files generated by other programs, this EA can be used to link a program with those files.

The name of this EA consists of the string ".ASSOCTABLE". The value of this EA contains application information and consists of multi-valued, multi-typed fields that link the application with:

  • the file type (that is, the value of a .TYPE EA),
  • the file extension,
  • and icon data for data files that it generates or references. The .ASSOCTABLE EA associates icons by file-type. The data file's file-type is indicated in the .TYPE EA, or, if the data file does not have a .TYPE EA, by the extension.

This data can be installed automatically by OS/2.

The format of the EA is as follows.

    EAT_MVMT 0000 0004 EAT_ASCII  .TYPE name
                       EAT_ASCII   file extension
                       EAT_BINARY  flags
                       EAT_ICON    icon data

The source for the .ASSOCTABLE EA is contained in the resource file for an application. The .ASSOCTABLE EA is created using the Resource Compiler from a table with the following form:

    ASSOCTABLE  assoctable -id
    BEGIN
    association_name,[extension],[flags], [icon_filename]
    association_name,[extension],[flags], [icon_filename]
     .
     .
     .
    END

The association_name is the name of a file type that the Resource Compiler understands. (This is the same name found in the .TYPE field of data files.)

The extension is the three letter file extension that is used to identify files of this type, if they have no .TYPE EA entry. (Three letter extensions should be used so that FAT file systems can make use of this EA). This field can be empty.

The icon_filename is the name of the file that contains the icon that is to be used to represent this file type. (This field can also be empty.)

The .ASSOCTABLE flag indicates that the program is the default application for data files with the specified type. This determines the program OS/2 will start when the file is double-clicked with the mouse.

If more than one program has marked itself as the EAF_DEFAULTOWNER for a particular data file .TYPE, OS/2 will not know which program to run when the file of this .TYPE is double-clicked on with the mouse. If no program is marked as the EAF_DEFAULTOWNER for a particular data file .TYPE, OS/2 will be similarly confused. In both cases, OS/2 provides the user with a list of applications that understand the file .TYPE, regardless of whether the application is the owner or not. The user selects the program to run from this list.

The flag entry indicates whether the application owns the file or merely recognizes the .TYPE. If this flag is set, the entry describing data files of this type cannot be edited. This flag is specified if a previously defined icon in the ASSOCTABLE is to be reused. Entries with this flag set have no icon data defined. The icon used for this entry will be the icon used for the previous entry.

EAF_ flags can be ORed together when specified in the ASSOCTABLE. The EAF_ flags are defined in PMWIN.H and PMWIN.INC.

.ASSOCTABLE Example

For example, My_Company's application, My_Application, generates or references data files that have the following .TYPE names: </pre>

   My_Company My_Application documentation
   My_Company My_Application macros
   My_Company My_Application spreadsheet
   My_Company My_Application chart
   Your_Company Your_Application forecast

</pre> The source for the .ASSOCTABLE extended attribute in the resource file for My_Application could look like the following.

    ASSOCTABLE
    BEGIN
    "My_Company My_Application documentation", "DOC", EAF_DEFAULTOWNER, My_App.ICO
    "My_Company My_Application macros", "MAC", EAF_DEFAULTOWNER+EAF_REUSEICON
    "My_Company My_Application spreadsheet", "SPR", EAF_DEFAULTOWNER+EAF_REUSEICON
    "My_Company My_Application chart", "CHT", EAF_DEFAULTOWNER+EAF_REUSEICON
    "Your_Company Your_Application forecast", "FOR", 0
    END

My_Application can load and use some files generated by Your_Application. However, because My_Application is not the default owner of those files, OS/2 does not run My_Application when the user double-clicks on the files with the mouse.

The following example illustrates how the value of the .ASSOCTABLE EA for My_Application might look. It is a multi-valued, multi-typed EA with five multi-valued, multi-typed entries (one for each file type referenced or generated by the application).


    EAT_MVMT   0000 0005          ; There are 5 associated file types

    EAT_MVMT   0000 0004          ; Description of 1st associated file type
    EAT_ASCII  0027 My_Company My_Application documentation  ; File type
    EAT_ASCII  0003 DOC           ; File extension
    EAT_BINARY flags              ; Flags
    EAT_ASCII  icon data          ; Physical icon data

    EAT_MVMT   0000 0004          ; Description of 2nd associated file type
    EAT_ASCII  0020 My_Company My_Application macros
    EAT_ASCII  0003 MAC
    EAT_BINARY flags
    EAT_ICON   icon data

    EAT_MVMT   0000 0004          ; Description of 3rd associated file type
    EAT_ASCII  0025 My_Company My_Application spreadsheet
    EAT_ASCII  0003 SPR
    EAT_BINARY flags
    EAT_ICON   icon data

    EAT_MVMT   0000 0004          ; Description of 4th associated file type
    EAT_ASCII  001F My_Company My_Application chart
    EAT_ASCII  0003 CHT
    EAT_BINARY flags
    EAT_ICON   icon data

    EAT_MVMT   0000 0004          ; Description of 5th associated file type
    EAT_ASCII  001F Your_Company Your_Application forecast
    EAT_ASCII  0003 FOR
    EAT_BINARY flags
    EAT_ICON   icon data

The .CLASSINFO Standard Extended Attribute

The .CLASSINFO extended attribute saves the instance data for a file system object.

The .CODEPAGE Standard Extended Attribute

The .CODEPAGE extended attribute (EA) contains the code page for the file. If this extended attribute is not provided, the code page of the file is the system default or is defined by the application.

The code page of the EA data associated with the file is assumed to be that of the file, unless the EA entry is specifically overridden in the code page field in the multi-valued extended attribute data type.

The .COMMENTS Standard Extended Attribute

The .COMMENTS extended attribute (EA) contains miscellaneous notes or reminders about the file (for example, peculiarities, restrictions, or requirements).

The name of this EA consists of the string ".COMMENT". The value of this EA consists of miscellaneous notes and can be multi-valued and of any type.

The .HISTORY Standard Extended Attribute

The .HISTORY extended attribute (EA) contains the modification history for a file object, indicating the author of the file and all subsequent changes. Each entry is separate field in a multi-value field and consists of be ASCII characters only.

The name of this EA consists of the string ".HISTORY". The value of this EA contains the modification history for a file object and can be multi-valued, with each action entry described in a separate field.

Each entry in the .HISTORY field has the following format:

   PERSON  ACTION(created, changed or printed)  DATE

For example, the following .HISTORY extended attribute contains two entries:

   EAT_MVMT 0000 0002
            EAT_ASCII 0017 Joe    Created  2/10/88
            EAT_ASCII 0017 Harry  Changed  2/11/88

This extended attribute can potentially become quite large. To avoid unwanted growth, an application can let the user decide when an entry should be added to this extended attribute. For example, there are some cases when it is important to note when a document is printed. However, it is probably unnecessary to note it every time the file is printed.

The .ICON Standard Extended Attribute

The .ICON extended attribute (EA) specifies the icon to be used for the file representation, for example when the application is minimized. This extended attribute contains the physical icon data used to represent the file object.

If there is no .ICON EA, OS/2 can use the .TYPE entry to determine a default icon to use for the particular file. If there is an .ICON entry, however, it is used instead of the default icon.

The name of this EA consists of the string ".ICON". The value of this EA contains the physical icon data and has the following format:

   EAT_ICON  data_length  data
   WORD      DWORD

The data is of type BITMAPARRAYFILEHEADER and is used to specify an array of one device-dependent and one device-independent icon bit maps. The GpiLoadBitmap and WinLoadPointer functions support this icon file format.

It is best to provide as much icon information as possible. Ideally, an icon should be 64-by-64 bits in 8-color, device-independent format.

The Icon Editor is used to create the icon, which is saved in an icon file. The .ICON extended attribute for an application is created by the Resource Compiler as part of the compile process by specifying the DEFAULTICON keyword, as in:

   DEFAULTICON <filename.ico>

This keyword uses the icon definition contained in the specified icon file (FILENAME.ICO) to create the .ICON EA for the application.

Applications store the binary icon data in this extended attribute. To install icons for data files, the applications can use the .ASSOCTABLE extended attribute, or DosSetPathInfo.

The .ICON1 Standard Extended Attribute

The .ICON1 extended attribute stores the animation icon (for example, the open folder icon) for a folder.

The .ICONPOS Standard Extended Attribute

The .ICONPOS extended attribute saves the icon positioning information for a folder.

The .KEYPHRASES Standard Extended Attribute

The .KEYPHRASES extended attribute (EA) contains key text phrases for the file. Such phrases can be used in performing a database-type search or in helping the user understand the nature of the file.

The name of this EA consists of the string ".KEYPHRASES". The value of this EA consists of key phrases in ASCII.

Key phrases are represented as ASCII characters. Multiple key phrases can be stored in the value of this extended attribute, each stored in a separate entry in a multi-valued field.

For example, the following extended attribute contains three key phrases:

   EAT_MVST 0000 0003 EAT_ASCII 0008 ABC Inc.
                      EAT_ASCII 000A Salesman A
                      EAT_ASCII 000F Product X sales

If there is more than one key phrase, each should be stored in a separate entry in a multi-value field.

The .LONGNAME Standard Extended Attribute

When an application attempts to write a file with a long name to a file system that does not support long names, it must generate a short name for the file. The application should notify the user of the new short name and save the original (long) name in the .LONGNAME extended attribute.

When a file is copied from a system that uses short names to a system that uses long names, the application should check the .LONGNAME extended attribute. If a value is present, the application should rename the file to the long name, then remove the .LONGNAME extended attribute.

The .PREVNAME Standard Extended Attribute

The .PREVNAME extended attribute saves the old class name when the user requests that an object, which is a descendent of WPDataFile, becomes another subclass of WPDataFile.

The .SUBJECT Standard Extended Attribute

The .SUBJECT extended attribute (EA) contains a brief summary of the content or purpose of the file object it is associated with.

The name of this EA consists of the string ".SUBJECT". The value of this EA consists of a single-valued ASCII string that contains the purpose of the file object.

The length of this field must be less than 40 characters.

The .TYPE Standard Extended Attribute

The .TYPE extended attribute (EA) indicates the file-type of the file object it is associated with. It is similar to a file name extension.

The name of this EA consists of the string ".TYPE". The value of this EA contains the file object's file-type. The following file types are predefined:

Plain text
OS/2 command file
DOS command file
Executable
Metafile
Bit map
Icon
Binary data
Dynamic link library
C code
Pascal code
BASIC code
COBOL code
FORTRAN code
Assembler code
Library
Resource file
Object code

Data files only require identification of the file type. For data files without EAs, the file type is derived from the file extension, if there is one.

File object types are represented as length-preceded ASCII strings, uniquely identifying the file object's type. This identifier is referenced within the application's .ASSOCTABLE EA in order to bind the data file type to the application. It is important that this name be a unique identifier because all file type names are public data. For example, if application A and application B both had a type name of SPREADSHEET, the filing system would not be able to identify A's SPREADSHEET from B's SPREADSHEET.

The recommended convention for defining file object types is:

  • Company_name
  • Application_name
  • Application-specific_name

For example, spreadsheet files generated by My_Application written by My_Company might have a file object type of the following.

   My_Company My_Application Spreadsheet

Type names must be ASCII characters and case is significant.

Note
The performance of extended attributes is dependent on the file system. Because some file systems store extended attributes in first-in/first-out (FIFO) order, it is important to write the .TYPE entry first so OS/2 can access that information quickly.

The .VERSION Extended Attribute

The .VERSION extended attribute (EA) contains the version number of the file format, as shown below.

   My_Application 1.0

The name of this EA consists of the string ".VERSION". The value of this EA contains the file object version number. This attribute can be ASCII or binary. Only the application that created the file object should modify the value of this EA. It can also be used to indicate an application or dynamic link library version number.

Managing Extended Attributes

An application can create, query, and set extended attributes (EAs) for any file object.

The application can define extended attributes for a file when the file is created with DosOpen. Similarly, the application can define EAs for a directory when the directory is created using DosCreateDir.

An application can define EAs for existing file objects by referencing the file object by its handle and calling DosSetFileInfo, or by referencing the file object by its name and calling DosSetPathInfo.

An application can examine the EAs for a file object by referencing the file object by its handle and calling DosQueryFileInfo, or by referencing the file object by its name and calling DosQueryPathInfo. The application can also call DosEnumAttribute, using either the file object's handle or its name, to get information about the file object's EAs.

In addition, an application can search for file objects and specify that certain EAs be returned by calling DosFindFirst.

Controlling Access to Extended Attributes

Like the file objects they are associated with, extended attributes (EAs) can have more than one process accessing them at the same time. This means that one process could be querying EAs for a file object, while another is setting EAs for the same file object.

In addition, operations on EAs are not atomic. That is, a query or set operation might not complete before another query or set operation is performed on the same object. If an error occurs before an entire list of EAs has been set, all, some, or none of them may actually remain set on the file object. This means that EAs may not remain in a consistent state unless the order in which the operations are performed can be guaranteed.

Sharing protection is provided so that unpredictable results do not occur during multiple simultaneous operations on extended attributes. EA manipulation is associated with the access permission to the related file object (file or directory).

Handle-based access permission is controlled by the sharing/access mode of the associated file object:

  • If the file object is open for read access, querying EAs (using DosQueryFileInfo) is permitted.
  • If the file object is open for write access, setting EAs (using DosSetFileInfo) is permitted.

Path-based access permission is controlled by adding the file object to the sharing set for the duration of the call: an application requires read access and file-sharing permission must be set to deny-write.

  • For setting EAs (using DosSetPathInfo), an application requires write access and file-sharing permission must be deny-read-write.
Note
The functions that set and query EAs fail if another process holds conflicting sharing rights to the file object.

No explicit EA sharing is performed for DosEnumAttribute. Implicit sharing exists if the caller passes the handle of an open file, since sharing access to the associated file is required to modify its EA. No sharing is performed if the caller passes the path name. This means that if some other process is editing the EAs, and changes them between two calls to DosEnumAttribute, inconsistent results might be returned (for example, the same values might be returned twice, some values might be missed, and so on).

To prevent the modification of EAs for the handle case, the file should be opened in deny-write mode before calling DosEnumAttribute. To prevent the modification of EAs for the path name case, the file should be open in deny-write mode before calling DosEnumAttribute. For the directory name case, no sharing is possible.

Extended Attribute Data Structures

There are a series of data structures through which OS/2 functions manipulate extended attributes (EAs) for applications:

  • Full EAs (FEA2s)
  • A list of full EAs (FEA2LIST)
  • Get EAs (GEA2)
  • A list of get EAs (GEA2LIST)
  • EAOP2s
Full Extended Attribute (FEA2) Data Structure

A full EA (FEA2) data structure contains the extended attribute name and value. The name length does not include the trailing NULL. The characters that form the name are legal file name characters.

An FEA2LIST is a list of FEA2 structures, preceded by the length of the list (including the length itself). FEA2Lists are used for querying, adding, deleting, or changing EAs. They are required input parameters for the functions that create or set extended attributes (DosSetFileInfo and DosSetPathInfo). They are required output parameters for the functions that query extended attributes (DosQueryFileInfo, DosQueryPathInfo, and DosEnumAttribute).

FEA2 data structures include the lengths of the extended attribute's names and values. EA name lengths of 0 are illegal and cause errors to be returned by EA functions. An EA value length of 0 has special meaning:

  • Setting an EA with a value length of 0 in the FEA2 data structure causes that attribute to be deleted, if possible.

SGetting an EA with a value length of 0 in the FEA2 data structure indicates that the attribute is not present.

Get Extended Attribute (GEA2) Data Structure

A Get EA (GEA2) is an extended attribute name. The name length does not include the trailing NULL.

A GEA2LIST is a list of GEA2 structures, preceded by a length of the list (including the length itself). GEA2Lists are used for retrieving the values for a particular set of extended attributes. They are required input parameters for the functions that query extended attributes (DosQueryFileInfo, DosQueryPathInfo, and DosEnumAttribute).

Note
GEA2 data structures include the lengths of extended attribute's names and values. EA name lengths of 0 are illegal and cause errors to be returned by EA functions. An EA value length of 0 has special meaning. Setting an EA with a value length of 0 in the FEA2 data structure causes that attribute to be deleted, if possible. Getting an EA with a value length of 0 in the FEA2 data structure indicates that the attribute is not present.
Extended Attribute Operation (EAOP2) Data Structure

An extended attribute operation (EAOP2) data structure consists of a GEA2LIST, an FEA2LIST, and an error field. All extended attribute manipulation is performed using this structure. Before calling an extended attribute function, an application must define an EAOP2 structure, with the GEA2LIST and FEA2LIST appropriately defined.

The use of GEA2LIST and FEA2LIST for each function is described further in the Control Program Programming Reference.

Preserving Extended Attributes

Extended attributes (EAs) are supported in OS/2's FAT file system and High Performance File System (HPFS). Extended attributes are not supported by the FAT file system used in versions of OS/2 prior to Version 1.2, nor are they supported in the DOS operating system.

EAs associated with a file object are not part of a file object or of its data, but are maintained separately and managed by the file system that manages that object. EAs reside on the volume on which the file object resides and are connected to their file object by pointers from the file object.

Therefore, EAs belonging to a file object are lost when moving that file object from a storage device managed by an OS/2 FAT or installable file system to a storage device managed by the old FAT file system.

EAs can be lost under other circumstances, as well:

  • When a program that does not recognize EAs (for example, an editor written for DOS) performs a non-truncating open on the files with which the EAs are associated
  • When the files they are associated with are sent over COM links

So that files with EAs can be manipulated under these circumstances, without losing their EAs, OS/2 provides a utility called EAUTIL EAUTIL enables users to separate extended attributes from the specified file object, optionally disassociating them from the file object. The extended attributes are placed into a specified HoldFile. This utility also enables users to reattach the separated extended attributes with their file objects.

EAUTIL can be applied to subdirectories, as well as to files. It does not support global file name characters in parameters; it operates on a single file object at each invocation.

Users can use EAUTIL to:

  • Strip EAs off files to be edited with a program that does not recognize EAs.
  • Place the EAs into normal files so they can be dealt with by old tools (such as backup, restore, and so on) or easily transmitted.
  • Reattach EAs to files after the files have been brought back from the systems where EAs are not supported.

Protecting Extended Attributes

Programs written for releases of OS/2 and DOS that do not support extended attributes (EAs) will tend to lose EAs simply because they do not know that they exist. OS/2 provides some controls that prevent old programs from destroying critical data without unduly restricting their activities. This is done by classifying programs and marking the extended attributes that are associated with files.

Programs are classified as:

  • Those that recognize EAs. These include OS/2 Version 1.2 and later programs.
  • Those that do not recognize EAs. These include programs written for releases of OS/2 and DOS that do not support EAs.

EAs associated with files are marked as critical or non-critical. Programs that do not recognize EAs are not permitted to manipulate files that have critical EAs associated with them. This protection does not apply to directories. EAs associated with directories cannot be marked as critical.

Critical Extended Attributes

Extended attributes (EAs) are non-critical by default. A non-critical EA is one that is not necessary to the functionality of the application. That is, if a non-critical EA is lost, the system continues to operate correctly. For example, losing the icons associated with data files does not generally cause any ill effect other than the inability to show the icon.

A critical extended attribute is one which is necessary to the correct operation of OS/2 or of a particular application. EAs should be marked as critical if their loss would cause the system or program to perform incorrectly. For example, a mail program might store mail headers in EAs. The loss of the header from a message would normally render the mail program completely unable to further use that message. This would be unacceptable, so the mail program should mark this EA as critical.

A file has critical extended attributes (EAs) if at least one EA attached to the file is marked as critical.

Marking EAs as critical only prevents programs that do not recognize EAs from losing the EAs from the file. It does not prevent deletion of files by any application.

Applications must be careful how they mark their EAs. If they are too aggressive marking EAs as critical, users might be prevented from accessing files that their application uses. EAs are marked as critical by setting the critical bit. The critical bit is bit 7 of the flags byte of the FEA2 data structure. If this bit is 0, the EA is a non-critical EA. If it is 1, it is a critical EA. The symbolic constant FEA_NEEDEA can be used to indicate a critical EA.

The creator of the EA determines whether it is critical or not.

Programs that do not recognize extended attributes (EAs) are prevented from performing certain operations on files that have critical EAs associated with them. For example, a program that does not recognize EAs is not permitted to perform a non-truncating open on a file with critical EAs associated with it, because programs cannot be permitted to read the data and ignore the EAs.

Programs that do not recognize EAs are, however, permitted to perform those operations that they can do completely. For example, they can delete files with critical EAs associated with them. Programs that do not recognize EAs are not prevented from accessing files whose EAs are not critical.

Programs that recognize EAs have no restrictions placed on their actions with respect to critical EAs.

Programs that recognize extended attributes must identify themselves to OS/2. This is done by including the NEWFILES declaration in the program's module definition file. The NEWFILES declaration is also how programs indicate that they understand and use long file names.

Searching for Extended Attributes

An application can search for file objects that have specific extended attribute names by calling DosFindFirst twice. The steps involved are:

  1. Call DosFindFirst for FileInfoLevel = 2, to get the length of the buffer required to hold the EAOP2 data associated with a matching file object.
  2. Call DosFindFirst for FileInfoLevel = 3, to get the EAOP2 data associated with the matching file object.

Supporting Extended Attributes

To support extended attributes, applications should do the following:

  1. Fill in the .ASSOCTABLE extended attribute for all major file types that the application recognizes or uses.
  2. Fill in the .ICON extended attribute for executable files.
  3. Set the .TYPE extended attribute for data files the application creates.
  4. Fill in and use the .LONGNAME extended attribute as appropriate.
  5. Support .HISTORY and .VERSION.
  6. Support the other Standard Extended Attributes as appropriate.