DownLoad

handsgridServers

Dec 4, 2013 (3 years and 10 months ago)

124 views

Getting Started



13

Chapter 1

Getting Started

Overview

This chapter instructs you in the preliminary procedures necessary to set
up BASIS WEBserver Gateway and use it to access BASIS databases.
You’ll find descriptions of the following:



the relationship

between BASIS WEBserver Gateway and Web servers



attaching BASIS WEBserver Gateway to multiple Web servers



configuring your BASIS WEBserver Gateway site



making your BASIS databases available to Web browsers



items to consider when setting up your BASIS data
base(s)

To learn how to define a BASIS database, see
Database Definition and
Development
. To learn how to load data into a BASIS database, see
Database Loading and Maintenance
.

14



Getting Started

How BASIS WEBserver Gateway Works with Web Servers

The BASIS WEBserver Gatewa
y attaches to a Web server. How this is
done depends on the specific Web server you are using.

Netscape Server

BASIS WEBserver Gateway is connected to the Netscape server by
adding the necessary lines to the Netscape server’s configuration files,
which co
ntrol the characteristics of the Netscape server during startup.
This is done automatically when BASIS WEBserver Gateway is
installed. The added lines in the configuration files cause the Netscape
server to incorporate BASIS WEBserver Gateway as part of
its
subprocesses.

Getting Started



15

Netscape Server
subprocesses
Socket
Queue
BASIS
database
BASIS
URL
regular
URL
regular
URL
BASIS
URL
regular
URL
User
User
User
BASIS
WEBserver
Gateway
BASIS
WEBserver
Gateway
BASIS
WEBserver
Gateway
regular
URL
BASIS
database

Figure 1
-
1: BASIS WEBserver Gateway/Netscape Server Relationship

16



Getting Started

Microsoft IIS

BASIS WEBserver Gateway is connected to the Microsoft IIS by
adding the necessary information to the Windows registry, which
control
s the characteristics of the Microsoft IIS during startup. This is
done automatically when BASIS WEBserver Gateway is installed.
The added registry entry causes the Microsoft IIS to incorporate
BASIS WEBserver Gateway as part of its process.

Microsoft Internet Information Server
Socket
Queue
BASIS
database
BASIS
URL
regular
URL
regular
URL
BASIS
URL
User
User
User
BASIS
WEBserver
Gateway dll
regular
URL
BASIS
database
HTTP
Server code

Figure 1
-
2: BASIS WEBserver Gateway/Microsoft IIS Relationship

Getting Started



17

As a result, when the Web server receives a BASIS
-
specific URL from a
user, it passes on the URL to the BASIS WEBserver Gateway portion of
the subprocess for handling. Figures 1
-
1 and 1
-
2 illustrate this relationship

for the Netscape server and the Microsoft IIS, respectively. (The Socket
Queue shown in the diagrams is a device to transmit data from the client to
the server and vice versa. It also distributes incoming URLs to a
vailable
subprocesses.)

You control how BASIS WEBserver Gateway appears to users on the
Web. You can use the ready
-
made forms, displays, and icons or develop
customized versions. You provide the entry point into the BASIS
WEBserver Gateway forms and dis
plays by setting up a hyperlink (in your
home page for instance) with an URL to one of these forms or displays.
The process of setting up a hyperlink (i.e., anchor) to a form or display is
discussed further in the section “Making Your BASIS Database Avail
able”
later in this chapter. The URLs to the BASIS WEBserver Gateway forms
and displays are described in the chapter “BASIS WEBserver Gateway
URLs.”

Each time a user clicks a button (or any hyperlink) on one of these forms
or displays, an URL is sent to t
he Web server for processing. It passes the
URL to BASIS WEBserver Gateway, which gets the necessary
information from the BASIS database and uses this information to
construct the proper BASIS WEBserver Gateway form or display on
-
the
-
fly to send back to t
he user. This process is illustrated in figure 1
-
3.

18



Getting Started

When a user clicks on
a hyperlink in a
BASIS WEBserver
Gateway display, the
BASIS URL is sent to
the Web server.
Socket
Queue
BASIS
database
Web Server
http://demo.idi.oclc.org:3456/BASIS/cic/all/document/DDW?...
The BASIS URL is
passed to the BASIS
WEBserver Gateway
portion for handling.
Using the information from
the BASIS database, the
BASIS WEBserver Gateway
contructs the appropriate
display on-the-fly and sends
it back to the user.
The BASIS
WEBserver
Gateway
accesses the
BASIS
database for
the
requested
information.
BASIS
WEBserver
Gateway

Figure 1
-
3: Processing of a BASIS URL

Getting Started



19

Attaching BASIS WEBserver Gateway to Multiple Web Servers

Microsoft IIS

BASIS WEBserver Gateway can be configured on one or more ports
for

the Microsoft Internet Information Server.

Netscape Server

You can create and start other Netscape servers (in addition to the one
started during installation). To attach BASIS WEBserver Gateway to
them, however, you need to modify the basis and Netscape
configuration files first. Instructions for modifying the configuration
files are below.

Preparing the Configuration Files

The basis configuration file is called
basis.conf

by default and is
located in
$DM_ROOT/www/server_root/config

on UNIX and in the

reg
istry as the value for the
BW_CONFIG

variable on Windows.
(You can change the file designated as the basis configuration by
setting the BW_CONFIG environment variable for both operating
systems.) The Netscape configuration file that you need to modify is
called
obj.conf

and is located in the config subdirectory under the
directory for your newly created Netscape server.

20



Getting Started

For the basis configuration file:

Required

Set the
BasisAccountDefault

option to the BASIS
user ID and password that you want BASIS
WEBserver Gateway to use at startu
p to sign on
automatically to the BASIS system.

IMPORTANT:

Make sure you have registered this user ID and password as
a valid BASIS account via the BASIS DMSA

module. Also, make sure
you have given this account a
ccess rights (via DMSA or DMDBA
) to each
database you want to make available through BASIS WEBserver Gateway.
For more information, see the BASIS manuals
System Administration

and
Database Definition and Development
.

O
ptional

If you want to customize the BASIS WEBserver
Gateway environment, forms, and displays, modify
the other configuration options. See the chapter called
“Customizing the Configuration File.”

Optional

If you want to set up a log file for troubleshoot
ing
purposes, specify a value for the BasisErrorLog
option. For more information, see the chapters
“Security and Troubleshooting” and “Customizing the
Configuration File.”


Do the following for the Netscape configuration file on UNIX
:

Required

To run a script that automatically makes the necessary

modifications to the Netscape configuration file, enter
the following command at your UNIX host prompt:

$DM_ROOT/www/bin/nsconfigmod
directory
path

where
directory path

is the full path of the directory
that contains the Netscape configuration file
Getting Started



21

(obj.conf).

Optional

If you want to implement security

for databa
ses
accessed by BASIS WEBserver Gateway, specify the
proper authentication setup. For more information,
see the chapter called “Security and
Troubleshooting.”

22



Getting Started


Do the following for the Netscape configuration file on Windows

Required

You must directly edit the obj.conf file before you are
able to attach BASIS WEBserver Gateway to an
additional Netscape server (
there is no script
.) (See
the “Files” appendix for a list of the changes that
must be made to the obj
.conf file for Windows.)

If you are creating another instance of the
direct

version of BASIS WEBserver Gateway and attaching
it to a new Netscape server, you need to have BASIS
WEBserver Gateway (direct) installed and you must
define environment variables

for your new Netscape
port.

If you are creating another instance of BASIS
WEBserver Gateway on Windows and attaching it to
a new Netscape server, you must define environment
variables and modify communication parameters in
order to access your new Netsc
ape server.

To define environment variables and modify
communication parameters for Windows, use the
Configuration Maintenance utility by clicking on the
icon labeled “BASIS Configuration Maintenance”
found in the BASIS Client Suite program group.

Getting Started



23

Mult
iple Connection Support

BASIS WEBserver Gateway supports a brokered Web server feature. This
is a way for a Web server port to use multiple OPI connections to BASIS.
Multiple connections allow concurrent requests to be serviced
simultaneously. For example,

brokering ensures that a user who is
downloading a large document will not monopolize the Web server by
keeping its connection very busy. The feature requires a proprietary API,
such as NSAPI or ISAPI. Brokering is not supported in CGI mode. The
brokering

feature is enabled by setting the BW_CONNECTIONS
environment variable.

BW_CONNECTIONS

The BW_CONNECTIONS environment variable sets the maximum
number of OPI connections on a port used by BASIS WEBserver.
This variable represents a performance tuning opp
ortunity where the
larger the number, the better the performance potential depending on
BASIS URL request volume and available system resources. Careful
consideration and observation should be exercised in setting this value
since each connection uses add
itional system resources. With an
inappropriate value it is possible to configure a system which actually
degrades the performance of BASIS and non
-
BASIS applications.
Open Text recommends a value of 3 to 5 for typical Pentium
desktop/server configuratio
ns with 64 to 128 MB of memory running
one or two WEBserver Gateway http ports.

For Windows users, this environment variable is set in the BASIS
Configuration Maintenance dialog box in the WEBserver Remote tab
under the Environment button. For UNIX users,
the variable is set in
the bwcfg.sh script found in the basisbin subdirectory under your
Netscape public port.

BW_CONNECTIONS does not specify the number of connections that
will be immediately created; it specifies the maximum number of
connections that m
ay be created based on load. For example, setting
BW_CONNECTIONS to 5 may never create 5 OPI processes (lines to
24



Getting Started

the kernel) to connect unless the load on BASIS WEBserver Gateway
is sufficient to require 5 connections. Each OPI process, after the first,
th
at is brought up due to load is a persistent line to the kernel until it is
disconnected either through the DISCONNECT URL or by stopping
the Web server. If the line is disconnected through DMSA, BASIS
WEBserver Gateway does not recognize that the line is
disconnected.
It will attempt to connect through the disconnected line and an error
results.

BASIS WEBserver contains special URLs that help you control and
monitor multiple connections. For more information about OPI
connection URLs, see “OPI Connection
Maintenance URLs” in
Chapter 2.

Getting Started



25

Making Your BASIS Database Available

On t
he World Wide Web, users access information by clicking on anchors
(hyperlinks
) they find in home pages and documents. The same holds true
for the information in your BASIS databases. Users will access
information in your BASIS databases

through anchors that you, as the
administrator, supply in your home page or converted HTML documents.
But with BASIS WEBserver Gateway, not only can you create anchors
that directly display document text, but you also have the advantage of
being able to

connect them to
any

of the BASIS WEBserver Gateway
forms and displays. For example, you can link an anchor to the Search
form where users can search your database for the documents of their
interest, or you can arrange it so that a summary list of relevan
t documents
appears when users click an anchor, etc. Plus, once users get to one
BASIS WEBserver Gateway form or display, they can access them all.

To create an anchor that

presents BASIS database information through a
BASIS WEBserver Gateway form or display, simply set its HREF attribute
to a BASIS WEBserver Gateway URL that contains the name of the
database, model, view, and the code of the desired form or display. More
d
etail about these URLs is provided later in this manual in the chapter
“BASIS WEBserver Gateway URLs.” For an example of how to specify
anchors in your home page, look at the source file of the sample home
page provided with the product.

Key Points:



Enter

your anchors in the standard HTML format.



You can have anchors that link to documents residing on a filesystem
as long as you set their HREF attributes to URLs with fully qualified
directory paths.



Anchors to internal locations within a document are not s
upported.

The following figure shows the BASIS WEBserver Gateway forms and
displays to which you c
an connect an anchor. It also shows the course
26



Getting Started

users can take to display a document when starting from each
form/display.

Getting Started



27

Web browser
text text text text text text text text text text text
text text text text text text text text text text text text
text text text text text text text text text text text text
text text text text text text text text text text text text
text text text text text text
Table of Contents
Display
BASIS WEBserver Gateway Forms and Displays
arrows show the progression
toward displaying a
document from each form
and display
an anchor can be linked to any
of the above forms and displays
Search Assistant
Form
Expanded
Summary Display
Search Form
Summary Display
Post Form
anchor
Document
Display

Figure 1
-
4: Connecting Anchors to BASIS WEBserver Gateway Forms and Displays

28



Getting Started

Considerations When Setting U
p Your BASIS Database

There is only one requirement for making a BASIS database accessible to
BASIS WEB
server Gateway:

Views to be accessed must include a primary key field, and this field
cannot be a multi
-
field
-
index (MFI) field.

No other special p
reparations must be made. However, there are certain
characteristics and features of BASIS WEBserver Gateway that you should
keep in mind when designing your BASIS database. If you already have
an existing database, you may want to make some modification
s based on
these characteristics and features before making the database available on
the Web. For instance, you can adjust various definition values to control
the way database data appears on certain BASIS WEBserver Gateway
forms and displays. Use the
BASIS DMDBA module to modify your
database definition. For more information about DMDBA, see the
Database Definition and Development

manual.

Note:

You can often change the default appearance of any form or
display by customizing it rather than making ch
anges to the database
definition.

Appearance of Forms and Displays

Some Actual Data Model (ADM) values in the database definition affect
the default appearance of certain BASIS WEBserver Gateway forms and
displays. The following describes these ADM values

and their effects:



The
display sequence order number

assigned to each field affects the
appearance of the following forms and displays for non
-
HT
ML
databases:


Document Summary
display

For each of the retrieved documents, this
display shows only the document’s first
晩f汤⁩渠瑨攠摩獰nay⁳ 煵q湣e牤 爮†r畴u
Getting Started



29

see Note bel
ow.

Search form

This form lists the fields in the order
indicated by their display sequence order
numbers.

For more information about
the appearance of fields on this form, see
the description of the
BasisSearchMaxFields option in the
chapter “Customizing the Configuration
File.”

30



Getting Started


Search Assistant form

This form initially shows the index terms
for the first indexed field in the display
sequence order (if the view doesn’t
c潮瑡楮⁡⁴數琠獴牥a洠晩m汤⤮l

䕸灡湤n搠d畭ua特
摩獰day

周楳⁤q獰污s⁳桯睳⁴桥⁦楥汤猠i渠瑨攠潲摥爠
楮摩ca瑥搠批⁴桥楲⁤楳灬ay⁳ 煵q湣e牤 爠
湵浢敲献⁂畴⁳敥⁎潴 ⁢ 汯眮

䑯a畭敮琠摩獰uay

周楳⁤q獰污s⁳桯睳⁴桥⁦楥汤猠i渠瑨攠潲摥爠
楮摩ca瑥搠t
y⁴桥楲⁤楳灬ay⁳ 煵q湣e牤 爠
湵浢敲献

Note:

Neither the Document Summary display nor the Expanded
Summary display can show the text stream field. For more information,
see “Document Summary Display” and “Expanded Summary Display” in
the “Action Codes a
nd Parameters for Forms and Displays” section of the
“BASIS WEBserver Gateway URLs” chapter. In the full Document
display, the text stream field must always be the last field; otherwise users
would not be able to scroll through text. For information abou
t field
display sequence order, see
Database Definition and Development,

“ADM
Definitions, “FIELD” DISPLAY_SEQUENCE_NUMBER parameter.



The
default test operator

you specify for each field will be used
during
a search if there is no test operator droplist box on the Search
form. (You can specify whether this box appears on the Search form
by setting the
BasisSearchOperatorOption
option in the basis
configuration file. For more information, see the chapter
“Cu
stomizing the Configuration File.”



The
field labels

you specify in the field statement will be used for all
forms and displays that contain fields.

Formatting Word
-
Processing/HTML Documents for Display

You can retain much of the original format of your word
-
processing and
HTML documents

when viewing them through BASIS WEBserver
Gateway by simply activating the HTML processing option from within
Getting Started



31

BASIS
Webtop

as you are updating or adding these documents to your
BASIS database.

For word
-
processing documents
, choosing the HTML processing option
from within BASIS
Webtop

preserves much of the original format by
converting structures such as tables, lists, and headings into HTML. As
HTML, these structures are handled more effectively by your Web
browser
. For your HTML (and converted word
-
processing) documents,
activating the HTML processing option ensures that document data is not
broken in the middle of an HTML structure such as a table <TABLE> or a
list <UL>. The end result is that you get documents d
isplayed through
BASIS WEBserver Gateway that look as much like their originals as
possible. For more information about how to update and add documents
using BASIS
Webtop
, see the
Webtop Online Help

or
Webtop Installation
and Administration

Guide
.

IMPORTA
NT:

Documents that are updated or added using the HTML
processing option within BASIS
Webtop

cannot be viewed through BASIS

WEBserver Gateway using a presenter. Using a presenter to show this
type of document will cause the document to be incorrectly disp
layed.

For more information about using presenters with BASIS WEBserver
Gateway, see the description for the BasisPresenter configuration
parameter in the chapter “Customizing the Configuration File.”

Access to embedded images in word
-
processing document
s is also
preserved when you choose to activate the HTML processing option from
within BASIS
Webtop
. As you update or add documents with embedded
images, the HTML processing option inserts a basis locator URL for each
associated image. The locator URL a
ttaches to the image and is used to
locate the image after it is stored in a user
-
defined record in a BASIS
database. To take advantage of this additional conversion feature, you
must load the
html.ddl

statement file found under the directory where you
ins
talled your BASIS Client Suite components. For more information
about updating your existing BASIS database definition, see
Database
Definition and Development
.

IMPORTANT:

Regardless of whether or not your word
-
processing
documents contain embedded images
, you must add the
32



Getting Started

HTML_OBJECT_LINK field from the html.ddl file to your ADM if you
plan to use the HTML processing option in BASIS
Webtop
.

NOTE:

Documents that contain very large tables may experience
performance and presentation problems.

Formatting ASCI
I Documents for Display

When displaying an ASCII document

from your BASIS database,
all data
in the text stream field is enclosed in an HTML <PRE> tag, which tells the
browser that the data is preformatted and shoul
dn’t be changed.
Depending on the converter or LINE_OPTION setting of the converter
that was used to load your original documents, you may have to override
this default by using the
BasisFullTextPre

option in the basis
configuration file. When the <PRE>
tag is not inserted, the currently used
Web browser determines the line breaks for the text stream field.
Allowing the Web browser to determine the line breaks can result in the
text being broken inappropriately in the middle of tables or graphics. For
m
ore information about converters, see
Database Loading and
Maintenance
.

The following table shows how you should set this option in each instance.

Getting Started



33


If documents are
loaded using

Set
BasisFullTextPre to

For each line
break, the system
outputs

any converter with
LINE_OPTION=HARD

Yes

a line feed

any converter with
LINE_OPTION=SOFT

No

an HTML <BR>
tag

BGML converter

No

an HTML <BR>
tag

HTML processing option

No

a line feed

Note:

For documents loaded with a BGML converter,

you can create a
presenter in your markup and style guide to map your BGML markup
elements to the appropriate HTML markup elements.

Adding HTML Elements to ASCII Text

It is strongly recommended that you do

not
insert anchors, images,

or
other HTML elements into ASCII text. A collision can occur between the
HTML elements that you insert and the navigational anchors that BASIS
WEBserver Gateway puts in ASCII text on
-
the
-
fly for display purposes.
This collision often causes unexpected
results such as the incorrect
highlighting of terms or the inappropriate splitting of anchors or both.

If you are going to insert HTML elements into ASCII text, ensure that any
document data you make into an anchor does not contain a context unit
break
such as the end of a sentence. BASIS WEBserver Gateway groups
document data into segments according to the context unit breaks. If an
anchor contains a context unit break, it is possible that when BASIS
WEBserver Gateway breaks up the document data into
segments, the front
half of the anchor could end up in one segment while the back half of the
anchor could end up in another.

34



Getting Started

Unsupported BASIS Features

BASIS WEBserver Gateway does not su
pport the following BASIS
capabilities:



Sectioned record styles.

Only conventional and continuous record
styles are supported.



JOIN clause in the FIND command.

However, composite views
defined in the definition database
are

supported. Since users cannot

join views during a search, you may want to define some extra
composite views in your database definition.

Getting Started



35



DBA
-
defined field lists.

A field name representing a list of fields as
defined by the DBA in the database definition cannot appear on the
Search f
orm.



Virtual fields in Post forms.

These fields will not appear on the
default Post form since their values are supplied by the system, not a
user. However, they
are

supported in the other BASIS WEBserver
Gateway forms and displays.

Defining a MIME Types

Field

Multimedia Internet Mail Extension (MIME) type is a standard enabling
computers using different browsers to exchange more than simple text
across the WEB through the use of standardized file suffixes and helper
applications. A helper application, l
ike the software used to create a
document or piece of a document, must be linked to the MIME type in
order to “help” a browser display information in its original format.

If you want users to be able to download the original source files of
documents to view them in their original format using their Web browsers,
then you may want to consider defining a field called MIMETYPE in your
database. A bro
wser must know the MIME type of a document so that it
can execute the proper application to download (and display) the
document. A MIMETYPE field can be a convenient way to convey this
information to BASIS WEBserver Gateway so that it can associate a
MIM
E type with a document file when passing the file to the browser for
display.

Note:

Users must have their browsers set up so that the particular MIME
type has an application defined for it, otherwise the browser will not be
able to display it.

This field

must have the name MIMETYPE and should contain the MIME
types for the documents in the database. The possible MIME types are
listed in the
mime types file

(basis.mime) provided with BASIS
WEBserver Gateway and included in the “Files” appendix.

A MIMETYP
E field is only
one

way of conveying the MIME type
information to BASIS WEBserver Gateway and the browser;
it is not
36



Getting Started

required
. The other methods you can use to specify a document’s MIME
type are:



specify this information in the URL when downloading the d
ocument

For more information about downloading documents using URLs, see
the section “Document Displays” in the chapter “BASIS WEBserver
URLs.”



specify a default MIME type by setting the BasisDownLoadExt option
in the configuration file

For more informati
on about default MIME types, see the section,
“Document display Options” in the chapter “Customizing the
Configuration File.”

Getting Started



37

If you do not specify a MIME type for a document in any of the ways
mentioned previously, the following occurs:

For a BASIS docum
ent, if there is a physical version of this document
(e.g., a word processing file), the MIME type of the returned document
is
application/octet
-
stream
. If there is no physical version, the indexed
text (ASCII) version is returned with the MIME type of
te
xt/plain
. If
the document is in HTML format, the document is returned with the
MIME type of
text/html
.

BASIS Databases Opened by BASIS WEBserver Gateway

Once a BASIS database is opened by BASIS WEBserver Gateway, it
remains open until it has



exceeded the

value of the
BasisDBMaxCacheAge

parameter

and



an URL is issued that opens another database

Note:

Both of the above conditions must be met before the database that
is currently open will close. A database that is currently open an
d that has
not exceeded the value of the BasisDBMaxCacheAge parameter will
remain open when a new database is opened.

Administrators should verify through DMSA that a BASIS database is not
open before modifying the definition of a BASIS database or perfor
ming a
backup of BASIS database files. If a database to be modified or backed up
is open, it should be deactivated and disconnected through DMSA or the
Web server should be taken down. (Taking down the Web server will
automatically close any open BASIS d
atabases). For more information
about DMSA, see
System Administration
. For more information about the
BasisDBMaxCacheAge parameter, see the “Customizing the
Configuration File” chapter.

38



Getting Started