REF Chapter 2: Environment Variables

advertisement

Chapter 2

Environment Variables

Environment variables are host system variables that are used by BASIS modules to control the BASIS environment. Environment variables can set default parameter values or even deactivate certain commands in interactive modules.

22

Environment Variables

Introduction

The way to assign a value to an environment variable varies from system to system. For example, to set the environment variable DM_AIDS to NO on your host system, do the following:

Windows

On Windows, environment variables are set as follows: set DM_AIDS=NO

UNIX

On UNIX, environment variables are set as follows:

Bourne shell example:

$ DM_AIDS=NO

$ export DM_AIDS

C shell example:

% setenv DM_AIDS NO

VMS

On VMS, issue the appropriate command:

$ DM_AIDS="NO" (LOCAL SYMBOL)

$ DM_AIDS=="NO" (GLOBAL SYMBOL)

The following sections provide lists of the various environment variables and brief descriptions of each one. Environment variables have been grouped according to their function.

Environment Variables

23

Sysgen Parameters

Following are the Sysgen environment variables:

DM_ADB Specifies the Authority Database file descriptor.

For the default is

Windows '%DM_RUNDMK%\ sysa.dm'

UNIX '$DM_RUNDMK/sysa.dm'

VMS 'DM$RUNDMK:SYSA.DM;0(32,16)'

DM_AIDS Indicates whether BASIS interactive modules issue the prompt that asks if user aids should be reviewed.

DM_BAKADB Specifies the Backup Authority Database file descriptor.

For the default is

Windows '%DM_RUNDMK%\sysabak.dm'

UNIX

VMS

'$DM_RUNDMK/sysabak.dm'

'DM$RUNDMK:SYSABAK.DM;0'

24

Environment Variables

DM_CCF Specifies the Communication Control Facility file descriptor.

DM_CCF does not apply to Windows. For Windows the CCF information is available in the Registry of a Kernel’s service. On

VMS the DM$CCF logical serves the function of this environment variable.

For

UNIX

VMS the default is

'$DM_RUNDMK/dmccfile.ccf'

'DM$RUNDMK:dmccfile.ccf'

DM_EDIT Determines which host system editor is invoked in interactive modules that support the RECALL/EDIT command.

DM_FQM_VIEW_LC

Specifies the length in characters of the FQM view buffer. The length can be from 1000 to 65000 characters. The default is 65000 characters.

DM_FQMUWF Specifies the FQM User Work File file descriptor.

For the default is

Windows '%DM_TMP%\fqm?????.$$'

UNIX

VMS

'$DM_TMP/fqm?????.$$'

'FQMU?????.TMP;#(32,32)'

DM_KS Specifies one-letter designator (for example., A) of the current

Kernel set. Available on UNIX and VMS only.

Environment Variables

25

DM_LOGINPROC

Specifies the Login Proc file descriptor.

For the default is

Windows '%DM%\dmlogin.prc'

UNIX

VMS

'$DM/etc/dmlogin.prc'

'DM$:DMLOGIN.PRC'

DM_MODE

DM_MRT

Specifies whether the user’s process is interactive or batch.

Available on UNIX and VMS only.

Specifies whether or not BASIS programs display the Module

Revision Tag.

DM_PRIMARY_KERNEL

Specifies the name of the user’s primary Kernel.

DM_RELEASE Specifies A two- or three-character release designator (for example,

V9). Available on UNIX and VMS only.

DM_TERM_DEFAULT

Specifies the numeric code of the default terminal.

For

Windows

UNIX

VMS the default is not applicable and valid codes are not applicable

4 (for Curses) 2 (for VT100) and 4 (for Curses)

7 (for EDT100) 2 (for VT100), 5 (for VT52),

7 for (EDT100), and 8 (for EDT52)

26

Environment Variables

DM_VOC Specifies the Vocabulary File file descriptor. On VMS the

DM$VOC logical serves the function of this environment variable.

For the default value is

Windows '%DM%\etc\dmvoc.vf'

UNIX '$DM/etc/dmvoc.vf'

VMS 'DM$:dmvoc.vf'

DMBATCH Specifies name of a batch queue to which certain BASIS modules and procs submit jobs.

Available on VMS only.

DMVERSION Specifies unique number based on process identifier used as version number for temporary files created by BASIS modules.

Available on UNIX and VMS only.

HVU_SEQ_BUFFER_LE

Specifies number of 8-page buffers allocated for DMR/HVU/ DMQ and the librarian manager. The default is 200. DMQ and the librarian manager are not available on Windows.

HVU_RND_BUFFER_LE

Specifies number of 1-page buffers allocated for DMR/HVU/ DMQ and the librarian manager. The default is 400. DMQ and the librarian manager are not available on Windows.

Environment Variables

27

UPWEXACTCASE

Indicates whether BASIS user passwords (UPW) are treated as case-sensitive. Prior to V10, all UPWs were considered uppercase

(case-insensitive). With V10 and later, UPWs may be mixed-case and are case-sensitive. For existing users, if UPWEXACTCASE is

N (the default), all uppercase-only UPWs are treated as caseinsensitive. If UPWEXACTCASE is Y, all UPWs are treated as case-sensitive.

UPW_LIFETIME

Gives the number of days that a user password is valid, from the time of creation or last change. A zero value means there is no expiration date. Legal values are 0:365.

DM_ARC_KERN_LOGS

When this environment variable is set (to any value), upon kernel startup the existing kernel and sort kernel log file are renamed by appending them with a date/time stamp. This allows multiple versions of the log files to be preserved; these may contain valuable evidence should an unexpected event occur.

Available on Unix/Linux and Windows only.

28

Environment Variables

Interactive Modules

The following environment variables affect interactive modules.

DM_AIDS Determines whether a prompt is issued to ask users whether they want to review the user aids for the module. If DM_AIDS is set to

YES, the prompt is issued. If DM_AIDS is set to NO, the prompt is not issued. The default is YES.

DM_EDIT

DM_MODE

DM_MRT

DM_SPAWN

Determines which host system editor is invoked in interactive modules that support the RECALL/EDIT command

Indicates whether a user’s process is INTERACTIVE or BATCH.

The value of this environment variable is set by the

DM$COMMANDS command

Determines whether the Module Revision Tag (MRT) is displayed when running a BASIS module. If DM_MRT is set to YES, the

MRT is displayed. If DM_MRT is set to NO, the MRT is not displayed. The default is YES. If MRT is specified on the command line for the module (where applicable), it takes precedence over the value of DM_MRT.

Determines whether the SPAWN command can be used in the interactive modules that support it. If DM_SPAWN is set to YES, the SPAWN command can be used. If DM_SPAWN is set to NO, the SPAWN command cannot be used. The default is YES.

Environment Variables

29

DM_SPAWN_COMMAND

Prefaces the spawned host command with a specified command, thus preventing the user from issuing SPAWN alone to return to the host system level.

In BASISplus/Express, the host command defined by

DM_SPAWN_COMMAND is executed when the Spawn action is selected. The DM_EXP_SPAWN_WINDOW can be used along with DM_SPAWN_COMMAND to ask for additional information via a pop-up window before spawning. For more information about

DM_EXP_SPAWN_WINDOW, see BASISplus/Express Volume 1,

“Environment Variables.”

BASISplus/Express is not available in Windows.

In FQM, the host command defined by DM_SPAWN_COMMAND is executed when the SPAWN command is entered. Any remaining text following the SPAWN command is concatenated to the

DM_SPAWN_COMMAND text. For example, if

Windows

UNIX

VMS

DM_SPAWN = yes

DM_SPAWN = yes

DM_SPAWN is set to YES

and

Windows

UNIX

VMS

DM_SPAWN_COMMAND=notepad

DM_SPAWN_COMMAND= telnet is set to LOGIN

30

Environment Variables

then when the user enters the FQM command

Windows SPAWN anyfile.tx t (Filename is optional)

UNIX SPAWN HOSTNAME

VMS SPAWN USERNAME

FQM will spawn the host command

Windows notepad anyfile.txt (Filename is optional)

UNIX telnet HOSTNAME

VMS LOGIN USERNAME instead of spawning to the host system level.

VMS

DM_BROADCAST_BOX

Indicates whether broadcast messages should be sent to the message box for user-written screen application programs. This variable should be set to NO for user-written screen application programs that perform a SPAWN while the screen is open. There is no problem, however, if the screen is closed before the SPAWN is performed.

YES The broadcast messages are sent to the message box.

NO The broadcast messages are not sent to the message box.

Default is YES.

Environment Variables

31

All

DM_FQM_TT_LE

Specifies the number of entries in the FQM translation table. The translation table is a cache that holds information about views and fields. This cache should be large enough to hold most of the frequently used information. Set this variable to the number of fields that will be referenced in an FQM session.

Minimum value is 100.

Maximum is 1000.

Default is 250.

DM_FQM_TTBUF_LC

Specifies the length in characters of the FQM translation buffer.

Controls the size of the buffer portion of the of the FQM translation table cache. Each entry requires from 80 to 200 bytes.

Minimum value is 8000.

Maximum is 32000.

Default is 12000.

UNIX, VMS

DM_ACTION_BAR_STYLE

Controls the style of Express, Thesaurus Manager, and

TECHLIBplus action bars. This variable can be set to CUA or

STANDARD. The default is STANDARD.

CUA The action bar will contain a single choice box to the left of the actions. Each action will have a single letter underlined to represent the valid choice for the box.

STANDARD The action bar will contain actions but no choice box. The user selects actions by moving the cursor over an action or by the [ARROW_BAR_RIGHT] and [ARROW_BAR_LEFT] keys.

32

Environment Variables

DM_USE_SCREEN_HELP

Controls what is displayed as context-sensitive help for a field. The default is ALL.

ALL FIELD information from the Definition Database is displayed. This information includes field name, usage/data type, index type, occurs, column width, and other field details.

COMMENTS Information from the COMMENT parameter of the

UDM AT statement for the field is displayed.

All

DM_AUTHENTICATION Designates the source from which values for UID and UPW on BASIS modules are derived. The default is ADB .

ADB The values for UID and UPW on

BASIS modules are matched with values in the Authority Database.

There is no relationship between the host account login name of the user and the value entered for UID.

HOST The values for UID and UPW on

BASIS modules are derived from the host account login name. (The

HOST account name must be entered in the Authority Database as a BASIS user and authorized for any existing databases which will be used.)

UNIX

On UNIX, this environment variable can be set in the setdmsite.sh or setdmsite.csh file, depending on which shell is being run.

Environment Variables

33

34

Environment Variables

DM_ENCRYPTED_UPW Determines whether the DMSA commands

EXPORT/ADB and IMPORT/ADB handle UPWs of user records in an encrypted form.

YES Use an encrypted form of the UPW to export/import a user record.

NO Use a non -encrypted form of the

UPW to export/import a user record.

YES is the default value.

NO must be specified only in a situation where you need to migrate an ADB between platforms having opposite word byte orderings.

The one kind of byte ordering for a computer word is termed big-endian (left to right). The other kind is called little-endian (right to left).

Big-endian platforms are as follows:

AIX (UNIX)

HP-UX (UNIX)

SunOS (UNIX)

Little-endian platforms are these:

Linux (UNIX)

VMS

Windows

Therefore, setting DM_ENCRYPTED_UPW to

NO is required when you must export an ADB on a little-endian platform and then import the ADB on a big-endian platform, or vice versa.

Environment Variables

35

DMNAM

The following environment variables affect the BASIS Network Access Module

(DMNAM). For more information about DMNAM, see System Administration .

DM_PRIMARY_KERNEL Indicates the name of the user’s primary Kernel.

DM_SEARCH_ORDER Indicates the order in which the Authority

Database (ADB) of the user’s primary Kernel and

Global Database Directory (GDD) are searched when BASIS opens a database.

If... Then...

DM_SEARCH_ORDER is set to ADB, only the ADB of the user’s primary

Kernel is searched.

DM_SEARCH_ORDER is set to GDD, only the GDD is searched.

DM_SEARCH_ORDER is set to (ADB, GDD), the ADB is searched and then the GDD.

DM_SEARCH_ORDER is set to (GDD, ADB), the GDD is searched and then the ADB. on VMS, the GDD is found for the logical name DM$GDD1,

Else the GDD is searched and then the ADB. the default is ADB.

36

Environment Variables

Run Time Binding

The following environment variables provide run time binding of the database name and the version number.

DM_DB_ database Controls the database that BASIS opens. The name of the database referenced in a user program is specified as part of the variable name. This variable is assigned the name of the database to be used at execution time. For example, if

DM_DB_TOUR is set to DTOUR, then a user program that references the TOUR database automatically uses the DTOUR database.

DM_DB_K_ database Lets a user define a host variable that will designate which Kernel will open a database.

This run time binding variable is for databases that have been ASSIGNed in DMSA as

READONLY=YES and KERNEL=$ALL.

Each read-only database assigned to

Kernel=$ALL can have its own host variable of the form

DM_DB_K_ database where database is the database specified on the user’s open request--e.g.,

DM_DB_K_database=DMKC7

The user can set or modify the host variable via the host command language or by using the

SET/HOST_VARIABLE proc command.

In BASIS release L1G, distributed access for shared read-only databases is improved. Usually,

BASIS is configured such that read-only databases are serviced by a Kernel that resides on the same node as that of the user.

Environment Variables

37

DM_DB_K_databasename=kernel_name overrides this processing and specifies the Kernel that opens a read-only database. This is necessary when join operations are to be performed between the read-only database and another writable database.

DM_DBVER_ database Controls the version of the database that BASIS opens. The name of the database referenced in a user program is specified as part of the variable name. This variable is assigned the name of the database to be used at execution time. For example, if DM_DBVER_TOUR is set to 3, then a user program that references the TOUR database automatically uses version 3 of the

DTOUR database.

Once these environment variables are defined, they affect the execution of all BASIS modules except DMDBA, and they affect the the execution of all user programs.

Thus, when they are no longer needed, these variables should be deleted.

You must be careful if you use these variables to specify a database to be opened at execution time that is different from the database you used when the program was precompiled.

The definitions of the view types in each of the Definition Databases must be consistent. If the definition of the view type in the database named by the

DM_DB_database variable is not consistent with the view data structure precompiled into the program, an execution error occurs. The fields’ data types, sizes, and relative positions (within the view data structures) must be the same for both view types.

Run time binding can also be used at precompile time by assigning the name of the

Definition Database to the DM_DB_database variable. For example, if

DM_DB_XTOUR is set to XDTOUR, then any program that is precompiled and includes references to the TOUR database uses the DTOUR database. Thus, a view data structure created by the precompiler is based on the view type definition in the

DTOUR Definition Database.

38

Environment Variables

Kernel Processing for FIND Commands

The following environment variables govern Kernel processing for FIND commands.

These Kernel optimization variables fine-tune FIND command processing based on specific needs.

WARNING: Use extreme caution in modifying the default settings of the following environment variables. These variables will affect all databases controlled by the

Kernel.

DM_FIND_AND_THRESHOLD_MAXNR

If DM_FIND_AND_THRESHOLD_MAXNR has a value of n , an AND operation that would result in more than n records will force the FIND command processor to not consider evaluating any restrictions in the AND operation by scanning the records. All indexes will be used in the evaluation.

If DM_FIND_AND_THRESHOLD_MAXNR has a value of n , an AND operation that may result in fewer than n records but more than

DM_FIND_AND_THRESHOLD_NR records will force the FIND command processor to consider evaluating any restrictions in the AND operation by scanning the records.

The DM_FIND_CF_PER_INDEX and

DM_FIND_CF_PER_RECORD values are used to make this determination. This variable is set to an integer from 1 to 100000000. The default is

3000.

Environment Variables

39

DM_FIND_AND_THRESHOLD_NR

Specifies the maximum size of the final result set.

The FIND command processor will always use this to turn off some of the indexes so it may scan the records in order to evaluate part of an AND operation.

In general, the most efficient way to process several retrieval expressions which are connected by Boolean ANDs is to create an intermediate set for each retrieval expression and then AND the intermediate sets. However, this method is inefficient when one or more of the intermediate sets is large and the final result set is small. In this case, rather than expending resources generating the large intermediate set(s), the small set is generated first and only those occurrences are checked for the other conditions.

DM_FIND_CF_PER_INDEX

DM_FIND_CF_PER_RECORD

If DM_FIND_AND_THRESHOLD_NR has a value of n , an AND operation that would result in fewer than n records will always force the FIND command processor to evaluate remaining restrictions in the AND operation by scanning the records. This variable is set to an integer from 1 to 100000000. The default is 2000.

This environment variable specifies the cost factor for accessing one reference in the index. This is used together with

DM_FIND_CF_PER_RECORD in deciding whether it is better to access indexes or to access records to satisfy the FIND command. This variable is set to an integer from 1 to 100000000.

The default is 1.

Specifies the cost factor for accessing one record in the database and scanning data to check retrieval tests. This is used together with

DM_FIND_CF_PER_INDEX in deciding whether it is better to access indexes or to access records to satisfy the FIND command. This variable is set to an integer from 1 to 100000000.

The default is 50000.

40

Environment Variables

DM_FIND_JOIN_THRESHOLD_MAXNR

Specifies the upper boundary of record occurrences that the optimization algorithm will not consider when using the non-index algorithm technique. This variable is set to an integer from

1 to 100000000. The default is 20000.

DM_FIND_JOIN_THRESHOLD_NR

Specifies the minimum number of records that the

FIND command processor will consider, using existing indexes to evaluate the join operation. If

DM_FIND_JOIN_THRESHOLD_NR has a value of n , joining a set of fewer than n records will always force the FIND command processor to create a temporary index from the set to perform the join operation. This variable is set to an integer from 1 to 100000000. The default is 10.

DM_FIND_JOIN_THRESHOLD_PERCENT

Specifies the minimum 1/100 percentage of record occurrences in a set to the total record occurrence that the FIND command processor will consider when using existing indexes to evaluate the join operation.

If DM_FIND_JOIN_THRESHOLD_PERCENT has a value of n , joining a set with a number of members that is less than n/100% of record occurrences will always force the FIND command processor to create a temporary index from the set to perform the join operation.

This variable is set to an integer from 1 to 10000.

The default is 2500, which would be 25%.

Environment Variables

41

DM_FIND_NO_WAIT_CNT

DM_FIND_RANGE_KEYS_OPT Specifies the maximum number of index terms to check when determining the optimization path. If a range restriction contains more than

DM_FIND_RANGE_KEYS_OPT terms, then the

FIND command will consider the cost of evaluating the range as unknown and not perform optimization on this part of the retrieval test.

In the simple case there might be a command of the form:

FIND VOA WHERE PARENT INCLUDES

'SOMEWHERE' AND ITEMS=1:10

Affects how quickly the FIND command relinquishes control to the scheduler, regardless of whether the FIND command is accessing data already cached in memory. This environment variable will ensure that the FIND command processor gives other requests a chance to be processed, even when all data pages are in memory.

This variable is set to an integer from 1 to 250.

The default is 25.

If you determine that this command is performing within your acceptable service level range and a command that specifies ITEMS=1:11 does not, you might improve performance by adjusting this parameter.

This variable is set to an integer from 1 to 10000.

The default is 50.

Note: Use caution in adjusting the value of this environment variable. It is data dependent and will affect all range optimizations.

42

Environment Variables

Environment Variables

43

DM_FIND_LOCK_QUOTA Specifies the quota of record-occurrence locks for a FIND command performed within a transaction.

For each member of a result set created within a transaction, the Kernel typically sets one recordoccurrence lock. If the number of such locks exceeds the quota, the Kernel elevates the recordtype lock from a shared to a protected mode, which enables the Kernel to void the recordoccurrence locks and thus conserve lock space.

(A lock-space shortage causes the Kernel to take radical measures, such as victimizing one or more user processes, in order to avoid the impasse.) minimum value: 2000 maximum value: 32000 default value: 8000

44

Environment Variables

Kernel Scheduler

The following environment variables tune the Kernel Scheduler. For more information about these environment variables, see System Administration .

DM_SCHEDULE_PRIORITY Determines the scheduling priority. The possible values for this variable are

{U,} {P,} {D} | NONE where

U

P

D

NONE indicates

User priority base

Program priority base

Database priority base

No scheduling priority

DM_RAISE_PRIORITY

DM_START_REQUESTS

DM_FIND_NO_WAIT_CNT

DM_NO_MOVEMENT_LIMIT

The default is NONE.

Determines the number of times a request is

“passed by” before its priority is incremented by 1 so that it will run until blocked. After the request is run, its priority is reset. This variable is set to an integer from 1 to 10. The default is 10.

Affects the frequency at which the scheduler attempts to start new requests. This variable is set to an integer from 1 to 10. The default is 10.

Affects how quickly the FIND command relinquishes control to the scheduler. This variable is set to an integer from 1 to 250. The default is 25.

Controls the number of times that the Kernel will loop in the scheduler before deciding that it is in a hung state and aborting itself. The default is

500000.

Environment Variables

45

Size Checking and Control

The following environment variable affects checking of database size.

DM_VALIDATE_FILE Affects whether or not the Kernel checks each database file when the file is opened. The Kernel checks to see that each database file is a size that is consistent with the size stored in the file’s internal data structure. The value can be YES or

NO.

YES means that the Kernel does the checking.

Because this checking is done when the file is opened, it will increase the time it takes to open a database, especially when it is very large.

NO means that the Kernel does not do the checking.

This environment variable is used only by the

Kernel. It needs to be set in the Kernel startup command procedure. The default is NO.

The following environment variables control the size of the heap used by the generalpurpose FQM TYPE Engine formatting tool. The TYPE Engine is used to present data in a readable format. This engine is used in various parts of the system, including the FQM

TYPE command and BASISplus/Express SHOW.

Note: BASISplus/Express is not available on Windows.

DM_FQMTE_HS_EXTLC Specifies the length in characters of a single heap extent used by the FQM TYPE Engine.

46

Environment Variables

For this variable is set to an integer from

Windows 4076 to

4000000

UNIX

VMS

DM_FQMTE_HS_NREXTS

2048

2048

4000000

4000000 and the default is

16384

8192

8192

Specifies the maximum number of extents that can be allocated by the FQM TYPE Engine. This variable is set to an integer from 10 to 255. The default is 50.

The following environment variables control the size of the page pools used by DMR,

HVU, DMQ (except on Windows), and the librarian manager. The size affects how many database pages can be used at the same time and how many write operations can be deferred.

HVU_RND_BUFFER_LE Specifies the maximum number of 1-page buffers allocated. The default is 400.

HVU_SEQ_BUFFER_LE Specifies the maximum number of 8-page buffers allocated. The default is 200.

Heap Manager and UPI Heap

The following environment variable affects the Heap Manager.

DM_HEAP_COMPRESS_PERCENT

Determines when a heap extent is compressed by the Heap Manager. A heap extent is compressed when DM_HEAP_COMPRESS_PERCENT of it contains deleted space. This variable is set to an integer from 30 to 100. The default is 30.

Environment Variables

47

The following environment variables affect the user program interface (UPI) heap.

DM_UPI_HS_EXTLC Specifies the length in characters of a single heap extent in the UPI heap. This variable is set to an integer from 65408 to 4000000. The default is

524288.

DM_UPI_HS_NREXTS

DM_UPI_WS_LC

Specifies the maximum number of extents that can be allocated in the UPI heap. This variable is set to an integer from 1 to 255. The default is 4.

Specifies the length in characters of the UPI work space.

For

Windows this variable is set to an integer from to

44004 80000 and the default is

44004

UNIX

VMS

27648

27648

80000

80000

27648

27648

DMKBC and DMSGC

The following environment variables affect the DMKBC (except on Windows) and

DMSGC heap.

DM_DMRC_HS_EXTLC Specifies the length in characters of a single heap extent in the DMRC heap. This variable is set to an integer from 16384 to 4000000. The default is

32768.

DM_DMRC_HS_NREXTS Specifies the maximum number of extents that can be allocated in the DMRC heap. This variable is set to an integer from 10 to 255. The default is

100.

48

Environment Variables

Document Handler

The following environment variables affect various features of the Document Handler.

Style Guide Heap

DM_STYG_HS_EXTLC

DM_STYG_HS_NREXTS

Specifies the length in characters of a single heap extent in the heap used by the Document Handler to buffer information from a style guide object file. This variable is set to an integer from 16384 to 4000000. The default is 16384.

Specifies the maximum number of extents that can be allocated in the heap used by the Document

Handler to buffer information from a style guide object file. This variable is set to an integer from

10 to 255. The default is 50.

General Purpose Heap

DM_DH_HS_EXTLC

DM_DH_HS_NREXTS

Specifies the length in characters of a single heap extent in the general purpose heap used by the

Document Handler. This variable is set to an integer from 16336 to 4000000. The default is

1000000.

Specifies the maximum number of extents that can be allocated in the general purpose heap used by the Document Handler. This variable is set to an integer from 10 to 255. The default is 50.

Text Stream Field Processing

DM_DH_TSMEM_LC Specifies the number of characters of a text stream field that can be in memory at one time before the Document Handler begins to use its workfile to buffer data for the text stream field.

This variable is set to an integer from 130816 to the amount of virtual memory available to the user’s process. The default is 196224.

Environment Variables

49

DM_DH_TSOVER_LC

DM_DH_MUL_BATCH_LC

Specifies the number of characters that the portion of a text stream field that is in memory can exceed

DM_DH_TSMEM_LC. This variable is set to an integer from 500 to 196224. The default is

65408.

Specifies the approximate length in characters for each batch of input (marked-up lines) read into memory during the import of a BGML document.

The specified value can range from

80

to

65000

.

The default value is 1500 , which is generally optimal with respect to both CPU and elapsed time.

A different value should not be specified unless:

1. all your documents have identical mark-up characteristics, i.e., same set of mark-up elements, same relative placement within a document, same frequency of occurrence, and

2. you have a large amount of document data to import.

If both these conditions are true, you should calculate your own optimal value by running numerous trial imports of a typical document with systematically varying values of

DM_DH_MUL_BATCH_LC. Vary the value by no less than 500 and run at least 3 trials for each different value.

Markup Parsing

DM_DH_MAX_HIDELC

DM_DH_MAX_TRANSLC

Specifies the maximum length in characters of a hidden string. This variable is set to an integer from 1 to 100000. The default is 100.

Specifies the maximum length in characters of a translate string. This variable is set to an integer from 1 to 100000. The default is 100.

50

Environment Variables

DM_DH_MAX_TAGLC

DM_DH_MAX_ENTLC

DM_DH_MAX_FLDLC

Specifies the maximum length in characters of a

BGML start or end tag. This variable is set to an integer from 1 to 65000. The default is 512.

Specifies the maximum length in characters of a

BGML entity reference. This variable is set to an integer from 1 to 16000. The default is 100.

Specifies the maximum length in characters of a field mark. This variable is set to an integer from

1 to 16000. The default is 100.

Paragraphs and Indentation

The following environment variables control the determination of paragraphs and the display of paragraph indentation in the Document Handler.

DM_DH_PARA_IND_MIN Specifies the paragraph parsing minimum value.

The default is 5 for non-Chinese text and 2 for

Chinese text.

DM_DH_PARA_IND_MAX

DM_DH_PARA_INDENT

Specifies the paragraph parsing maximum value.

The default is 10 for both non-Chinese and

Chinese text.

Specifies the paragraph indentation displayed.

The default is 5 for non-Chinese text and 2 for

Chinese text.

Given default values for the DM_DH_PARA_INDENT, DM_DH_PARA_IND_MIN, and DM_DH_PARA_IND_MAX environment variables, the following actions occur:

For non-Chinese text an indentation of 5 spaces is displayed at the beginning of a paragraph, and paragraphs are located by searching for indentations of between 5 and

10 spaces.

For Chinese text--both simplified and traditional--an indentation of 2 spaces is displayed at the beginning of a paragraph, and paragraphs are located by searching for indentations of between 2 and 10 spaces.

For more information about these environment variables, see the section titled “Paragraph

Parsing in Document Handler” below.

Environment Variables

51

Sorting

The following environment variables override the normal character sorts.

DM_SORT_TMP Specifies the directory in which to locate sort temporary files. By default, the directory pointed to by DM_TMP is used. To put sort temporary files into a different location, set this environment variable to point to the new location.

HVU_MRG_SPLITS Allows HVU, DMR, and DMQ (except on

Windows), to override the normal 40, 100, and 250 character sorts. By using HVU_MRG_SPLIT, you can specify different split points and multiple buckets for each split point and significantly improve sorting performance during large HVU,

DMR, and DMQ loads.

Unlike the previous method of sorting that was based on the maximum key size, this method of sorting merges the split points (and buckets).

The format is an increasing (or equal) list of integers. For example, setting this environment variable to 4,4,5,5,5,6,6,10,20 creates the following buckets:

2 buckets that contain 4 character terms or less

3 buckets that contain 5 character terms, 2 buckets that contain 6 character terms, 1 bucket that contains 7-10 character terms, 1 bucket that contains 11-20 character terms, 1 bucket that contains 21-250 character terms

The maximum number of buckets is 255.

The maximum number of buckets for one term size is 9.

52

Environment Variables

VMS

DM_SORT_STATS

For the file names are and

Windows %HMI????% %HMO????%

UNIX

VMS

$HMI????

HMI????

$HMO????

HMO????

The first 3 question marks in the file name are replaced by the term size. The last question mark is the bucket sequence number (1-9).

(VMS only) Controls whether sort statistics will be printed or not. If DM_SORT_STATS is set to

YES, all BASIS modules invoking the system sort

(for example, HVU, FQM RANK, FQM TALLY,

DMR, and MTCDB) will print statistics from each sort run to SYS$ERROR. The statistics produced are similar to those that are produced by the /STAT qualifier on the VMS DCL SORT. If

DM_SORT_STATS is set to NO, the sort statistics will not be printed.

The default is NO.

Environment Variables

53

OpenAPI

All

The following environment variables affect OpenAPI:

DM_OPI_HS_EXTLC Specifies the length in characters of a single heap extent in the OPI heap. This variable is set to an integer from 16336 to 4000000. The default is

1000000.

DM_OPI_HS_NREXTS Specifies the maximum number of extents that can be allocated in the OPI heap. This variable is set to an integer from 10 to 255. The default is 50.

54

Environment Variables

UNIX Operating System

The following environment variables are valid only on UNIX.

DM_PATH Is used by BASIS users whose UNIX operating system supports both System V and BSD utilities to ensure that the System V bin directories get searched first. The default is $PATH.

DM_SHELL

DM_NAM_SUB_PROCS

DM_TMP

Specifies an alternate Bourne shell.

BASIS needs a Bourne shell to execute start-up procedures and batch jobs.

(Note this does not require a BASIS user to operate under a Bourne shell.)

If the Bourne shell is not named /bin/sh (standard default) DM_SHELL should be set to the nonstandard name.

Specifies the number of network communication subprocesses used by the kernel for DMNAM.

The default is 1.

Specifies the directory where temporary files are located. The default is /usr/tmp.

Environment Variables

55

VMS Operating System

The following environment variables are valid only on VMS.

DM_SORT_WORK_FILES Specifies the number of temporary work files that the VMS sort package can use. This variable is set to an integer (1 :9) value. The default is 2.

DM_GLOBAL_MEMORY Tells BASIS where to place the data structures for inter-process communications, direct-access I/O, etc. This variable can be set to either P0 or P1.

The default is P1.

DM_SPAWN_LOGICALS

DM_SPAWN_SYMBOLS

Specifies whether or not process logical names are copied to a SPAWNed process via the proc

SPAWN command. The default is YES.

Specifies whether or not process symbols are copied to a SPAWNed process via the proc

SPAWN command. The default is YES.

WARNING: All BASIS modules that SPAWN will honor the

DM_SPAWN_LOGICALS and DM_SPAWN_SYMBOLS host variables. This includes DMDBA, DMFORM, EXPRESS, and TECHLIBplus. Unexpected results may occur when these variables are set to NO.

56

Environment Variables

Character Set Table

All

For information about changing character sets, see the NLS.HLP file in the online help area. For information about how to access the online help area on your operating system, see BASIS Reference, “Basics.”

National Language Support (NLS)

The following environment variables are used by the National Language Support features in BASIS.

DM_DMVPM_TTEXT Specifies a range of message numbers that are redirected to the TTEXT field of SYSRES for the

DMVPM VFTOHVU action. Message ranges must be separated by colons and listed with commas. (Does not apply to Windows.)

Environment Variables

57

DM_LANGUAGE

DM_LANG

DM_LANG_SOURCE

Specifies a language for Express (not applicable to Windows) and TECHLIBplus international versions. Following are abbreviations for languages:

CAT

CHT

DEU

ENG

ENU

ESP

FRA

FRC

ITA

JPN

KOR

U01 through U09

Catalan

Traditional Chinese

German

United Kingdom English

United States English

Spanish

European French

Canadian French

Italian

Japanese

Korean

User-defined languages

Specifies the locale of the user environment.

Locales are of the form

“language_country.codeset” and are defined in the locale database by

DMLOCALE.

Specifies the locale of the source data. Used to activate run-time filtering.

58

Environment Variables

DM_KAT_HS_EXTLC

DM_KAT_HS_NREXTS

DM_LDB_HS_EXTLC

DM_LDB_HS_NREXTS

Specifies the length in characters of a single heap extent in a Keyed Access Table structure. KAT structures are used in various NLS features to hold symbols. This variable is set to an integer from 500 to 4000000. The default is 50000.

Specifies the maximum number of extents that can be allocated in the Keyed Access Table structure.

This variable is set to an integer from 1 to 255.

The default is 50.

Specifies the length in characters of a single heap extent in for Locale Database objects. This variable is set to an integer from 500 to 4000000 for all operating systems. The default is 25000.

Specifies the maximum number of extents that can be allocated for Locale Database objects. This variable is set to an integer from 1 to 255. The default is 50.

Morphological Indexing

The following environment variable is used to enable or disable morphological indexing.

DM_EXITCPI To enable morphological indexing, whether by the BASIS default component or by a customized Component Programming

Interface (CPI) EXIT component, in the setdmsite file, set the

DM_EXITCPI environment variable to Y. The default is N.

To disable morphological indexing, set the DM_EXITCPI environment variable to N.

Environment Variables

59

60

Environment Variables

Windows Add DM_EXITCPI=Y to the Kernel’s environment by means of the BASIS

Configuration utility or regedt32.exe.

Also add DM_EXITCPI=Y to the dmcmds.bat file.

% setenv DM_EXITCPI Y UNIX C shell

UNIX Bourne/Korn shell $ export DM_EXITCPI=Y

VMS DM_EXITCPI=="Y"

Paragraph Parsing in Document Handler

The user may change the default values for the DM_DH_PARA_INDENT,

DM_DN_PARA_IND_MIN, and DM_DH_IND_MAX environment variables to tailor the paragraph processing and parsing to accommodate a particular setting.

For example, assume that the settings are

DM_DH_PARA_INDENT=3

DM_DH_PARA_IND_MIN=3

DM_DH_PARA_IND_MAX=10

Then adding the following record to a database would produce context units as indicated

(assuming the CONTENTS field is defined so that paragraphs are the context units):

Environment Variables

61

-----------------------------------------------------------------------

ID.......= 2

CONTENTS> This is the first context unit. <- 3 spc => new par

-----------------------------------------------

This is the first context unit. <- 1 spc => last

-----------------------------------------------

This is the first context unit. <- 2 spc => last

-----------------------------------------------

This is the second context unit. <- 3 spc => new par

-----------------------------------------------

This is the third context unit. <- 4 spc => new par

-----------------------------------------------

This is the fourth context unit. <- 5 spc => new par

-----------------------------------------------

This is the fifth context unit. <- 6 spc => new par

-----------------------------------------------

This is the sixth context unit. <- 7 spc => new par

-----------------------------------------------

This is the seventh context unit. +

<- 8 spc => new par

-----------------------------------------------

This is the eighth context unit. +

<- 9 spc => new par

-----------------------------------------------

This is the ninth context unit. +

<- 10 spc => new par

-----------------------------------------------

This is the ninth context unit. +

<- 11 spc => last

-----------------------------------------------

This is the tenth context unit. +

<- 3 spc => new par

-----------------------------------------------

Action >

(Add,Delete,Exit,Find,Help,Match,Print,Replace,Show,>,<,?)

Member# 1 of 1 for Set 3 (For Delete, Replace and Show)

-----------------------------------------------------------------------

Notice how the indentation to produce a new context unit (i.e., identify a new paragraph) must be within the range indicated by MIN and MAX (including endpoints). Thus, the lines with 1, 2, and 11 spaces are identified as being part of the last context unit.

The following FQM session illustrates the values of the CONTENTS field when a FIND and TYPE are performed on the record:

FQM V5 R191 930208 [L1G] P000.000 CS010 (RW V5 R63)

The <TESTR.EXPRESS> user model is open with UPDATE intent.

FQM> find par where id=2

Result set 1 contains 1 references to 1 members.

62

Environment Variables

FQM> type contents(1)

CONTENTS

-----------------------------------------------------------------------

This is the first context unit. This is the first context unit.

This is the first context unit.

FQM> type contents(2)

CONTENTS

-----------------------------------------------------------------------

This is the second context unit.

FQM> type contents(3)

CONTENTS

-----------------------------------------------------------------------

This is the third context unit.

FQM> type contents(4)

CONTENTS

-----------------------------------------------------------------------

This is the fourth context unit.

FQM> type contents(5)

CONTENTS

-----------------------------------------------------------------------

This is the fifth context unit.

FQM> type contents(6)

CONTENTS

-----------------------------------------------------------------------

This is the sixth context unit.

FQM> type contents(7)

CONTENTS

-----------------------------------------------------------------------

This is the seventh context unit.

FQM> type contents(8)

CONTENTS

-----------------------------------------------------------------------

This is the eighth context unit.

FQM> type contents(9)

CONTENTS

-----------------------------------------------------------------------

This is the ninth context unit. This is the ninth context unit.

FQM> type contents(10)

CONTENTS

-----------------------------------------------------------------------

This is the tenth context unit.

Note: The DM_DH_PARA_INDENT must be within the range of the

DM_DH_PARA_MIN and DM_DH_PARA_MAX values. If the

DM_DH_PARA_INDENT is not within the range, the system would display paragraphs correctly but could not locate them during parsing. When this situation is detected, error

DHSTAT.BAD_PARAGRAPH_INDENT=51543 is returned. Also error processing looks for values outside the range of 2 to 10, which is the current set of legal values for these environment variables.

Environment Variables

63

DM_CONCEPT

The following environment variable is used by the Concept Mining library.

DM_CONCEPT Specifies the location of the concept mining initialization file, concept.ini as well as other files used for concept mining. The concept.ini file contains user-configurable parameters that are used to automatically extract concepts (personal names, company names, keywords, phrases) from documents as they are imported. This file should be should be commonly accessible by the programs that use it, i.e. HVU, FQM, and OPIRPC.

For the default is

Windows '%DM_CONCEPT%'

UNIX

VMS

'$DM_CONCEPT’

'DM$CONCEPT'

64

Environment Variables

Download