============================================ = Eloquence Client for MPE Reference Guide = ============================================ Welcome to Eloquence for MPE, the client library which allows your HP 3000 software to access remote Eloquence databases. This document is intended to provide you with the basic steps necessary to get started using the Eloquence for MPE client. If you're reading this from your HP 3000 we assume you have already successfully installed the software, which, at this writing, consists solely of a single NMXL library file. Further, we assume you have installed the library in the default location, and that it is called IMAGE3K.PUB.ELOQ. It should look very similar to this... :listf image3k.pub.eloq,2 ACCOUNT= ELOQ GROUP= PUB FILENAME CODE ------------LOGICAL RECORD----------- ----SPACE---- SIZE TYP EOF LIMIT R/B SECTORS #X MX IMAGE3K NMXL 128W FB 6630 4096000 1 7088 6 * If the CODE, SIZE, TYP or EOF columns don't match what you see on your system, then there may have been a problem with the installation. If that's the case, then please review your steps or contact customer service. Requirements ------------ The following must be true in order to access remote Eloquence databases using the Eloquence client: - Your HP 3000 is on a network. - One of a) You know the IP address of a remote system running Eloquence server software, or b) You know the node name of the remote system and your HP 3000 can resolve node names (most likely via a DNS server, or perhaps via HOSTS.NET.SYS) - Your HP 3000 can PING the remote system. (Use PING.NET.SYS if you know the remote IP address, or NETTOOL.NET.SYS if you are using a node name.) - The software which will access the remote Eloquence database makes use of the standard TurboIMAGE APIs (Image intrinsics). In other words, it doesn't do any privileged direct file access of the Image data set files. (Certain HP and third-party utilities open Image data sets directly, and therefore can't be used to access remote Eloquence databases.) Accessing the Eloquence client ------------------------------ The MPE Eloquence client is accessed simply by adding an "XL=..." parameter to the invocation of any program which does standard TurboIMAGE calls. If you would normally do... :run myprog ...to access a TurboIMAGE database, then the following would be used to invoke the functionality of the Eloquence client: :run myprog;xl="image3k.pub.eloq" The default mode of the MPE Eloquence client is to pass Image calls to TurboIMAGE unaltered. In other words, if you employ none of the mechanisms discussed below to redirect your Image calls to Eloquence, then your software should function exactly as it would if you hadn't specified the Eloquence client in the XL list of the :RUN statement. This allows you to easily toggle between Image and Eloquence without having to run your software in multiple ways. Simply add the client library to your XL list, and forget about it. Setting up the default Eloquence server instance ------------------------------------------------ An MPE CI variable called EQ_DBSERVER (or an environment variable, if running a POSIX program from within the shell) is used to specify the default server location where the Eloquence client looks in order to find a remote Eloquence database. The value of the variable follows the format "server:port", where "server" can either be a node name or an IP address, and "port" is usually 8102. From the MPE prompt you'd set the EQ_DBSERVER variable by doing one of the following: 1) If the Eloquence server resides in the same subnet as your HP 3000 then simply do... :setvar EQ_DBSERVER "somenode:8102" 2) If the Eloquence server is in a different subnet, then use a fully qualified domain name... :setvar EQ_DBSERVER "somenode.somecompany.com:8102" 3) Use an IP address... :setvar EQ_DBSERVER "192.168.0.1:8102" Similarly, inside the shell the command to set EQ_DBSERVER is... $ export EQ_DBSERVER="somenode:8102" For more information on database names and EQ_DBSERVER settings please visit our online documentation: http://www.hp-eloquence.com/support/B07/relnotes /B0700/hp3k/compat.html#db_name (Sorry for the wrap; these two strings need to be pasted together to create a valid URL) Notes on the port number ------------------------ The port number depends on the database server instance. There can be multiple server processes per system, and each process uses a different port number. The number used for each instance is configured in the server configuration file. Unless specified, Eloquence uses the "eloqdb" name to define the port number, as designated in the /etc/services file. By default, during installation, this eloqdb service is mapped to the port number 8102, so this is normally what the first Eloquence database instance uses. If the port number (or another service name) is not specified in the EQ_DBSERVER variable or in the database name, the "eloqdb" name is looked up in /etc/services (or in NIS). If it is not present, then the connection fails. Under MPE/iX the services file is actually called SERVICES.NET.SYS but there is usually a symbolic link present in the /etc/services location pointing to the actual file. An entry for "eloqdb" in the SERVICES file should look like this: eloqdb 8102/tcp # Eloquence data base server Accessing remote Eloquence databases ------------------------------------ Once you have your EQ_DBSERVER variable set up (or not -- it's not required in all cases) you can employ one or more of the following mechanisms to access a remote Eloquence database using your MPE software. 1) Pass to DBOPEN's basename parameter a database identifier in the form "server:port/basename". This describes a specific Eloquence instance. It is similar in format to the EQ_DBSERVER variable, except an actual basename is also specified. 2) Pass a "magic" name to DBOPEN in the form "basename.eloq.eloq". "eloq.eloq" is a signal to the Eloquence client that "basename" is actually a remote Eloquence database, and not an Image database. In this case the Eloquence instance must have been previously set with the EQ_DBSERVER variable. 3) Set an MPE file equation that redirects the requested database to the "magic" location. For example, if the basename passed to DBOPEN is "mybase", and there is a file equation in effect for mybase, such as ":file mybase=other.eloq.eloq", then "other" will be opened as an Eloquence database in the remote location specified by EQ_DBSERVER. 4) Set an MPE CI variable whose name follows the format "eq_base_group_account" and whose contents specifies either an Eloquence instance (as described in method 1 above) or a magic name (as described in method 2). For example, if DBOPEN sees "mybase.mygroup.myacct" and you really wanted to open a remote Eloquence database called "eqbase" you could do :setvar eq_mybase_mygroup_myacct "eqbase.eloq.eloq" or :setvar eq_mybase_mygroup_myacct "eqserver:8102/eqbase" Please note that with the exception of method 1, which immediately opens the Eloquence database as specified, these methods can be combined, and each one supersedes the previous ones. A few examples may help to illustrate. All examples assume ":setvar EQ_DBSERVER 'eqserver:8102'": Method 1, Eloquence instance specified directly inside a program: basename := " eqserver:8102/mybase "; DBOPEN(basename,... ); This opens an Eloquence database "mybase" on the remote Eloquence server "eqserver". Method 2, magic name inside a program: basename := " mybase.eloq.eloq "; DBOPEN(basename,... ); Opens the same database as the first example. Method 3, file equation before running the program: :file somebase.data = mybase.eloq.eloq :run myprog;xl='image3k.pub.eloq' Then inside the program... basename := " somebase.data "; DBOPEN(basename,... ); Opens the same database as the first two examples. Method 4, setvar before running the program: :setvar eq_somebase_data_myacct "mybase.eloq.eloq" or :setvar eq_somebase_data_myacct "eqserver:8102/mybase" Then :run myprog;xl='image3k.pub.eloq' Opens the same database as the above examples. Combine Methods 2 and 3: :file mybase.eloq.eloq = somebase.data Then inside the program... basename := " mybase.eloq.eloq "; DBOPEN(basename,... ); Method 3 (the file equation) overrides Method 2, and you end up getting an Image database, not Eloquence!!! Combine Methods 2 and 4: :setvar eq_mybase_eloq_eloq "eqserver2:8106/otherbase" Then inside the program... basename := " mybase.eloq.eloq "; DBOPEN(basename,... ); Method 4 (the setvar) overrides Method 2, and you end up getting an Eloquence database called "otherbase" on a server called "eqserver2" rather than "mybase" on "eqserver". Of course, you could also combine Methods 2 and 4 to end up opening an Image database as well. Combine Methods 3 and 4: :file somebase.data = mybase.eloq.eloq :setvar eq_mybase_eloq_eloq "eqserver2:8106/otherbase" Then inside the program... basename := " somebase.data "; DBOPEN(basename,... ); This will open "otherbase" on the server "eqserver2". Combine Methods 2, 3 and 4: Left as an exercise for the reader, but certainly possible! A "real world" Eloquence client example --------------------------------------- If your HP 3000 is on a network with access to the internet, then the following is a good test to see the Eloquence client at work: :setvar EQ_DBSERVER "invent9k.external.hp.com:8102" :file sample=sample.eloq.eloq :run query.pub.sys;xl="image3k.pub.eloq" HP32216D.03.20 QUERY/NM FRI, JAN 23, 2004, 11:53 AM COPYRIGHT HEWLETT-PACKARD CO. 1976 >b=sample PASSWORD = >> { just hit RETURN here } MODE = >>5 >s=customers >find custno="32001 " 1 ENTRIES QUALIFIED >r all CUSTNO =32001 MATCHCODE =B¿HM NAME1 =Ch. BÑhm GmbH & Co KG NAME2 =Feinmechanik NAME3 = STREET =Archimedesstr. 1-4 ZIPCITY =D-7268 GECHINGEN PHONE =08458/776 TURNOVER = .000000000000000 = 29475.5300000000 = 584773.570000000 SALESAREA =D >exit END OF PROGRAM : Note: if you don't have access to name resolution services, then try replacing the string "invent9k.external.hp.com" with the IP address 192.6.38.25 in the SETVAR statement above. ---------- 2004-03-03