dtextbody(1) — Commands

CDE

NAME

dtextbody − utility to access external MIME body parts

SYNOPSIS

dtextbody body-part-as-file

DESCRIPTION

The dtextbody program is a tool used by dtmail to access remote MIME body parts. It provides an easy-to-use interface for transfering the data from a remote system to the local system.

FILE FORMAT

The body-part-as-file is the contents of a Content-Type: Message/External-Body body part as described in RFC-1521. The following is an excerpt from RFC-1521 covering the external message:

7.3.3.     The Message/External-Body subtype
   The external-body subtype indicates that the actual body data are not
   included, but merely referenced. In this case, the parameters
   describe a mechanism for accessing the external data.
   When an entity is of type "message/external-body", it consists of a
   header, two consecutive CRLFs, and the message header for the
   encapsulated message. If another pair of consecutive CRLFs appears,
   this of course ends the message header for the encapsulated message.
   However, since the encapsulated message’s body is itself external, it
   does NOT appear in the area that follows. For example, consider the
   following message:
      Content-type: message/external-body;
access-type=local-file;
          name="/u/nsb/Me.gif"
      Content-type: image/gif
      Content-ID: <id42@guppylake.bellcore.com>
      Content-Transfer-Encoding: binary
      THIS IS NOT REALLY THE BODY!
   The area at the end, which might be called the "phantom body", is
   ignored for most external-body messages. However, it may be used to
   contain auxiliary information for some such messages, as indeed it is
   when the access-type is "mail-server". Of the access-types defined
   by this document, the phantom body is used only when the access-type
   is "mail-server". In all other cases, the phantom body is ignored.
   The only always-mandatory parameter for message/external-body is
   "access-type"; all of the other parameters may be mandatory or
   optional depending on the value of access-type.
      ACCESS-TYPE -- A case-insensitive word, indicating the supported
      access mechanism by which the file or data may be obtained.
      Values include, but are not limited to, "FTP", "ANON-FTP", "TFTP",
      "AFS", "LOCAL-FILE", and "MAIL-SERVER". Future values, except for
      experimental values beginning with "X-" must be registered with
      IANA, as described in Appendix E .
   In addition, the following three parameters are optional for ALL
   access-types:
      EXPIRATION -- The date (in the RFC 822 "date-time" syntax, as
      extended by RFC 1123 to permit 4 digits in the year field) after
      which the existence of the external data is not guaranteed.
      SIZE -- The size (in octets) of the data. The intent of this
      parameter is to help the recipient decide whether or not to expend
      the necessary resources to retrieve the external data. Note that
      this describes the size of the data in its canonical form, that
      is, before any Content- Transfer-Encoding has been applied or
      after the data have been decoded.
      PERMISSION -- A case-insensitive field that indicates whether or
      not it is expected that clients might also attempt to overwrite
      the data. By default, or if permission is "read", the assumption
      is that they are not, and that if the data is retrieved once, it
      is never needed again. If PERMISSION is "read-write", this
      assumption is invalid, and any local copy must be considered no
      more than a cache. "Read" and "Read-write" are the only defined
      values of permission.
   The precise semantics of the access-types defined here are described
   in the sections that follow.
   The encapsulated headers in ALL message/external-body entities MUST
   include a Content-ID header field to give a unique identifier by
   which to reference the data. This identifier may be used for
   cacheing mechanisms, and for recognizing the receipt of the data when
   the access-type is "mail-server".
   Note that, as specified here, the tokens that describe external-body
   data, such as file names and mail server commands, are required to be
   in the US-ASCII character set. If this proves problematic in
   practice, a new mechanism may be required as a future extension to
   MIME, either as newly defined access-types for message/external-body
   or by some other mechanism.
   As with message/partial, it is specified that MIME entities of type
   message/external-body must always have a content-transfer-encoding of
   7-bit (the default). In particular, even in environments that
   support binary or 8-bit transport, the use of a content-transfer-
   encoding of "8bit" or "binary" is explicitly prohibited for entities
   of type message/external-body.
   An access-type of FTP or TFTP indicates that the message body is
   accessible as a file using the FTP [RFC-959] or TFTP [RFC-783]
   protocols, respectively. For these access-types, the following
   additional parameters are mandatory:
      NAME -- The name of the file that contains the actual body data.
      SITE -- A machine from which the file may be obtained, using the
      given protocol. This must be a fully qualified domain name, not a
      nickname.
   Before any data are retrieved, using FTP, the user will generally
   need to be asked to provide a login id and a password for the machine
   named by the site parameter. For security reasons, such an id and
   password are not specified as content-type parameters, but must be
   obtained from the user.
   In addition, the following parameters are optional:
      DIRECTORY -- A directory from which the data named by NAME should
      be retrieved.
      MODE -- A case-insensitive string indicating the mode to be used
      when retrieving the information. The legal values for access-type
      "TFTP" are "NETASCII", "OCTET", and "MAIL", as specified by the
      TFTP protocol [RFC-783]. The legal values for access-type "FTP"
      are "ASCII", "EBCDIC", "IMAGE", and "LOCALn" where "n" is a
      decimal integer, typically 8. These correspond to the
      representation types "A" "E" "I" and "L n" as specified by the FTP
      protocol [RFC-959]. Note that "BINARY" and "TENEX" are not valid
      values for MODE, but that "OCTET" or "IMAGE" or "LOCAL8" should be
      used instead. IF MODE is not specified, the default value is
      "NETASCII" for TFTP and "ASCII" otherwise.
7.3.3.2. The "anon-ftp" access-type
   The "anon-ftp" access-type is identical to the "ftp" access type,
   except that the user need not be asked to provide a name and password
   for the specified site. Instead, the ftp protocol will be used with
   login "anonymous" and a password that corresponds to the user’s email
   address.
7.3.3.3. The "local-file" and "afs" access-types
   An access-type of "local-file" indicates that the actual body is
   accessible as a file on the local machine. An access-type of "afs"
   indicates that the file is accessible via the global AFS file system.
   In both cases, only a single parameter is required:
      NAME -- The name of the file that contains the actual body data.
   The following optional parameter may be used to describe the locality
   of reference for the data, that is, the site or sites at which the
   file is expected to be visible:
      SITE -- A domain specifier for a machine or set of machines that
      are known to have access to the data file. Asterisks may be used
      for wildcard matching to a part of a domain name, such as
      "∗.bellcore.com", to indicate a set of machines on which the data
      should be directly visible, while a single asterisk may be used to
      indicate a file that is expected to be universally available,
      e.g., via a global file system.
7.3.3.4. The "mail-server" access-type
   The "mail-server" access-type indicates that the actual body is
   available from a mail server. The mandatory parameter for this
   access-type is:
      SERVER -- The email address of the mail server from which the
      actual body data can be obtained.
   Because mail servers accept a variety of syntaxes, some of which is
   multiline, the full command to be sent to a mail server is not
   included as a parameter on the content-type line. Instead, it is
   provided as the "phantom body" when the content-type is
   message/external-body and the access- type is mail-server.
   An optional parameter for this access-type is:
      SUBJECT -- The subject that is to be used in the mail that is sent
      to obtain the data. Note that keying mail servers on Subject lines
      is NOT recommended, but such mail servers are known to exist.
   Note that MIME does not define a mail server syntax. Rather, it
   allows the inclusion of arbitrary mail server commands in the phantom
   body. Implementations must include the phantom body in the body of
   the message it sends to the mail server address to retrieve the
   relevant data.
   It is worth noting that, unlike other access-types, mail-server
   access is asynchronous and will happen at an unpredictable time in
   the future. For this reason, it is important that there be a
   mechanism by which the returned data can be matched up with the
   original message/external-body entity. MIME mailservers must use the
   same Content-ID field on the returned message that was used in the
   original message/external-body entity, to facilitate such matching.
7.3.3.5. Examples and Further Explanations
   With the emerging possibility of very wide-area file systems, it
   becomes very hard to know in advance the set of machines where a file
   will and will not be accessible directly from the file system.
   Therefore it may make sense to provide both a file name, to be tried
   directly, and the name of one or more sites from which the file is
   known to be accessible. An implementation can try to retrieve remote
   files using FTP or any other protocol, using anonymous file retrieval
   or prompting the user for the necessary name and password. If an
   external body is accessible via multiple mechanisms, the sender may
   include multiple parts of type message/external-body within an entity
   of type multipart/alternative.
   However, the external-body mechanism is not intended to be limited to
   file retrieval, as shown by the mail-server access-type. Beyond
   this, one can imagine, for example, using a video server for external
   references to video clips.
   If an entity is of type "message/external-body", then the body of the
   entity will contain the header fields of the encapsulated message.
   The body itself is to be found in the external location. This means
   that if the body of the "message/external-body" message contains two
   consecutive CRLFs, everything after those pairs is NOT part of the
   message itself. For most message/external-body messages, this
   trailing area must simply be ignored. However, it is a convenient
   place for additional data that cannot be included in the content-type
   header field. In particular, if the "access-type" value is "mail-
   server", then the trailing area must contain commands to be sent to
   the mail server at the address given by the value of the SERVER
   parameter.
   The embedded message header fields which appear in the body of the
   message/external-body data must be used to declare the Content-type
   of the external body if it is anything other than plain ASCII text,
   since the external body does not have a header section to declare its
   type. Similarly, any Content-transfer-encoding other than "7bit"
   must also be declared here. Thus a complete message/external-body
   message, referring to a document in PostScript format, might look
   like this:
      From: Whomever
      To: Someone
      Subject: whatever
      MIME-Version: 1.0
      Message-ID: <id1@host.com>
      Content-Type: multipart/alternative; boundary=42
      Content-ID: <id001@guppylake.bellcore.com>
      --42
      Content-Type: message/external-body;
           name="BodyFormats.ps";
           site="thumper.bellcore.com";
           access-type=ANON-FTP;
           directory="pub";
           mode="image";
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>
      --42
      Content-Type: message/external-body;
           name="/u/nsb/writing/rfcs/RFC-MIME.ps";
           site="thumper.bellcore.com";
           access-type=AFS
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>
      --42
      Content-Type: message/external-body;
           access-type=mail-server
           server="listserv@bogus.bitnet";
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>
      get RFC-MIME.DOC
      --42--
   Note that in the above examples, the default Content-transfer-
   encoding of "7bit" is assumed for the external postscript data.
   Like the message/partial type, the message/external-body type is
   intended to be transparent, that is, to convey the data type in the
   external body rather than to convey a message with a body of that
   type. Thus the headers on the outer and inner parts must be merged
   using the same rules as for message/partial. In particular, this
   means that the Content-type header is overridden, but the From and
   Subject headers are preserved.
   Note that since the external bodies are not transported as mail, they
   need not conform to the 7-bit and line length requirements, but might
   in fact be binary files. Thus a Content-Transfer-Encoding is not
   generally necessary, though it is permitted.
   Note that the body of a message of type "message/external-body" is
   governed by the basic syntax for an RFC 822 message. In particular,
   anything before the first consecutive pair of CRLFs is header
   information, while anything after it is body information, which is
   ignored for most access-types.
   The formal grammar for content-type header fields for data of type
   message is given by:
   message-type := "message" "/" message-subtype
   message-subtype := "rfc822"
                   / "partial" 2#3partial-param
                   / "external-body" 1∗external-param
                   / extension-token
   partial-param :=     (";" "id" "=" value)
              / (";" "number" "=" 1∗DIGIT)
              / (";" "total" "=" 1∗DIGIT)
         ; id & number required; total required for last part
   external-param :=   (";" "access-type" "=" atype)
              / (";" "expiration" "=" date-time)
                   ; Note that date-time is quoted
              / (";" "size" "=" 1∗DIGIT)
              / (";" "permission" "=" ("read" / "read-write"))
                   ; Permission is case-insensitive
              / (";" "name" "=" value)
              / (";" "site" "=" value)
              / (";" "dir" "=" value)
              / (";" "mode" "=" value)
              / (";" "server" "=" value)
              / (";" "subject" "=" value)
          ; access-type required;others required based on access-type
   atype := "ftp" / "anon-ftp" / "tftp" / "local-file"
                  / "afs" / "mail-server" / extension-token
                  ; Case-insensitive

-----

FILES