# Creating Data Types Manually

There are two ways to create a data type definition:

- Using the Create Action tool. Using Create Action is covered in SAG.dtCrA.mkr.1.

- By manually creating the data type definition.

Creating a data type manually requires you to edit a database file.

This chapter describes how to manually create data type definitions.

SAG.CrDT.div.3
SAG.CrDT.div.4
SAG.CrDT.div.5
SAG.CrDT.div.8
SAG.CrDT.div.14

## See Also

- For an introduction to data types, see SAG.IntAc.mkr.1.

- For reference information about data type definitions, see the `dtdtsfile(4)` man page.

## Reasons You Must Create a Data Type Manually

Manually creating a data type lets you use all the capabilities built into the syntax of data type definitions.

You must create a data type manually if you want to use these features of data types:

- Location (path)-based data typing

- The ability to specify actions associated with the data type other than Open and Print

- Multiple name, pattern, or content criteria for the same data type—for example, a data type based on files named `*.abc` or `*.def`

- Link-based data typing

## Components of a Data Type Definition: Criteria and Attributes

A data type definition consists of two separate database definitions:

- The
  `DATA_ATTRIBUTES` definition.

  The `DATA_ATTRIBUTES` definition describes the data type's name and the appearance and behavior of files of this type.

- The `
  DATA_CRITERIA` definition.

  The `DATA_CRITERIA` definition describes the typing criteria. Each criteria definition specifies the `DATA_ATTRIBUTES` definition to which the criteria apply.

There must be at least one `
DATA_CRITERIA` definition for each `DATA_ATTRIBUTES` definition; a `DATA_ATTRIBUTES` definition can have multiple `DATA_CRITERIA` associated with it.

For example, you could create an attributes definition for PostScript files that described how PostScript files look and behave in File Manager. Then, you could create two separate criteria for the PostScript data type— one based on file name and the other based on file content.

For more information, see SAG.CrDT.div.14.

## Creating a Data Type Manually: General Steps

This section describes how to create a data type configuration file.

### Configuration Files for Data Types

The requirements for configuration files containing data type definitions are:

- The files must use the naming convention name`.dt`

- The files must be located on the database search path. The default search path is:

  Personal data types | HomeDirectory`/.dt/types`
  System-wide data types | `/etc/dt/appconfig/types/`language
  Built-in data types | `/usr/dt/appconfig/types/`language. You should not use this directory.

For information on modifying the database search path, see SAG.Datab.mkr.6.

### To Create a Data Type Definition

1. Open an existing database file or create a new one.

   For more information, see the previous section, SAG.CrDT.mkr.5.

2. Define the data attributes for the data type using the syntax:

       DATA_ATTRIBUTES data_type_name
       {
        ICON         image_name
        DESCRIPTION  string
                     attribute_field
                     attribute_field
         …
       }

   where:

   data_type_name | A unique name given to this data type.
   image_name | File name or path of an icon file. Use the base name for the file. For example, for icon files `myimage.m.pm` and `myimage.t.pm`, use `myimage`.
   attribute_field | Field that defines the appearance or behavior of the data type.
   string | Character string. The contents will be the on-item help for the data type.

   See SAG.CrDT.div.8.

3. Define the data criteria for the data type using the syntax:

       DATA_CRITERIA criteria_name
       {
        DATA_ATTRIBUTES_NAME  data_type_name
                              criteria_field
                              criteria_field
            …
       }

   where:

   criteria_name | Unique name for this criteria definition
   data_type_name | Name used in the `DATA_ATTRIBUTES` definition
   criteria_field | Field used to define the criteria for assigning a file to this data type

   See SAG.CrDT.div.14.

4. Save the database file.

5. Create the icons for the data type.

   For more information, see SAG.CrDT.div.10.

6. If necessary, create the actions listed in the `ACTIONS` field of the attributes definition.

7. Double-click Reload Actions in the Desktop_Tools application group to reload the database.

### Example of Creating a Personal Action and Data Type

Suppose your system contains an application named `xgif`, which displays GIF pictures. Ordinarily, you run the program by executing:

    xgif filename

You want to be able to display GIF pictures several ways:

- By double-clicking a GIF data file

- By selecting the data file and choosing the application from the Selected menu

  1. Open a new file HomeDirectory`/.dt/types/GifViewer.dt` for editing.

  2. Type the data type definitions:

         DATA_ATTRIBUTES Gif
         {
          DESCRIPTION  Gif image file.
          ICON         GifIcon
          ACTIONS      View
         }
         DATA_CRITERIA Gif_Criteria
         {
          DATA_ATTRIBUTES_NAME  Gif
          NAME_PATTERN          *.gif
         }

  3. Type the action definition for the GifViewer action:

         ACTION GifViewer
         {
          EXEC_STRING     xgif %(File)Arg_1“Gif file to view:”
          WINDOW_TYPE     NO_STDIO
          DESCRIPTION     Double-click or drop a file to \
                          start the Gif viewer.
         }

     Since the definition does not include an `ICON` field, the action will use the system's default icon.

  4. Type the following map action to connect the GifViewer action to the View action listed in the data type definition. Use the `ARG_TYPE` field to restrict this view action to Gif-type files.

         ACTION View
         {
          ARG_TYPE    Gif
          TYPE        MAP
          MAP_ACTION  GifViewer
         }

  5. Save the file.

  6. Double-click Reload Actions in the Desktop_Tools application group to reread the database.

## Defining the Data Attributes of a Data Type

The `DATA_ATTRIBUTES` definition defines the appearance and behavior of the data type. It specifies the name of the data type, and provides the ability to specify:

- The File Manager icon (`ICON` field)

- The double-click behavior and contents of the Selected menu (`ACTIONS` field)

- The data type's on-item help (`DESCRIPTION
  ` field)

### Specifying the Icon Image Used for a Data Type

Use the `
ICON` field to specify the icon used in File Manager. If you do not specify an icon image, File Manager displays only a label.

The value of the `
ICON` field can be:

- A
  base file name.

  The base file name is the name of the file containing the icon image, minus the file-name suffixes for size (`l`,`m`, and `t`) and image type (`bm` and `pm`). For example, if files are named `GameIcon.m.pm` and `GameIcon.t.pm`, use `GameIcon`.

  If you use the base file name, the icon files must be placed in a directory on the icon search path:

  - Personal icons: HomeDirectory`/.dt/icons`

  - System-wide icons: `/etc/dt/appconfig/icons/`language

- An absolute path to the icon file, including the full file name.

  You should use the absolute path only if the icon file is not located on the icon search path. For example, if icon file `GameIcon.m.pm` is placed in the directory `/doc/projects`, which is not on the icon search path, the value of the `ICON` field would be `/doc/projects/GameIcon.m.pm`.

SAG.CrDT.tbl.1 lists icon sizes you should create and the corresponding file names.

### Icon Names and Sizes for Data Type Icons

`Size in Pixels` | `Bitmap Name` | `Pixmap Name`
48 by 48 | name`.l.bm` | name`.l.pm`
32 by 32 | name`.m.bm` | name`.m.pm`
16 by 16 | name`.t.bm` | name`.t.pm`

### Associating Data Types with Actions

There are two ways that data types are associated with actions:

- The `
  ACTIONS` field in the `DATA_ATTRIBUTES` definition lists the actions that will appear in File Manager's Selected menu. The first action in the list is the default (double-click) action.

- Actions can be restricted to specified data types using the action definition's `
  ARG_TYPE` field.

For example, the following data type definition creates a data type for special “readme” files created by your system administrator that use the naming convention `*.rm`.

    DATA_ATTRIBUTES SysReadmeFile
    {
     ICON     SysReadMe
     ACTIONS  Open,Respond
    }
    DATA_CRITERIA SysReadmeFileCriteria
    {
     NAME_PATTERN           *.rm
     DATA_ATTRIBUTES_NAME   SysReadmeFile
    }

A special Respond action is defined below for the file. It opens a writable copy of the file in Text Editor. When the file is saved and Text Editor is exited, the file is mailed to the system administrator (mail address `sysadmin@utd`).

    ACTION Respond
    {
     ARG_TYPE     SysReadmeFile
     EXEC_STRING  /bin/sh -c 'cp %Arg_1% $HOME/readme.temp;\
                  chmod +w $HOME/readme.temp;              \
                  dtpad $HOME/readme.temp;                 \
                  cat $HOME/readme.temp |                  \
                  /usr/bin/mailx sysadmin@utd;             \
                  rm $HOME/readme.temp'
     WINDOW_TYPE  NO_STDIO
    }

### Hiding Files Based on Data Type

If a file is an invisible data type, it never appears in File Manager.

Use the `PROPERTIES` field in the `DATA_ATTRIBUTES` definition to specify that objects of this type be hidden:

    PROPERTIES  invisible

### Specifying Behaviors When the File Is Manipulated

The following `DATA_ATTRIBUTES` fields are used primarily by application programmers. They specify how files behave when the user performs various desktop activities.

For more information, see the Common Desktop Environment Programmer's Guide, which is part of the developer environment documentation.

Field | Description
`MOVE_TO_ACTION` | For containers such as directories. Specifies an action to be run when a file is moved to a container of this data type.
`COPY_TO_ACTION` | For containers such as directories. Specifies an action to be run when a file is copied to a container of this data type.
`LINK_TO_ACTION` | Specifies an action to be run when a file is linked to a file of this data type.
`IS_TEXT` | Specifies that files of this data type contain text that can be displayed in a text box.
`MEDIA` | Specifies the corresponding ToolTalk media type.
`MIME_TYPE` | Specifies the corresponding MIME type.
`X400_TYPE` | Specifies the corresponding X400 type.

## Defining the Data Criteria for a Data Type

The `
DATA_CRITERIA` definition defines the criteria used to assign an object type to a file or directory.

You can use the following criteria for object typing:

Criteria | Description
File name | The file name must match a specified pattern. Use the `NAME_PATTERN` field.
File location | The path must match a specified pattern. Use the `PATH_PATTERN` field.
File contents | A specified portion of the file's contents must match specified data. Use the `CONTENT` field.
File mode | The file must possess the specified permissions (read, write, execute, directory). Use the `MODE` field.
Symbolic links | The typing is based on the file to which the object is linked.

You can use more than one criteria for a data type. However, you should not use the `NAME_PATTERN` and `PATH_PATTERN` criteria in the same data type.

### Name-Based Data Types

Use the `NAME_PATTERN` field to specify the naming requirement. The field value can include the following wildcards:

`?` | Matches any single character
`*` | Matches any sequence of characters (including a null string)
`[`cc…`]` | Matches any of the characters (c) enclosed in brackets
`[`c−c`]` | Matches any of the characters in the range c through c

#### Examples

- The following data type definition creates a data type based on the file name. The file name must begin with `QS` and end with `.doc`.

      DATA_ATTRIBUTES QS_Doc
      {
       DESCRIPTION  This file contains a document for the QS project.
       ICON         Word_Doc
       ACTIONS      Open
      }

      DATA_CRITERIA QS_Doc_Criteria
      {
       NAME_PATTERN          QS*.doc
       DATA_ATTRIBUTES_NAME  QS_Doc
      }

- The following definition creates a data type for directories named `Demo_`n where n is 0 through 9.

      DATA_ATTRIBUTES Demo_directory
      {
       DESCRIPTION  This is a directory. Double-click to open it.
       ICON         Demo
       ACTIONS      OpenInPlace,OpenNewView
      }

      DATA_CRITERIA Demo_directory_criteria
      {
       NAME_PATTERN          Demo_[0-9]
       MODE                  d
       DATA_ATTRIBUTES_NAME  Demo_directory
      }

### Location-Based Data Types

Use the `
PATH_PATTERN` field to specify the path. You can use the same wildcard characters as with `NAME_PATTERN`.

For example, the following data type uses a criteria based on path.

    DATA_ATTRIBUTES Project_Graphics
    {
     DESCRIPTION   Graphics file for the QS project. Double-click the \
                   icon to see the graphic.
     ICON          QSgraphics
    }
    DATA_CRITERIA Project_Graphics_Criteria
    {
     DATA_ATTRIBUTES_NAME  Project_Graphics
     PATH_PATTERN          */projects/QS/graphics/*
    }

### Data Types Based on Name and Location

To create a data type based on both file name and location, include the name in the `PATH_PATTERN` value. You cannot use both `NAME_PATTERN` and `PATH_PATTERN` in the same criteria definition.

#### Examples

- The QS_Source_Files data type defined below applies to all files named `app` n`.c`, where n= 1 through 9, located in subdirectories of `*/projects/QS`.

      DATA_ATTRIBUTES QS_Source_Files
      {
         …
      }
      DATA_CRITERIA QS_Source_Files_Criteria
      {
       PATH_PATTERN      */projects/QS/*/app[1-9].c
       DATA_ATTRIBUTES_NAME      QS_Source_Files
      }

- The following data type applies to all files in the directory `/doc/project1` named `ch` nn`.`xxx where n is 0 through 9, and xxx is any three-character file- name suffix.

      DATA_ATTRIBUTES ChapterFiles
      {
       DESCRIPTION  Chapter file for the project document.
       ICON         chapter
       ACTIONS      Edit,Print
      }

      DATA_CRITERIA Chapter_Criteria
      {
       PATH_PATTERN          /doc/project1/ch[0-9][0-9].???
       DATA_ATTRIBUTES_NAME  ChapterFiles
      }

### Using File Modes as a Typing Criteria

Use the `
MODE` field to specify the required permissions.

Mode criteria are usually used in combination with name-based, location- based, or content-based data typing. They allow you to limit a data type to a file or directory, or to specify the required read, write, and execute permissions.

The `MODE` field can include the following logical operators and characters:

Operator | Description
`!` | Logical operator NOT
`&` | Logical operator AND
| | Logical OR

Character | Description
`f` | The data type applies only to files
`d` | The data type applies only to directories
`r` | The file is readable by any user
`w` | The file is writable by any user
`x` | The file is executable by any user
`l` | The file is a link
`u` | The file is set-uid
`g` | The file is set-gid

The default for a particular criterion is that the mode does not matter.

#### Examples

- The following mode fields restrict the data type as described:

  `f&!w` | Read-only files
  `!w` | Read-only files and directories
  `f&x` | Executable files
  `f&w&x` | Files that are both writable and executable
  x|!w | Files that are executable or read-only

- The following data type definition creates a data type for read-only, non- executable files whose file names follow the naming convention `*.doc`. It assumes that a View action has been defined for the data type.

      DATA_ATTRIBUTES ReadOnlyDocument
      {
       ICON         read_only
       DESCRIPTION  This document is not writable. Double-clicking  \
                    runs your editor with a read-only copy of the   \
                    file.
       ACTIONS      View
      }

      DATA_CRITERIA ReadOnlyDocument_Criteria
      {
       NAME_PATTERN          *.doc
       MODE                  !d&!x&!w
       DATA_ATTRIBUTES_NAME  ReadOnlyDocument
      }

### Content-Based Data Typing

Use the `
CONTENT` field to specify data typing based on the content of the file. Content-based data typing can be used in combination with name- or location- based data typing.

The typing can be based on either string or numeric content for files. The first byte in the file is numbered 0.

- For string content of a file, use the syntax:

      CONTENT  starting_byte string string

- For number content of a file, use the syntax:

      CONTENT starting_byte byte number
      CONTENT starting_byte short number
      CONTENT starting_byte long number

- For the contents of a directory, use the syntax:

      CONTENT 0 filename “file_name”

  Use standard C notation for octal (leading `0`) and hexidecimal (leading `0X`) numbers.

Use of content-based data typing will result in slower system performance. Wherever possible, use name- and location-based typing instead.

For example, the following data type, Writable_Wingz, applies to all files with write permission containing the string `WNGZ` at the beginning of the file.

    DATA_ATTRIBUTES Writable_Wingz
    {
     …
    }

    DATA_CRITERIA Writable_Wingz_Criteria
    {
     CONTENT               0 string WNGZ
     MODE                  w&!d
     DATA_ATTRIBUTES_NAME  Writable_Wingz
    }

### To Create a Data Type with Several Independent Criteria

You can create a data type with several independent criteria—that is, the file is assigned to the data type if it meets either (or both) of the criteria.

1. Create the `DATA_ATTRIBUTES` definition for the data type.

2. Create a `
   DATA_CRITERIA` definition for each criteria.

   Use the `DATA_ATTRIBUTES_NAME` field to connect each criteria to the same `DATA_ATTRIBUTES` definition.

For example, the following definitions create the Mif data type. Typing is based on name or content.

    DATA_ATTRIBUTES Mif
    {
     ICON         Frame
     ACTION_LIST  Open,Print
    }

    DATA_CRITERIA Mif_Name_Criteria
    {
     DATA_ATTRIBUTES_NAME  Mif
     NAME_PATTERN          *.mif
    }

    DATA_CRITERIA Mif_Content_Criteria
    {
     DATA_ATTRIBUTES_NAME  Mif
     CONTENT               1 string MIFFile
    }

## Creating Localized Data Types

The search path for data types includes language-dependent locations. The desktop uses the value of
LANG to determine the locations searched for data type definitions.

### Locations for Localized Data Types

Localized data type definitions must be placed in the proper language- dependent directories along the actions search path.

The default search path is:

- Personal actions: HomeDirectory`/.dt/types`

- System-wide actions: `/etc/dt/appconfig/types/`language

- Built-in actions: `/usr/dt/appconfig/types/`language

### To Localize a Data Type

1. Create a file in the appropriate language-dependent directory (for example, in `/etc/dt/appconfig/types/japanese`).

2. Copy the data type definition to the language-dependent configuration file.

3. Localize one or more fields in the data type definition.