.
contact contact

Eloquence B.07.10 - MPE Client Library

 
.
 

Contents


Introduction

What is the Eloquence Client Library for MPE/iX?

The Eloquence Client Library for MPE/iX is a port of the Eloquence image3k library to MPE (as an NMXL). It provides access to remote Eloquence databases from (native mode) MPE programs.

User programs that reference the library and which utilize the standard set of Image intrinsics can access remote Eloquence databases as if they were local to the HP 3000. Certain HP-supplied system utilities, such as QUERY.PUB.SYS can also reference the client library and gain access to remote Eloquence databases.

Current Limitations

  • The Eloquence client is not compatible with any TPI product (Superdex/Omnidex). However you may use the TPI functions included with the Eloquence server.

  • As specified in the Eloquence documentation (Eloquence image3k documentation), the Eloquence database is close but not 100% compatible to TurboIMAGE. As a consequence, the TurboIMAGE utilities (such as DBUTIL) will not work with the Eloquence client XL.

  • Programs that access remote Eloquence databases via the client XL must make use of standard TurboIMAGE intrinsics. Privileged direct access to data set files (which is employed by some well known third party utilities, such as SUPRTOOL in PRIV mode) is not supported.

  • Accessing a database remotely is expected to be noticeably slower than accessing a local database, depending on application and network properties. Version B.07.10 of the Eloquence Client Library uses techniques like client side caching to mitigate some of the underlying handicaps.

How do I obtain the Eloquence client software?

The Eloquence Client Library for MPE is available for download via the web:

After downloading the above binary file, you need to upload it to your HP 3000 for unpacking. We recommend to use the FTP file transfer program (also available from the Command Prompt on Windows). The following example shows the FTP commands for transferring the local PC file in binary mode, creating a file in bytestream format and with a POSIX style (HFS) filename on the HP 3000 side:

  C:\> ftp your3000.example.com
  Connected to your3000.example.com.
  220 HP ARPA FTP Server [A0012C05] (C) Hewlett-Packard Co. 2000 [PASV SUPPORT]

  Name (your3000.example.com:yourname): user.demo
  331 Password required for USER.DEMO.  Syntax: userpass,acctpass
  Password:
  230 User logged on
  Remote system type is MPE/iX.

  ftp> binary
  200 Type set to I.

  ftp> put C:\temp\image3k.tar.Z /tmp/image3k.tar.Z;REC=,,B
  150 File: /tmp/image3k.tar.Z;REC=,,B opened; data connection will be opened
  226 Transfer complete.

  ftp> bye
  221 Server is closing command connection

Note the ;REC=,,B option in the above example that is appended to the target filename without any spaces. This overrides the default BUILD parameters on the HP 3000 side to have the target file created in bytestream format.

If you prefer to use your favorite terminal emulator's file transfer option, make sure to perform the transfer in binary mode and create the target file as bytestream or fixed binary (FB) format on the HP 3000 side (not variable binary VB format).

How do I install the Eloquence client software?

After transferring the above image3k.tar.Z archive file to your HP 3000, you uncompress and unpack it with the POSIX tar utility that is included with recent versions of MPE/iX and may be invoked from inside the POSIX shell or from the MPE command prompt. The following example shows the use of the tar command to unpack the files; it assumes that you are already logged on to the MPE group or directory where you want the library to be placed (use CHGROUP or CHDIR as needed):

  :LISTFILE /tmp/image3k.tar.Z ,2
  PATH= /tmp/

  CODE  ------------LOGICAL RECORD-----------  ----SPACE----  FILENAME
          SIZE  TYP        EOF      LIMIT R/B  SECTORS #X MX
            1B  BA      313344 2147483647   1     1232  4  *  image3k.tar.Z

  :XEQ /bin/tar "-xvzopf /tmp/image3k.tar.Z"
  x README, 14149 bytes, 28 tape blocks
  x IMAGE3K, 1749504 bytes, 3417 tape blocks

  :LISTF IMAGE3K ,2
  ACCOUNT=  DEMO    GROUP=  PUB

  FILENAME  CODE  ------------LOGICAL RECORD-----------  ----SPACE----
                    SIZE  TYP        EOF      LIMIT R/B  SECTORS #X MX
  IMAGE3K   NMXL    128W  FB        6834    4096000   1     6848  7  *

  :# optionally purge the compressed tar archive after unpacking it...
  :PURGE /tmp/image3k.tar.Z
Notice that you may install or copy the Eloquence Client Library for MPE into any MPE group or directory of your choice. However, if you plan to use it in conjunction with PRIV MODE programs or libraries, it needs to reside in an MPE group which has PM capability (using PUB.SYS is possible) as you would otherwise get the following error message from the MPE loader when attempting to run privileged programs or libraries together with the IMAGE3K library:
  :RUN DEMOPROG.PRV.DEMO;XL="IMAGE3K.PUB.DEMO"
  FILE BEING LOADED IS LESS PRIVILEGED THAN THE PREVIOUS
  FILE IN THE BINDING SEQUENCE.
  File = IMAGE3K.PUB.DEMO
  The file being loaded is less privileged than the previous file in the binding
  sequence. (LDRERR 602)
  Native mode loader message 602
  Unable to load program to be run. (CIERR 625)

Reference Guide

Revision: Eloquence B.07.10, 2008-07-04

Welcome to Eloquence for MPE, the client library which allows your HP 3000 software to access remote Eloquence databases.

This third release of the IMAGE3K library is based on the B.07.10 code base and adds performance and improved compatibility while simplifying its use.

Please note: This IMAGE3K release includes some changes in configuration over the previous version. Even if you previously used an older IMAGE3K version, please read this document and review the section on changes to previous versions.

Additional information is available on the Eloquence web site:


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 a custom location IMAGE3K.GRP.ACCT, with GRP and ACCT being an MPE group and account of your choice (using PUB.SYS is possible). It should look very similar to this...

:listf image3k.GRP.ACCT,2
ACCOUNT=  ACCT       GROUP=  GRP

FILENAME  CODE ------------LOGICAL RECORD-----------  ----SPACE----
                 SIZE  TYP        EOF      LIMIT R/B  SECTORS #X MX

IMAGE3K   NMXL   128W  FB        6834    4096000   1     6848  1  *

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.GRP.ACCT"

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 domain, 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 POSIX 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:


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. Select the default database target with EQ_DEFAULT

    The IMAGE3K client library checks the EQ_DEFAULT environment variable to decide whether to open databases on the Eloquence server or local TurboIMAGE databases by default.

    If EQ_DEFAULT is set to "ELOQUENCE", "@ELOQUENCE" or "@E", the client library attempts all DBOPENs against the Eloquence server, unless option 2 below overrides selected database names.

    If EQ_DEFAULT is to set "IMAGE", "@IMAGE" or "@I", or not defined at all, the client library attempts all DBOPENs against TurboIMAGE databases, unless option 2 below overrides selected database names.

  2. Override EQ_DEFAULT for selected databases with EQ_dbname

    You may set database specific environment variables to override the default behavior established by the EQ_DEFAULT variable. The name of such variables needs to match the database name used by the DBOPEN call(s) in your program(s), prefixed by the characters EQ_ (single underscore character). If your DBOPEN qualifies the MPE database name with group and/or account, you need to add the group and/or account to the variable name, delimited by underscore characters (instead of the . character).

    The value of such variables defines whether you want the respective database to be opened locally (i.e. TurboIMAGE) or on the Eloquence server defined by EQ_DBSERVER or specified explicitly:

    If EQ_dbname is set to "@ELOQUENCE" or "@E", the DBOPEN is attempted against the Eloquence server specified in EQ_DBSERVER (regardless of the EQ_DEFAULT setting).

    If EQ_dbname is set to "@IMAGE" or "@I", the DBOPEN is attempted on the local system, i.e. TurboIMAGE database (regardless of the setting of EQ_DEFAULT).

    If EQ_dbname exists, is not empty, and contains none of the above special keywords, it is considered to reference a database name or fully qualified database name (i.e. with optional host and or port) and the DBOPEN is attempted against the referenced Eloquence server.


Examples:

  1. Redirect all DBOPENs to an Eloquence Server...
    :SETVAR EQ_DBSERVER, "myserver.example.com:8102"
    :SETVAR EQ_DEFAULT,  "ELOQUENCE"
    
    :RUN MYPROG; XL="image3k.GRP.ACCT"
  2. Keep all DBOPENs on TurboIMAGE, except for TOYDB...
    :SETVAR EQ_DBSERVER, "myserver.example.com:8102"
    :SETVAR EQ_DEFAULT,  "IMAGE"
    :SETVAR EQ_TOYDB,    "@ELOQUENCE"
    
    :RUN MYPROG; XL="image3k.GRP.ACCT"
  3. Like example (b), but open TESTDB on another server with a different name...
    :SETVAR EQ_DBSERVER, "myserver.example.com:8102"
    :SETVAR EQ_DEFAULT,  "IMAGE"
    :SETVAR EQ_TOYDB,    "@ELOQUENCE"
    :SETVAR EQ_TESTDB,   "other-sys.example.com:4711/MYDB.TEST"
    
    :RUN MYPROG; XL="image3k.GRP.ACCT"
  4. Example (b) if MYPROG opens TOYDB using group and/or account...
    :SETVAR EQ_DBSERVER, "myserver.example.com:8102"
    :SETVAR EQ_DEFAULT,  "IMAGE"
    
    :SETVAR EQ_TOYDB,          "@ELOQUENCE"
    :SETVAR EQ_TOYDB_GRP,      "@ELOQUENCE"
    :SETVAR EQ_TOYDB_GRP_ACCT, "@ELOQUENCE"
    
    :RUN MYPROG; XL="image3k.GRP.ACCT"

Please note when accessing eloquence databases, the PASSWORD argument of the DBOPEN call is usually ignored and does not grant access. You need to use the EQ_DBUSER/EQ_DBPASSWORD CI variables to specify the credentials to database access. If not present a user "public" used used by default.

For more information, please refer to:


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"
  :setvar EQ_sample "@eloquence"
  :run query.pub.sys;xl="image3k.GRP.ACCT"

  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.


Changes to previous IMAGE3K versions

This document describes the third release of the Eloquence image3k library. This release is based on the B.07.10 code base, supporting new functionality and compatibility improvements.

  • The new EQ_DBCACHE CI variable may be used to disable the new client side caching functionality (by default its enabled).

MPE specific changes include:

  • The EQ_DEFAULT CI variable may be used to specify the default database system

  • The IMAGE3K library supports auditing functionality. The following information is uploaded to the server:

    • job/session number
    • job name (if set)
    • streamed by (for jobs)
    • pin number
    • program name
    • account/group
  • The EQ3K_NO_TPI CI variable may be used to indicate to applications the Eloquence database does not support TPI functionality. When set to a nonzero value it causes DBINFO mode 803 to indicate TPI functionality is not available. This may be used to work around problems with applications not using TPI functions correctly.

  • For use in PRIV mode applications it is sufficient to install the IMAGE3K library to a group with PM capabilities.

  • The EQ3K_DEBUG CI variable may be used to specify a log file to trace the called Eloquence intrinsics.


The section below shortly describes the changes implemented in this release that may require attention if you previously used the IMAGE3K library on MPE.

  • The initial IMAGE3K release on MPE only supported access to Eloquence databases. It required special considerations to be used from PRIV mode applications.

    This release of the IMAGE3K library behaves similar to the original version when the EQ_DEFAULT CI variable is set to "ELOQUENCE" to specify Eloquence is used by default. For use in PRIV mode applications it is sufficient to install the IMAGE3K library to a group with PM capabilities.

  • The second IMAGE3K library added support to access to Eloquence and IMAGE transparently. It supported a complex set of options (file equations, CI variables and "magic" group/account names) to specify the use of Eloquence or IMAGE and the name of the database.

    This version of the IMAGE3K library simplifies the configuration options.

    • The new EQ_DEFAULT CI variable may be used to specify the default database system. The IMAGE3K library defaults to using IMAGE.
    • File equations are no longer used within the IMAGE3K library (they are supported, as usual, when IMAGE is used)
    • The "magic" eloq.eloq group/account name is no longer treated special
    • The EQ_ CI variables are no longer fully qualified. Instead, the database name passed by the application is used, any dots present are replaced by an underscore character.

 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2008-12-22  
  Copyright © 1995-2008 Marxmeier Software AG