HP 3000 Manuals HP 3000 Manuals
Access Through a Local Application Program If you want to access a remote database using a local application program, you have three methods to choose from. * Establishing communications link and remote session interactively. * Using the COMMAND intrinsic. * Using a database-access file. In all three cases, a local program accesses a remote database and the data is passed across the communication line. Method 1--Establishing Communications Link and Remote Session Interactively To use the first method, interactively establish a communications link and a remote session and enter a FILE equation for each remote database. The FILE equation specifies which database is to be accessed on which remote system and device. A local application program can now access a remotely located database, as shown in Figure 9-2 .Click here to view figure. Figure 9-2. Using Method 1 For details about using this method refer to the NS3000/XL User/Programmer Reference Manual. Method 2--Using the COMMAND Intrinsic The second method is very similar to the first, but you use the MPE/iX COMMAND intrinsic within your application program to establish the communications link, remote session and remote database access. To use this method you must issue a REMOTE HELLO command (either with the DSLINE parameter or issue the DSLINE as a separate command) and a FILE equation by calling the COMMAND intrinsic for each of these commands. Use of the COMMAND intrinsic is explained in the MPE/iX Intrinsics Reference Manual, and information about accessing remote files is given in the NS3000/XL User/Programmer Reference Manual. Figure 9-3 contains a diagram of method 2.
NOTE Remote logon parameters must define a valid logon known to the remote machine. For example, if a particular user name requires a password on the remote machine, the password parameter is required in the database-access file and must be supplied in the HELLO command.
After you have created the file with an editor, you must KEEP it UNNumbered. The file name must follow the same rules as a database name. It must be an alphanumeric string from 1 to 6 characters; the first character must be alphabetic. Records 3 through n define a table that tells TurboIMAGE/XL which user, account, and group names on the local computer can access which user, account, and group names on the remote computer. You can specify remote user identification for more than one local user by creating a record for each local "user.account,group" using the record 3 format shown earlier. An at-sign (@) can be substituted for any user, account, or group name in the record. If an at-sign is substituted for lusername, lacctname, or lgroupname, the name is replaced with the corresponding name specified at logon time. TurboIMAGE/XL searches for a match between the local user, account and group names in the user table and the names used to log on to the local session. When a match has been found, TurboIMAGE/XL performs a REMOTE HELLO using the corresponding rusername, racctname, rgroupname, and passwords, if present. If an at-sign is found, it is replaced with the corresponding name to the left of =HELLO. For example, if the record contains USERA.ACCTA,GROUPA=HELLO@.ACCTB,@, TurboIMAGE/XL replaces the first at-sign with USERA and the second with GROUPA. If an at-sign is not found, no substitutions are made. In either case, the information to the right of =HELLO is used as the remote logon identification. Example Record 1 FILE ORDERS=ORDERS:NODEX Record 2 DSLINE NODEX Record 3 USERA.ACCTA,GROUPA=HELLO USERB.ACCTA,GROUPB Record 4 @.ACCTA,GROUPA=HELLO USERA.ACCTA,GROUPA Record 5 USERB.ACCTB,@=HELLO USERB.ACCTX,@ End of file If a user logs on with the logon identification indicated in the first column below, TurboIMAGE/XL uses the corresponding USER.ACCT,GROUP identification in the second column to establish communication with the remote system. Logon Identification Remote Identification User1 USERA.ACCTA,GROUPA USERB.ACCTA,GROUPB User2 USERB.ACCTA,GROUPA USERA.ACCTA,GROUPA User3 USERB.ACCTB,GROUPB USERB.ACCTX,GROUPB User4 USERA.ACCTB,GROUPB None, no match found. The first user's logon identification matches the local user, account, and group names specified in record 3, so the remote names specified in that record are used. The second user's account matches record 3 but the user name does not, so TurboIMAGE/XL looks for another table entry with account ACCTA. Because the entry in record 4 specifies any user (@) of ACCTA if their group is GROUPA, the second user's remote identification will be that specified in record 4. The third user logs on to ACCTB and a match is found in record 5 because it specifies the same user name and accepts any group in the account. The fourth user's account matches record 5 but the user name does not match. Therefore, the fourth user cannot access the remote database with this application program. Activating a Database-Access File. After you have constructed a database-access file, you must use the DBUTIL utility program to activate the file. The complete syntax for running the utility program is given in chapter 8. Here is a summary of the operating instructions: :RUN DBUTIL.PUB.SYS : >>ACTIVATE database-access file name Verification follows: FILE command: <result> DSLINE command: <result> HELLO command: <result> ACTIVATED >>EXIT DBUTIL verifies that the file to be activated adheres to the following criteria: * Has a file code of zero. * Is an unnumbered, ASCII file. * Has a record length <=128 characters. * Has at least three records. If any of these conditions is not satisfied, activation fails, and the following message is printed: filename is NOT a suitable database-access file If the file has already been activated, the following message is printed: filename is already ACTIVE If all of the above are satisfied, DBUTIL prints the following message: Verification follows: Then the utility program verifies the syntax of the following records: * Record 1. * Record 2 through nodename, which must be identical to the nodename specified in record 1. * Records 3 through n, through the parameter rgpasw. This means that for records 2 through n only the positional parameters (those whose function is determined by their relative position within the command) are verified by DBUTIL. The remaining keyword parameters are checked by the command interpreter at DBOPEN time. If all of the above conditions are met, DBUTIL successfully activates the database-access file, by changing the file code to the TurboIMAGE/XL reserved code -402, which makes it a privileged (PRI V) file. Deactivating a Database-Access File. In order to deactivate the database-access file, you use the DEACTIVATE command of the DBUTIL utility program. Complete syntax for this program is given in chapter 8. Here is a summary of the operating instructions: :RUN DBUTIL.PUB.SYS : >>DEACTIVATE database-access file name DEACTIVATED >>EXIT You can do this if you want to edit the content of the database-access file or to prevent access through this file to the remote database. Referencing the Database. To reference the database from your local application program, use the database-access file name instead of the root file name when calling the TurboIMAGE/XL procedure. The word array specified as the base parameter must contain a pair of blanks followed by the left-justified database-access file name and terminated by a semicolon or blank (_). TurboIMAGE/XL recognizes the -402 file code and establishes a communications link to the remote HP 3000. If the database is successfully opened, TurboIMAGE/XL replaces the pair of blanks with the baseid of the assigned Remote Database Control Block. The base parameter must remain unchanged for the remainder of the process. When the application program calls the DBCLOSE procedure or terminates execution, automatic REMOTE BYE and DSLINE commands are issued to terminate the session and close the communications line. Example The example in Figure 9-5 illustrates how to create and activate a database-access file. A description follows the example. In this sample case, the file named ORDDBA is to be used to gain access to the ORDERS database residing on a remote system in the PAYACCT account. The remote system is referenced by nodename NODEX. After the database-access file is created, it is enabled by using the DBUTIL utility program. ________________________________________________________________________ | | | 1 | | | | :HELLO MEMBER1.PAYACCT | | : | | | |2 | | | | :EDITOR | | | | HP32201A.00.00 EDIT/3000 FRI, SEP 6, 1991, 3:30 PM | | (C) HEWLETT-PACKARD CO. 1985 | | | |3 | | | | /ADD | | 1 FILE ORDERS=ORDERS:NODEX | | 2 DSLINE NODEX | | 3 MEMBER1.PAYACCT=HELLO MEMBER1.PAYACCT | | 4 MEMBER2.PAYACCT=HELLO @.PAYACCT | | 5 // | | | |4 | | | | /KEEP ORDDBA,UNN | | /END | | | |5 | | | | :RUN DBUTIL.PUB.SYS | | >>ACTIVATE ORDDBA | | Verification follows: | | FILE command: Looks good | | DSLINE command: Looks good | | HELLO command: Looks good | | HELLO command: Looks good | | ACTIVATED | | >>EXIT | | | | END OF PROGRAM | | | ________________________________________________________________________ Figure 9-5. Preparing a Database-Access File Description 1 Initiate an MPE/iX session by logging on with appropriate user name and account. 2 Initiate text editor execution. 3 Enter the Editor ADD command in response to the first prompt, then enter the lines to define the database-access file. 4 Save the work file in a disk file (ORDDBA in the above example). Remember to keep it unnumbered. Then exit the Editor. 5 Initiate execution of DBUTIL and activate the database-access file ORDDBA. Verification messages will follow (in session mode). Exit from DBUTIL. Example Figure 9-6 illustrates use of the database-access file through a program named APPLICAN. A description follows the example. In this sample case, after logging on to the local system, the user runs the program named APPLICAN from the local session. The base array in this program contains __ORDDBA. When a call to DBOPEN is executed, TurboIMAGE/XL establishes a communication line and remote session. When the program closes the database, TurboIMAGE/XL closes the line and terminates the remote session. ________________________________________________________________________ | | | 1 | | | | :HELLO MEMBER2.PAYACCT | | : | | | |2 | | | | :RUN APPLICAN | | | |3 | | | | HP3000 / MPE/iX G.00.00 FRI SEP 6, 1991, 3:55 PM | | ENVIRONMENT 1: ELECTRA.DOC.ITG | | | |4 | | | | WELCOME TO SYSTEM B. | | : | | CPU=2. CONNECT=1. FRI, SEP 6, 1991, 3:59 PM | | ENVIRONMENT 1: ELECTRA.DOC.ITG CLOSED | | | |5 | | | | :BYE | | | ________________________________________________________________________ Figure 9-6. Using a Database-Access File Description 1 Initiate an MPE/iX session on the local system by logging on with the appropriate user name and account. 2 Execute the application program APPLICAN. (The program calls DBOPEN using __ORDDBA as the baseid.) 3 TurboIMAGE/XL establishes a communications line and remote session. 4 When the database is closed, TurboIMAGE/XL closes communications line and ends remote session. 5 Log off local system.