RDBA Access Methods

There are three ways to open a remote TurboIMAGE database within a program:

When the file specified in a FILE command is a remote database, the syntax (for the first two methods) is the same as it is for a remote file; you can specify the location of the database in the formal or actual designator or in the DEV= option. When using the third method, creating a database-access file, the FILE command may specify a remote database location only in the DEV= option — not in the formal or actual designator. (For details see the description of the FILE command in the "Remote File Access" chapter of this manual.)

With all three access methods you must call the DBOPEN intrinsic within the program to open the remote database. In the first two cases you call DBOPEN with the database root file name supplied in the FILE command. In the third case you use the database-access file name.

In the first case a user needs to know the location of the database. The application program that accesses the database does not need to have this information. The second case embeds the information in the application and frees the user from the responsibility of knowing the location. The third case insulates both the user and the application program from the information.The COMMAND intrinsic allows a program to execute MPE/iX commands. The first parameter of the intrinsic is a string of characters giving a specific command. You can issue a series of COMMAND calls within your program to establish a remote session (DSLINE and REMOTE HELLO commands) and identify the remote database (FILE command). You can then call DBOPEN to open the database. When you have called DBCLOSE to close the remote database, you must call COMMAND again to execute REMOTE BYE and DSLINE;CLOSE commands. See the MPE/iX Intrinsics Reference Manual for a detailed explanation of the COMMAND intrinsic.

A database-access file contains a FILE command, a DSLINE command, and one or more remote logon commands. When you call DBOPEN with the name of this file, the remote session is established and the remote database is opened. You can then call other TurboIMAGE intrinsics to perform the desired operations upon the database.

The database-access file has the following general format:

     FILE dbname;DEV=envId#
     DSLINE envid
     locuser.locacct=HELLO remuser.remacct

More than one local/remote logon sequence equation may be included in the file. When you call DBOPEN with the database-access file name, a remote session is established for the remote user that has been "equated" with your local logon name. (An @ sign in the remote user, account, or group name position on the right side of an equation is automatically replaced by the corresponding local name on the left. An @ sign in a local name position on the left is replaced by the name you actually used when you logged on.)

Under the database-access file method, the remote session is released automatically when the database is closed (with or without an explicit DBCLOSE call).

Before you can reference a database-access file in a program, you have to ACTIVATE it by means of the DBUTIL utility program. At the MPE/iX prompt, type the following command (user input is bold):

     RUN DBUTIL.PUB.SYS
     >>ACTIVATE dbaccessfilename
          VERIFICATION FOLLOWS:
               FILE COMMAND:     LOOKS GOOD
               DSLINE COMMAND:   LOOKS GOOD
               HELLO COMMAND:    LOOKS GOOD
          ACTIVATED
     >>EXIT

DBUTIL checks to see that the file has a file code of zero, is an unnumbered, ASCII file, has a record length not greater than 128 characters, and contains at least three records. In order to edit the database-access file or prevent programs from referencing it, you must issue a DEACTIVATE command within the DBUTIL program.

One of the benefits of the database-access file method is that it restricts who may use the database and thereby enhances security. (The contents of the database-access file itself can be hidden from the user who simply runs the application program.) Under this method, however, you can access only one database in any one remote session. Under the other two methods, you can access more than one database by means of multiple FILE commands.

You can use QUERY, Hewlett-Packard's interactive database inquiry facility, to retrieve information from a remote database. You could run QUERY.PUB.SYS locally, specifying either the database name itself or the appropriate database-access file name. If you use the actual database name, you must have previously established a session on the remote node and issued a FILE command for the remote database.

It is more efficient to run QUERY directly in the remote environment. At the MPE/iX prompt, type the following commands (user input bold):

DSLINE LEO
REMOTE HELLO NSUSER.NSACCT
REMOTE RUN QUERY.PUB.SYS
>DATA-BASE=databasename>

For more information on TurboIMAGE and QUERY, see the TurboIMAGE Data Base Management System Reference Manual, especially the sections entitled "Using a Remote Database;" and also see the QUERY/3000 Reference Manual.