Oracle Context Option Administrator's Guide

Library

Product

Contents

Index

CHAPTER 8. Executables and Utilities

ctxsrv/ctxsrvx Executables
ctxctl Utility
ctxload Utility

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

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/ctxsrvx for each ConText server that you want to start.

Note: ctxsrv and ctxsrvx can only be executed by the Oracle user, CTXSYS. The CTXSYS user is created automatically during installation of ConText Option.

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.

Note: A ConText server started by ctxsrvx will process all requests, except requests for Linguistic Services (document themes or Gists). If you want to process requests for Linguistic Services, use ctxsrv.

In addition, if you want to generate theme indexes or perform theme queries, do not use ctxsrvx to start ConText server processes.

You can also use the ctxctl utility to start and shut down ConText servers. For more information about ctxctl, see "ctxctl Utility" in this chapter.

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, you do not have to specify a value for sqlnet_address to connect to a remote 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 (create and drop indexes)
M DML personality (update text table)
L Linguistic personality

The default is QDM.

Note: Oracle does not recommend assigning all the personalities to a single ConText server. This will result in the server bearing the majority of the processing load.

In addition, If you choose to execute ctxsrvx, do not specify a Linguistic personality in the command-line. If you do, the ConText server will start up; however, it will not process requests for the Linguistic Services.

-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.

Example

The following example starts a ConText server with the Query and DDL personality mask, with messages logged to a file named ctx.log.

	ctxsrv -user ctxsys/ctxsys -personality QD -log ctx.log

ctxctl Utility

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

Note: If both of the ctxsrv and ctxsrvx executables are available, the ctxctl utility starts ConText servers using the ctxsrvx executable. If both executables are available and you want to start up a ConText server using ctxsrv, you must call ctxsrv directly from the host machine command-line.

Syntax

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

	ctxctl

Once ctxctl is running, you can issue the following commands from the ctxctl 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.

Note: The ConText servers listed in the status output may be connected to different database instances.

start n loader query ddl dml linguistic

Starts n number of servers, each with all the personalities specified. The personalities can be typed in any order.

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

		start 2 linguistic dml ddl

Note: The ConText server(s) will be started on the host machine from which the start command is issued.

stop pid

Shuts down the ConText server identified by pid. The status command provides the pid for all currently running ConText servers.

quit|exit

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

ctxload Utility

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

batch loading of text

importing and exporting thesauri for use in queries

Text Loading

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

Suggestion: If the target table does not contain a LONG or LONG RAW column or you do not want to load text into a LONG or LONG RAW column, you may want to use SQL*Loader to populate the table with text.

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.

Note: The ctxload utility does not support load files that contain both embedded text and file pointers. You must use one method or the other when creating a load file.

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

For more information about creating a load file for text loading, see "Structure of Text Load File" in this chapter.

Thesaurus Importing and Exporting

Use ctxload to load a thesaurus from an import file into the ConText Option 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.

For more information about creating an import file for thesaurus importing, see "Structure of Thesaurus Import File" in this chapter.

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.

-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.

Note: Thesaurus name must be unique. If the name specified for the thesaurus is identical to an existing thesaurus, ctxload returns an error and does not overwrite the existing thesaurus.

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

-file

If text is being loaded, -file specifies the name of the load file which contains the document header markers, structured data, and embedded long data (text) or filename pointers (see the -separate argument).

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

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

Note: If the name specified for the thesaurus dump file is identical to an existing file, ctxload overwrites the existing file.

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 (document).

-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).

Note: The value for -longsize must be entered as a numeric value. Do not include a 'K' or 'k' to indicate Kilobytes.

-date

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

For more information about the available date format models, see Oracle7 Server SQL Reference.

-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.dmp.

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

Structure of Text Load File

The load file must use the following format for each document and 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.

TEXT

is the actual text of the document or a pointer to a separate file containing the text.

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 Option and it must be loaded into a LONG RAW column

Tiles, Tile Attributes, and Attribute Values

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 comments.

	<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 Filename Pointers in Load File

	<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.

Using ctxload with 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.

Suggestion: Because a LONG column is an inefficient means of storing file pointers, you probably do not want to use ctxload to load file pointers into columns that use the external data store. You may want to consider using SQL*Loader to load the file pointers instead.

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.

Note: In compliance with ISO-2788 standards, a TT marker can be placed before a phrase to indicate that the phrase is the top term in a hierarchy; however, the TT marker is not required. In fact, ctxload ignores TT markers during import.

In ConText Option, a top term is identified as any phrase that does not have a broader term (BT, BTG, BTP).

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.

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

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

broader_term

is a word or phrase that conceptually provides a more general description or category (broader term) for phrase.

For example, the word elephant may have a broader term of land mammal.

narrower_term

is a word or phrase that conceptually provides a more specific description (narrower term) for phrase.

For example, the word elephant may have a narrower terms of indian elephant and african elephant.

synonym

is a word or phrase that has the same meaning (synonym) for phrase.

For example, the word elephant may 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 may have a related term of wooly mammoth.

Note that related terms are not transitive. If a phrase has two or more related terms, the terms are related only to the parent phrase and not to each other.

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

INCORRECT:

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

CORRECT:

		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 whitespace, then the related term on the same line

multiple related terms require multiple RT markers

INCORRECT:

			MOVING PICTURE CAMERAS
				NT CINE CAMERAS 
 				TELEVISION CAMERAS

CORRECT:

			MOVING PICTURE CAMERAS
				NT CINE CAMERAS
				NT 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

Prev Next

Library

Product

Contents

Index