DATMAN TECHNICAL BULLETIN #031
From: Kan Yabumoto tech@datman.com
To: DATMAN user
Subject: HOTAPI, DATMAN's new Application Programming Interface (API)
Date: 1999-11-11
====================================================================
Introduction:
From its earliest version beginning in 1993, DATMAN has always
provided mechanisms to allow users to control the file system
and the tape drive from a batch file and possibly from an
application program.
The mechanisms were provided solely by the user-interface utilities,
DATMAN.EXE and DATMAN32.EXE for the DOS and Win32 environments
respectively. But, the methods hardly qualified to be called API.
The utilities were designed to be invoked either manually or
from a batch file. In the past, when one needed to write an
application that would format a DATMAN tape, the program had
to invoke the bulky DATMAN32.EXE program via a system() function
to achieve the goal. The same huge overhead was there even for
a small job such as retrieving the current DATMAN volume status.
That was then.
Enter HOTAPI, an API for programmers and non-programmers:
We feel the revolutionary DATMAN file system deserves a well-
conceived API design with great flexibility and ease of use.
In short, it has to be simple but powerful.
Now, DATMAN-99 has a true API with HOTAPI. It is not just a
traditional interface which requires programming skills.
The HOTAPI operation is directly accessible to any user even if
their experience is in batch file programming only.
Reserved file name:
HOTAPI uses a scheme with a reserved name(s) in the DATMAN
volume directory name space.
\$DATMAN$\$HOTAPI$
All of the DATMAN HOTAPI actions are invoked via this "virtual"
directory. The directory does not actually exist but when
you access a file inside the "virtual" directory, an API
command corresponding to the "virtual" file will be invoked
inside the DATMAN file system. The API uses a subset of
the common file I/O system API just like DATMAN is known
to do best. In short, being a file system, DATMAN can interact
with you or your application program in a special way.
Compatible with any language:
The entire HOTAPI protocol is specified with text data only.
No compiler or linker is needed. As a matter of fact, we
do not release any library modules for HOTAPI. If you are
an end user with a batch file (or possibly a Perl script as the
only programming choice), HOTAPI is ideal for you.
However, it is equally easy to incorporate DATMAN control
code in your application program. There is no messy DLL
headache, or library module version mismatch as the DATMAN
versions continue to be improved.
It is a documented protocol with the entire source code for
the DATMANIA utility as a sample program. It is written in C,
but the operations can be written in any language including
Visual Basic, Visual C++, Java, Perl. You name it.
HOTAPI Examples:
Just look at a few examples, first.
type t:\$datman$\$hotapi$\status
type t:\$datman$\$hotapi$\eject
echo >t:\$datman$\$hotapi$\format mylabel "This is cool"
The HOTAPI commands like these can be entered from the keyboard,
or be placed in a batch file. The first two exaples opens the
corresponding files in the virtual directory in Read-Only mode.
In those cases, no arguments are written to the opened file (the
STATUS and EJECT commands don't take any command argument. The
text strings generated by the commands will be typed by the
commands.
The third example invokes DATMAN' FORMAT command with the two
required arguments (a label and a comment text). The output text
of the ECHO command (the label followed by the comment string),
are written to the file caleld "FORMAT" in the virtual directory
with the redirection mechanism (>). The ECHO command opens the
FORMAT file in the virtual directory in Write-Only mode and
therefore, no text will be shown by the command (however, there
is a way to retrieve the text generate by the FORMAT command).
How does HOTAPI work?
A HOTAPI file in the reserved directory behaves very much like
a file in an ordinary directory on the surface.
From a programmer's point of view, it has to be opened first,
accessed in read or write mode to transfer block(s) of data,
and then, closed. This three-step sequence (Open-Write-Close
or Open-Read-Close) invokes a corresponding action inside the
DATMAN file engine. Here, the ultimate goal is to cause some
actions in the DATMAN file system, and the exchange of the data
to the virtual file is the means to achieve the goal.
Luckily, the command shell which controls the DOS box (COMMAND.COM),
includes the ECHO and TYPE commands which perform the three-step
action transparently to the user. The ECHO command is good for
sending a command with an argument text, whereas the TYPE command
is convenient to receive data from the file engine and display
the text on the console.
Although you may also use the COPY command, you should avoid it
because its rigorous checking mechanism makes it very
inefficient. It also puts out unwanted warning messages.
The difference between ECHO and TYPE:
These two built-in commands in the COMMAND.COM program are equally
handy for HOTAPI. While both can be used for any DATMAN HOTAPI,
one is more suitable than the other depending on the command.
When you invoke a command which requires one or more parameters,
you must open it in write-only mode (ECHO) and the parameters should
be written to the file as an ASCII text string. In this case,
the action is initiated when the file is closed.
If you are to retrieve the current status of the file system,
it is more convenient to open the STATUS command in read-only
mode so that the text generated by the command will be read from
the corresponding virtual file to be displayed. The TYPE command
is therefore ideal for this.
One API for both 16-bit and 32-bit programs:
One of the strengths of HOTAPI is that it can be invoked either
from a 16-bit (DOS) program or a 32-bit (Win32) program.
The API virtual directory and file names are kept intentionally
in the so-called 8.3 (short name) format.
Naturally compatible with networking:
Just as the DATMAN file system is compatible with popular
network operating systems, (NetWare, Microsoft Networks, etc).
the DATMAN HOTAPI is inherently compatible with networking.
As a matter of fact, the network-compatibility was one of
the motives for the very HOTAPI design. As long as the DATMAN
volume is setup to be shared from other computers in the network,
the virtual directory and virtual files (HOTAPI commands) can
be invoked over the network.
For the network, the local driveletter specifier (T:) will be
substituted by an appropriate UNC (Universal Naming Convention
---- the name starting with double \\backslashes like this) to
address the DATMAN volume object:
As local drive: type t:\$datman$\$hotapi$status
Across network: type \\Myserver\t\$datman$\$hotapi$\status
Note that the virtual directory name, "\$datman$\$hitapi$"
must be appended immediately to the root level name which
is usally the server name followed by the sharename of the
DATMAN drive whatever it is named (many people use an alphabet
corresponding to the driveletter; e.g., \\myserver\t ).
DATMAN Interface Agent (DATMANIA):
So far, the HOTAPI protocol was described in terms of the interaction
by using the ECHO and TYPE commands. In fact, one of the virtues of
the API is that the default command shell is all you need. But, in
a batch file script for an unattended backup for example, it is
highly desirable to have the ERRORLEVEL which reflects the result of
the API call. The bundled utility program, DATMANIA serves as a
batch file enhanser to set the ERRORLEVEL based upon the returned
value from the HOTAPI functions. It also provides more natural user
interface than the raw ECHO/TYPE commands. The full DATMANIA
source code is available as an example for user-applications which
incorporate the HOTAPI protocol to control DATMAN programmatically.
License for DATMAN HOTAPI:
For personal use and/or non-commercial programming activities,
you may use the DATMAN HOTAPI protocol free of charge.
When you incorporate any part of our DATMANIA.C program
(which is copyrighted) in your program, you must show the same
copyright notice which appears at the beginning of the DATMANIA.C
source file TB #033 .
If you plan to use DATMAN HOTAPI as part of your application
program, incorporating the code shown in the DATMANIA.C file
in whole or in part, for the purpose of distribution outside
of your own organization, you need to be a licensed DATMAN-PRO
user and pay a one-time license fee to Pixelab.
A list of the DATMAN HOTAPI command set is available in TB #032 .