<!-- $XConsortium: ch09.sgm /main/7 1996/09/08 19:37:22 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter Id="PG.datat.div.1">
<Title Id="PG.datat.mkr.1">Accessing the Data-Typing Database</Title>
<Para>This chapter describes the data-typing functions and how to use the data-
typing database.</Para>
<InformalTable Id="PG.datat.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Summary121'--><XRef Role="JumpText" Linkend="PG.datat.mkr.2"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Data Criteria and Data Attributes122'--><XRef Role="JumpText" Linkend="PG.datat.mkr.5"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Data-Typing Functions129'--><XRef Role="JumpText" Linkend="PG.datat.mkr.9"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Registering Objects as Drop Zones133'--><XRef Role="JumpText" Linkend="PG.datat.mkr.12"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Example of Using the Data-Typing Database134'--><XRef Role="JumpText" Linkend="PG.datat.mkr.14"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Sect1 Id="PG.datat.div.2">
<Title Id="PG.datat.mkr.2">Summary</Title>
<Para>Data typing provides an extension to the attributes of files and data beyond
what is provided by the traditional UNIX file systems. These extensions consist
of attributes, such as icon names, descriptions, and actions, that can be
performed on files and data. This information is stored in name/value pairs in
the <Filename>DATA_ATTRIBUTES</Filename> table (or database). The desktop uses a certain set of
<Filename>DATA_ATTRIBUTES</Filename>, described in the following paragraphs. The
<Filename>DATA_ATTRIBUTES</Filename> table is extendable for future and application-specific
growth, although extending this table is not recommended because other
applications may not check the additions.</Para>
<Para>Data is matched with a specific file or data entry in a <Filename>DATA_CRITERIA</Filename> table.
The <Filename>DATA_CRITERIA</Filename> table entries are sorted in decreasing order from most
specific to least specific. For example, <Filename>/usr/lib/lib*</Filename> is more specific than
<Filename>/usr/*</Filename> and would, therefore, appear first. When a request to type a file or
data is made, the table is checked in sequence to find the best match using the
information provided either from the file or from the data. When an
information and entry match is found, <Filename>DATA_ATTRIBUTES_NAME</Filename> is used to
find the proper <Filename>DATA_ATTRIBUTES</Filename> entry.</Para>
<Sect2 Id="PG.datat.div.3">
<Title Id="PG.datat.mkr.3">Library and Header Files<IndexTerm>
<Primary>data typing</Primary>
<Secondary>library</Secondary>
</IndexTerm><IndexTerm>
<Primary>library</Primary>
<Secondary>data typing</Secondary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>library</Secondary>
</IndexTerm><IndexTerm>
<Primary>library</Primary>
<Secondary>actions</Secondary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libDtSvc&lt;Default Para Font> library</Primary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libXm&lt;Default Para Font> library</Primary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libX11&lt;Default Para Font> library</Primary>
</IndexTerm></Title>
<Para>To use data typing, you need to link to the <Command>libDtSvc</Command> library. Actions are
usually loaded with the data-typing information. Actions require links to the
<Command>libXm</Command> and <Filename>libX11</Filename> libraries. The header files are <ComputerOutput>Dt/Dts.h</ComputerOutput> and <ComputerOutput>Dt/Dt.h</ComputerOutput>.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.4">
<Title Id="PG.datat.mkr.4">Demo Program<IndexTerm>
<Primary>data typing</Primary>
<Secondary>demo program</Secondary>
</IndexTerm><IndexTerm>
<Primary>demo program</Primary>
<Secondary>data typing</Secondary>
</IndexTerm></Title>
<Para>A demo program containing an example of how to use the data-typing
database is in <Filename>/usr/dt/examples/dtdts/datatypes/datatyping.c</Filename>.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.datat.div.5">
<Title Id="PG.datat.mkr.5">Data Criteria and Data Attributes<IndexTerm>
<Primary>data typing</Primary>
<Secondary>data criteria</Secondary>
</IndexTerm><IndexTerm>
<Primary>data criteria</Primary>
</IndexTerm><IndexTerm>
<Primary>data attributes</Primary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>data attributes</Secondary>
</IndexTerm></Title>
<Para>Data typing consists of two parts:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>A database that stores data criteria and data attributes</Para>
</ListItem>
<ListItem>
<Para>A collection of routines that query the database</Para>
</ListItem>
</ItemizedList>
<Para>The attributes of<IndexTerm>
<Primary>data typing</Primary>
<Secondary>criteria</Secondary>
</IndexTerm><IndexTerm>
<Primary>criteria, data typing</Primary>
</IndexTerm>
data criteria, in alphabetical order, are:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>CONTENT</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>DATA_ATTRIBUTES_NAME</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_NAME</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_PATH</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>MODE</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>NAME_PATTERN</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>PATH_PATTERN</Filename></Para>
</ListItem>
</ItemizedList>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.7"> describes the data criteria in the order in which you are most likely to
use them.</Para>
<Table Id="PG.datat.tbl.1" Frame="Topbot">
<Title Id="PG.datat.mkr.6">Data Criteria in Order of Most Likely Use</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.82341 in">
<ColSpec Colname="2" Colwidth="3.44445 in">
<ColSpec Colname="3" Colwidth="1.72817 in">
<THead>
<Row>
<Entry><Para><Literal>Criteria</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
<Entry><Para><Literal>Typical Usage</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Filename>DATA_ATTRIBUTES_NAME</Filename></Para></Entry>
<Entry><Para>The name of this type of data. This value is a
<Filename>record_name</Filename> in the data attributes table.</Para></Entry>
<Entry><Para>POSTSCRIPT</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>NAME_PATTERN</Filename></Para></Entry>
<Entry><Para>A shell pattern-matching expression describing the file
names that could match this data. The default is an empty
string, which means to ignore file patterns in matching.</Para></Entry>
<Entry><Para><Filename>*.ps</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>CONTENT</Command></Para></Entry>
<Entry><Para>Three values that are interpreted as the start, type, and
value fields of the magic file used by the file utility. See
the <Filename>file</Filename>(1) man page for more information. The default
is an empty field, which means to ignore contents in
matching. The following types are examples of what can
be matched: string, byte, short, long, and file name.</Para></Entry>
<Entry><Para><Command>0 string !&percnt;</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>MODE</Command></Para></Entry>
<Entry><Para>A string of zero to four characters that match the mode
field of a <Command>stat</Command> structure. See the <Filename>stat(2)</Filename> man page for
more information. The first character indicates:</Para><Para><Command>d</Command> matches a directory</Para><Para><Command>s</Command> matches a socket</Para><Para><Command>l</Command> matches a symbolic link</Para><Para><Command>f</Command> matches a regular file</Para><Para><Command>b</Command> matches a block file</Para><Para><Command>c</Command> matches a character special file</Para></Entry>
<Entry><Para><Filename>f&amp;!x</Filename></Para></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>The characters listed below can be either the first or
subsequent characters:</Para><Para><Command>r</Command> matches any file with any of its user, group, or
other read permission bits set.</Para><Para><Command>w</Command> matches any file with any of its user, group, or
other write permission bits set.</Para><Para><Command>x</Command> matches any file with any of its user, group, or
other execute or directory-search permission
bits set.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>For example, the <Command>MODE</Command> field of <Command>frw</Command> matches any regular
file that is readable or writable; <Command>x</Command> matches any file with
any of its executable or search bits set.</Para><Para>The default is an empty field, which means to ignore the
mode in matching.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>PATH_PATTERN</Filename></Para></Entry>
<Entry><Para>A shell pattern-matching expression describing the
absolute path names that could match this data. The
default is an empty string, which means to ignore path
patterns in matching.</Para></Entry>
<Entry><Para>*/<Symbol Role="Variable">mysubdir</Symbol>/*</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_NAME</Filename></Para></Entry>
<Entry><Para>See <Filename>dtdtsfile(4)</Filename> man page.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_PATH</Filename></Para></Entry>
<Entry><Para>See <Filename>dtdtsfile(4)</Filename> man page.</Para></Entry>
<Entry></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>Some of the more common attributes of data types, in alphabetical order, are:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>ACTIONS</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>COPY_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>DESCRIPTION</Command></Para>
</ListItem>
<ListItem>
<Para><Command>ICON</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>INSTANCE_ICON</Filename></Para>
</ListItem>
<ListItem>
<Para>IS_EXECUTABLE</Para>
</ListItem>
<ListItem>
<Para><Filename>IS_TEXT</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>MEDIA</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>MIME_TYPE</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>MOVE_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para>NAME_TEMPLATE</Para>
</ListItem>
<ListItem>
<Para><Command>PROPERTIES</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>X400_TYPE</Filename></Para>
</ListItem>
</ItemizedList>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.6"> describes the data attributes in the order in which you are most likely
to use them.</Para>
<Table Id="PG.datat.tbl.2" Frame="Topbot">
<Title Id="PG.datat.mkr.7">Data Attributes in Order of Most Likely Use</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.82341 in">
<ColSpec Colname="2" Colwidth="3.20635 in">
<ColSpec Colname="3" Colwidth="1.9623 in">
<THead>
<Row>
<Entry><Para><Literal>Criteria</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
<Entry><Para><Literal>Typical Usage</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>DESCRIPTION</Command></Para></Entry>
<Entry><Para>A human-readable description of this data. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the name of the data attribute should be used.</Para></Entry>
<Entry><Para>This is a PostScript page
description.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ICON</Command></Para></Entry>
<Entry><Para>The name of the icon to be used for this data. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the standard icon should be used. See
<Filename>dtdtsfile(4)</Filename> for more details on icon naming.</Para></Entry>
<Entry><Para><Command>Dtps</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>PROPERTIES</Command></Para></Entry>
<Entry><Para>Keywords to indicate properties for this data. Valid
values are invisible and visible. If this field is <Command>NULL</Command> or
is not included in the data attribute record, the visible
property should be assumed. Use this if you want to
completely hide files from the user.</Para></Entry>
<Entry><Para><Command>invisible</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ACTIONS</Command></Para></Entry>
<Entry><Para>A list of actions that can be performed on this data.
This list refers to names in the action table for actions
that are to be presented to the user for objects of this
type. If this field is <Command>NULL</Command> or is not included in the data
attribute record, no action is available.</Para></Entry>
<Entry><Para><Filename>Open,Print</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>NAME_TEMPLATE Field</Command></Para></Entry>
<Entry><Para>A string used to create a new file for data of this type.
The string is passed to <Filename>sprintf</Filename>(3) with the file
name as the single argument. The default is empty.
Contrast this field with the <Filename>NAME_PATTERN</Filename> field of
the data criteria table in that the template is used to
create a specific file, such as <Filename>&percnt;s.c</Filename>, whereas the
pattern is used to find files, such as <Filename>*.c</Filename>.</Para></Entry>
<Entry><Para><Filename>&percnt;s.ps</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>IS_EXECUTABLE Field</Command></Para></Entry>
<Entry><Para>A string-Boolean value that tells users of this data
type that it can be executed as an application. If
<Filename>IS_EXECUTABLE</Filename> is set to <Command>true</Command> <Filename>(</Filename>see
<Filename>DtDtsIsTrue()</Filename>) the data is executable. If this field
is <Command>NULL</Command>, is not included in the data attribute record,
or is not set to true, then the data is considered not
executable.</Para></Entry>
<Entry><Para><Command>true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>MOVE_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is moved to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_MOVE</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>COPY_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is copied to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_COPY</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is linked to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_LINK</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para>IS_TEXT</Para></Entry>
<Entry><Para>A string-Boolean value that tells users of this data
type that it is suitable for manipulation (viewing or
editing) in a text editor or text widget. The <Filename>IS_TEXT</Filename>
field is set to <Command>true</Command> <Filename>(</Filename>see <Filename>DtDtsIsTrue()</Filename>) if the data
is textual in nature and if it should be presented to
the user in text form. Criteria for making this
determination include whether data consists of
human language, is generated and maintained
manually, is usefully viewable and editable in a text
editor, or contains no (or only minimal) structuring
and formatting information.</Para></Entry>
<Entry><Para>See
<!--Original XRef content: 'Table&numsp;9&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.8"> for more
examples.</Para></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>If the <Filename>IS_TEXT</Filename> field is <Command>true</Command>, the data is eligible to be
displayed directly by an application. That is, the
application can load the data directly into a text
editing widget, such as <Command>XmText</Command>.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para>MEDIA Field</Para></Entry>
<Entry><Para>The names in the <Command>MEDIA</Command> name space describe the
form of the data itself. <Command>MEDIA</Command> names are used as
ICCCM selection targets, named in the <Command>MEDIA</Command> field of
the data-type records, and used in the type parameter
of ToolTalk Media Exchange messages.</Para><Para>The <Command>MEDIA</Command> name space is a subset of the name space
of selection target atoms as defined by the ICCCM.
All selection targets that specify a data format are
valid <Command>MEDIA</Command> names, and all valid <Command>MEDIA</Command> names can
be used directly as selection targets. Some selection
targets specify an attribute of the selection (for
example, <Filename>LIST_LENGTH</Filename>) or a side effect to occur (for
example, <Command>DELETE</Command>), rather than a data format. These
attribute selection targets are not part of the <Command>MEDIA</Command>
name space.</Para></Entry>
<Entry><Para><Command>POSTSCRIPT</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>MIME_TYPE</Filename></Para></Entry>
<Entry><Para><Command>MEDIA</Command> is the desktop internal, unique name for data
types. However, other external naming authorities
have also established name spaces. Multipurpose
Internet Message Extensions (MIME), as described in
the referenced MIME RFC, is one of those external
registries, and is the standard-type name space for the
desktop mailer.</Para></Entry>
<Entry><Para><Filename>application/postscript</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>X400_TYPE</Filename></Para></Entry>
<Entry><Para>X.400 types are similar in structure to the <Command>MEDIA</Command> type,
but are formatted using different rules and have
different naming authorities.</Para></Entry>
<Entry><Para><Command>1 2 840 113556 3 2 850</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>INSTANCE_ICON Field</Command></Para></Entry>
<Entry><Para>The name of the icon to be used for this instance of
data, typically a value such as <Filename>&percnt;</Filename><Symbol Role="Variable">name</Symbol><Filename>&percnt;.icon</Filename> [Bug in
<Command>dtdtsfile(4)</Command> man page, too.] If <Filename>INSTANCE_ICON</Filename>
is set, the application should use it instead of <Command>ICON</Command>. If
this field is <Command>NULL</Command> or is not included in the data
attribute record, the <Command>ICON</Command> field should be used.</Para></Entry>
<Entry><Para><Filename>/</Filename><Symbol Role="Variable">myicondir</Symbol><Filename>/&percnt;</Filename><Symbol Role="Variable">name</Symbol><Filename>&percnt;.</Filename>bm</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>DATA_HOST</Filename></Para></Entry>
<Entry><Para>The <Filename>DATA_HOST</Filename> attribute is not a field that can be
added to the data attributes table in the <Filename>*.dt</Filename> file, but
it may be returned to an application reading
attributes from the table. The data-typing service
adds this attribute automatically to indicate the host
system from which the data type was loaded. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the data type was loaded from the local
system.</Para></Entry>
<Entry></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>The <Filename>IS_TEXT</Filename> field differs from the text attribute of the <Filename>MIME_TYPE</Filename> field,
which is the <Command>MIME</Command> content type, as described in the referenced <Command>MIME_ RFC</Command>. The
<Command>MIME</Command> content type determines whether the data consists of textual characters
or byte values. If the data consists of textual characters, and the data is labeled
as <Filename>text/*</Filename>, the <Filename>IS_TEXT</Filename> field determines whether it is appropriate for the data
to be presented to users in textual form.</Para>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.8"> shows some examples of <Filename>IS_TEXT</Filename> usage with different <Command>MIME_TYPE</Command> attributes.</Para>
<Table Id="PG.datat.tbl.3" Frame="Topbot">
<Title Id="PG.datat.mkr.8">IS_TEXT Attribute Examples</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="3.67858 in">
<ColSpec Colname="2" Colwidth="1.33134 in">
<THead>
<Row>
<Entry><Para><Literal>Description and MIME_TYPE Attribute</Literal></Para></Entry>
<Entry><Para><Literal>IS_TEXT Value</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para>Human language encoded in ASCII with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Human language encoded in E*UC, JIS, Unicode, or an ISO
Latin charset with <Command>MIME_TYPE text/plain;
charset=XXX</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>CalendarAppointmentAttrs with a <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>HyperText Markup Language (HTML) with a <Command>MIME_TYPE
text/html</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>PostScript with <Command>MIME_TYPE application/postscript</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>C program source (<Filename>C_SRC</Filename>) with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Bitmaps and pixmaps (<Command>XBM</Command> and <Command>XPM</Command>) with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Project or module files for the desktop application building
service with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Shell scripts with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Encoded text produced by <Filename>uuencode</Filename>(1) with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>*<Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>See the <Filename>dtdtsfile(4)</Filename> man page for more information about data-type
attributes.</Para>
</Sect1>
<Sect1 Id="PG.datat.div.6">
<Title Id="PG.datat.mkr.9">Data-Typing Functions<IndexTerm>
<Primary>functions</Primary>
<Secondary>data typing</Secondary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>functions</Primary>
<Secondary>data typing</Secondary>
</IndexTerm></Title>
<Para>To look up an attribute for a data object, you must first determine the type of
the object and then ask for the appropriate attribute value for that type. The
functions that you can use to query the database for data information are
shown in
<!--Original XRef content: 'Table&numsp;9&hyphen;4'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.10">. Each of these functions has a man page in section 3.
Refer to the appropriate man page for more information.</Para>
<Table Id="PG.datat.tbl.4" Frame="Topbot">
<Title Id="PG.datat.mkr.10">Data-Typing Database Query Functions<IndexTerm>
<Primary>data typing</Primary>
<Secondary>database query functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>database query functions, data typing</Primary>
</IndexTerm></Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="2.5 in">
<ColSpec Colname="2" Colwidth="2.5 in">
<THead>
<Row>
<Entry><Para><Literal>Function</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>DtDtsBufferToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the list of data attributes for a
given buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsBufferToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the data attribute for a given
buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsBufferToDataType</Command></Para></Entry>
<Entry><Para>Finds the data-type name for a given
buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataToDataType</Command></Para></Entry>
<Entry><Para>Finds the data type for a given set of
data.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeIsAction</Command></Para></Entry>
<Entry><Para>Returns the resulting saved data type for
the directory.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeNames</Command></Para></Entry>
<Entry><Para>Finds a complete list of available data
types.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the attribute list for a given data
attribute name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the attribute value for a given data
attribute name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the list of data attributes for a
given file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the data attribute value for a given
file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToDataType</Command></Para></Entry>
<Entry><Para>Finds the data type for a given file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFindAttribute</Command></Para></Entry>
<Entry><Para>Finds the list of data types where
attribute <Command>name</Command> matches <Command>value</Command>.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeAttributeList</Command></Para></Entry>
<Entry><Para>Frees the memory of the given attribute
list.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeAttributeValue</Command></Para></Entry>
<Entry><Para>Frees the memory of the given attribute
value.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeDataType</Command></Para></Entry>
<Entry><Para>Frees the application memory for the
given data-type name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeDataTypeNames</Command></Para></Entry>
<Entry><Para>Releases memory created with the
<Command>DtDtsDataTypeNames</Command> or
<Command>DtDtsFindAttribute</Command> call.</Para></Entry>
</Row>
<Row>
<Entry><Para>DtDtsIsTrue</Para></Entry>
<Entry><Para>A convenience function that converts a
string to a Boolean.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsRelease</Command></Para></Entry>
<Entry><Para>Unloads the data-typing database
information, generally in preparation for
a reload.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsSetDataType</Command></Para></Entry>
<Entry><Para>Sets the data type for the specified
directory.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtsLoadDataTypes</Command></Para></Entry>
<Entry><Para>Initializes and loads the database fields
for the data-typing functions. Use instead
of <Command>DtDbLoad</Command> when you do not need to
use actions or action types and you need
extra performance. Use <Command>DtDbLoad</Command> when
you need to use actions.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>You can type data and retrieve attributes in one of three ways: simple,
intermediate, or advanced.</Para>
<Sect2 Id="PG.datat.div.7">
<Title>Simple Data Typing</Title>
<Para>The simplest way to type data is to use the following functions:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsFileToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsFileToAttributeValue</Command></Para>
</ListItem>
</ItemizedList>
<Para>When you use these functions, a file is typed and a single attribute, or the
entire list, is retrieved. System calls are made, data is typed, and the attribute is
retrieved. These functions call the intermediate data-typing functions.</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsBufferToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsBufferToAttributeValue</Command></Para>
</ListItem>
</ItemizedList>
<Para>Buffers are assumed to have a mode that matches regular files that have
read/write permissions. See
<!--Original XRef content: '&xd2;Advanced Data Typing'--><XRef Role="SectionTitle" Linkend="PG.datat.mkr.11"> to type read-only
buffers.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.8">
<Title>Intermediate Data Typing</Title>
<Para>When you type data and retrieve attributes, the data-typing part of the process
is the most expensive in terms of performance. You can type data in a second
way that improves performance by separating the data-typing and attribute-
retrieval functions. Use the following functions for intermediate data typing:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsBufferToDataType</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsFileToDataType</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsDataTypeToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para>DtDtsDataTypeToAttributeValue</Para>
</ListItem>
</ItemizedList>
<Para>Use these functions if your application queries for more than a single attribute
value. When you use these functions, an object is typed and then that type is
used to retrieve one or more attributes from the attribute list.</Para>
<Para>Using the intermediate data-typing functions is the recommended way to type
data and retrieve attributes. These functions call the advanced data-typing
functions and make the same assumptions about buffers as the simpler data
typing.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.9">
<Title Id="PG.datat.mkr.11">Advanced Data Typing</Title>
<Para>Advanced data typing separates system calls, data typing, and attribute
retrieval even further. Advanced data typing is more complicated to code
because it uses data from existing system calls, which are initialized in advance
and are not included as part of the data-typing function. Use the following
function for advanced data typing:</Para>
<Para><Command>DtDtsDataToDataType</Command></Para>
<Para>To type a read-only buffer, a <Command>stat</Command> structure should be passed that has the
<Filename>st_mode</Filename> field set to <Command>S_IFREG | S_IROTH | S_IRGRP | S_IRUSR</Command>.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.10">
<Title>Data Types That Are Actions (DtDtsDataTypeIsAction)</Title>
<Para>For every action in a database a <Emphasis>synthetic data type</Emphasis> is generated when a
database is loaded that allows actions to be typed. These data types may have
two additional attributes:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Filename>IS_ACTION</Filename> is a string-Boolean value that tells users of this data type that it
is an action. If <Filename>IS_ACTION</Filename> is set to the string <Command>true</Command> (independent of case),
the data is an action.</Para>
</ListItem>
<ListItem>
<Para><Filename>IS_SYNTHETIC</Filename> is a string-Boolean value that tells users of this data type
that it was generated from an entry in the <Command>ACTION</Command> table. If <Filename>IS_SYNTHETIC</Filename>
is set to <Command>true</Command>, the data type was generated.</Para>
</ListItem>
</ItemizedList>
</Sect2>
</Sect1>
<Sect1 Id="PG.datat.div.11">
<Title Id="PG.datat.mkr.12">Registering Objects as Drop Zones<IndexTerm>
<Primary>data typing</Primary>
<Secondary>registering objects as drop zones</Secondary>
</IndexTerm><IndexTerm>
<Primary>drop zone</Primary>
<Secondary>registering objects</Secondary>
</IndexTerm><IndexTerm>
<Primary>registering objects as drop zones</Primary>
</IndexTerm></Title>
<Para>If your application defines data types, follow these steps to ensure that it
provides all the drag and drop behavior that you intend:</Para>
<OrderedList>
<ListItem>
<Para>In your application, decide if you need to define any data types.</Para>
</ListItem>
<ListItem>
<Para>For each data type you define, decide whether you want the associated
object to be a drop zone.</Para>
</ListItem>
<ListItem>
<Para>For each object that you want to register as a drop zone, decide which
operations&mdash;move, copy, or link&mdash;you want to define.</Para>
</ListItem>
<ListItem>
<Para>For the drop operations that are valid for each object, define the appropriate
drop actions (set the <Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and
<Filename>LINK_TO_ACTION</Filename> attributes).</Para>
</ListItem>
</OrderedList>
<Para>If your application displays icons for data objects, you may choose to support
those icons as drop zones. If so, you need to query the <Filename>MOVE_TO_ACTION</Filename>,
<Filename>COPY_TO_ACTION</Filename>, or <Filename>LINK_TO_ACTION</Filename> attributes to determine the drop
behavior for those data objects. Objects should support drop operations only if
the corresponding attribute value is not <Command>NULL</Command>. If all three attributes have <Command>NULL</Command>
values, the object should not be registered as a drop site. Whenever you set at
least one of these attributes for an object with a defined data type, your
application registers that object as a drop zone.</Para>
<Para>When a user drags an object to a drop zone, your application determines
which gesture (that is, which drag operation) was used to make the drop.
Based on the drag operation and the drop zone's data type, the application
retrieves a drop attribute from the data-typing database. It then calls
<Command>DtActionInvoke</Command>, using the following two rules to determine its parameters:</Para>
<OrderedList>
<ListItem>
<Para Id="PG.datat.mkr.13">If the user drops objects A and B onto object C, call <Command>DtActionInvoke</Command> with
C, A and B as <Symbol Role="Variable">args</Symbol>. The <Command>action</Command> is the value of either <Filename>MOVE_TO_ACTION</Filename>,
<Filename>COPY_TO_ACTION</Filename>, <Filename>LINK_TO_ACTION</Filename> of C. If object C is an action, the args
list does not include C. Also, the <Command>action</Command> is C.</Para>
</ListItem>
</OrderedList>
<Para>The File Manager, along with its directory and folder objects, exemplifies how
the desktop uses the move, copy, and link drop attributes. A user can drag and
drop objects (files) to directory folders. File Manager defines
<Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and <Filename>LINK_TO_ACTION</Filename> actions for
folder objects. These actions perform the appropriate file system move, copy,
and link system functions.</Para>
<Para>See <Filename>/usr/dt/appconfig/types/C/dtfile.dt</Filename> for an example of how to
define the <Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and <Filename>LINK_TO_ACTION</Filename>
attributes. See
<!--Original XRef content: 'Chapter&numsp;5, &xd2;Integrating with Drag and Drop'--><XRef Role="ChapNumAndTitle" Linkend="PG.dndPG.mkr.1">, for information
about how to use drag and drop.</Para>
</Sect1>
<Sect1 Id="PG.datat.div.12">
<Title Id="PG.datat.mkr.14">Example of Using the Data-Typing Database<IndexTerm>
<Primary>data typing</Primary>
<Secondary>code example</Secondary>
</IndexTerm><IndexTerm>
<Primary>code example</Primary>
<Secondary>data typing</Secondary>
</IndexTerm></Title>
<Para>This section contains example code of how to use data typing. You can find this
example code in <Filename>/usr/dt/examples/dtdts/datatyping.c</Filename>. The example
code displays the data type, icon name, and supported actions for each file
passed to it. You can then use the <Command>dtaction</Command> client to run a supported action
on the file. The usage for <Command>datatyping</Command> is:</Para>
<ProgramListing>datatyping <Symbol Role="Variable">file1</Symbol> [<Symbol Role="Variable">file2</Symbol> <Symbol Role="Variable">...</Symbol>]
#include &lt;Xm/Form.h>
#include &lt;Xm/Text.h>
#include &lt;Dt/Dts.h>

#define ApplicationClass &ldquo;DtDatatyping&ldquo;

static Widget text;

static void DisplayTypeInfo(int, char**);

int main(int argc, char **argv)
{
    XtAppContext appContext;
    Widget toplevel, form;
    Arg args[20];
    int n;

    toplevel = XtAppInitialize(&amp;appContext, ApplicationClass,

 NULL,  0,
        argc, argv, NULL, NULL, 0);

    if (argc == 1) {
        printf(&ldquo;&percnt;s: No files specified.\n&ldquo;, argv[0]);
        exit(1);
    }

    form = XmCreateForm(toplevel, &ldquo;form&ldquo;, NULL, 0);
    XtManageChild(form);
    n = 0;
    XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNtopAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNeditable, False); n++;
    XtSetArg(args[n], XmNeditMode, XmMULTI_LINE_EDIT); n++;
    XtSetArg(args[n], XmNrows, 25); n++;
    XtSetArg(args[n], XmNcolumns, 90); n++;
    text = XmCreateScrolledText(form, &ldquo;text&ldquo;, args, n);
    XtManageChild(text);

    XtRealizeWidget(toplevel);
 if (DtAppInitialize(appContext, XtDisplay(toplevel), toplevel,

  argv[0],
                                                ApplicationClass) == False) {
        printf(&ldquo;&percnt;s: Couldn't initialize Dt\n&ldquo;, argv[0]);
        exit(1);
    }

    DtDbLoad();

    DisplayTypeInfo(argc, argv);

    XtAppMainLoop(appContext);
}

static void DisplayTypeInfo(int argc, char **argv)
{
    char *file;
    char *datatype;
    char *icon;
    char *actions;
    char str[100];
    int i;

    sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;-20s\n&ldquo;,
                &ldquo;File&ldquo;,
                &ldquo;DataType&ldquo;,
                &ldquo;Icon&ldquo;,
                &ldquo;Actions&ldquo;);
    XmTextInsert(text, XmTextGetLastPosition(text), str);

    sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;-20s\n&ldquo;,
                &ldquo;-------------------&ldquo;,
                &ldquo;--------&ldquo;,
                &ldquo;----&ldquo;,
                &ldquo;-------&ldquo;);
    XmTextInsert(text, XmTextGetLastPosition(text), str);

      for(i=1; i &lt; argc; i++) {
        char *file = argv[i];

        /* find out the Dts data type */
        datatype = DtDtsFileToDataType(file);

        if(datatype) {
            /* find the icon attribute for the data type */
            icon = DtDtsDataTypeToAttributeValue(datatype,

   DtDTS_DA_ICON, file);
        }

  /*  Directly find the action attribute for a file */

        actions = DtDtsFileToAttributeValue(file,

   DtDTS_DA_ACTION_LIST);

        sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;s\n&ldquo;,
                        file,
                        datatype?datatype:&ldquo;unknown&ldquo;,
                        icon?icon:&ldquo;unknown&ldquo;,
                        actions?actions:&ldquo;unknown&ldquo;);
        XmTextInsert(text, XmTextGetLastPosition(text), str);

        /* Free the space allocated by Dts */

        DtDtsFreeAttributeValue(icon);
        DtDtsFreeAttributeValue(actions);
        DtDtsFreeDataType(datatype);
    }
</ProgramListing>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->
