9
Executables and Utilities

This chapter provides reference information for using the executables and utilities provided with ConText.

The executables and utilities discussed in this chapter are:

• ctxsrv/ctxsrvx Executables
• ctxctl Utility
• ctxload Utility

ctxsrv/ctxsrvx Executables

The ctxsrv and ctxsrvx executables start ConText servers. You execute ctxsrv or ctxsrvx for each ConText server that you want to start.

The ctxsrvx executable starts a ConText server with the Linguistic Services disabled. The executable for ctxsrvx is considerably smaller than ctxsrv, resulting in less memory required to run the executable.

You can also use the ctxctl utility to start and shut down ConText servers

Syntax

The syntax for executable ctxsrv or ctxsrvx is:

ctxsrv|ctxsrvx -user ctxsys/passwd[@sqlnet_address]
              [-personality RQDML]
              [-logfile log_name]
              [-sqltrace]

where:

-user

specifies the username and password for the Oracle user CTXSYS.

The username and password may be immediately followed by @sqlnet_address to permit logon to remote databases. The value for sqlnet_address is a database connect string. If the TWO_TASK environment variable is set to a remote database, you do not have to specify a value for sqlnet_address to connect to the database.

-personality

specifies the personality mask for the ConText server started by ctxsrv/ctxsrvx. The possible values can be any combination of:

• R (Loader personality)
• Q (Query personality)
• D (DDL personality)
• M (DML personality)
• L (Linguistic personality)

The default is QDM.

-logfile

specifies the name of a log file to which the ConText server writes all session information and errors.

-sqltrace

enables the ConText server to write to a trace file in the directory specified by the USER_DUMP_DEST initialization parameter.

Before you specify -sqltrace for ctxsrv or ctxsrvx, you should specify a value for USER_DUMP_DEST in your initsid.ora file.

Examples

The following example starts a linguistically-disabled ConText server with a Query and DDL personality mask and writes all server messages to a file named ctx.log:

ctxsrvx -user ctxsys/ctxsys -personality QD -log ctx.log &




Note:


In this example, the server is run as a background process in a UNIX-based environment. This is useful if you need to use the window/screen from which you started the server for other tasks.
  

The following example starts a linguistically-enabled ConText server with a Linguistic personality and writes all server messages to a file named ctx.log. Because -user is not specified, ConText prompts you to enter a user:

ctxsrv -personality L -log ctx.log

...
ConText: Release 2.0.6.0.0 - Production on Sat Jun  7 14:06:26 1997
...
Copyright (c) Oracle Corporation 1979, 1996.  All rights reserved.
...
Enter user:

At the prompt, enter 'CTXSYS/password', where password is the password assigned to the CTXSYS user.

ctxsrv -personality L -log ctx.log < pword.txt

ctxctl Utility

The ctxctl utility is a shell script that can be used to start up and shut down ConText servers on the system from which you run ctxctl. It can also be used to check the status of all the ConText servers currently running on the system.

Syntax

To start ctxctl, at the operating system prompt, type:

ctxctl

Once ctxctl is running, you can issue the following commands from the ctxctl command prompt:

help [command]

Provides online help for the specified command. If called without a command, it provides a list of all the commands you can use in ctxctl.

status

Provides a list of all the ConText servers and their personality masks currently running on the server host.

start n [load query ddl dml ling]

Starts n number of servers, each with the personalities specified. The personalities can be typed in any order, but must be typed in lowercase and exactly as they are named (e.g. load, query, ddl, dml, ling).

If you do not specify a personality, ctxctl starts the specified number of servers, each with the query, ddl, and dml personalities.

The first time you type the start command for a ctxctl session, ConText prompts you to enter the password for the ConText administrator (CTXSYS). After you enter the password, ConText starts the specified number of servers

stop pid | all

Shuts down the ConText server identified by pid or shuts down all ConText servers (all).

The status command can be used to obtain the pid for all currently running ConText servers.

quit | exit

Terminates ctxctl and returns you to the command-line of the host machine.

Examples

The following example starts two ConText servers, each with a DML, DDL, and Query personality mask:

command> start 2 query dml ddl

The following example shuts down a ConText server with a pid of 230454:

command> stop 23054

ctxload Utility

The ctxload utility can be used to perform the following operations:

• Text Loading
• Thesaurus Importing and Exporting

Text Loading

Use ctxload to load text from a load file into a LONG or LONG RAW column in a table.

A load file is an ASCII flat file that contains the plain text, as well as any structured data (title, author, date, etc.), for documents to be stored in a text table; however, in place of the text for each document, the load file can store a pointer to a separate file that holds the actual text (formatted or plain) of the document.

The ctxload utility creates one row in the table for each document identified by a header in the load file.

Thesaurus Importing and Exporting

Use ctxload to load a thesaurus from an import file into the ConText thesaurus tables.

An import file is an ASCII flat file that contains an entry for each synonym, broader term, and narrower term which can be used to expand queries.

ctxload can also be used to export a thesaurus by dumping the contents of the thesaurus into a flat file.

Syntax

The syntax for running ctxload is:

ctxload -user username[/password][@sqlnet_address]
        -name object_name
        -file file_name
       [-thes]
       [-thesdump]
       [-separate]
       [-longsize n]
       [-date date_mask]
       [-log file_name]
       [-trace]
       [-commitafter n]
       [-verbose]

Mandatory Arguments

-user

Specifies the username and password of the user running ctxload.

The username and password can be followed immediately by @sqlnet_address to permit logon to remote databases. The value for sqlnet_address is a database connect string. If the TWO_TASK environment variable is set to a remote database, you do not have to specify a value for sqlnet_address to connect to the database.

-name

If ctxload is being used to load text, -name specifies the name of the table to be loaded. The table must be accessible to the user specified in the command-line.

If ctxload is being used to import a thesaurus, -name specifies the name of the thesaurus to be imported. The thesaurus name is used to specify the thesaurus to be used for expanding query terms in queries.

If ctxload is being used to export a thesaurus, -name specifies the name of the thesaurus to be exported.

If a thesaurus is being loaded, -file specifies the name of the import file which contains the thesaurus entries.

If a thesaurus is being exported, -file specifies the name of the export file created by ctxload.

Optional Arguments

-thes

Specifies that ctxload imports a thesaurus. The file from which it loads the thesaurus is specified by the -file argument. The name of the thesaurus to be imported is specified by the -name argument.

-thesdump

Specifies that ctxload exports a thesaurus. The name of the thesaurus to be exported is specified by the -name argument. The file into which the thesaurus is dumped is specified by the -file argument.

-separate

For text loading, specifies that the text of each document in the load file is actually a pointer to a separate text file. During processing, ctxload loads the contents of each text file into the LONG or LONG RAW column for the specified row.

-longsize

For text loading, specifies the maximum number of kilobytes to be loaded into the LONG or LONG RAW column. This argument may be necessary for loading separate data and to help reduce memory usage when loading smaller embedded data.

The minimum value is 1 (Kb, i.e. 1024 bytes) and the maximum value is machine-dependent. The default is 64 (Kb).

-date

Specifies the TO_CHAR date format for any date columns loaded using ctxload.

-log

Specifies the name of the log file to which ctxload writes any national-language supported (NLS) messages generated during processing. If you do not specify a log file name, the messages appear on the standard output.

-trace

Specifies that a server process trace file is enabled using 'ALTER SESSION SET SQL_TRACE TRUE'. This command captures all processed SQL statements in a trace file, which can be used for debugging purposes. The location of the trace file is operating-system dependent and may be modified using the USER_DUMP_DEST initialization parameter.

-commitafter

Specifies the number of rows (documents) that are inserted into the table before a commit is issued to the database. The default is 1.

-verbose

Specifies that non-NLS messages can appear on standard output.

Usage Notes

The following conditions apply to the command-line syntax:

• if you do not specify -thes or -thesdump, by default ctxload loads text into the specified table.
• for text loading, you do not need to specify a column name because ctxload automatically loads text to the LONG or LONG RAW column in a table and a table can contain only one such column
• if you use embedded text instead of separate file pointers in the text load file, do not use the -separate option
• loading text from separate files (using the -separate option) is faster, in general, than loading text embedded in the load file

Text Load Example

The following example loads documents from the reviews.txt load file into table docs for user jsmith. It also writes log information to a file called log2.out. Because -commitafter was not specified, each row (document) is committed to the database after it is inserted into the docs table.

Also, because -separate was not specified, ctxload expects the text for each document to be embedded in the reviews.txt file.

ctxload -user jsmith/123abc -name docs -file 	review.txt -log log2.out

Thesaurus Import Example

The following example imports a thesaurus named tech_doc from an import file named tech_thesaurus.txt:

ctxload -user jsmith/123abc -thes -name tech_doc -file 	tech_thesaurus.txt

Thesaurus Export Example

The following example dumps the contents of a thesaurus named tech_doc into a file named tech_thesaurus.out:

ctxload -user jsmith/123abc -thesdump -name tech_doc -file tech_thesaurus.out

Structure of Text Load File

The load file must use the following format for each document, as well as any structured data associated with the document:

<TEXTSTART: col_name1=doc_data, col_name2=doc_data,...col_nameN=doc_data>
text. . . 
<TEXTEND>

where:

<TEXTSTART: ... >

is a header marker that indicates the beginning of a document. It also may contain one or more of the following fields used to specify structured data for a document:

col_name

is the name of a column that will store structured data for the document.

doc_data

is the structured data that will be stored in the column specified in col_name.

text

is the text of the document to be loaded or the name (and location, if necessary) of an operating system file containing the text to be loaded.

<TEXTEND>

indicates the end of the document.

Load File Structure

The following conditions apply to the structure of the load file:

• for each document to be loaded, either the text of the document or a pointer to a separate file must be in the load file.
• embedded text and separate file pointers cannot be used together in the same load file
• if the text for your documents is embedded in the load file, the text must be in ASCII format
• if pointers to separate files are used, the text in the files can be in plain (ASCII) format or a proprietary format (e.g. MS Word)
• if the text in a separate file is in a proprietary format, the format must be supported by ConText and it must be loaded into a LONG RAW column
• each separate file must contain a single document (the contents of a separate file are stored as a single row in the table)

Load File Syntax

The following conditions apply to the syntax utilized in the text load file:

• <TEXTSTART: ... > and <TEXTEND> must each start on a new line
• the structured data parameters within the <TEXTSTART: ... > string do not have to be in any particular order
• a newline character (either hard or soft return) cannot occur between a col_name and the beginning of its associated doc_data

  Note: The entire value for doc_data does not have to be on the same line as the col_name; only the beginning of the value and the col_name must share the same line.

• the first col_name should be on the same line as the 'TEXTSTART:'
• the '>' character which indicates the end of the <TEXTSTART: ... > string must be on the same line as the last doc_data field for the document
• structured and LONG data may span more than one line
• single quote-marks must be escaped in doc_data (e.g. don't must be entered as don''t)
• each <TEXTSTART: ... > string must be followed by the text of a document or a pointer to a separate file
• the text or file pointer must be placed after the complete <TEXTSTART: ... > string and should start on a new line
• the last character in the load file should be a newline character

Example of Embedded Text in Load File

The following example illustrates a correctly formatted text load file containing structured employee information, such as employee number (1000, 1024) and name (Joe Smith, Mary Jones), and the text for each document, which, in this case, is resume:

<TEXTSTART: EMPNO=1000, ELNAME='Smith', EFNAME='Joe'>
Joe has an interesting resume, includes...cliff-diving.
<TEXTEND>
<TEXTSTART: EMPNO=1024, EFNAME='Mary', ELNAME='Jones'>
Mary has many excellent skills, including...technical,
marketing, and organizational.  Team player.
<TEXTEND>

Example of File Name Pointers in Load File

The following example illustrates a correctly formatted text load file containing structured employee information, such as employee number (1000, 1024) and name (Joe Smith, Mary Jones), and a file name pointer for each document.

<TEXTSTART: EMPNO=1024, EFNAME='Mary', ELNAME='Jones'>
mjones.doc
<TEXTEND>
<TEXTSTART: EMPNO=1000, EFNAME='Joe', EFNAME='Smith'>
jsmith.doc
<TEXTEND>




Note:


To use the load file in this example, you would have to specify the -separate argument when executing ctxload.
  

Structure of Thesaurus Import File

The import file must use the following format for the entries in the thesaurus:

phrase
BT broader_term
NT narrower_term1
NT narrower_term2
. . .
NT narrower_termN
BTG broader_term
NTG narrower_term1
NTG narrower_term2
. . .
NTG narrower_termN
BTP broader_term
NTP narrower_term1
NTP narrower_term2
. . .
NTP narrower_termN
SYN synonym2
SYN synonym2
. . .
SYN synonymN
USE synonym1
RT related_term1
RT related_term2
. . .
RN related_termN
SN text

where:

phrase

is a word or phrase that is defined as having synonyms, broader terms, narrower terms, and/or related terms.

BT, BTG, BTP, NT, NTG, NTP

are markers that indicate the relationship between the phrase and its broader (generic|partitive) terms and narrower (generic|partitive) terms.

If an entry does not have a broader (generic|partitive) term, but has one or more narrower (generic|partitive) terms, the entry is created as a top term.

SYN, USE

are markers that indicate the relationship between the phrase and its synonyms (SYN), as well as the preferred synonym (USE) for the phrase.

RT

is the marker that indicates the relationship between phrase and its related terms.

SN

is the marker that indicates the following text is a scope note (i.e. comment) for the preceding entry.

broader_term

is a word or phrase that conceptually provides a more general description or category for phrase. For example, the word elephant could have a broader term of land mammal.

narrower_term

is a word or phrase that conceptually provides a more specific description for phrase. For example, the word elephant could have a narrower terms of indian elephant and african elephant.

synonym

is a word or phrase that has the same meaning for phrase. For example, the word elephant could have a synonym of pachyderm.

related_term

is a word or phrase that has a meaning related to, but not necessarily synonymous with phrase. For example, the word elephant could have a related term of wooly mammoth.

Import File Structure for Terms

The following conditions apply to the structure of the entries in the import file:

• each entry (phrase, BT, NT, or SYN) must be on a single line followed by a newline character
• entries can consist of a single word or phrases
• the maximum length of an entry (phrase, BT, NT, or SYN) is 255 characters, not including the BT, NT, and SYN markers or the newline characters
• entries cannot contain parentheses or plus signs.
• each line of the file that does not start with the BT, NT, and SYN markers indicates a phrase
• a phrase can occur more than once in the file
• each phrase can have one or more narrower term entries (NT, NTG, NTP), broader term entries (BT, BTG, BTP), synonym entries, and related term entries
• each broader term, narrower term, synonym, and preferred term entry must start with the appropriate marker and the markers must be in capital letters
• the broader terms, narrower terms, and synonyms for a phrase can be in any order
• holographs must be followed by parenthetical disambiguators everywhere they are used

  For example: cranes (birds), cranes (lifting equipment)

• compound terms are signified by a plus sign between each factor (e.g. buildings + construction)
• compound terms are allowed only as synonyms or preferred terms for other terms -- never as terms by themselves, or in hierarchical relations.
• terms can be followed by a scope note (SN), total maximum length of 2000 characters, on subsequent lines
• multi-line scope notes are allowed, but require an SN marker on each line of the note

  Example of Incorrect SN usage:

  VIEW CAMERAS
  SN Cameras with through-the lens focusing and a
  range of movements of the lens plane relative to
  the film plane
  
  
  

  Example of Correct SN usage:

  VIEW CAMERAS
  SN Cameras with through-the lens focusing and a
  SN range of movements of the lens plane relative
  SN to the film plane
  
  
  

• Multi-word terms cannot start with reserved words (e.g. use is a reserved word, so use other door is not an allowed term; however, use is an allowed term)

Import File Structure for Relationships

The following conditions apply to the relationships defined for the entries in the import file:

• related term entries must follow a phrase or another related term entry
• related term entries start with the RT marker, followed by white space, then the related term on the same line
• multiple related terms require multiple RT markers

  Example of incorrect RT usage:

  MOVING PICTURE CAMERAS
  NT CINE CAMERAS 
  TELEVISION CAMERAS
  
  

  Example of correct RT usage:

  MOVING PICTURE CAMERAS
  RT CINE CAMERAS
  RT TELEVISION CAMERAS
  
  

• Terms are allowed to have multiple broader terms, narrower terms, and related terms

Example 1 of Import File

The following example illustrates a correctly formatted thesaurus import file:

cat
SYN feline
cat
NT domestic cat
NT wild cat
BT mammal
mammal
BT animal
domestic cat
NT persian cat
NT siamese cat
wild cat
NT bengal tiger
dog
BT mammal
NT domestic dog
NT wild dog
SYN canine

Example 2 of Import File

The following example illustrates a correctly formatted thesaurus import file:

35MM CAMERAS
BT MINIATURE CAMERAS
CAMERAS
BT OPTICAL EQUIPMENT
NT MOVING PICTURE CAMERAS
NT STEREO CAMERAS
LAND CAMERAS
USE VIEW CAMERAS
VIEW CAMERAS
SN Cameras with through-the lens focusing and a range of 
SN movements of the lens plane relative to the film plane
UF LAND CAMERAS
BT STILL CAMERAS

Loading Text into External Data Store Columns

The ctxload utility is best suited for loading text into columns that utilize the direct data store for storing text. However, if you use the external data store (i.e. in your text column, you store pointers to documents in your file system), you can use ctxload to load the file pointers.

To use ctxload with external data store columns, the following conditions must exist:

• the column that you are using to store the file pointers is a LONG column
• each file pointer is embedded in the load file as the text of the document; however do not use the -separate option in the ctxload command-line.

For example:

<TEXTSTART: EMPNO=1010, ENAME='Mary Jones'>
mjones.pdf
<TEXTEND>

In this example, the file name mjones.pdf will be loaded into the LONG column for the table and the structured employee information, such as employee number (1010) and name (Mary Jones), will be loaded into the specified columns.