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.[REV BEG] * Establishing commuications 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.[REV END] 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 .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.Figure 9-3. Using Method 2 If you want to access more than one remotely located database with an application program, you must enter one FILE equation for each remote database. To terminate execution perform the following steps: 1. Close the database. 2. Log off (REMOTE BYE). 3. Close the communication line. Method 3--Using a Database-Access File The third method involves creating a special priviliged (PRIV) file which is called the database-access file (DBA file). This file provides TurboIMAGE/XL with the necessary information to establish a communications link and a remote session. It also specifies the remote database or database-access file name so that the necessary TurboIMAGE/XL intrinsics can be executed on the remote computer. Figure 9-4 illustrates method 3.Figure 9-4. Using Method 3 Using the database-access file, only one database can be accessed using each database-access file per DSLINE. For example, if two computers are linked through two DSLINEs, you can open one database on each line. When the user or an application program calls DBOPEN with the database-access file name, the remote session is established and the remote database is opened. Then other TurboIMAGE/XL intrinsics can perform desired operations on the database. Under this method the remote session is automatically released when the database is closed (with or without an explicit DBCLOSE call). A second REMOTE HELLO on one DSLINE terminates the previous REMOTE HELLO. For multiple remote database access, method 1 or method 2 is recommended. If the database-access file is used, an automatic REMOTE BYE and DSLINE commands are issued on the communications line specified in the database-access file when the application program closes the database or terminates execution. Using method 3, the database administrator can set up a user-table that provides more control over the database access and enhances database security. To create the database-access file, use an editor such as EDIT/3000. First use the SET LENGTH command to accommodate the largest record to be included in the database-access file if the record exceeds the default length specified for your editor. The length must be less than or equal to 128 characters. The following sections discuss how to create, activate, deactivate, and reference a database-access file. Creating a Database-Access File. The content of the database-access file should be created in the format shown below. Syntax Record 1 FILE dbname1=dbname2:nodename Record 2 DSLINE nodename[;...] (See NS3000/XL document for applicable parameters.) Record 3 lusername.lacctname[,lgroupname]=HELLO rusername[/rup asw] .racctname[/rapasw][,rgroupname[/rgpasw]]... (See MPE/iX commands document for additional parameters.) Record 4 Same format as record 3. Specifies other "user.account,group" identification. : Record n Parameters dbname1 is the name of the database-access file on the local system or the database on the remote system you want to access, or is the formal file designator used in the program if dbname2 is specified. (Required parameter.) dbname2 is the name of the database-access file or the database on the remote system you want to access. (Required parameter.) nodename is the remote location of the database. This parameter is preceded by a colon when used with the FILE command; if followed by options with the DSLINE command, it is followed by a semicolon. (Required parameter.) Refer to the NS3000/XL User/Programmer Reference Manual for additional information. lusername is a user name on the local HP 3000, as established by an account manager, that allows you to log on under this account. This name is unique within the account. It contains from 1 to 8 alphanumeric characters, beginning with a letter. An at-sign (@) can be used to indicate the logon user name. (Required parameter.) lacctname is the name of your account on the local HP 3000 as established by a system manager. It contains 1 to 8 alphanumeric characters, beginning with a letter. An at-sign (@) can be used to indicate the logon account. (Required parameter.) lgroupname is the name of a file group to be used for the local file domain as established by an account manager. It contains from 1 to 8 alphanumeric characters, beginning with a letter. An at-sign (@) can be used to indicate the logon group. (Optional parameter.) rusername is a user name on the remote HP 3000 that allows you to log on under the remote account. It follows the same rules as username. An at-sign (@) can be used to indicate rusername as with lususername. (Required parameter.) rupasw is the password assigned to username. (Optional parameter.) racctname is the name of the logon account on the remote HP 3000. It follows the same rules as lacctname. An at-sign (@) can be used to indicate racctname is the same as lacctname. (Required parameter.) rapasw is the password assigned to racctname. (Optional parameter.) rgroupname is the name of the logon group on the remote HP 3000. It follows the same rules as lgroupname. An at-sign (@) can be used to indicate rgroupname is the same as lgroupname. (Optional parameter.) rgpasw is the password assigned to rgroupname. (Optional parameter.) Discussion The following syntax rules apply: * No spaces are allowed around any periods that could exist in the second file reference in record 1 (for example, dbname2.group). * Passwords are not allowed with the local user, account, and group names. They are not necessary because the local user passes the security password checks when logging onto the local system.
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.
![[]](../../pic3k/M012332/FFN393c50.gif)
![[]](../../pic3k/M012332/FFN403c50.gif)
![[]](../../pic3k/M012332/FFN413c50.gif)