The FN$DCL and FN$SPAWN functions are disabled by default for users in captive accounts.

You can change this default and allow use of the FN$DCL and FN$SPAWN functions from captive accounts by using the logical name DTR$CAPTIVE_ALLOWED. Before you invoke Datatrieve, use the DCL ASSIGN or DEFINE command to define or assign the logical name DTR$CAPTIVE_ALLOWED to be either FN$DCL, FN$SPAWN, or both.

$ DEFINE DTR$CAPTIVE_ALLOWED FN$DCL
$ DEFINE DTR$CAPTIVE_ALLOWED FN$SPAWN
$ DEFINE DTR$CAPTIVE_ALLOWED FN$DCL, FN$SPAWN

You can type FN$DCL and FN$SPAWN in either uppercase or lowercase; the translation is not case sensitive. If you define DTR$CAPTIVE_ALLOWED to be both FN$DCL and FN$SPAWN and use quotation marks in the definition or assignment, you must use a set of quotation marks for each function and separate them with a comma:

$ DEFINE DTR$CAPTIVE_ALLOWED "FN$DCL", "FN$SPAWN"

As Datatrieve checks the value of DTR$CAPTIVE_ALLOWED during startup, you cannot change the definition of DTR$CAPTIVE_ALLOWED from within Datatrieve using the function FN$CREATE_LOG.

If the translation of DTR$CAPTIVE_ALLOWED is not valid, Datatrieve continues as if the logical name were not defined, but does not issue a message notifying you that it is ignoring the logical name.

If your application allows users to enter commands at the DTR> prompt and you define DTR$CAPTIVE_ALLOWED as FN$DCL, be aware that users can spawn a process by entering SPAWN with the FN$DCL function:

DTR> FN$DCL ("SPAWN")
$

You can allow a captive account to use the FN$DCL function to access DCL commands other than the DCL SPAWN command. To exclude SPAWN, set the AUTHORIZE parameter PRCLM to a value of 1 for the captive account.

You cannot use FN$DCL in a DECwindows environment unless you have invoked Datatrieve from the DCL command line in a DECterm window.

If you use FN$DCL in a Datatrieve DECwindows session, the subprocess is spawned to the DECterm window from which you invoked Datatrieve.

The subprocess displays any output generated by the DCL command included as the argument to the FN$DCL function. This output appears in the DECterm window. To see the output, you may want to move the DECterm window from back to front. When the subprocess is complete, the DTR> prompt in the main application window is reactivated.

The first parameter is the name of the key whose definition you want to delete.

The second parameter is the state string. You must specify the state name DEFAULT when there is no alternate state.

APPLICATION specifies application keypad mode.

NUMERIC specifies numeric keypad mode.

The first parameter specifies the keypad key name.

The second parameter is the state string. You must specify the state name DEFAULT when there is no alternate state.

Use FN$SPAWN as a single and complete Datatrieve statement. Do not use this function within another simple or compound statement (unlike other functions).

The FN$SPAWN function inherits attributes from the caller (the main Datatrieve process it spawned from). Refer to the VSI OpenVMS RTL Library (LIB$) Manual for more information.

The FN$DCL and FN$SPAWN functions are disabled by default for users in captive accounts.

You can change this default and allow use of the FN$DCL and FN$SPAWN functions from captive accounts by using the logical name DTR$CAPTIVE_ALLOWED. Before you invoke Datatrieve, use the DCL ASSIGN or DEFINE command to define or assign the logical name DTR$CAPTIVE_ALLOWED to be either FN$DCL, FN$SPAWN, or both.

$ DEFINE DTR$CAPTIVE_ALLOWED FN$DCL
$ DEFINE DTR$CAPTIVE_ALLOWED FN$SPAWN
$ DEFINE DTR$CAPTIVE_ALLOWED FN$DCL, FN$SPAWN

You can type FN$DCL and FN$SPAWN in either uppercase or lowercase; the translation is not case sensitive. If you define DTR$CAPTIVE_ALLOWED to be both FN$DCL and FN$SPAWN and use quotation marks in the definition or assignment, you must use a set of quotation marks for each function and separate them with a comma:

$ DEFINE DTR$CAPTIVE_ALLOWED "FN$DCL", "FN$SPAWN"

Since Datatrieve checks the value of DTR$CAPTIVE_ALLOWED during startup, you cannot change the definition of DTR$CAPTIVE_ALLOWED from within Datatrieve using the function FN$CREATE_LOG.

If the translation of DTR$CAPTIVE_ALLOWED is not valid, Datatrieve continues as if the logical name were not defined, but does not issue a message notifying you that it is ignoring the logical name.

If your application allows users to enter commands at the DTR> prompt and you define DTR$CAPTIVE_ALLOWED as FN$DCL, be aware that users can spawn a process by entering SPAWN with the FN$DCL function:

DTR> FN$DCL ("SPAWN")
$

You can allow a captive account to use the FN$DCL function to access DCL commands other than the DCL SPAWN command. To exclude SPAWN, set the AUTHORIZE parameter PRCLM to a value of 1 for the captive account.

You cannot use FN$SPAWN in a DECwindows environment unless you have invoked Datatrieve from the DCL command line in a DECterm window.

If you use FN$SPAWN during a Datatrieve DECwindows session, the subprocess is spawned to the DECterm window from which you invoked Datatrieve.

You must input any commands to your FN$SPAWN process from the DCL prompt of the DECterm window. When you have completed your subprocess, enter the LOGOUT command at the DCL prompt to return control to your Datatrieve session.

A character string

An ordinal number of starting character (numerical position within string)

The length of desired substring

To invoke a procedure, you must have P (PASS_THRU), S (SEE), and E (DTR EXECUTE/EXTEND) access to it.

You cannot invoke a procedure during an ADT, EDIT, or Guide Mode session.

You cannot include the invocation of a procedure in the definition of a domain, record, or table.

Do not allow a procedure to invoke itself, either directly or indirectly; you may create an infinite loop.

If the procedure contains any commands, you cannot include an invocation of the procedure within a BEGIN-END block.

If the procedure consists of full commands or statements, Datatrieve executes each command or statement in the procedure in order.

If the procedure contains only a clause or an argument from a command or statement, Datatrieve includes the procedure within the command or statement containing the procedure invocation.

You can use either a colon (:) or EXECUTE before the procedure name. The results are the same.

You can nest procedures by invoking a procedure within another procedure, but you must be careful not to allow the procedure to invoke itself.

You can invoke a procedure in a REPEAT statement to execute it a number of times or in a FOR statement to apply it to a collection of records. You must, however, use care when invoking a procedure in these statements. For example, the following syntax can be used, but the results may be unexpected:

REPEAT n :procedure-name

This statement does not execute the procedure n times. When Datatrieve encounters the first complete statement in the procedure, it assumes that the REPEAT statement is also complete. Therefore, it executes the first command or statement in the procedure n times. Datatrieve then executes the remaining commands or statements in the procedure once.

To repeat the entire procedure n times, enclose the procedure invocation in a BEGIN-END block:

REPEAT n
    BEGIN
      :procedure-name
    END

Use a similar technique for procedure invocations controlled by a FOR loop. For example:

FOR rse
    BEGIN
       :procedure-name
    END

Remember that if you use a procedure in this way, it cannot include a FIND, SELECT, or DROP statement because these statements cannot be used in BEGIN-END blocks.

When you invoke a command file, it must be on a line by itself.

You cannot invoke command files while you are using the Application Design Tool (ADT) or Guide Mode.

You cannot invoke a command file in a loop created by the FOR, REPEAT, or WHILE statements.

You cannot include a command file invocation within a BEGIN-END block.

Do not allow a command file to invoke itself, either directly or indirectly; you can create an infinite loop.

When you invoke a command file using the DCL DATATRIEVE command, you must use double quotation marks around the @ command and the command file. This is to prevent the operating system from interpreting the commands contained in the command file as a DCL commands.

If you do not include a file type in the file specification, Datatrieve uses a .COM file type as a default. If there is no file in the specified OpenVMS directory with a .COM file type, Datatrieve uses a .DTR file type as a default.

If the command file consists of full commands or statements, Datatrieve executes each command or statement in the command file in order.

If the command file ends with an incomplete Datatrieve command or statement, Datatrieve returns a CON> prompt, waiting for you to supply the missing elements.

You can include comments in a command file by placing an exclamation mark (!) before each comment line.

To display the lines of a command file when you invoke it, enter the SET VERIFY command either from DCL or Datatrieve command level.

If the abort occurs during an interactive session, Datatrieve stops executing the statement containing the ABORT statement and returns control to the Datatrieve command level (indicated by the DTR> prompt). The ABORT statement does not end the interactive session.

If the abort occurs in a procedure or command file, the result depends on whether SET ABORT is in effect:

If the abort occurs within a STORE or MODIFY statement, Datatrieve does not store a new record or modify the target record.

If the abort occurs during an interactive session, Datatrieve displays a message containing the value of the value expression you specify in the ABORT statement:

DTR> ABORT "Bad value for LOA."
ABORT: Bad value for LOA.
DTR> ABORT 3+2
ABORT: 5
DTR>

If you invoke Datatrieve with an invocation command line (for example, $ DTR32 @BIGJOB), the effect of an ABORT statement depends on whether SET ABORT is in effect:

When you submit a batch stream containing a Datatrieve command file, any ABORT statements in the command file behave as they would if you had entered them during an interactive session:

The Boolean expression is true and the ABORT statement is in the THEN clause.

The Boolean expression is false and the ABORT statement is in the ELSE clause.

You cannot invoke ADT from an application program using the Datatrieve Call Interface.

Do not use the ADT command in a command file.

The record definition and data file definition created by ADT do not contain all the features, clauses, and options available when using the Datatrieve DEFINE or REDEFINE commands.

The length of the domain name cannot exceed 27 characters.

See the following commands for the access privileges needed to add the domain and record definitions to the data dictionary and to define the data file for the domain: DEFINE DOMAIN, DEFINE RECORD, DEFINE FILE, and DELETE.

You cannot use ADT to create a new version of a domain or record definition.

Datatrieve invokes the Application Design Tool, which asks you a series of questions about the domain, the size and type of the fields you want in the record, and the name and type of the data file. On VT100-, VT200-, and VT300-family terminals and workstations, the current state of the record definition is displayed in the upper part of the screen or window. There is a reverse facility, enabling you to return to an earlier stage of your dialogue with ADT. See the VSI Datatrieve User Guide for additional information on ADT.

ADT gives you the option of having ADT enter your definitions immediately into the CDD/Repository data dictionary or having ADT write a command file you can invoke at a later time.

If you respond to any of ADT's questions with a Ctrl/Z, Datatrieve returns control to command level (indicated by the DTR> prompt), and displays the following message:

ADT exited by user request
DTR>

For records with ALIGNED_MAJOR_MINOR allocation and for fields with SYNCHRONIZED clauses in records with MAJOR_MINOR allocation, Datatrieve aligns fields on word boundaries. When Datatrieve shifts a field to the next word boundary, it considers the bytes it skips as part of the record. These bytes are called filler bytes.

The number of filler bytes Datatrieve inserts when MAJOR_MINOR and ALIGNED_MAJOR_MINOR are in effect depends on the data type of the field.

Fields begin on quadword boundaries if they are declared DATE, COMP_2 (or DOUBLE), and QUAD (COMP for numbers from PICTURE 9(10) to 9(18)).

Fields begin on longword boundaries if they are declared LONG (COMP for numbers from PICTURE 9(5) to 9(9)), and COMP_1 (or REAL).

Fields begin on word boundaries if they are declared WORD (COMP for numbers from PICTURE 9(1) to 9(4)).

When the allocation is either ALIGNED_MAJOR_MINOR or MAJOR_MINOR, the group field boundaries are aligned according to the maximum alignment of the elementary fields that comprise the group.

When the allocation is LEFT_RIGHT, fields begin on word boundaries if they are declared DATE, QUAD, COMP_2 (or DOUBLE), LONG, COMP_1 (or REAL), and WORD.

The ALLOCATION clause is an optional record definition clause. If you include it in your record definition, it can affect the way Datatrieve handles the internal storage and retrieval of data in some or all of the fields in your data file.

If you want to use Datatrieve on data files created with Datatrieve, you must add an ALLOCATION LEFT-RIGHT clause to the Datatrieve record definition to ensure that Datatrieve can interpret your data correctly.

An elementary field Assignment statement can be used only in a MODIFY . . . USING or STORE . . . USING statement. See the MODIFY Statement and the STORE Statement for more information.

To use an Assignment statement inside a STORE . . . USING statement, you must ready the domain for WRITE or EXTEND access. To use this statement inside a MODIFY . . . USING statement, you must ready the domain for WRITE or MODIFY access. See the READY Command for more information.

You cannot assign a value to a COMPUTED BY field.

Datatrieve stores the value of the value expression in the specified field, performing any data type conversions necessary.

If the value expression is a prompting value expression (*.prompt-name), Datatrieve prompts for the value of the field. Datatrieve rejects your input and reprompts for the value if any of the following occurs:

If the value expression is not a prompting value expression and truncation, conversion, or sign errors occur, Datatrieve accepts the value with a warning:

When using this type of Assignment statement, you may want Datatrieve to check your values for validity and give you the opportunity to recover from an error caused by invalid input. The prompting value expression, shown in the Assignment statement that follows, provides the only means for you to recover from truncation, conversion, or sign errors, or VALID IF failures. This facility is especially useful when you are creating records with the STORE . . . USING statement:

field-name = *.prompt-name

If you are unsure of the name of a field or the general type of data it contains, use the SHOW FIELDS command (see the SHOW Command). SHOW FIELDS displays a brief description of each field in a readied domain.

A group field Assignment statement can be used only in a MODIFY . . . USING or STORE . . . USING statement. See the MODIFY Statement and the STORE Statement for more information.

To use an Assignment statement in a MODIFY . . . USING statement, you must ready the domain containing group-field-1 for MODIFY or WRITE access. To use it in a STORE . . . USING statement, you must ready the domain for WRITE or EXTEND access. See the READY Command for more information.

Both group-field-1 and group-field-2 must have at least one elementary field with the same field name or query name.

You can use a variable Assignment statement anywhere a Datatrieve statement is allowed.

The variable-name must be defined with the DECLARE statement.

Datatrieve assigns the specified value to the variable.

If the value expression is a prompting value expression (*.prompt-name) Datatrieve prompts for the value of the field. Datatrieve rejects your input and reprompts for the value if any of the following occurs:

If the argument value expression is not a prompting value expression and truncation, conversion, or sign errors occur, Datatrieve accepts the value with a warning:

AT TOP OF PAGE and AT BOTTOM OF PAGE are ignored in DTIF reports.

Elements NEW_PAGE, NEW_SECTION, and REPORT_HEADER are ignored in AT statements in DTIF format.

You cannot specify the summary elements NEW_PAGE and NEW_SECTION in either an AT BOTTOM OF PAGE PRINT statement, or an AT TOP OF PAGE PRINT statement.

For relational sources, Datatrieve uses the relation's name as the top-level group field. This top-level field cannot be used in AT TOP or AT BOTTOM statements. For example, with the EMPLOYEES relational domain, you cannot use this statement:

AT BOTTOM OF EMPLOYEES PRINT EMPLOYEE_ID

You cannot use OCCURS fields from views in AT TOP OF or AT BOTTOM OF statements. Using view domain fields defined with OCCURS clauses in Report Writer AT statements causes a NODATA error message.

You cannot specify a statistical expression in an AT TOP statement unless you have already formed a current collection. Datatrieve evaluates the statistical expression based on the records in the current collection.

Under certain conditions, specifying an AT TOP OF clause may have an effect on the subsequent column positioning of the field if it is also specified in the PRINT detail line. This occurs under the following combination of circumstances:

To print the field value in the column you specify, you must explicitly suppress the header for the individual field using a hyphen in parentheses (-).

The AT BOTTOM OF field-name statement and the AT TOP OF field-name statement establish a pattern of control breaks for the entire report, dividing the report into groups of records with a common value for the field. Datatrieve displays the summary line at the bottom of the control group for which the field name is the sort key. Statistical expressions are computed for the records for the detail lines in that control group.

When you specify AT BOTTOM OF field-name PRINT field-name, the Report Writer prints the value in the specified field of the last detail line in the control group.

If you use AT BOTTOM OF field-name, Datatrieve checks the sort order of the collection or record stream you want to report. You can establish a sort order with the FIND, SORT, or REPORT statements.

If AT BOTTOM OF REPORT is included in a report specification, Datatrieve displays the header line or summary line below the detail lines on the last page of the report. Statistical expressions are computed for the records for all of the detail lines in the report.

If an AT TOP OF REPORT is included in a report specification, Datatrieve displays the header line or summary line above the detail lines on the first page of the report and suppresses the report header on the first page of the report. The report header is displayed on the following pages of the report, and the page numbers begin with Page 1 on the second physical page of the report. To specify a title page for your report, end the print list with NEW_PAGE or NEW_SECTION.

If an AT BOTTOM OF PAGE statement is included in a report specification, Datatrieve displays the header line or summary line at the bottom of each page of the report. Statistical expressions are computed for the records for the detail lines on that page.

If an AT TOP OF PAGE is included in a report specification, Datatrieve displays the header line or summary line at the top of each page of the report and replaces the report header on every page.

The header and summary elements may contain modifiers to specify edit strings or to suppress headers.

If you use AT BOTTOM OF field-name without having sorted the records, the Report Writer divides the detail lines into control groups anyway. A new control group is formed every time the value in the specified field changes. If no values in that field are repeated in consecutive detail lines, the Report Writer treats each line as a separate control group and prints the header and summary lines above and below each line as indicated in the record specification.

You may want to follow this approach in the following situation. For example, the records may already be sorted according to an indexed key field. If there is only one level of control break, the Report Writer divides the control groups at the appropriate places. However, if you want multiple levels of control groups, you must sort the records in advance with a FIND, SORT, or REPORT statement.

In table formats, AT TOP OF PAGE and AT BOTTOM OF PAGE are ignored.

You must observe all restrictions on the statements included in the BEGIN-END block. This manual lists these restrictions in the descriptions of the various statements.

Do not use FIND, SELECT, or DROP statements in a BEGIN-END block.

You cannot use Datatrieve commands in a BEGIN-END block. Consequently, a BEGIN-END block cannot include a procedure that contains Datatrieve commands.

You cannot invoke a command file in a BEGIN-END block. That is, you cannot have a line in a BEGIN-END block that contains an at sign (@) followed by a file specification. Datatrieve treats a command file invocation as a command and does not execute command files specified within a BEGIN-END block.

Within a BEGIN-END block, Datatrieve executes the statements in the order you entered them.

When the BEGIN-END block includes a DECLARE statement, the variable it defines is a local variable. You cannot refer to a local variable from outside the BEGIN-END block. Datatrieve automatically releases all local variables when it completes the BEGIN-END block in which they are defined.

If a BEGIN-END block that defines a local variable is in a FOR loop or REPEAT statement, the local variable is initialized each time Datatrieve executes the BEGIN-END block. The variable is initialized to zero, space, the DEFAULT value, or the MISSING value depending on the way you defined the variable in the DECLARE statement. See the DECLARE Statement, the DEFAULT VALUE Clause, and the MISSING VALUE Clause for more information.

When you create a single BEGIN-END block interactively, Datatrieve prompts you, after you press the Return key, for the elements needed to complete an individual statement or to complete the block. The CON> prompt indicates that Datatrieve is ready for you to continue entering statements or elements of statements into the BEGIN-END block.

After you enter END, Datatrieve executes all the statements in the BEGIN-END block. When Datatrieve completes the last statement in the BEGIN-END block, you see the DTR> prompt, indicating you have returned to Datatrieve command level. If you are entering nested BEGIN-END blocks, Datatrieve continues to prompt you with the CON> until you have entered the END that completes the outermost BEGIN-END block.

Datatrieve does not execute any of the statements in the nested blocks until you enter the END that completes the outermost BEGIN-END block.

If you enter Ctrl/C while Datatrieve is executing the statements in a BEGIN-END block, Datatrieve does not execute any of the remaining statements that follow in the block.

Datatrieve treats the whole BEGIN-END block as one statement, regardless of the number of statements or nested BEGIN-END blocks it contains. As Ctrl/C cancels the execution of the current statement, it cancels the execution of the remainder of the entire, outermost BEGIN-END block, regardless of its complexity or the number of levels of other BEGIN-END blocks nested in it.

If a statement in a BEGIN-END block prompts you for a value and you enter a Ctrl/C, Datatrieve reprompts you for the value; it does not end the execution of the BEGIN-END block. To end the execution of a BEGIN-END block when Datatrieve is prompting you for a value, enter Ctrl/C. Datatrieve then ends the execution of the outermost BEGIN-END block and returns you to Datatrieve command level.

You can use a BEGIN-END block anywhere you can use a Datatrieve statement.

You can nest BEGIN-END blocks. There is virtually no limit on the levels of nested BEGIN-END blocks you can form.

To repeat an entire sequence of Datatrieve statements, put the statements in a BEGIN-END block, and put the BEGIN-END block in a REPEAT statement.

If you invoke a procedure in a REPEAT statement (using the form REPEAT n:procedure-name), Datatrieve repeats the first statement of the procedure n times and then executes the other statements in the procedure once each.

To repeat all the statements of a procedure you invoke in a REPEAT statement, put the procedure invocation in a BEGIN-END block, and put the BEGIN-END block in the REPEAT statement.

Use a BEGIN-END block to include more than one Datatrieve statement in a FOR loop.

Use a BEGIN-END block to include more than one Datatrieve statement in the THEN and ELSE clauses in an IF-THEN-ELSE statement.

When storing or modifying records, use BEGIN-END blocks to include more than one statement in the USING and VERIFY USING clauses of the STORE and MODIFY statements.

If you write a procedure that uses consecutive PRINT statements to format your output, the line spacing changes when you put the procedure in a BEGIN-END block. The one blank line between the result of each PRINT statement disappears. To preserve that spacing when you include the procedure in a BEGIN-END block, edit the procedure and insert a SKIP print-list element at the beginning of the second and each succeeding PRINT statement.

The Datatrieve CDO command is the same as spawning a CDO command but is more efficient because no subprocess is created.

The Datatrieve SET DICTIONARY command controls the default dictionary directory setting used by the CDO command. When you enter a SET DICTIONARY command, the default dictionary used by the CDO command is also changed. However, a CDO SET DEFAULT command does not change your current Datatrieve default dictionary directory setting.

You must observe all restrictions on the statements used in the CHOICE statement. This manual lists these restrictions in the descriptions of the various statements.

Datatrieve does not evaluate view domain fields defined with an OCCURS clause when you use such fields in CHOICE statements.

Datatrieve evaluates each Boolean expression in order. When a Boolean expression evaluates to true, Datatrieve executes the corresponding statement in the THEN clause. Then Datatrieve goes on to execute the next command or statement after END_CHOICE.

If you specify an ELSE clause and all the preceding Boolean expressions evaluate to false, Datatrieve executes statement-n in the ELSE clause.

If you do not specify an ELSE clause and all the preceding Boolean expressions evaluate to false, Datatrieve does not execute any of the statements in the THEN clauses and is ready to execute the next command or statement it encounters.

This clause is valid for elementary fields only.

You cannot use an OCCURS clause or a VALID IF clause in a COMPUTED BY field.

As it does not exist in the record, you cannot assign a value to a COMPUTED BY field. STORE and MODIFY statements cannot refer to a COMPUTED BY field.

You cannot redefine a COMPUTED BY field with the REDEFINES clause.

Do not use a MISSING VALUE, PICTURE, or USAGE clause when defining a COMPUTED BY field. A COMPUTED BY field is a virtual expression, so you cannot use a clause that specifies how the value is stored.

COMPUTED BY fields are useful if you display arithmetic computations frequently. COMPUTED BY fields allow you to specify the computation once in the record definition, and then to print its value simply by referring to its field name. Generally, the computation includes the name of one or more fields in the record definition.

A COMPUTED BY field does not occupy space in a record. It exists solely in the record definition. The value of a COMPUTED BY field is calculated only when you use it in a statement.

You can use the CHOICE or IF-THEN-ELSE value expression in defining a COMPUTED BY field. This is useful if the value of the field depends on other field values.

You can use a COMPUTED BY field as a sort key in SORT and SUM statements and in the SORTED BY clause of record selection expressions. You can also use a COMPUTED BY field to form control groups in the AT TOP and AT BOTTOM statements of the Datatrieve Report Writer.

If you include a COMPUTED BY clause in a field definition, you do not have to include any other field definition clause. However, you may want to use an EDIT_STRING clause to format the computed value when it is printed.

Edit strings are not inherited from the fields that make up a COMPUTED BY value. If you want a specific representation for the COMPUTED BY field, explicitly specify an edit string for that field.

The value expression of a COMPUTED BY field in a record definition cannot refer to a list field in the same domain. To compute the value of a list field in the same domain, ready the domain containing the list field and then declare a variable outside the record definition to include the COMPUTED BY value expression.

When a COMPUTED BY field refers to a list field in another domain, you must ready the domain with the list field before you ready the domain with the COMPUTED BY field. You must finish the domains in the reverse order: the domain with the COMPUTED BY field first and the domain with the list field last.

Invoking Datatrieve with the DATATRIEVE command is particularly useful if you are working in a DECwindows environment and you want to submit a Datatrieve command procedure from a foreign command line. Normally, if your system is defined to invoke the DECwindows interface and you try to execute a Datatrieve command from a foreign command line, the Datatrieve main application window appears on your screen. By using the DCL DATATRIEVE command with the /INTERFACE=CHARACTER_CELL qualifier, you can enter the command on a foreign command line and the main application window will not be displayed.

You can abbreviate this DCL command to the shortest form that is unique among other DCL commands.

If you are not certain about the default image of Datatrieve that was installed on your system, see your system manager or the person in charge of Datatrieve on your system.

In the variable definition, you must include at least one COMPUTED BY, PICTURE (PIC), or USAGE clause to specify the data type, length, scale, and edit string of the variable.

Although you can include other field definition clauses, you cannot use an OCCURS clause or REDEFINES clause in the variable definition. A variable can have the properties of only an elementary, nonrepeating field in a Datatrieve record definition.

When you use a DECLARE statement at the Datatrieve command level, Datatrieve creates a global variable. A global variable exists until you end the Datatrieve session, until you explicitly release the variable with the RELEASE command, or until you enter a DECLARE statement for a variable of the same name.

Unless you define a global variable with a COMPUTED BY clause, the global variable retains the value you assign it until you explicitly release the variable with a RELEASE command, assign a new value to the variable, or end your Datatrieve session. The value of a global variable defined with a COMPUTED BY clause depends on the value expression that controls the computation. If the value expression is based on the value of a field in a record, the variable has a value only when there is a valid single record context in which to resolve the value expression.

When you use a DECLARE statement as part of any other Datatrieve statement, such as a BEGIN-END or THEN statement, Datatrieve creates a local variable. A local variable exists only within the statement in which it is defined. Datatrieve releases all local variables created within a statement when it encounters the end of that statement.

For example, if you define a local variable in the third BEGIN-END block in a series of four nested BEGIN-END blocks, you can refer to, assign values to, and retrieve values from the variable in the third and fourth blocks. That is, after Datatrieve executes the DECLARE statement in the third block, the value of the variable can be changed or retrieved by any of the remaining statements in the third block, including any of the statements in the fourth and innermost block. That local variable, however, has no meaning for any statement outside those two inner blocks. No statement in the first or second block and outside the two inner blocks can refer to the local variable defined in the third one.

If the statement that defines a local variable is in a FOR loop or REPEAT statement, the local variable is initialized each time Datatrieve executes the statement.

The initial value assigned to the variable by Datatrieve depends on the field definition clauses included in the DECLARE statement in which the variable was defined. Datatrieve assigns the DEFAULT value to the variable if one is defined. If no DEFAULT value is defined but a MISSING value is, Datatrieve assigns the MISSING value to the variable.

If neither a DEFAULT nor MISSING value is defined, numeric variables are initialized as zero, and alphanumeric and alphabetic variables are initialized as spaces.

To assign a value to the variable, use the following format of the Assignment statement:

variable-name = value-expression

See Chapter 1, "Value Expressions and Boolean Expressions" and the DECLARE Statement for more information on assigning values to variables.

Two SHOW commands let you display the names and types of the global variables currently defined: SHOW FIELDS and SHOW VARIABLES (see the SHOW Command for more information):

DTR> DECLARE X REAL.
DTR> DECLARE Y PIC 9(5).
DTR> DECLARE A PIC XX.
DTR> DECLARE B PIC AAA.
DTR> SHOW VARIABLES
Global variables
   X    <Number>
   Y    <Number>
   A    <Character string>
   B    <Character string>

DTR>

Use the RELEASE command (see the RELEASE Command) to remove global variables from your workspace and from the context stack:

DTR> SHOW VARIABLES
Global variables
   X    <Number>
   Y    <Number>
   A    <Character string>
   B    <Character string>

DTR> RELEASE X, A
DTR> SHOW VARIABLES
Global variables
   Y    <Number>
   B    <Character string>

DTR>

DECLARE_ATT is legal within the REPORT statement only.

DECLARE_ATT statements must precede all other statements in the report specification.

RESET is not a valid name for a DECLARE_ATT statement.

Attributes declared through DECLARE_ATT can be used in subsequent SET and PRINT statements.

If there are multiple DECLARE_ATTs with the same name, latter ones override the earlier ones.

Font size is specified in typographical points.

Text attributes are ignored when a DTIF format is chosen.

In DDIF and PS formats, all attributes are encoded.

Note that certain devices or receiving applications may not process correctly the attributes set. For example, certain terminals do not support ANSI escape sequences.

For TEXT format reports, attributes are applied through the introduction of standard ANSI escape sequences in the text file. The following table defines the applicability of text attributes to TEXT format:

There are different default text attributes for the headers (report title, column headers) and body (all other components) of the report. The default text attributes are shown in Table 4.2, ''DECLARE_ATT Print Attributes''.

You cannot invoke a procedure in a port declaration.

In the port declaration, you must include at least one PICTURE (or PIC) clause or one USAGE clause.

You cannot ready a port that is already declared. When you declare a port, Datatrieve automatically readies the port for WRITE access.

If you press the Return key before typing the semicolon, Datatrieve prompts you to continue the declaration with the CON> prompt. Datatrieve continues to prompt you with the CON> prompt until you type a semicolon and press the Return key, or until it detects a syntax error.

If you make a syntax error while entering the port declaration, Datatrieve returns to command level (indicated by the DTR> prompt) without creating the port.

If your application program declares a port at the Datatrieve command level, Datatrieve creates a port that is available to your application program until you end your access to it with the FINISH command or until you exit from your session. Such a port is a global port and, in this respect, is similar to a global variable.

If your application program declares the port at some level in a compound statement, the port is valid only for the remainder of the statement in which it is declared and for those statements contained in the statement in which it is declared. Such a port is a local port and, in this respect, is similar to a local variable.

You cannot define a synonym for the keyword CURRENT.

You cannot use the DECLARE SYNONYM command within a BEGIN-END block.

You cannot use the DECLARE SYNONYM command within a FOR loop.

You cannot define a keyword as a synonym for another keyword. For example, you cannot define PRINT as a synonym for FIND.

You cannot define the same synonym for two different keywords. For example, if you have already defined A as a synonym for ALL, you cannot define A as a synonym for AVERAGE.

You cannot use the DTR$SYNONYM file for creating synonyms for user-defined keywords (UDK). If you want to create synonyms for user-defined keywords, you can use the startup command file DTR$STARTUP.

Datatrieve interprets the synonym in exactly the same way as the keyword with which you associated it.

This synonym is in effect for the current Datatrieve session only. When you exit from Datatrieve, all the synonyms you defined with DECLARE SYNONYM are released.

Use DECLARE SYNONYM to define temporary synonyms during a particular Datatrieve session.

You can define a synonym for a user-defined keyword.

You can define a synonym for another synonym. For example:

DTR> DECLARE SYNONYM P FOR PRINT
DTR> DECLARE SYNONYM PR FOR P

Now PR is a synonym for the keyword PRINT. You can use PR, PRINT, or P interchangeably.

If you want to define synonyms that will remain in effect in future Datatrieve sessions, include the assignment of synonyms in your DTR$STARTUP command file.

You can also assign synonyms using a DTR$SYNONYM file (the DECLARE SYNONYM command replaced this method for assigning synonyms and is still the recommended method for users).

Create a file containing a list of keywords and their corresponding abbreviations. Use one keyword/abbreviation pair per line. Capitalize all keywords and definitions and leave at least one space between the keyword and the abbreviation. Assign the logical name DTR$SYNONYM to this file. When you invoke Datatrieve, it uses this file to find any synonyms you have defined. If you make an incorrect synonym file entry, Datatrieve does not produce an error message, but the synonym does not work.

When you use Assignment statements in the USING clause of a STORE statement but make no assignment to the field with the default value specified in the DEFAULT VALUE clause

When you respond either to prompts from a STORE statement without a USING clause or to prompting value expressions in the USING clause of a STORE statement and, in response to a prompt, you press the Tab key and then the Return key

Relational and Oracle DBMS database path names do not have version numbers.

To define a DMU format database you must have the following access privileges:

To define a CDO format database you must have the following access privileges:

When you define an Oracle DBMS database using Format 2, you cannot use the same path name for both the database and the schema.

For Rdb/VMS, the root file is the file specification of the database file.

All ancestors of the dictionary directory you want to create must exist.

The name you assign to the dictionary directory you want to create must not duplicate the name of any other directory or dictionary object in the parent directory.

The dictionary path name does not have a version number.

To define a DMU format dictionary directory you must have the following access privileges:

To define a CDO format dictionary directory you must have the following access privileges:

Before you define a CDO dictionary directory, you must create the dictionary through CDO. If the dictionary does not exist, you will get an error message. For example, if you enter the following command and the dictionary DISK1:[SWANSON.DTRWORK] does not exist, the DEFINE DICTIONARY command will fail:

DTR> DEFINE DICTIONARY DISK1:[SWANSON.DTRWORK]NEWDICT

Datatrieve creates an empty directory in the CDD/Repository data dictionary system. In this directory, you can place other dictionary directories and the definitions of dictionary objects.

If you do not enter the path name on the same input line as the DEFINE DICTIONARY command, Datatrieve prompts you for it with the DFN> prompt. After you enter the completed command, you return to the Datatrieve command level.

Datatrieve does not make the newly created directory your default dictionary directory. Your default dictionary directory setting is unaffected by the DEFINE DICTIONARY command, regardless of its relationship to the new directory within the data dictionary.

CDD/Repository provides the new directory with a default access control list. Two user identification criteria are supplied: a wildcarded UIC and the username of your process.

If you define the dictionary directory in the DMU format dictionary, six privileges are granted: C (CONTROL), D (LOCAL_DELETE), H (HISTORY), P (PASS_THRU), S (SEE), and X (EXTEND). No privileges are denied, and none are banished. The access privileges you have to the new directory depend on the privileges that are granted, denied, and banished by the ancestors of the new directory.

If you define the dictionary directory in the CDO format dictionary, four privileges are granted: U (CHANGE), C (CONTROL), D (DELETE), and S (SHOW).

The chapter on ACL in the VSI Datatrieve User Guide explains access control lists and the Datatrieve and CDD/Repository access privileges.

You can verify the creation of the new dictionary directory. Use the SET DICTIONARY command to make the parent of the new directory your default dictionary directory. Then enter the SHOW DICTIONARIES command. Datatrieve displays the name of the new directory along with those of any other dictionary directories cataloged in your default directory.

To change your default directory to the newly created directory, use the SET DICTIONARY command. If your current default directory is the parent of the new directory, you can specify the new directory's given name in the SET DICTIONARY command.

If your current default directory is not the parent of the new directory, you can use either the new directory's full dictionary path name or the appropriate relative path name in the SET DICTIONARY command.

Once you have changed your default directory, you can use the SHOW DICTIONARY command to display the complete dictionary path name of your new default directory.

You do not have to set your default dictionary directory to the newly created directory to define either dictionary objects or directories in that new directory. With the appropriate DEFINE command, you need only specify the full or relative dictionary path name of the directory or object you want to define.

To enter definitions of dictionary elements in a directory you create, use the following commands: DEFINE DOMAIN, DEFINE PORT, DEFINE PROCEDURE, DEFINE RECORD, DEFINE TABLE.

To create new versions of dictionary elements, use the following commands: REDEFINE DOMAIN, REDEFINE PORT, REDEFINE PROCEDURE, REDEFINE RECORD, REDEFINE TABLE (for further information, see the REDEFINE Command).

To change the access control list for a dictionary directory, use the DEFINEP command.

Use the SHOWP command to see the access control list for the new dictionary directory.

To show your access privileges to your current default dictionary directory, enter the SHOW PRIVILEGES command.