1 Commands_Statements_Clauses These topics describe all DEC DATATRIEVE commands, statements and clauses. Only formats, arguments and examples are provided in Help. For full descriptions see the DEC DATATRIEVE Reference Manual. 2 :_(EXECUTE) Invokes a DEC DATATRIEVE procedure. Format { : } { } procedure-name { EXECUTE } { } 3 Argument procedure-name Is the given name, full dictionary path name, or relative dictionary path name of the DEC DATATRIEVE procedure you want to invoke. 3 Examples The following example invokes a procedure to find the employee in PERSONNEL with the largest salary. It uses EXECUTE to invoke the procedure from the DIGITAL Command Language (DCL) level. In this example, DTR is the global symbol for invoking DEC DATATRIEVE. DTR> SHOW MAX_SALARY PROCEDURE MAX_SALARY READY PERSONNEL PRINT PERSONNEL WITH SALARY = MAX SALARY OF PERSONNEL END_PROCEDURE DTR> EXIT $ DTR EXECUTE MAX_SALARY FIRST LAST START SUP ID STATUS NAME NAME DEPT DATE SALARY ID 00012 EXPERIENCED CARLA SPIVA TOP 12-Sep-1972 $75,892 00012 $ The following example invokes a procedure three times. The procedure displays employees in a given department with salaries greater than $40,000. DTR> SHOW BIG_SALARY PROCEDURE BIG_SALARY FOR PERSONNEL WITH DEPT = *."the department" BEGIN IF SALARY GT 40000 THEN PRINT ID, NAME, DEPT,START_DATE, SALARY END END_PROCEDURE DTR> REPEAT 3 CON> BEGIN CON> :BIG_SALARY CON> END Enter the department: F11 FIRST LAST START ID NAME NAME DEPT DATE SALARY 00891 FRED HOWL F11 9-Apr-1976 $59,594 78923 LYDIA HARRISON F11 19-Jun-1979 $40,747 Enter the department: T32 38462 BILL SWAY T32 5-May-1980 $54,000 83764 JIM MEADER T32 4-Apr-1980 $41,029 Enter the department: TOP 00012 CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 DTR> The following example invokes a procedure to specify an edit string clause for a variable: DTR> DEFINE PROCEDURE E_S DFN> EDIT_STRING IS $$,$$$.99 DFN> END_PROCEDURE DTR> DECLARE PRICE_PER_FT COMPUTED BY PRICE/LOA :E_S. DTR> PRINT TYPE, PRICE_PER_FT OF FIRST 5 YACHTS PRICE PER MANUFACTURER MODEL FT ALBERG 37 MK II $998.68 ALBIN 79 $688.46 ALBIN BALLAD $916.67 ALBIN VEGA $688.89 AMERICAN 26 $380.58 DTR> 2 @_(Invoke_Command_File) Invokes a command file. Format @ file-spec 3 Argument file-spec Is the file specification for the file you want to execute. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version 3 Example The following example invokes a command file, BUILDER.COM, from DCL to produce a report on yachts by a specified builder. $ DATATRIEVE "@BUILDER" READY YACHTS REPORT YACHTS WITH BUILDER = *.BUILDER SET COLUMNS_PAGE = 70 PRINT BOAT END_REPORT Enter BUILDER: ALBIN 11-Oct-1982 Page 1 LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN 79 SLOOP 26 4,200 10 $17,900 ALBIN BALLAD SLOOP 30 7,276 10 $27,500 ALBIN VEGA SLOOP 27 5,070 08 $18,600 $ 2 ABORT_Statement Stops the execution of a single statement, an entire procedure, or a command file. Format ABORT [value-expression] 3 Argument value-expression Is a DEC DATATRIEVE value expression, usually a character string literal. 3 Examples The following example shows how to store a record in the YACHTS domain. If the value of the BEAM field is 0, the operation is aborted and a message is displayed. DTR> STORE YACHTS VERIFY USING [Looking for statement] DTR> IF BEAM EQ 0 THEN ABORT "Bad value for BEAM" Enter MANUFACTURER: AMERICAN Enter MODEL: 1980 Enter RIG: SLOOP Enter LENGTH_OVER_ALL: 25 Enter DISPLACEMENT: 7500 Enter BEAM: 0 Enter PRICE: 10000 ABORT: Bad value for BEAM DTR> The following example shows how to define a procedure to write a report on the current collection and abort the entire procedure if there is no current collection to report on. DTR> DEFINE PROCEDURE YACHT_REPORT DFN> SET ABORT DFN> PRINT "HAVE YOU ESTABLISHED A CURRENT COLLECTION?" DFN> IF *."YES or NO" CONTAINING "N" THEN DFN> ABORT "SORRY-NO COLLECTION, NO REPORT." DFN> REPORT DFN> PRINT BOAT DFN> AT BOTTOM OF REPORT PRINT COUNT, TOTAL PRICE DFN> END_REPORT DFN> END_PROCEDURE DTR> :YACHT_REPORT HAVE YOU ESTABLISHED A CURRENT COLLECTION? Enter YES or NO: NO ABORT: SORRY--NO COLLECTION, NO REPORT. DTR> In the following example, a procedure is defined to update the OWNERS domain after the sale of a boat. The boat is checked against the inventory in the YACHTS domain and the procedure is aborted if the boat is not in YACHTS. Then, the OWNERS domain is checked for a record of the boat. If a record exists, the owner's name is changed and the boat name is updated, if desired. If no record exists, a new record is stored in the OWNERS domain. The procedure requires MODIFY or WRITE access to OWNERS for the update and EXTEND or WRITE access for the entry of a new record. The example aborts because there is no YACHTS record for an ALBERG 42. The value expression specified in the ABORT statement includes the variables BLD and MOD. DTR> SHOW SALE_BOAT PROCEDURE SALE_BOAT READY YACHTS, OWNERS WRITE SET ABORT DECLARE BLD PIC X(10). DECLARE MOD PIC X(10). BLD = *."BUILDER'S NAME" MOD = *."MODEL" IF NOT ANY YACHTS WITH (BUILDER = BLD AND MODEL = MOD) THEN BEGIN PRINT SKIP, "RECORD NOT FOUND IN YACHTS.", SKIP ABORT "POSSIBLE INVENTORY ERROR FOR--"||BLD|||MOD END ELSE PRINT SKIP, "YACHTS RECORD FOUND FOR "|BLD|||MOD IF ANY OWNERS WITH (BUILDER = BLD AND MODEL = MOD) THEN BEGIN FOR OWNERS WITH (BUILDER = BLD AND MODEL = MOD) MODIFY USING BEGIN PRINT COL 10, NAME, SKIP NAME = *."NEW OWNER'S NAME" PRINT COL 10, BOAT_NAME, SKIP IF *."CHANGE BOAT NAME? Y/N" CONTAINING "Y" THEN PRINT SKIP THEN BOAT_NAME = *."NEW BOAT NAME" END END ELSE STORE OWNERS USING BEGIN NAME = *."NEW OWNER'S NAME" BOAT_NAME = *."BOAT NAME" BUILDER = BLD MODEL = MOD END END_PROCEDURE DTR> :SALE_BOAT Enter BUILDER'S NAME: ALBERG Enter MODEL: 42 RECORD NOT FOUND IN YACHTS. ABORT: POSSIBLE INVENTORY ERROR FOR--ALBERG 42 DTR> 2 ADT_Command Invokes the Application Design Tool (ADT), an interactive aid that helps you define a domain, its associated record, and its data file. Format ADT 3 Arguments None. 3 Example Invoke the Application Design Tool: DTR> ADT Do you want detailed prompts? (YES or NO) : See the Computer Based Training Package (CBT) for a sample ADT session. 2 ALLOCATION_Clause Specifies the type of word boundary alignment DEC DATATRIEVE uses when storing records in a data file associated with a record definition. It also controls the way DEC DATATRIEVE retrieves data from files created by user programs or other applications software. Format { MAJOR_MINOR } ALLOCATION [IS] { ALIGNED_MAJOR_MINOR } { LEFT_RIGHT } { } 3 Arguments MAJOR_MINOR Causes DEC DATATRIEVE to use MAJOR_MINOR alignment when storing or retrieving data in a data file. MAJOR_MINOR forces word boundary alignments according to data types for elementary fields defined with the SYNCHRONIZED clause and forces group fields to the maximum alignment of the elementary fields they contain. MAJOR_MINOR is the default for DEC DATATRIEVE. ALIGNED_MAJOR_MINOR Causes DEC DATATRIEVE to use ALIGNED_MAJOR_MINOR alignment when storing or retrieving data in a data file. ALIGNED_MAJOR_MINOR forces word boundary alignments according to data types for all elementary fields in the record and group fields to the maximum alignment of the elementary fields they contain. LEFT_RIGHT Causes DEC DATATRIEVE to use LEFT_RIGHT alignment when storing or retrieving data in a data file. LEFT_RIGHT forces word boundary alignment for elementary fields defined as COMP, COMP_1, COMP_2, and DATE. 3 Example The following example shows the use of the ALLOCATION clause with the YACHT record: DELETE YACHT; REDEFINE RECORD YACHT OPTIMIZE ALLOCATION IS LEFT_RIGHT 01 BOAT. 03 TYPE. 06 MANUFACTURER PIC X(10) QUERY_NAME IS BUILDER. 06 MODEL PIC X(10). 03 SPECIFICATIONS QUERY_NAME SPECS. 06 RIG PIC X(6) VALID IF RIG CONT "SLOOP","KETCH","MS","YAWL". 06 LENGTH_OVER_ALL PIC XXX VALID IF LOA BETWEEN 15 AND 50 QUERY_NAME IS LOA. 06 DISPLACEMENT PIC 99999 QUERY_HEADER IS "WEIGHT" EDIT_STRING IS ZZ,ZZ9 QUERY_NAME IS DISP. 06 BEAM PIC 99 MISSING VALUE IS 0. 06 PRICE PIC 99999 MISSING VALUE IS 0 VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 EDIT_STRING IS $$$,$$$. ; 2 Assignment_Statements An Assignment statement assigns a value to an elementary field, a group field, or a variable. To assign a value to an elementary field the format is: field-name = value-expression To assign a value to a group field the format is: group-field-name-1 = group-field-name-2 To assign a value to a variable the format is: variable-name = value-expression 2 AT_Clauses_ AT clauses can be used in FOR loops only. An AT TOP clause specifies that when a group starts, the statement in the AT TOP clause has to be executed before executing the main code in the FOR loop. An AT BOTTOM clause specifies that an action has to be executed after the last record of a group has been processed and before the first record in the next group. Format AT BOTTOM OF field-name [,...] statement AT TOP OF field-name [,...] statement 3 Arguments field-name Is a field from the record definition for the loop's record stream. statement Is a DATATRIEVE statement. 3 Example In the following example the first AT BOTTOM clause is ignored because it is contained in an IF statement. DTR> DECLARE VAR PIC 9. ; DTR> READY CDD$TOP.DTR$LIB.DEMO.YACHTS ; DTR> VAR = 0 ; DTR> FOR FIRST 2 YACHTS CON> BEGIN CON> IF VAR EQ 0 THEN CON> BEGIN CON> AT BOTTOM OF MODEL PRINT "Model change"; CON> END ; CON> AT BOTTOM OF BUILDER PRINT "Builder change"; CON> IF VAR GT 0 THEN CON> BEGIN CON> AT TOP OF MODEL PRINT "start model"; CON> END ; CON> PRINT MODEL , BUILDER ; CON> END ; MODEL MANUFACTURER 37 MK II ALBERG Builder change 79 ALBIN Builder change DTR> 2 AT_Statements_(Report_Writer) The Report Writer AT statements display header and summary lines at the top and bottom of the report, and at the top and bottom of pages and control groups (groups of sorted records with the same value in one or more fields). The AT TOP statement summarizes information for the entire group of records in the current collection, not the records of the page, group, or report that you specify in the statement. The AT BOTTOM statement calculates the summary information based on the records of the page, group, or report that you specify in the statement. With the two forms of the AT statement, you can specify the value, position, and format of the print objects in the header and summary lines: The AT statements accept the same types of print objects as a PRINT statement. Format { REPORT } AT BOTTOM OF { PAGE } PRINT summary-element [, ...] { field-name } { } { REPORT } { header-element } AT TOP OF { PAGE } PRINT { } [, ...] { field-name } { summary-element } { } 3 Arguments field-name Is a field from the record definition for the report's record stream or a variable. header-element Specifies the value, position, and format of the fields. 3 Examples The following example shows the use of both the AT BOTTOM and AT TOP statements: DTR> SHOW SALARY_REPORT PROCEDURE SALARY_REPORT REPORT PERSONNEL WITH DEPT = "D98","E46","T32" SORTED BY DEPT SET REPORT_NAME = "SALARY REPORT" SET COLUMNS_PAGE = 60 AT TOP OF DEPT PRINT DEPT PRINT ID, FIRST_NAME|||LAST_NAME ("NAME"), SALARY AT BOTTOM OF DEPT PRINT SKIP, COL 36, DEPT|||"TOTAL:", TOTAL SALARY USING $$$$,$$$, SKIP, COL 13, "***********************************", SKIP, COL 32, "OVERALL TOTAL:", COL 50, RUNNING TOTAL (TOTAL SALARY) USING $$$$,$$$, SKIP END_REPORT END_PROCEDURE See the DEC DATATRIEVE User's Guide for more examples of the AT TOP statement. 2 BEGIN_END_Statement Groups DEC DATATRIEVE statements into a single compound statement called a BEGIN-END block. Format BEGIN statement-1 [statement-2] . . . END 3 Arguments BEGIN Marks the beginning of a BEGIN-END block. statement Is a DEC DATATRIEVE statement. Within the BEGIN-END block, end each statement with a semicolon, a RETURN, or both. END Marks the end of the BEGIN-END block. 3 Examples The following example shows how to store five records in the domain PHONES, each having LOCATION MB1-H2 and DEPARTMENT CE. The SET NO PROMPT command suppresses the "[Looking for . . .]" prompts preceding each CON> prompt. This example also shows how DEC DATATRIEVE responds to CTRL/C and CTRL/Z when it is prompting you for input. DTR> READY PHONES WRITE DTR> SET NO PROMPT DTR> REPEAT 5 STORE PHONES USING DTR> BEGIN CON> NAME= *.NAME CON> NUMBER= *.NUMBER CON> LOCATION= "MB1-H2" CON> DEPARTMENT= "CE" CON> END Enter NAME: FRED Enter NUMBER: 555-1234 Enter NAME: GERRY Enter NUMBER: ^C Enter NUMBER: Execution terminated by operator DTR> The following example shows how to use a BEGIN-END block to put three statements in the USING clause of a MODIFY statement, print a YACHTS record, modify the price, and print the result of the modification: DTR> READY YACHTS WRITE DTR> SET NO PROMPT DTR> FOR YACHTS WITH PRICE = 0 CON> MODIFY USING CON> BEGIN CON> PRINT CON> PRICE = *."NEW PRICE" CON> PRINT CON> END LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE BLOCK I. 40 SLOOP 39 18,500 12 Enter NEW PRICE: 30000 LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE BLOCK I. 40 SLOOP 39 18,500 12 $30,000 BUCCANEER 270 SLOOP 27 5,000 08 Enter NEW PRICE: Execution terminated by operator DTR> The following example shows how a BEGIN-END block is treated as a single statement: DTR> DEFINE PROCEDURE LOOP_EXAMPLE DFN> PRINT "SHOW HOW A BEGIN-END WORKS WITH REPEAT" DFN> PRINT "AND MORE THAN ONE STATEMENT" DFN> END_PROCEDURE DTR> DTR> REPEAT 2 :LOOP_EXAMPLE SHOW HOW A BEGIN-END WORKS WITH REPEAT SHOW HOW A BEGIN-END WORKS WITH REPEAT AND MORE THAN ONE STATEMENT DTR> REPEAT 2 BEGIN :LOOP_EXAMPLE; END SHOW HOW A BEGIN-END WORKS WITH REPEAT AND MORE THAN ONE STATEMENT SHOW HOW A BEGIN-END WORKS WITH REPEAT AND MORE THAN ONE STATEMENT DTR> 2 CDO_Command Passes a command line to the Common Dictionary Operator (CDO) utility. Format CDO cdo-command-line 3 Argument cdo-command-line Is a command line to be passed to the CDO. 3 Example In the following example, a change in field definition FLD_ A causes a message to be displayed when you READY MY_DB. The message is displayed and cleared and the CLEAR NOTICES command is verified using the CDO command. DTR> CDO SHOW NOTICES MY_DB USR$DISK:[RICK.TEST]GLOBAL.MY_DB;1 is possibly invalid, triggered by CDD$DATA_ELEMENT USR$DISK:[RICK.TEST]GLOBAL.FLD_A;1 DTR> CDO CLEAR NOTICES MY_DB DTR> CDO SHOW NOTICES MY_DB %CDO-I-NOMESSAGES, USR$DISK:[RICK.TEST]GLOBAL.MY_DB;1 has no notices DTR> 2 CHOICE_Statement Causes DEC DATATRIEVE to execute one of a series of statements or compound statements, depending on the evaluation of a series of conditional (Boolean) expressions. The CHOICE statement is a convenient substitute for nested IF-THEN-ELSE statements. Format CHOICE [OF] boolean-expression-1 [THEN] statement-1 [boolean-expression-2 [THEN] statement-2] . . . . . . . . . [ELSE statement-n] END_CHOICE 3 Arguments CHOICE Marks the beginning of a CHOICE statement. OF Is an optional language element you can use to clarify syntax. boolean-expression Is a Boolean expression. THEN Is an optional language element you can use to clarify syntax. statement Is a simple or compound statement you want DEC DATATRIEVE to execute if the corresponding Boolean expression evaluates to true. ELSE statement-n Specifies the statement you want DEC DATATRIEVE to execute if all the preceding Boolean expressions evaluate to false. END_CHOICE Marks the end of the CHOICE statement. 3 Examples The following example shows how to define a procedure MODIFY_ YACHTS, prompt the user to identify a record by specifying the BUILDER and MODEL of a yacht, and print the record, prompting the user to modify a field from YACHTS. This process is continued until the user replies to a prompt that no further changes need to be made. DTR> SHOW MODIFY_YACHTS PROCEDURE MODIFY_YACHTS READY YACHTS WRITE FOR YACHTS WITH BUILDER = *."the builder" AND MODEL = *."the model" BEGIN PRINT PRINT SKIP PRINT "The fields you can modify are: RIG,LOA,DISP,BEAM,PRICE" MODIFY USING WHILE *."Y to modify a field, N to exit" CONT "Y" BEGIN DECLARE FLD PIC X(5). FLD = *."field to modify" CHOICE FLD = "RIG" THEN RIG = *.RIG FLD = "LOA" THEN LOA = *.LOA FLD = "DISP" THEN DISP = *.DISP FLD = "BEAM" THEN BEAM = *.BEAM FLD = "PRICE" THEN PRICE = *.PRICE ELSE PRINT "That's not a field in YACHTS." END_CHOICE PRINT PRINT SKIP END PRINT SKIP, "No more changes." END END_PROCEDURE DTR> :MODIFY_YACHTS Enter the builder: ALBIN Enter the model: 79 LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN 79 SLOOP 26 4,200 10 $17,900 The fields you can modify are: RIG, LOA, DISP, BEAM, PRICE Enter Y to modify a field, N to exit: Y Enter field to modify: RIG Enter RIG: KETCH LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN 79 KETCH 26 4,200 10 $17,900 Enter Y to modify a field, N to exit: Y Enter field to modify: RUG That's not a field in YACHTS. ALBIN 79 KETCH 26 4,200 10 $17,900 Enter Y to modify a field, N to exit: N No more changes. DTR> The following example shows how to print the TYPE and PRICE of the yachts by ALBERG and ALBIN, indicating whether the price is inexpensive, moderate, or expensive. Column headers are suppressed: DTR> READY YACHTS DTR> FOR YACHTS WITH BUILDER = "ALBERG" OR BUILDER = "ALBIN" CON> CHOICE CON> PRICE LT 20000 THEN PRINT TYPE(-),PRICE(-),"INEXPENSIVE" CON> PRICE LT 30000 THEN PRINT TYPE(-),PRICE(-),"MODERATE" CON> ELSE PRINT TYPE(-), PRICE(-), "EXPENSIVE" CON> END_CHOICE ALBERG 37 MK II $36,951 EXPENSIVE ALBIN 79 $17,900 INEXPENSIVE ALBIN BALLAD $27,500 MODERATE ALBIN VEGA $18,600 INEXPENSIVE DTR> 2 CLOSE_Command Closes a Record Management System (RMS) trace file you created with an OPEN command as a log for your interactive dialogue with DEC DATATRIEVE. Format CLOSE 3 Arguments None. 3 Example The following example shows a CLOSE command: DTR> CLOSE 2 COMMIT_Statement Makes permanent all the changes you made to relational and Oracle CODASYL DBMS databases since the most recent COMMIT or ROLLBACK statement or, if you have not performed a COMMIT or ROLLBACK, since the first database READY command. The COMMIT statement does not affect collections; collections are maintained. For Oracle CODASYL DBMS databases, the COMMIT statement performs a COMMIT RETAINING. For relational databases, the COMMIT statement starts a new transaction that gives you a new look at the database. When you have both relational and Oracle CODASYL DBMS databases readied, the COMMIT statement commits all Oracle CODASYL DBMS and relational databases, regardless of whether you made any changes to their data. Domains based on RMS files are not affected by the COMMIT statement. Format COMMIT 3 Arguments None. 3 Examples The following Oracle CODASYL DBMS example connects an employee named Hill to a part LA36 in the RESPONSIBLE_FOR set. The COMMIT statement makes this change permanent. DTR> FIND E IN EMPLOYEES WITH EMP_LAST_NAME = "HILL" DTR> SELECT 1 DTR> FOR P IN PART WITH PART_DESC = "LA36" CON> CONNECT P TO E.RESPONSIBLE_FOR DTR> COMMIT DTR> The following relational database example stores a record in the relation DEPARTMENTS. The COMMIT statement makes this change permanent: DTR> READY DATABASE PERSONNEL USING DEPARTMENTS WRITE DTR> STORE DEPARTMENTS Enter DEPARTMENT_CODE: SENG Enter DEPARTMENT_NAME: SOFTWARE ENGINEERING Enter MANAGER_ID: 87215 DTR> COMMIT DTR> 2 COMPUTED_BY_Clause Describes a COMPUTED BY field. Format COMPUTED BY value-expression 3 Argument value-expression Is a DEC DATATRIEVE value expression. 3 Examples In the following example, the price per pound of a yacht is computed as the price divided by the displacement. In this case, both the PRICE and DISP fields are defined in the record definition. 06 PRICE_PER_POUND EDIT_STRING $$$,$$9.99 COMPUTED BY PRICE/DISP. When the PRICE_PER_POUND field is used in a command or statement, DEC DATATRIEVE divides the value of the record's PRICE field by the value of its DISP field. The result of the computation is the value of the PRICE_PER_POUND field. In the following example, the discount price of a yacht is computed. The amount of the discount varies with the price of a yacht. The field PRICE is defined in the record definition for YACHTS: 06 DISCOUNT_PRICE COMPUTED BY CHOICE PRICE LT 20000 THEN (PRICE * .9) PRICE LT 30000 THEN (PRICE * .8) PRICE LT 40000 THEN (PRICE * .7) ELSE (PRICE * .6) END_CHOICE EDIT_STRING IS $$$,$$$. When DISCOUNT_PRICE is used in a command or statement, DEC DATATRIEVE evaluates each Boolean expression in order until one evaluates to true. Then it performs the corresponding computation on PRICE. In the following example, the value of the SALESFORCE field is derived from a dictionary or domain table named SALES_TABLE: 06 SALESFORCE EDIT_STRING IS X(20) COMPUTED BY MANUFACTURER VIA SALES_TABLE. In this example, DEC DATATRIEVE uses the value of the MANUFACTURER field in the current record to search the dictionary or domain table SALES_TABLE for a matching code. If one is found, DEC DATATRIEVE uses its translation as the value of the SALESFORCE field. 2 CONNECT_Statement Makes explicit connections between a record and the Oracle CODASYL DBMS sets you specify in the TO list. Before establishing the connections, DEC DATATRIEVE sets up a currency indicator for each set specified in the TO list. Format CONNECT context-name-1 [TO] {[context-name-2.] set-name-1} [,...] 3 Arguments context-name-1 Is the name of a valid context variable or the name of a collection with a selected record. It must identify a record occurrence of a domain with a record type that participates in the specified set type. That record must not be a member of the sets specified by the TO list, but its record type must be a valid member type in the specified set types. context-name-2 Is the name of a valid context variable or the name of a collection with a selected record. It must identify a record that participates in the specified set. If the SYSTEM owns the set, you do not need to establish a context for the set. If the set is not owned by the SYSTEM and the context name is not present, DEC DATATRIEVE uses the most recent single record context of a domain with a record type that participates in the specified set type. set-name Is the name of a set type. 3 Example The following example connects an employee named Hill to a part LA36 in the RESPONSIBLE_FOR set. P and E in the following example are context names. E refers to a collection with a selected record and P to a record stream. The records in these contexts are all owner records or member records in the set. DTR> FIND E IN EMPLOYEES WITH EMP_LAST_NAME = "HILL" DTR> SELECT 1 DTR> FOR P IN PART WITH PART_DESC = "LA36" CON> CONNECT P TO E.RESPONSIBLE_FOR DTR> 2 CROSS_Clause You use the CROSS clause to perform the following tasks: o Compare records from one domain or collection o Combine records from two or more domains or collections o Flatten hierarchical domains to ease access to the list items Format CROSS [context-variable IN] rse-source [OVER field-name] [...] 3 Arguments context-variable Is the name of a valid context variable. A context variable is a temporary name that identifies a record stream to DEC DATATRIEVE. rse-source Is the record selection expression (RSE) that identifies the records you want to work with. field-name Is a field whose values form the basis for the cross operation. 3 Example The following query uses one RSE that includes five out of the six optional elements of an RSE. DEC DATATRIEVE processes the query far faster than if nested FOR loops were used: DTR> DEFINE PROCEDURE CROS DFN> READY YACHTS DFN> PRINT BUILDER, RIG, A.RIG OF DFN> A IN YACHTS CROSS YACHTS OVER BUILDER WITH DFN> RIG GT A.RIG REDUCED TO BUILDER, RIG, A.RIG DFN> END_PROCEDURE DTR> :CROS MANUFACTURER RIG RIG AMERICAN SLOOP MS CHALLENGER SLOOP KETCH GRAMPIAN SLOOP KETCH IRWIN SLOOP KETCH ISLANDER SLOOP KETCH NORTHERN SLOOP KETCH PEARSON SLOOP KETCH DTR> 2 DATATRIEVE_Command The DCL command DATATRIEVE starts a DEC DATATRIEVE session. This DCL command lets you specify several optional qualifiers that let you customize your DEC DATATRIEVE session. Format [ {DECWINDOWS } ] [ /INTERFACE= { } ] DATATRIEVE [ {CHARACTER_CELL } ] ["DATATRIEVE"] [ /[NO]DEBUG ] [ /VARIANT=image-suffix ] [ ] 3 Arguments /INTERFACE = { DECWINDOWS } { CHARACTER_CELL } Specifies the display interface to be used by DEC DATATRIEVE. If your default environment is the command line interface, then CHARACTER_CELL is the default. If your system is properly defined to invoke the DECwindows Motif interface, then DECwindows Motif is the default. This qualifier overrides the setting specified by the DTR$NOWINDOWS logical. /[NO]DEBUG Specifies whether DEC DATATRIEVE should display special debug messages. The default is NODEBUG. /VARIANT = image-suffix Indicates the 1- to 26-character suffix applied to a DEC DATATRIEVE image upon installation to uniquely identify that image. This qualifier is needed only if you invoke a DEC DATATRIEVE image that was not selected as the default image at installation time. If the default image you are running includes a suffix and you want to run an image that does not include a suffix, use the /VARIANT qualifier alone, as in the following example: $ DATATRIEVE/VARIANT "DATATRIEVE" Specifies a DEC DATATRIEVE command or statement that is to be executed by DEC DATATRIEVE. It allows the user to execute a DEC DATATRIEVE command, statement, or procedure without entering interactive DEC DATATRIEVE. If the DEC DATATRIEVE argument contains more than one word, it must be placed in quotation marks. 3 Example The following example shows how to execute the DEC DATATRIEVE SHOW DICTIONARY command without entering interactive DEC DATATRIEVE. $ DATATRIEVE/INTERFACE=CHARACTER_CELL "SHOW DICTIONARY" The default directory is _CDD$TOP.DTR$LIB.DEMO $ 2 DECLARE_DATABASE_Command Creates a temporary database object that specifies a relational database (Format 1) or a Oracle CODASYL DBMS database instance (Format 2). Format 1 DECLARE DATABASE rdb-database-name ON root-file-spec; Format 2 DECLARE DATABASE dbms-database-name [USING] [SUBSCHEMA] subschema-name [OF] [SCHEMA] schema-path-name ON root-file-spec; 3 Arguments rdb-database-name Is the name of the relational database you want to declare. It must be a simple name. root-file-spec Is the name of the database root file. For relational databases, the default file type is .RDB; for Oracle CODASYL DBMS, the default file type is .ROO. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version dbms-database-name Is the name you choose for the Oracle CODASYL DBMS database instance. It must be a simple name. subschema-name Is the name of a subschema for the specified schema. schema-path-name Is the dictionary path name of a Oracle CODASYL DBMS schema. ;(semicolon) Ends the DECLARE DATABASE command. 3 Examples Declare a relational database object: DTR> DECLARE DATABASE MY_DB ON DTR$LIBRARY:PERSONNEL.RDB ; DTR> Declare a Oracle CODASYL DBMS database instance. The Oracle CDD/Repository path name of the schema is CDD$COMPATIBILITY.DTR$LIB.DEMO.DBMS.PARTS. The name of the subschema is DTR_SUBSCHEMA, and the root file is DTR$LIBRARY:DTRPARTDB.ROO: DTR> DECLARE DATABASE MY_PARTS_DB USING SUBSCHEMA DTR_SUBSCHEMA DFN> OF SCHEMA CDD$COMPATIBILITY.DTR$LIB.DEMO.DBMS.PARTS DFN> ON DTR$LIBRARY:DTRPARTDB.ROO ; 2 DECLARE_DOMAIN_Command Creates the temporary definition of a DATATRIEVE domain. The following sections explain how to declare domains for CDD$DATABASE objects, Oracle CODASYL DBMS databases, network domains based on domains residing at other DECnet[TM] nodes, domains based on relational databases, domains based on single RMS files, and views based on one or more domains. Format To declare a CDD$DATABASE domain, use the following syntax: DECLARE DOMAIN domain-name [USING] database-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [WITH] RELATIONSHIPS ; To declare a Oracle CODASYL DBMS domain, use the following syntax: DECLARE DOMAIN domain-name [USING] record-name [OF] [DATABASE] database-path-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] ; To declare a network domain, use the following syntax: DECLARE DOMAIN domain-name [USING] remote-path-name AT node-spec [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To declare a relational domain, use the following syntax: DECLARE DOMAIN domain-name [USING] relation-name [OF] [DATABASE] database-path-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To declare a domain based on a RMS file, use the following syntax: DECLARE DOMAIN domain-name [USING] record-path-name ON file-spec [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To declare a view domain, use the following syntax: DECLARE DOMAIN view-name OF domain-name-1 [,...][BY ] [USING] level-number-1 field-name-1 OCCURS FOR rse-1. level-number-2 field-name-2 { OCCURS FOR rse-n } . { FROM domain-name-n } . . . . . . . . . [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; 3 Arguments domain-name Is the name of the domain you are declaring. It must be a simple name. database-name Is the name of a CDD$DATABASE object, defined through CDO using the DEFINE DATABASE command, that points to a CDD$RMS_DATABASE object. Refer to the Oracle CDD/Repository documentation for more information on CDD$RMS_DATABASE objects. record-name Is the name of a record type contained in a subschema of the specified Oracle CODASYL DBMS database. database-path-name Is the DEC DATATRIEVE definition of the database instance. It is a dictionary pathname. remote-path-name Is the given name, full dictionary path name, or relative dictionary path name of a domain definition at another node in a network of computers linked by DECnet. That domain, the associated record definition, and the associated data file must already exist in the data dictionary at the remote node before you can ready the network domain. It is a dictionary pathname. node-spec Specifies the network address. If the login procedure used by the remote process does not supply the necessary login information (user name, password, and, optionally, account name), either the person readying the network domain or the network domain definition must supply this information. You can use any of the following formats to specify the network address and to provide the best level of access security for your installation: node-name"username password [account-name]") Examples of this format are: BIGVAX"WARTON KNOCKKNOCK DEPT32" ELEVEN"LINTE LETMEIN" When you specify the network address using this format, users do not have to supply login information when readying the network domain. node-name"*.username-prompt *.password-prompt [*.account-prompt]" Examples of this format are: WINKEN"*.USERNAME *.PASSWORD *.ACCOUNT" VAXTWO"*.'user name' *.'password'" PDPTWO"*.'user name' *.'password'" When you specify the network address using this format, users are prompted for login information when they ready the network domain. This method provides the best security. node-name Two examples of this format are: BIGVAX DEC:.zko.star Note that Poor Man's Routing is not accepted in AT clauses. When you specify the network address with this format, the account used by the remote process must provide login information automatically. If you prefer, you can combine elements from the first two formats. For example, you can explicitly specify the user name and specify a prompting value expression for the password: SNOOPY"CLARK *.PASSWORD" relation-name Is the name assigned to the relation when the database was created. record-name Is the given name, full dictionary path name, or relative dictionary path name of the record definition to be associated with the domain. You must enter the permanent or temporary definition of this record (with the DEFINE RECORD or the DECLARE RECORD commands) before you can ready the domain. file-spec Is the OpenVMS file specification of the RMS file containing the data for the domain. This file must exist when you ready the domain. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version view-name Is the name of the view being defined. It must be a simple name. domain-name-1 Is either the given name, full dictionary path name, or relative dictionary path name of a domain containing records to be included in the view. If the domain name is a domain path name, it cannot duplicate the name of the view. When specifying more than one domain path name, use a comma to separate each name from the next. level-number Is the level number for a field in the view definition. field-name Is the name of a field in the view definition. If field-name is followed by an OCCURS FOR clause, field-name has no relationship to any field in the domain or domains specified in the RSE. Whether or not field-name is the same as the names of any of those fields does not matter. If field-name is followed by a FROM clause, field-name must be the name of a field in a domain specified in the OF domain-name-1 [,...] clause. OCCURS FOR rse Indicates that the associated field is to be included in the view only for those records specified by the RSE. The RSE must contain a reference to one of the domains, relations, or Oracle CODASYL DBMS records listed in the OF clause. FROM domain-name Indicates that the definition of the associated field is identical to that of the field of the same name in the domain, relation, or Oracle CODASYL DBMS record specified by domain-name- n. The argument domain-name must be the same as that used in the preceding OCCURS FOR clause. . (period) Ends a field definition. form-name Is a form name. file-name For VAX TDMS and DEC FMS[TM] forms it is the name of a form library. For DECforms[TM] forms it is the form file name, which can either be a .FORM or a .EXE file. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version exchange-rec Is the path name of a record used to send and receive data with DECforms. RELATIONSHIPS It is ignored except in the declaration of a CDD$DATABASE domain where it is required to specify the characteristics of the related object. ; (semicolon) Ends the domain definition. 3 Examples Declare the DATATRIEVE domain D0 as pointing to the CDD$DATABASE database D_CDD$DATABASE. DTR> DECLARE DOMAIN D0 USING D_CDD$DATABASE WITH RELATIONSHIPS ; Declare the Oracle CODASYL DBMS domain D2. The name of the record-type is VENDOR, and the name of the database instance is CDD$TOP.DTR$LIB.DEMO.DBMS.PARTS_DB. The domain definition includes the FORM clause. DTR> DECLARE DOMAIN D2 DFN> USING VENDOR OF DATABASE CDD$TOP.DTR$LIB.DEMO.DBMS.PARTS_DB DFN> FORM IS EMPFOR IN FORMS:PARTS.FLB; DTR> Declare a network domain called REMOTE_YACHTS: DTR> DECLARE DOMAIN REMOTE_YACHTS USING DFN> CDD$TOP.DTR$LIB.DEMO.YACHTS AT DFN> VAX32"SMITH ADRIENNE" FORM IS YACHT1 IN DTRFRM; DTR> The following example declares a DEC DATATRIEVE domain that automatically uses a form. The domain is declared for the relation EMPLOYEES. DTR> DECLARE DOMAIN EMPLOYEES DFN> USING EMPLOYEES OF DATABASE PERSONNEL DFN> FORM IS EMPFOR IN FORMSLIB; DTR> Declare the domain PHONES. Use the record definition PHONE_REC that is cataloged in the directory CDD$TOP.DEPARTMENT. Specify PHONE.DAT as the data file: DTR> DECLARE DOMAIN PHONES USING DFN> CDD$TOP.DEPARTMENT.PHONE_REC ON PHONE.DAT; DTR> Declare a view of yacht and owner information: DTR> DECLARE DOMAIN BOAT_VIEW OF YACHTS, OWNERS USING 01 BOAT_INFO OCCURS FOR YACHTS. 03 TYPE FROM YACHTS. 03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT.TYPE. 05 NAME FROM OWNERS. 05 BOAT_NAME FROM OWNERS. ; DTR> READY BOAT_VIEW DTR> PRINT FIRST 4 BOAT_VIEW BOAT MANUFACTURER MODEL NAME NAME ALBERG 37 MK II ALBIN 79 ALBIN BALLAD ALBIN VEGA STEVE DELIVERANCE HUGH IMPULSE DTR> You can use a view domain such as BOAT_VIEW as a source for modifying data in a domain based on a RMS file. 2 DECLARE_PORT_Command Creates a temporary definition of a DEC DATATRIEVE port. It has a different syntax than the DECLARE PORT statement. The DECLARE PORT command can be used only as top level phrase; it only creates the temporary definition without readying the port. Format DECLARE PORT port-name [USING] record-name ; 3 Arguments port-name Is the name of the port being defined. It must be a simple name. record-name Is the name of a DECLARED record, or the full or relative dictionary path of the record definition to be associated with the port. ; (semicolon) Ends the port definition. 3 Example The following example defines a port for transferring records between the YACHTS domain and an application program: DTR> DECLARE PORT MY_YPORT USING CDD$TOP.DTR$LIB.DEMO.YACHT; DTR> 2 DECLARE_PROCEDURE_Command Creates the temporary definition of a procedure. Format DECLARE PROCEDURE procedure-name . . . END_PROCEDURE 3 Arguments procedure-name Is the name of the procedure you want to declare. It must be a simple name. END_PROCEDURE Ends the procedure definition. 3 Examples DTR> DECLARE PROCEDURE GRZ1 DFN> PRINT "I am Alessandra's mother" ; DFN> :ALE1 ; DFN> END_PROCEDURE ; DTR> DTR> DECLARE PROCEDURE ALE1 DFN> PRINT "I am Grazia's daughter" ; DFN> END_PROCEDURE ; DTR> DTR> :GRZ1 I am Alessandra's mother I am Grazia's daughter The following example shows how to declare a procedure that displays a group of boats with a price less than a figure you supply when the procedure runs: DTR> DECLARE PROCEDURE PRICE_LIST DFN> READY CDD$TOP.DTR$LIB.DEMO.YACHTS DFN> PRINT SKIP, COL 20, DFN> '*** Price List of YACHTS ***', SKIP ; DFN> FOR FIRST 5 YACHTS WITH PRICE NE 0 AND DFN> PRICE LE *.'the ceiling price' DFN> PRINT BOAT DFN> PRINT SKIP, COL 10, 'See anything interesting?' DFN> END_PROCEDURE ; DTR> DTR> :PRICE_LIST ; *** Price List of YACHTS *** Enter the ceiling price: 4500 LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE CAPE DORY TYPHOON SLOOP 19 1,900 06 $4,295 VENTURE 21 SLOOP 21 1,500 07 $2,823 VENTURE 222 SLOOP 22 2,000 07 $3,564 WINDPOWER IMPULSE SLOOP 16 650 07 $3,500 See anything interesting? DTR> 2 DECLARE_RECORD_Command Creates a temporary definition of a record. Format DECLARE RECORD record-name [USING] [OPTIMIZE] [ {MAJOR-MINOR } ] [ ALLOCATION IS {ALIGNED-MAJOR-MINOR } ] [ {LEFT-RIGHT } ] [ { } ] definition [,...] ; 3 Arguments record-name Is the name of the record being declared. [USING] OPTIMIZE This clause is ignored. { MAJOR-MINOR } ALLOCATION IS { ALIGNED-MAJOR-MINOR } { LEFT-RIGHT } Specifies the type of word-boundary alignment DEC DATATRIEVE uses when storing records in the data file. It also controls the way DEC DATATRIEVE retrieves data from data files created by user programs or other application software. The default allocation is no alignment. See the DEC COBOL[TM] documentation set for more information on word-boundary alignment and allocation of fill bytes. definition Is the description of the fields in the record. Each definition has one of the following formats: level-number-1 field-name-1. level-number-2 field-name-2 field-definition-2. [level-number-n field-name-n field-definition-n.] . . . . . . . . . or {FIELD } level-number-n FROM {GROUP } path-name. { } level-number Is the level number for the field in the record definition. It indicates the relationship of the field to the other fields in the record definition. field-name Is the name of the field. Every field must have a name. The keyword FILLER is a special field name that can be repeated at the same level in the record definition. field-definition Is a field definition. A record definition must contain at least one field definition. Elementary fields must have at least one field definition clause, but group fields are not required to have any field definition clauses. Each field definition must end with a period (.). FROM Allows you to create a definition using fields imported from dictionary field/record definitions. FIELD Specifies that you are referencing an existing field. If the field-pathname points to a Oracle CDD/Repository object, this must be a CDO field. Otherwise it identifies the first field of a DECLAREd or a text-definition record. GROUP Specifies that you are referencing an existing group field. If the field-pathname points to a Oracle CDD/Repository object, this must be a CDO record. Otherwise it may point to a DECLAREd or a text-definition record. path-name Specifies the path name of the field or record referenced by a FROM field. It can be a simple name (for DECLAREd object) or a relative or absolute dictionary pathname. ; (semicolon) Ends the record definition. 3 Examples The following example defines the record PHONE_REC: DTR> DECLARE RECORD PHONE_REC USING DFN> 01 PHONE. DFN> 02 NAME PIC X(20). DFN> 02 NUMBER PIC 9(7) EDIT_STRING IS XXX-XXXX. DFN> 02 LOCATION PIC X(9). DFN> 02 DEPARTMENT PIC XX. DFN> ; [Record is 38 bytes long.] The following example defines the record FAMILY: DTR> DECLARE RECORD FAMILY USING DFN> 01 FAMILY. DFN> 03 PARENTS. DFN> 06 FATHER PIC X(10). DFN> 06 MOTHER PIC X(10). DFN> 03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. DFN> 03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS. DFN> 06 EACH_KID. DFN> 09 KID_NAME PIC X(10) QUERY_NAME IS KID. DFN> 09 AGE PIC 99 EDIT_STRING IS Z9. DFN> ; [Record is 142 bytes long.] DTR> The following example declares the record YACHT_REC using fields from other records. DTR> DECLARE RECORD VERSION_ID USING DFN> 01 VERSION_ID PIC x(16) . DFN> ; [Record is 16 bytes long.] DTR> DTR> DECLARE RECORD SUPER_YACHT USING DFN> 01 SUPER_BOAT . DFN> 10 FROM GROUP CDD$TOP.DTR$LIB.DEMO.YACHT . DFN> 10 SPEED REAL . DFN> 10 FROM FIELD VERSION_ID . DFN> ; DTR> DTR> DECLARE DOMAIN SUPER_YACHTS USING SUPER_YACHT DFN> ON NDS_DECLARE_HELP_02.DAT ; DTR> DTR> SET NO CDD ; DTR> DEFINE FILE FOR SUPER_YACHTS ; DTR> READY SUPER_YACHTS ; DTR> SHOW FIELDS FOR SUPER_YACHTS ; SUPER_YACHTS SUPER_BOAT BOAT TYPE MANUFACTURER (BUILDER) MODEL SPECIFICATIONS (SPECS) RIG LENGTH_OVER_ALL (LOA) DISPLACEMENT (DISP) BEAM PRICE SPEED VERSION_ID 2 DECLARE_TABLE_Command Creates the temporary definition of a dictionary or domain table. list (ACL) for the table. The following sections explain how to declare dictionary and domain tables. Format To declare a dictionary table use the following syntax: DECLARE TABLE table-name [QUERY_HEADER [IS] "header-segment"[/...]] [EDIT_STRING [IS] edit-string] [USING] code-field : translation-field [,] {"code-1" } { "translation-1" } {code-1 }: { translation-1 }[,] { } { } [ {"code-2" } {"translation-2" } ] [ {code-2 }: {translation-2 } ][,] [ { } { } ] . . . . . . [ { "translation-n" } ] [ ELSE {translation-n } ] [ { } ] END_TABLE To declare a domain table use the following syntax: DECLARE TABLE table-name FROM [DOMAIN] domain-name [QUERY_HEADER [IS] "header-segment"[/...]] [EDIT_STRING [IS] edit-string] [USING] code-field : translation-field [,] [ { "translation-string" } ] [ ELSE {translation-string } ] [ { } ] END_TABLE 3 Arguments table-name Is the name of the dictionary table being defined. It must be a simple name. "code" : "translation" Is a code-and-translation pair. You must separate each pair with a colon. The comma after each pair is optional. If the code or translation conforms to the rules for DEC DATATRIEVE names given in the DEC DATATRIEVE User's Guide, you do not have to enclose it in quotation marks. However, DEC DATATRIEVE converts to uppercase any lowercase letters in an unquoted code or translation. If the code or translation does not conform to the rules for DEC DATATRIEVE names (especially if it contains any spaces), or if you want to preserve lowercase letters, you must enclose the code or translation in quotation marks (" ") and follow the rules for character string literals. ELSE "translation" Is the translation to be used if you specify a code not defined in the dictionary table. The rules for specifying this translation string are the same as those for codes and translations. END_TABLE Ends the dictionary table definition. 3 Examples The following example declares a table of department codes and specifies a query header for the translations of the table: DTR> DECLARE TABLE DEPT_TABLE DFN> QUERY_HEADER IS "Responsible"/"Department" DFN> CE : "Commercial Engineering" DFN> PE : "Plant Engineering" DFN> CS : "Customer Support" DFN> RD : "Research and Development" DFN> SD : "Sales Department" DFN> ELSE "UNKNOWN DEPARTMENT" DFN> END_TABLE DTR> DTR> print "John belongs to " | ( "RD" via DEPT_TABLE ) ; John belongs to Research and Development The following example declares a table with a translation for each possible rig and includes an edit string in the definition that displays the translation in a 10 character wide column: DTR> DECLARE TABLE RIGGING DFN> EDIT_STRING IS T(10) DFN> QUERY_HEADER "TYPE OF"/"RIGGING" DFN> SLOOP : "ONE MAST" DFN> KETCH : "TWO MASTS, BIG ONE IN FRONT" DFN> YAWL : "SIMILAR TO KETCH" DFN> MS : "SAILS AND A BIG MOTOR" DFN> ELSE "SOMETHING ELSE" DFN> END_TABLE DTR> PRINT "KETCH" VIA RIGGING TYPE OF RIGGING TWO MASTS, BIG ONE IN FRONT DTR> The following example shows how to declare a domain table that returns the price of a yacht when you enter a value for LENGTH_ OVER_ALL. The example specifies a query header and an edit string for the translation field: DTR> DECLARE TABLE LOA_PRICE_TABLE DFN> FROM CDD$TOP.DTR$LIB.DEMO.YACHTS DFN> QUERY_HEADER IS "SAMPLE"/"PRICE" DFN> EDIT_STRING IS $$$,$$$ DFN> USING LOA : PRICE DFN> ELSE "NO BOATS IN STOCK WITH THAT LOA." DFN> END_TABLE DTR> PRINT 26 VIA LOA_PRICE_TABLE SAMPLE PRICE $17,900 DTR> 2 DECLARE_Statement Defines a global or a local variable. Format DECLARE variable-name variable-definition . 3 Arguments variable-name Is the name of the variable being defined. The name must conform to the rules for names listed in the DEC DATATRIEVE User's Guide. variable-definition Is the definition of the variable, which consists of field definition clauses. If you include more than one such clause, separate them with spaces, tab characters, or carriage returns. Refer to the chapter on record definitions in the DEC DATATRIEVE User's Guide for information on field definition clauses. . (period) Ends the DECLARE statement. 3 Examples Declare the global variable NEW_BEAM as a 2-digit numeric field with a DEFAULT value of 10: DTR> DECLARE NEW_BEAM PIC 99 DEFAULT VALUE IS 10. DTR> PRINT NEW_BEAM NEW BEAM 10 DTR> Declare the global variable X as a single-precision floating- point number, with a MISSING VALUE of 36: DTR> DECLARE X REAL MISSING VALUE IS 36. DTR> PRINT X X 36.0000000 DTR> SHOW VARIABLES Global variables X Declared as: X REAL MISSING VALUE IS 36. DTR> RELEASE X DTR> SHOW FIELDS No ready sources or global variables declared. DTR> Declare the variable DUE as a date. Assign today's date to DUE and suppress the header with a hyphen in parentheses: DTR> DECLARE DUE USAGE IS DATE. DTR> DUE = "TODAY" DTR> PRINT DUE (-) 22-Sep-90 DTR> 2 DECLARE_ATT_Statement_(Report_Writer) Specifies text control elements (font family, character size, weight, slant, underline) overriding or complementing the default attributes for the ATT argument used by the Report Writer's PRINT and SET statements. Format { FAMILY= font-option } { SIZE= point-size } { {BOLD } } DECLARE_ATT att-name { { } } [,...] { [NO] {ITALIC } } { {UNDERLINE } } { {REVERSE } } { } 3 Arguments att-name Is the user-defined name of the attribute list. This name is used by the ATT clause in the Report Writer Print statement. DECLARE_ATT Print Attributes shows the options which can be controlled by the DECLARE_ATT statement. Table 1-1 DECLARE_ATT Print Attributes Header AttributOptions default Body default Family HELVETICA HELVETICA HELVETICA TIMES COURIER AVANTGARDE SYMBOL LUBALIN_ GRAPH NC_ SCHOOLBOOK SOUVENIR Point 8 10 12 14 14 10 Size 18 24 36 48 72 96 Bold BOLD BOLD NO BOLD NO BOLD Italic ITALIC NO ITALIC NO ITALIC NO ITALIC UnderlinUNDERLINE NO NO UNDERLINE NO UNDERLINE UNDERLINE Reverse REVERSE NO NO REVERSE NO REVERSE REVERSE font-option Is the font family chosen. Available options are listed in DECLARE_ATT Print Attributes. point-size Is the point size for the chosen font family. Available options are listed in DECLARE_ATT Print Attributes. 3 Example The following example shows a number of DECLARE_ATT statements: DTR> REPORT PAYABLES WITH INVOICE_DUE NOT MISSING - RW> SORTED BY AGE ON AGING_REPORT.PS FORMAT PS RW> RW> DECLARE_ATT TITLE FAMILY = TIMES, SIZE = 24, BOLD, NOITALIC RW> DECLARE_ATT DATE_PAGE FAMILY = TIMES, SIZE = 14, NOBOLD, ITALIC RW> DECLARE_ATT COL_HDR FAMILY = TIMES, SIZE = 12, BOLD, ITALIC RW> DECLARE_ATT DETAIL FAMILY = NC_SCHOOLBOOK, SIZE = 10 RW> DECLARE_ATT TOT_ACCNTS FAMILY = HELVETICA, SIZE = 12, NOBOLD RW> DECLARE_ATT TOTAL FAMILY = HELVETICA, SIZE = 14, BOLD RW> DECLARE_ATT ULINE UNDERLINE RW> DECLARE_ATT NO_ULINE NOUNDERLINE RW> DECLARE_ATT GRAND_TOTAL FAMILY = HELVETICA, SIZE = 14, BOLD, ITALIC 2 DECLARE_PORT_Statement Creates a temporary DEC DATATRIEVE port with the name you specify and readies the port for WRITE access. DEC DATATRIEVE does not enter a definition of the port in the Oracle CDD/Repository data dictionary. Format DECLARE PORT port-name USING level-number-1 field-definition-1. [level-number-2 field-definition-2.] . . . . . . [level-number-n field-definition-n.] ; 3 Arguments port-name Is the name of the port. It cannot duplicate a DEC DATATRIEVE keyword or the given name of any domain you may bring into your workspace. level-number Is the level number for the field in the port declaration. It indicates the relationship of the field to the other fields of the port. field-definition Is a field definition. A port declaration must have at least one field definition. Each field definition ends with a period. ; (semicolon) Ends the port declaration. 3 Example The following example shows a port declared for YACHTS records in a DEC Fortran program: CALL DTR$COMMAND (DAB,'DECLARE PORT BOAT_PORT USING 1 01 YACHT. 2 03 BOAT. 3 06 BUILDER PIC X(9). 4 06 MODEL PIC X(10). 5 06 RIG PIC X(6). 6 06 LOA PIC X(3). 7 06 DISP PIC X(5). 8 06 BEAM PIC XX. 9 06 PRICE PIC X(5).;') 2 DECLARE_SYNONYM_Command Defines a synonym for a DEC DATATRIEVE keyword. Format DECLARE SYNONYM { synonym [FOR] keyword } [,...] 3 Arguments synonym Is the name of the synonym being defined. The name must conform to the rules for names listed in the DEC DATATRIEVE User's Guide. FOR Is an optional word to clarify syntax. keyword Is the name of a DEC DATATRIEVE keyword for which a synonym is being defined. 3 Examples Define synonyms for the keywords FIND and PRINT. Use the synonyms to form a collection of the first two yachts, and then print the collection. DTR> READY YACHTS DTR> DECLARE SYNONYM FD FOR FIND, PT FOR PRINT DTR> FD FIRST 2 YACHTS; PT CURRENT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBERG 37 MK II KETCH 37 20,000 12 $36,951 ALBIN 79 SLOOP 26 4,200 10 $17,900 DTR> Calculate the price per foot and per pound for the first five yachts. To save typing, define synonyms for COMPUTED, EDIT_ STRING, and PRINT. DTR> SET NO PROMPT DTR> DECLARE SYNONYM CD FOR COMPUTED CON> E_S FOR EDIT_STRING, PT FOR PRINT DTR> DECLARE PER_FT CD BY (PRICE/LOA) E_S $$$$.99. DTR> DECLARE PER_LB CD BY (PRICE/DISP) E_S $$.99. DTR> FOR FIRST 5 YACHTS CON> PT TYPE, PRICE, PER_FT, PER_LB PER PER MANUFACTURER MODEL PRICE FT LB ALBERG 37 MK II $36,951 $998.68 $1.85 ALBIN 79 $17,900 $688.46 $4.26 ALBIN BALLAD $27,500 $916.67 $3.78 ALBIN VEGA $18,600 $688.89 $3.67 AMERICAN 26 $9,895 $380.58 $2.47 DTR> 2 DEFAULT_VALUE_Clause Specifies a default value for initializing a field to which you do not make a direct assignment in STORE or Restructure statements. Format DEFAULT [VALUE] [IS] literal 3 Argument VALUE IS Are optional keywords you can use to clarify the syntax of the clause. literal Is either a numeric or character string literal. 3 Examples Define a field in a student record that sets a default value for tuition owed at registration. 09 TUITION_DUE PIC Z(4)9.99 EDIT_STRING IS $$$,$$$.99 DEFAULT VALUE IS 4800. Define a date field with the default value of the day you store the record: 03 DATE_IN USAGE DATE DEFAULT "TODAY". 2 DEFINE_DATABASE_Command Defines a path name for a relational database (Format 1) or a path name for a Oracle CODASYL DBMS database instance (Format 2). Format 1 DEFINE DATABASE rdb-database-path ON root-file-spec; Format 2 DEFINE DATABASE dbms-database-path [USING] [SUBSCHEMA] subschema-name [OF] [SCHEMA] schema-path-name ON root-file-spec; 3 Arguments rdb-database-path Is the Oracle CDD/Repository path name of the relational database you want to define. The path name can be either a DMU or a CDO style path name. root-file-spec Is the name of the database root file. For relational databases, the default file type is .RDB; for Oracle CODASYL DBMS, the default file type is .ROO. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version dbms-database-path Is the Oracle CDD/Repository path name you choose for the Oracle CODASYL DBMS database instance. The path name can be either a DMU or a CDO style path name. Although a DMU style path name is still accepted, you are recommended to use a CDO path name. subschema-name Is the name of a subschema for the specified schema. schema-path-name Is the CDO path name of a Oracle CODASYL DBMS schema. ;(semicolon) Ends the DEFINE DATABASE command. 3 Examples Define a relational database path name: DTR> DEFINE DATABASE CDD$TOP.DEPT29.PERSONNEL ON DFN> DBA2:[D29.DAT]PERSONNEL.RDB; DTR> Define a Oracle CODASYL DBMS database instance. The Oracle CDD/Repository path name of the schema is SYS$COMMON:[CDDPLUS]DBMS.PARTS. The name of the subschema is PARTSS1, and the root file is DB0:[BULGAKOV]PARTSDB.ROO: DTR> DEFINE DATABASE PARTS_DB DFN> USING PARTSS1 DFN> OF SYS$COMMON:[CDDPLUS]DBMS.PARTS DFN> ON DB0:[BULGAKOV]PARTSDB.ROO; DTR> 2 DEFINE_DICTIONARY_Command Creates a dictionary directory in the Oracle CDD/Repository data dictionary system. Format DEFINE DICTIONARY path-name 3 Argument path-name Is the given name, the full dictionary path name, or a relative dictionary path name of the dictionary you want to create. The DEFINE DICTIONARY command accepts both DMU and CDO style path names. A complete CDO style path name has the following format: node-spec::device:[directory]file-name.type;version 3 Examples Use a given name to define a dictionary directory named TEST when CDD$TOP.RESEARCH is your default directory: DTR> SHOW DICTIONARY The default directory is CDD$TOP.RESEARCH DTR> DEFINE DICTIONARY TEST DTR> SHOW DICTIONARIES Dictionaries: DEMO TEST DTR> SET DICTIONARY TEST DTR> SHOW DICTIONARY The default dictionary is CDD$TOP.RESEARCH.TEST DTR> SHOW PRIVILEGES Privileges for CDD$TOP.RESEARCH.TEST R (DTR_READ) - may ready for READ, use SHOW and EXTRACT W (DTR_WRITE) - may ready for READ, WRITE, MODIFY, or EXTEND M (DTR_MODIFY) - may ready for READ, MODIFY E (DTR_EXTEND/EXECUTE) - may ready to EXTEND, or access table or procedure C (CONTROL) - may issue DEFINEP, SHOWP, DELETEP commands D (LOCAL_DELETE) - may delete a dictionary object F (FORWARD) - may create a subdictionary H (HISTORY) - may add entries to object's history list P (PASS_THRU) - may use given name of directory or object in pathname S (SEE) - may see (read) dictionary U (UPDATE) - may update dictionary object X (extend) - may create directory or object within directory DTR> Use a relative dictionary path name to define a dictionary directory in the CDD$TOP.MANUFACTURING directory when CDD$TOP.DTR$LIB is your default directory: DTR> SHOW DICTIONARY The default directory is CDD$TOP.DTR$LIB DTR> DEFINE DICTIONARY DFN> -.MANUFACTURING.TEST DTR> SET DICTIONARY -.MANUFACTURING DTR> SHOW DICTIONARIES INVENTORY TEST DTR> SHOWP TEST 1: [*,*], Username: "JONES" Grant - CDHPSX, Deny - None, Banish - none DTR> Use a full name to define a CDO dictionary directory named TEST. DISK1:[SWANSON.DTRWORK] is your default directory: DTR> SHOW DICTIONARY The default directory is DISK1:[SWANSON.DTRWORK] DTR> DEFINE DICTIONARY DISK1:[SWANSON.DTRWORK]TEST DTR> SHOW DICTIONARIES Dictionaries: MYDICT TEST DTR> 2 DEFINE_DOMAIN_Command Stores a domain definition in the Oracle CDD/Repository data dictionary system. The following sections explain how to define domains for CDD$DATABASE objects, Oracle CODASYL DBMS databases, network domains based on domains residing at other DECnet[TM] nodes, domains based on relational databases, domains based on single RMS files, and views based on one or more domains. Format To define a CDD$DATABASE domain, use the following syntax: DEFINE DOMAIN domain-name [USING] database-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [WITH] RELATIONSHIPS ; To define a Oracle CODASYL DBMS domain, use the following syntax: DEFINE DOMAIN domain-name [USING] record-name [OF] [DATABASE] database-path-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] ; To define a network domain, use the following syntax: DEFINE DOMAIN domain-name [USING] remote-path-name AT node-spec [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To define a relational domain, use the following syntax: DEFINE DOMAIN domain-name [USING] relation-name [OF] [DATABASE] database-path-name [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To define a domain based on a RMS file, use the following syntax: DEFINE DOMAIN path-name [USING] record-name ON file-spec [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; To define a view domain, use the following syntax: DEFINE DOMAIN view-path-name OF domain-name-1 [,...][BY ] [USING] level-number-1 field-name-1 OCCURS FOR rse-1. level-number-2 field-name-2 { OCCURS FOR rse-n } . { FROM domain-name-n } . . . . . . . . . [FORM [IS] form-name [IN] file-name [USING exchange-rec]] [[WITH] RELATIONSHIPS] ; 3 Arguments domain-name Is the Oracle CDD/Repository dictionary path name of the domain you are defining. The domain-name can be either a DMU or CDO style path name. database-name Is the name of a CDD$DATABASE object, defined through CDO using the DEFINE DATABASE command, that points to a CDD$RMS_DATABASE object. Refer to the Oracle CDD/Repository documentation for more information on CDD$RMS_DATABASE objects. record-name Is the name of a record type contained in a subschema of the specified Oracle CODASYL DBMS database. database-path-name Is the DEC DATATRIEVE definition of the database instance. The database-path-name can be both DMU and CDO style path name. remote-path-name Is the given name, full dictionary path name, or relative dictionary path name of a domain definition at another node in a network of computers linked by DECnet. That domain, the associated record definition, and the associated data file must already exist in the data dictionary at the remote node before you can ready the network domain. The domain-name can be either a DMU or CDO style path name. node-spec Specifies the network address. If the login procedure used by the remote process does not supply the necessary login information (user name, password, and, optionally, account name), either the person readying the network domain or the network domain definition must supply this information. You can use any of the following formats to specify the network address and to provide the best level of access security for your installation: Examples of this format are: BIGVAX"WARTON KNOCKKNOCK DEPT32" ELEVEN"LINTE LETMEIN" When you specify the network address using this format, users do not have to supply login information when readying the network domain. Examples of this format are: WINKEN"*.USERNAME *.PASSWORD *.ACCOUNT" VAXTWO"*.'user name' *.'password'" PDPTWO"*.'user name' *.'password'" When you specify the network address using this format, users are prompted for login information when they ready the network domain. This method provides the best security. Two examples of this format are: BIGVAX DEC:.zko.star Note that Poor Man's Routing is not accepted in AT clauses. When you specify the network address with this format, the account used by the remote process must provide login information automatically. If you prefer, you can combine elements from the first two formats. For example, you can explicitly specify the user name and specify a prompting value expression for the password: SNOOPY"CLARK *.PASSWORD" relation-name Is the name assigned to the relation when the database was created. path-name Is the given name, full dictionary path name, or relative dictionary path name of the domain being defined. The path name cannot resolve to the full dictionary path name of any other object or directory in the data dictionary system. The path-name can be either a DMU or CDO style path name. record-name Is the given name, full dictionary path name, or relative dictionary path name of the record definition to be associated with the domain. You must enter this record definition in the data dictionary (with the DEFINE RECORD command) before you can ready the domain. The dictionary path name of the record cannot resolve to the full dictionary path name of any other directory or object in the data dictionary. The record-name can be either a DMU or CDO style path name. file-spec Is the OpenVMS file specification of the RMS file containing the data for the domain. This file must exist when you ready the domain. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version view-path-name Is the given name, full dictionary path name, or relative dictionary path name of the view being defined. The path name cannot resolve to the full dictionary path name of any other object or directory in the data dictionary. The view-path-name may be either a DMU or CDO style path name. domain-name-1 Is either the given name, full dictionary path name, or relative dictionary path name of a domain containing records to be included in the view. If the domain name is a domain path name, it cannot duplicate the name of the view. When specifying more than one domain path name, use a comma to separate each name from the next. The domain-name may be either a DMU or CDO style path name. level-number Is the level number for a field in the view definition. field-name Is the name of a field in the view definition. If field-name is followed by an OCCURS FOR clause, field-name has no relationship to any field in the domain or domains specified in the RSE. Whether or not field-name is the same as the names of any of those fields does not matter. If field-name is followed by a FROM clause, field-name must be the name of a field in a domain specified in the OF domain-name-1 [,...] clause. OCCURS FOR rse Indicates that the associated field is to be included in the view only for those records specified by the RSE. The RSE must contain a reference to one of the domains, relations, or Oracle CODASYL DBMS records listed in the OF clause. FROM domain-name Indicates that the definition of the associated field is identical to that of the field of the same name in the domain, relation, or Oracle CODASYL DBMS record specified by domain-name- n. The argument domain-name must be the same as that used in the preceding OCCURS FOR clause. . (period) Ends a field definition. form-name Is a form name. file-name For VAX TDMS and DEC FMS[TM] forms it is the name of a form library. For DECforms[TM] forms it is the form file name, which can either be a .FORM or a .EXE file. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version exchange-rec Is the Oracle CDD/Repository path name (either DMU or CDO) of a record used to send and receive data with DECforms. RELATIONSHIPS Causes relationships to be set up between the domain being defined and one of the following items: o The CDD$DATABASE object o The domain specified on the remote node o The record definition o The objects referenced by the view ; (semicolon) Ends the domain definition. 3 Examples Define the CDD$DATABASE domain NEWYACHTS. Use the already defined CDD$DATABASE YACHTS. DTR> DEFINE DOMAIN NEWYACHTS USING YACHTS_DB DFN> WITH RELATIONSHIPS; Define the Oracle CODASYL DBMS domain EMPLOYEES. The name of the record-type is EMPLOYEE, and the name of the database instance is PARTS_DB. The domain definition includes the FORM clause. DTR> DEFINE DOMAIN EMPLOYEES DFN> USING EMPLOYEE OF DATABASE PARTS_DB DFN> FORM IS EMPFOR IN FORMS:PARTS.FLB; DTR> Define a network domain called REMOTE_YACHTS: DTR> DEFINE DOMAIN REMOTE_YACHTS USING DFN> CDD$TOP.DTR$LIB.DEMO.YACHTS AT DFN> VAX32"SMITH ADRIENNE" FORM IS YACHT1 IN DTRFRM; DTR> The following example defines a DEC DATATRIEVE domain that automatically uses a form. The domain is defined for the relation EMPLOYEES. DTR> DEFINE DOMAIN EMPLOYEES DFN> USING EMPLOYEES OF DATABASE PERSONNEL DFN> FORM IS EMPFOR IN FORMSLIB; DTR> Define the domain PHONES. Use the record definition PHONE_REC that is cataloged in the directory CDD$TOP.DEPARTMENT. Specify PHONE.DAT as the data file: DTR> DEFINE DOMAIN PHONES USING DFN> CDD$TOP.DEPARTMENT.PHONE_REC ON PHONE.DAT; DTR> Define a view of yacht and owner information: DTR> SHOW BOAT_VIEW DOMAIN BOAT_VIEW OF YACHTS, OWNERS USING 01 BOAT_INFO OCCURS FOR YACHTS. 03 TYPE FROM YACHTS. 03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT.TYPE. 05 NAME FROM OWNERS. 05 BOAT_NAME FROM OWNERS. ; DTR> READY BOAT_VIEW DTR> PRINT FIRST 4 BOAT_VIEW BOAT MANUFACTURER MODEL NAME NAME ALBERG 37 MK II ALBIN 79 ALBIN BALLAD ALBIN VEGA STEVE DELIVERANCE HUGH IMPULSE DTR> You can use a view domain such as BOAT_VIEW as a source for modifying data in a domain based on a RMS file. 2 DEFINE_FILE_Command Creates an RMS sequential or indexed sequential data file for the DEC DATATRIEVE RMS domain specified by the dictionary path name. Format for Defining a Sequential File DEFINE FILE [FOR] path-name [ ALLOCATION = n ] [ SUPERSEDE ] [,...] [ MAX ] [ ] Format for Defining an Indexed File DEFINE FILE [FOR] path-name [ ALLOCATION = n ] [ SUPERSEDE ] [,...] [ MAX ] [ ] { KEY = field-name-1 [ ( [NO]CHANGE[,] [NO]DUP) ] } [,...] Format for Defining an RMS File Using a FDL File DEFINE FILE [FOR] domain-name USING fdl-file-spec 3 Arguments path-name Is the dictionary path name of the DEC DATATRIEVE domain based on a RMS file for which you want to create a data file. domain-name Is the name of the DEC DATATRIEVE domain for which you want to create a data file. ALLOCATION = n Specifies an unsigned nonzero integer that determines the number of disk blocks initially allocated for the data file. If you omit this argument, zero blocks are allocated for the file. When you store records into the data file, RMS automatically extends the data file according to the cluster size established by your system manager. SUPERSEDE Causes DEC DATATRIEVE to delete any existing data file that exactly matches the complete file specification, including the version number, in your RMS domain definition. The new file you are defining replaces the existing data file. If your domain based on a RMS file does not include a file version number, the old file is not deleted, and the new file is assigned the next higher version number. MAX Causes DEC DATATRIEVE to create a fixed-length RMS file for a domain whose record definition contains an OCCURS . . . DEPENDING clause. The length of every record in the data file has the maximum possible size, as determined by the value of the MAX argument in the OCCURS . . . DEPENDING clause: OCCURS min TO max TIMES DEPENDING ON field-name Each record can then store the maximum number of items in the list defined by the OCCURS . . . DEPENDING clause. If you omit this argument, DEC DATATRIEVE does not create a file with fixed-length records of the maximum possible size. The size of each record is determined when you store the record. If the file is defined as a sequential file, a record size cannot be increased to include more list items after it is initially stored. KEY = field-name Causes DEC DATATRIEVE to create an RMS indexed file and specifies a field in the domain's record definition to be used as an index key for the domain's data file. The first key field specified in the DEFINE FILE command is the primary key, and all subsequent ones are alternate keys. If you specify more than one KEY clause, use a comma (,) to separate each clause from the next. If you are defining a file for a hierarchical record, do not make a list field the primary key. If you omit this clause, DEC DATATRIEVE creates an RMS sequential file. CHANGE Determines whether or not you can modify the content of the associated key field. The default is NOCHANGE for the primary key field and CHANGE for alternate key fields. See Allowed Combinations of Key Field Attributes for the allowed combinations of key field attributes. DUP Determines whether or not you can assign the same value to the specified key fields of two or more records. The default is NO DUP for the primary key field and DUP for alternate key fields. See Allowed Combinations of Key Field Attributes for the allowed combinations of key field attributes. Table 1-2 Allowed Combinations of Key Field Attributes Key Field Attributes CHANGE NO Key CHANGE + NO CHANGE NO CHANGE Type + DUP DUP + DUP + NO DUP Primary Not Not Allowed Allowed Allowed Allowed AlternatAllowed Allowed Allowed Allowed USING fdl-file-spec Specifies the FDL file to be used in creating the RMS file. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version 3 Examples The following example shows how to define an indexed file for the domain PAYABLES using the field NAME as the primary key and TYPE as the alternate key, and allowing no changes to the alternate key: DTR> DEFINE FILE FOR PHONES KEY=NAME(DUP), KEY=TYPE(NO CHANGE) DTR> The following example defines a sequential file for the domain FAMILIES: DTR> DEFINE FILE FOR FAMILIES DTR> The following example shows how to define a new indexed file for the domain YACHTS using the group field TYPE as the primary key, allowing duplicate values for this key. This command replaces the previous data file for YACHT. DTR> DEFINE FILE FOR YACHTS SUPERSEDE, KEY=TYPE (DUP) DTR> The following example defines a new file for the YACHTS domain using the specifications included in YACHTS.FDL, a file created outside of DEC DATATRIEVE: DTR> DEFINE FILE FOR YACHTS USING YACHTS.FDL DTR> 2 DEFINE_PORT_Command Enters the definition of a DEC DATATRIEVE port in the specified or implied directory of the Oracle CDD/Repository data dictionary system and creates an access control list (ACL) for the port. Format DEFINE PORT path-name [USING] record-name ; 3 Arguments path-name Is the given name, full dictionary path name, or relative dictionary path name of the port being defined. The path name cannot resolve to the full dictionary path name of any other object or directory in the data dictionary system. DEFINE PORT will accept both DMU and CDO style path names. record-name Is the given name, full dictionary path name, or relative dictionary path name of the record definition to be associated with the port. The dictionary path name of the record cannot resolve to the full dictionary path name of any other object or directory in the data dictionary system. DEFINE PORT will accept both DMU and CDO style path names. ; (semicolon) Ends the port definition. 3 Example The following example defines a port for transferring records between the YACHTS domain and an application program: DTR> DEFINE PORT YPORT USING CDD$TOP.DTR$LIB.DEMO.YACHT; DTR> 2 DEFINE_PROCEDURE_Command Enters a procedure definition into the Oracle CDD/Repository data dictionary system and creates an access control list (ACL) for the procedure. Format DEFINE PROCEDURE procedure-name . . . END_PROCEDURE 3 Arguments procedure-name Is the given name, full dictionary path name, or relative dictionary path name of the procedure you want to define. The path name cannot resolve to the full dictionary path name of any other object or directory in the data dictionary. Procedures can be defined in either the DMU or CDO dictionary. END_PROCEDURE Ends the procedure definition. 3 Examples The following example shows how to define a procedure to set your default directory to the DEMO directory, which contains the sample data for the YACHTS, OWNERS, and FAMILIES domains: DTR> DEFINE PROCEDURE DEMO DFN> SET DICTIONARY CDD$TOP.DTR$LIB.DEMO DFN> SHOW DICTIONARY DFN> END_PROCEDURE DTR> :DEMO The default directory is CDD$TOP.DTR$LIB.DEMO DTR> The following example shows how to define a procedure that displays a group of boats with a price less than a figure you supply when the procedure runs: DTR> DEFINE PROCEDURE PRICE_LIST DFN> READY YACHTS DFN> PRINT SKIP, COL 20, DFN> '*** Price List of YACHTS ***', SKIP DFN> FOR YACHTS WITH PRICE NE 0 AND DFN> PRICE LE *.'the ceiling price' DFN> PRINT BOAT DFN> PRINT SKIP, COL 10, 'See anything interesting?' DFN> END_PROCEDURE DTR> :PRICE_LIST *** Price List of YACHTS *** Enter the ceiling price: 5,000 LENGTH OVER MANUFACTURER MODEL RIG ALL DISPLACEMENT BEAM PRICE CAPE DORY TYPHOON SLOOP 19 1,900 06 $4,295 VENTURE 21 SLOOP 21 1,500 07 $2,823 VENTURE 222 SLOOP 22 2,000 07 $3,564 WINDPOWER IMPULSE SLOOP 16 650 07 $3,500 See anything interesting? DTR> The following example shows how to use a OpenVMS command line to invoke the procedure created in the first example: $ DTR32 EXECUTE DEMO The default directory is CDD$TOP.DTR$LIB.DEMO $ 2 DEFINE_RECORD_Command Enters a record definition in the Oracle CDD/Repository data dictionary and creates an access control list (ACL) for the record. Format DEFINE RECORD record-name [USING] [OPTIMIZE] [ {MAJOR-MINOR } ] [ ALLOCATION IS {ALIGNED-MAJOR-MINOR } ] [ {LEFT-RIGHT } ] [ { } ] definition [,...] ; 3 Arguments record-name Is the given name, full dictionary path name, or relative dictionary path name of the record being defined. The record path name cannot resolve to the full dictionary path name of any other object or directory in the data dictionary system. DEFINE RECORD will accept both DMU and CDO style path names. [USING] OPTIMIZE Allows you to optimize record definitions, reducing the central processing unit (CPU) time needed to ready a domain that refers to the record. See the Usage Notes section for special considerations. { MAJOR-MINOR } ALLOCATION IS { ALIGNED-MAJOR-MINOR } { LEFT-RIGHT } Specifies the type of word-boundary alignment DEC DATATRIEVE uses when storing records in the data file. It also controls the way DEC DATATRIEVE retrieves data from data files created by user programs or other application software. The default allocation is no alignment. See the DEC COBOL[TM] documentation set for more information on word-boundary alignment and allocation of fill bytes. definition Is the description of the fields in the record. Each definition has one of the following formats: level-number-1 field-name-1. level-number-2 field-name-2 field-definition-2. [level-number-n field-name-n field-definition-n.] . . . . . . . . . or {FIELD } level-number-n FROM {GROUP } path-name. { } level-number Is the level number for the field in the record definition. It indicates the relationship of the field to the other fields in the record definition. field-name Is the name of the field. Every field must have a name. The keyword FILLER is a special field name that can be repeated at the same level in the record definition. field-definition Is a field definition. A record definition must contain at least one field definition. Elementary fields must have at least one field definition clause, but group fields are not required to have any field definition clauses. Each field definition must end with a period (.). FROM Allows you to create a definition using fields imported from CDO field/record definitions. FIELD Specifies that you are referencing an existing CDO field. GROUP Specifies that you are referencing an existing CDO group field. path-name Specifies the path name of the field or record referenced by a FROM field. The record or field specified by this path name must reside in a CDO format dictionary. ; (semicolon) Ends the record definition. 3 Examples The following example defines the record PHONE_REC: DTR> DEFINE RECORD PHONE_REC USING DFN> 01 PHONE. DFN> 02 NAME PIC X(20). DFN> 02 NUMBER PIC 9(7) EDIT_STRING IS XXX-XXXX. DFN> 02 LOCATION PIC X(9). DFN> 02 DEPARTMENT PIC XX. DFN> ; [Record is 38 bytes long.] DTR> The following example defines the record FAMILY: DTR> DEFINE RECORD FAMILY USING DFN> 01 FAMILY. DFN> 03 PARENTS. DFN> 06 FATHER PIC X(10). DFN> 06 MOTHER PIC X(10). DFN> 03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. DFN> 03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS. DFN> 06 EACH_KID. DFN> 09 KID_NAME PIC X(10) QUERY_NAME IS KID. DFN> 09 AGE PIC 99 EDIT_STRING IS Z9. DFN> ; [Record is 142 bytes long.] DTR> The following example defines the record ACCOUNT_BALANCE_REC using the OPTIMIZE qualifier. Note that the USING clause is optional. DTR> DEFINE RECORD ACCOUNT_BALANCE_REC USING OPTIMIZE . . . DFN> ; DTR> The following example defines the record YACHT_REC in the CDO format dictionary using fields from a CDO dictionary. Note that you can mix fields from an existing CDO dictionary and fields private to DEC DATATRIEVE in the same record definition. Field BEAM uses CDD$DEFAULT.BEAM as a path. Fields LOA and PRICE are defined only for this record. DTR> DEFINE RECORD YACHT_REC USING DFN> 01 BOAT. DFN> 03 FROM GROUP SYS$COMMON:[CDDPLUS]DTR32.TYPE. DFN> 03 SPECIFICATIONS. DFN> 06 LOA PIC 99. DFN> 06 FROM FIELD BEAM. DFN> 06 PRICE PIC 999999. DFN> ; DTR> 2 DEFINE_TABLE_Command Enters the definition of a dictionary or domain table in the data dictionary (Oracle CDD/Repository) and creates an access control list (ACL) for the table. The following sections explain how to define dictionary and domain tables. Format To define a dictionary table use the following syntax: DEFINE TABLE path-name [QUERY_HEADER [IS] "header-segment"[/...]] [EDIT_STRING [IS] edit-string] [USING] code-field : translation-field [,] {"code-1" } { "translation-1" } {code-1 }: { translation-1 }[,] { } { } [ {"code-2" } {"translation-2" } ] [ {code-2 }: {translation-2 } ][,] [ { } { } ] . . . . . . [ { "translation-n" } ] [ ELSE {translation-n } ] [ { } ] END_TABLE To define a domain table use the following syntax: DEFINE TABLE path-name FROM [DOMAIN] domain-name [QUERY_HEADER [IS] "header-segment"[/...]] [EDIT_STRING [IS] edit-string] [USING] code-field : translation-field [,] [ { "translation-string" } ] [ ELSE {translation-string } ] [ { } ] END_TABLE 3 Arguments path-name Is the given name, full dictionary path name, or relative dictionary path name of the dictionary table being defined. The full dictionary path name of the table cannot resolve to the full dictionary path name of any other object or directory in the data dictionary system. The DEFINE TABLE command accepts both DMU or CDO style path names. "code" : "translation" Is a code-and-translation pair. You must separate each pair with a colon. The comma after each pair is optional. If the code or translation conforms to the rules for DEC DATATRIEVE names given in the DEC DATATRIEVE User's Guide, you do not have to enclose it in quotation marks. However, DEC DATATRIEVE converts to uppercase any lowercase letters in an unquoted code or translation. If the code or translation does not conform to the rules for DEC DATATRIEVE names (especially if it contains any spaces), or if you want to preserve lowercase letters, you must enclose the code or translation in quotation marks (" ") and follow the rules for character string literals. ELSE "translation" Is the translation to be used if you specify a code not defined in the dictionary table. The rules for specifying this translation string are the same as those for codes and translations. END_TABLE Ends the dictionary table definition. 3 Examples The following example defines a table of department codes and specifies a query header for the translations of the table: DTR> DEFINE TABLE DEPT_TABLE DFN> QUERY_HEADER IS "Responsible"/"Department" DFN> CE : "Commercial Engineering" DFN> PE : "Plant Engineering" DFN> CS : "Customer Support" DFN> RD : "Research and Development" DFN> SD : "Sales Department" DFN> ELSE "UNKNOWN DEPARTMENT" DFN> END_TABLE DTR> The following example defines a table with a translation for each possible rig and includes an edit string in the definition that displays the translation in a 10 character wide column: DTR> DEFINE TABLE RIGGING DFN> EDIT_STRING IS T(10) DFN> QUERY_HEADER "TYPE OF"/"RIGGING" DFN> SLOOP : "ONE MAST" DFN> KETCH : "TWO MASTS, BIG ONE IN FRONT" DFN> YAWL : "SIMILAR TO KETCH" DFN> MS : "SAILS AND A BIG MOTOR" DFN> ELSE "SOMETHING ELSE" DFN> END_TABLE DTR> PRINT "KETCH" VIA RIGGING TYPE OF RIGGING TWO MASTS, BIG ONE IN FRONT DTR> The following example shows how to define a domain table that returns the price of a yacht when you enter a value for LENGTH_ OVER_ALL. The example specifies a query header and an edit string for the translation field: DTR> DEFINE TABLE LOA_PRICE_TABLE DFN> FROM YACHTS DFN> QUERY_HEADER IS "SAMPLE"/"PRICE" DFN> EDIT_STRING IS $$$,$$$ DFN> USING LOA : PRICE DFN> ELSE "NO BOATS IN STOCK WITH THAT LOA." DFN> END_TABLE DTR> PRINT 26 VIA LOA_PRICE_TABLE SAMPLE PRICE $17,900 DTR> 2 DEFINEP_Command Adds an entry to the access control list (ACL) for a dictionary object or dictionary directory. Format DEFINEP [FOR] path-name sequence-number [,] { PW = password } { UIC = [uic-spec] } { USER = username } { } { TTnn: } { { } } [,...] {,} { {LOCAL } } { TERMINAL = {NONLOCAL } } { {BATCH } } { { } } { {NETWORK } } { {GRANT } {privilege-list } } { {DENY } = { } } [,...] { {BANISH } {ALL } } { { } } 3 Arguments path-name Is the given name, full dictionary path name, or relative dictionary path name of the dictionary object or dictionary directory whose ACL list you want to change. DEFINEP accepts both DMU and CDO style path names. sequence-number Is the sequence number of the entry to be added to the ACL. This number must be an unsigned, nonzero integer. PW = password Specifies a password to be appended to the given name of the dictionary object or dictionary directory when used alone in a command or statement or as part of a full or relative dictionary path name. You can specify a password in an ACL entry on a directory or object either in the DMU or in the CDO format dictionary. UIC = [uic-spec] Specifies the UIC or group of UICs to which the added ACL entry applies. The UIC specification must be enclosed in square brackets and must conform to the OpenVMS rules for specifying UICs (see the OpenVMS documentation set). You can specify numeric and alphanumeric UICs and rights identifiers. (A rights identifier is a single text string enclosed in brackets. The system manager defines a rights identifier in the system rights database. The identifier indicates all members of a particular group.) USER = username Specifies the OpenVMS user name to which the added ACL entry applies. Do not put the user name in parentheses or brackets. LOCAL TERMINAL = NONLOCAL BATCH NETWORK Specifies a particular terminal or a type of terminal to which the added ACL entry applies. o TTnn: is the number of a specific terminal line to which the added ACL entry applies. You can specify a particular terminal only in ACL entries in the DMU format dictionary. o LOCAL specifies that the added ACL entry applies to all terminals hard-wired to your local system. o NONLOCAL specifies that the added ACL entry applies to the local system's dial-up terminal lines, to batch jobs on the local system, to remote terminals logged in to the system by DECnet, and to processes initiated by a DEC DATATRIEVE Distributed Data Manipulation Facility (DDMF) on a remote node in a network of Digital computers. o BATCH specifies that the added ACL entry applies to all batch jobs run on the local system. o NETWORK specifies that the added ACL entry applies to all processes initiated by a DEC DATATRIEVE Distributed Data Manipulation Facility (DDMF) on a remote node in a network of Digital computers. , (comma) Separates user identification criteria and privilege specifications. GRANT Specifies the privileges granted by the added ACL entry. DENY Specifies the privileges denied by the added ACL entry. BANISH Specifies, for a dictionary directory and all its descendants, the access privileges that the entry denies and the privileges that no ACL of any of the descendants can grant. The BANISH clause is valid in ACL entries either in the DMU or in the CDO format dictionary. privilege-list Is a letter or string of letters, each one of which is the abbreviation for the access privilege granted, denied, or banished by the added ACL entry. 3 Example The following example defines an ACL entry for a DMU format dictionary directory that uses all the user identification criteria and all the privilege specifications: DTR> DEFINEP FOR MONTHLY_DATA 1 PW = "SECRET", USER = JONES, [Looking for define privilege option] CON> UIC = [240,240], TERMINAL = NETWORK, GRANT = PSRWME, [Looking for define privilege option] CON> DENY = CDUXH, BANISH = FG DTR> 2 DELETE_Command Deletes one or more dictionary objects and their access control lists from the Oracle CDD/Repository data dictionary system. Format DELETE path-name-1 [,...] ; 3 Arguments path-name Is the given name, full dictionary path name, or relative path name of the dictionary object you want to remove from the data dictionary system. DELETE accepts both DMU and CDO style path names. If you specify more than one dictionary path name, separate each path name from the next with a comma. ; (semicolon) Ends the DELETE command. 3 Examples The following example shows how to delete two domain versions from your default dictionary: DTR> SHOW DOMAINS Domains: * YACHTS;4 * YACHTS;3 * YACHTS;2 * YACHTS;1 The following example does not specify a version number, so DEC DATATRIEVE deletes the highest version, YACHTS;4. DTR> DELETE YACHTS; DTR> SHOW DOMAINS Domains: * YACHTS;3 * YACHTS;2 * YACHTS;1 DTR> DELETE YACHTS;2; DTR> SHOW DOMAINS Domains: * YACHTS;3 * YACHTS;1 2 DELETEP_Command Deletes an entry from the access control list (ACL) of an object or directory in the data dictionary system. Format DELETEP path-name sequence-number 3 Arguments path-name Is the dictionary path name of the object or directory whose ACL you want to change. DELETEP accepts both DMU and CDO style path names. sequence-number Is a nonzero integer indicating the entry's position in the ACL. 3 Example The following example shows the ACL of the DMU YACHTS domain and deletes an entry from it: DTR> SHOWP YACHTS 1: [*,*], Username: "STARKEY" Grant - CDEFGHMPRSUWX, Deny - none, Banish - none 2: [*,*], Username: "DUNCAN" Grant - EHMPRSUW, Deny - CDFGX, Banish - none 3: [*,*], Username: "HARRISON" Grant - CDEFGHMPRSUWX, Deny - none, Banish - none 4: [*,*] Grant - none, Deny - CDEFGHMPRSUWX, Banish - none DTR> DELETEP YACHTS 2 DTR> SHOWP YACHTS 1: [*,*], Username: "STARKEY" Grant - CDEFGHMPRSUWX, Deny - none, Banish - none 2: [*,*], Username: "HARRISON" Grant - CDEFGHMPRSUWX, Deny - none, Banish - none 3: [*,*] Grant - none, Deny - CDEFGHMPRSUWX, Banish - none DTR> See the chapter on ACL in the DEC DATATRIEVE User's Guide for other examples of working with ACLs. 2 DISCONNECT_Statement Removes records from the sets you specify in the TO list of the CONNECT statement. The DISCONNECT statement can be used only for sets in which Oracle CODASYL DBMS retention is optional. Format DISCONNECT context-name-1 [FROM] set-name-1 [,...] 3 Arguments context-name-1 Is the name of a valid context variable or the name of a collection with a selected record. The target record must be a member of the specified sets. set-name Is the name of a Oracle CODASYL DBMS set. 3 Examples The following example removes a part with a specified PART_ID from its membership in the set ALL_PARTS_ACTIVE: DTR> FOR P IN PART WITH PART_ID = "TU4722AS" CON> DISCONNECT P FROM ALL_PARTS_ACTIVE DTR> The following example removes the group named PLANT ENGINEERING from the set MANAGES: DTR> FIND GROUPS WITH GROUP_NAME = "PLANT ENGINEERING" DTR> SELECT DTR> DISCONNECT CURRENT FROM MANAGES DTR> 2 DISPLAY_Statement Displays the value of a single DEC DATATRIEVE value expression. The value displayed is not formatted by any edit string associated with the value expression. Format DISPLAY value-expression 3 Argument value-expression Is a DEC DATATRIEVE value expression. 3 Examples The following example shows how to declare a numeric variable with a money edit string, give it a value, and use both the PRINT statement and the DISPLAY statement to display that value: DTR> DECLARE SALARY PIC Z(5)9V99 EDIT_STRING $$$$$$.99. DTR> SALARY = 15753.67 DTR> PRINT SALARY SALARY $15753.67 DTR> DISPLAY SALARY DISPLAY: 15753.67 DTR> The following example redeclares the above variable as a character variable, assigns a new value, and displays that value: DTR> DECLARE SALARY PIC X(15). DTR> SALARY = "MUCH TOO LOW" DTR> PRINT SALARY SALARY MUCH TOO LOW DTR> DISPLAY SALARY DISPLAY: MUCH TOO LOW The following example displays the group fields TYPE and SPECS from the domain YACHTS: DTR> READY YACHTS DTR> FIND FIRST 1 YACHTS [1 Record found] DTR> SELECT; PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBERG 37 MK II KETCH 37 20,000 12 $36,951 DTR> DISPLAY TYPE DISPLAY: ALBERG 37 MK II DTR> DISPLAY SPECS DISPLAY: KETCH 37 200001236951 DTR> 2 DISPLAY_FORM_Statement Lets you display data on a form and collect data from a VAX TDMS or DEC FMS form. Format DISPLAY_FORM form-name IN file-name [USING statement-1] [RETRIEVE [USING] statement-2] 3 Arguments form-name Is the name of the VAX TDMS or DEC FMS form to be used with the domain. file-name Is the file specification of the form library file containing the form. File-name can be a VAX TDMS request library file or an DEC FMS forms library. The default file type for VAX TDMS request library files is .RLB; the default file type for DEC FMS form libraries is .FLB. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version statement-1 Is a DEC DATATRIEVE statement or a series of statements within a BEGIN-END block. Statement-1 can include one or more PUT_FORM assignment statements for assigning values to fields on a form. The PUT_FORM statement has the following format: PUT_FORM form-field = value-expression form-field Is the name of a field in a form. value-expression Is any DEC DATATRIEVE value expression. statement-2 Is a DEC DATATRIEVE statement or a series of statements within a BEGIN-END block. Statement-2 can include GET_FORM value expressions for assigning values on a form to DEC DATATRIEVE fields or variables. The GET_FORM value expression has the following format: GET_FORM form-field form-field Is the name of a field in a form. 3 Examples The following example shows that you can display a form for a domain even if the form was not specified in the domain definition: DTR> DISPLAY_FORM YACHTF IN FORMSLIB; The following example displays the MANUFACTURER and MODEL fields on a form for the first five records of YACHTS: DTR> FOR FIRST 5 YACHTS CON> DISPLAY_FORM YACHTF IN FORMSLIB USING CON> BEGIN CON> PUT_FORM MANUFA = MANUFACTURER CON> PUT_FORM MODEL = MODEL CON> END; The following example displays the MANUFACTURER and MODEL fields on a form for the first record of YACHTS and assigns the values to two variables, BUILT and MODELLER: DTR> DECLARE BUILT PIC X(10). DTR> DECLARE MODELLER PIC X(10). DTR> FOR FIRST 1 YACHTS CON> DISPLAY_FORM BOATS IN [MORRIS]DTR32.FLB USING CON> BEGIN CON> PUT_FORM MANUFA = MANUFACTURER CON> PUT_FORM MODEL = MODEL CON> END RETRIEVE USING CON> BEGIN CON> BUILT = GET_FORM MANUFA CON> MODELLER = GET_FORM MODEL CON> END DTR> PRINT BUILT BUILT ALBERG DTR> PRINT MODELLER MODELLER 37 MK II DTR> You can use a form to store and modify values for selected fields. You can also associate more than one form with a single domain. See the DEC DATATRIEVE Guide to Interfaces for more examples. 2 DROP_Statement Removes the selected record from a collection, but does not remove that record from the data file in which it resides. Format DROP [collection-name] 3 Argument collection-name Is the name of a collection. If the DROP statement does not contain this argument, it affects the CURRENT collection. 3 Example In the following example, a record is stored in YACHTS and a series of collections is formed. The DROP statement is illustrated using the SELECT, DROP, ERASE, and PRINT statements and the SHOW collection-name command: DTR> READY YACHTS WRITE DTR> STORE YACHTS USING BUILDER = "HINKLEY", DTR> FIND YACHTS WITH BUILDER = "HINKLEY" [1 record found] DTR> FIND A IN CURRENT [1 record found] DTR> FIND B IN YACHTS [114 records found] DTR> SELECT B; PRINT B.BOAT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBERG 37 MK II KETCH 37 20,000 12 $36,951 DTR> FIND C IN YACHTS [114 records found] DTR> SELECT LAST; PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE WRIGHT SEAWIND II SLOOP 32 14,900 00 $34,480 DTR> SHOW C Collection C Domain: YACHTS Number of Records: 114 Selected Record: 114 DTR> DROP DTR> SHOW C Collection C Domain: YACHTS Number of Records: 114 Selected Record: 114 (Dropped) DTR> PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBERG 37 MK II KETCH 37 20,000 12 $36,951 DTR> DROP Target record has already been dropped. DTR> SHOW B Collection B Domain: YACHTS Number of Records: 114 Selected Record: 1 DTR> DROP B DTR> SHOW B Collection B Domain: YACHTS Number of Records: 114 Selected Record: 1 (Dropped) DTR> RELEASE C DTR> DROP Target record has already been dropped. DTR> ERASE No target record for ERASE. DTR> RELEASE B DTR> PRINT No record selected, printing whole collection LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE HINKLEY 0 00 DTR> DROP No collection with selected record for DROP. DTR> SHOW CURRENT Collection A Domain: YACHTS Number of Records: 1 No Selected Record DTR> SELECT; ERASE; SHOW CURRENT Collection A Domain: YACHTS Number of Records: 1 Selected Record: 1 (Erased) DTR> DROP No collection with selected record for DROP. DTR> 2 EDIT_Command Invokes an editor to edit the previous command or statement, one or more types of object definitions, or the dictionary object specified by the dictionary path name. Format [ {DOMAINS } ] [ {PLOTS } ] [ { } ] [ [ALL] {PROCEDURES } [,...] [RECOVER] ] [ {RECORDS } ] EDIT [ {TABLES } ] [ ] [ ] [ ALL [RECOVER] ] [ ] [ [path-name] [RECOVER] ] [ ] 3 Arguments ALL Places all the objects in your Oracle CDD/Repository default directory in an editing buffer. The keyword ALL is optional when used with the object types, but required when used alone or with only RECOVER. path-name Is the given name, full dictionary path name, or relative path name of a DEC DATATRIEVE domain, record, procedure, or table definition you want to edit. EDIT accepts both DMU and CDO style path names. DOMAINS You can specify one or more types of object definitions with the EDIT command. This allows you to edit all the domains, plots, procedures, records, or tables from your current default Oracle CDD/Repository directory. RECOVER Allows recovery for edited dictionary objects. 3 Example The following example shows how to edit the definition for the record YACHT: DTR> EDIT YACHT REDEFINE RECORD YACHT USING 01 BOAT. 03 TYPE. 06 MANUFACTURER PIC X(10) QUERY_NAME IS BUILDER. 06 MODEL PIC X(10). 03 SPECIFICATIONS QUERY_NAME SPECS. 06 RIG PIC X(6) VALID IF RIG EQ "SLOOP","KETCH","MS","YAWL". 06 LENGTH_OVER_ALL PIC XXX VALID IF LOA BETWEEN 15 AND 50 QUERY_NAME IS LOA. 06 DISPLACEMENT PIC 99999 QUERY_HEADER IS "WEIGHT" EDIT_STRING IS ZZ,ZZ9 QUERY_NAME IS DISP. 06 BEAM PIC 99 MISSING VALUE IS 0. 06 PRICE PIC 99999 MISSING VALUE IS 0 VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 EDIT_STRING IS $$$,$$$. ; [Record is 41 bytes long.] You can now edit the record definition. If SET EDIT_BACKUP is in effect, the old version of the YACHT record is retained in the data dictionary when you exit the editor. 2 EDIT_STRING_Clause Specifies the output format of a field value. Format EDIT_STRING [IS] edit-string 3 Argument edit-string Is one or more edit string characters describing the output format of the field value. 2 END_REPORT_Statement_(Report_Writer) Ends the report specification. Format END_REPORT 3 Example For examples of report specifications, see the chapters on writing reports in the DEC DATATRIEVE User's Guide. 2 ERASE_Statement Permanently removes one or more data records from an indexed or relative data file, a Oracle CODASYL DBMS database, or a relational database. Format ERASE [ALL [OF rse] ] 3 Arguments ALL Causes DEC DATATRIEVE to permanently remove from the data file every record in the current collection. ALL OF rse Causes DEC DATATRIEVE to permanently remove from the data file every record identified by the record selection expression. 3 Examples The following example shows how to erase all the yachts built by Albin: DTR> FIND YACHTS WITH BUILDER EQ "ALBIN" [3 records found] DTR> ERASE ALL In the following example, a procedure is defined that erases selected yachts: DTR> DEFINE PROCEDURE SELL_BOAT DFN> FIND YACHTS WITH BUILDER EQ *.BUILDER AND DFN> MODEL = *.MODEL DFN> PRINT ALL DFN> IF *."Y IF BOAT SOLD" CONT "Y" THEN ERASE ALL DFN> END_PROCEDURE DTR> 2 EXIT_Command Ends a DEC DATATRIEVE session. Format { EXIT } { CTRL/Z} { } 3 Parameters None. 3 Examples The following example shows how to end a DEC DATATRIEVE session: DTR> EXIT $ The following example shows the result of entering CTRL/Z to the Enter prompt of a STORE statement: DTR> READY YACHTS WRITE DTR> STORE YACHTS Enter MANUFACTURER: Execution terminated by operator DTR> 2 EXTRACT_Command Copies the Oracle CDD/Repository data dictionary definition of one or more dictionary objects or types of object definitions to a command file. Format { {DOMAINS } } { {PLOTS } } { [ALL] {PROCEDURES } [,...] [ON] file-spec } { { } } { {RECORDS } } { {TABLES } } EXTRACT { } { ALL [ON] file-spec } { } { } { [ON] file-spec path-name [,...] } { } { } { path-name [,...] [ON] file-spec } 3 Arguments ALL Causes DEC DATATRIEVE to copy into the specified command file the definitions of one or more dictionary objects in your default dictionary directory. The keyword ALL is optional when used with the types of object definitions such as PLOTS or DOMAINS. The keyword ALL is required, however, when used with the EXTRACT ALL [ON] file-spec syntax. DOMAINS Allows you to extract all the domains, plots, procedures, records, or tables from your current default Oracle CDD/Repository directory. file-spec Is the OpenVMS specification of the RMS file to contain the definitions. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version path-name Is the given name, full dictionary path name, or relative path name of the dictionary object whose definition you want to copy. If you specify more than one dictionary path name, use a comma to separate each one from the next. EXTRACT accepts both DMU and CDO style path names. 3 Example Extract all the definitions in a dictionary directory to create a backup file: DTR> EXTRACT ALL ON BAKUP1 DTR> 2 FIND_Statement Establishes a collection of records from a domain, view, collection, or list. The collection formed with the FIND statement becomes the current collection. Format FIND rse 3 Argument rse Is a record selection expression specifying the records to be included in the collection. 3 Examples The following example forms a collection of yachts longer than 30 feet and gives the collection the name BIG-ONES: DTR> FIND BIG-ONES IN YACHTS WITH LOA GT 30 [57 records found] DTR> The following example forms a collection of the 10 most expensive yachts: DTR> FIND FIRST 10 YACHTS SORTED BY DESC PRICE [10 records found] DTR> 2 FINISH_Command Ends your access to domains, domain tables, relations, and Oracle CODASYL DBMS records. The FINISH command also releases any collections associated with the domains. For Oracle CODASYL DBMS, when the last Oracle CODASYL DBMS domain or record is finished, collections are purged, a commit with no retention is performed, and databases are unbound. The last FINISH commits all Oracle CODASYL DBMS databases. A commit is not done until you finish the last Oracle CODASYL DBMS record or domain. For relational sources, when the last domain or relation is finished, a commit is performed and no collections are retained. Format [ ALL ] [ [ domain-name ] ] FINISH [ [ ] [,...] ] [ [ dbms-record-name ] ] [ [ rdb-relation-name ] ] [ ] 3 Arguments ALL Ends your control over all readied domains, relations, Oracle CODASYL DBMS records, and all domain or dictionary tables loaded in your workspace. domain-name Is the given name of a readied domain or domain table you want to finish. If you specify the names of more than one domain or domain table, separate each from the next with a comma (,). rdb-relation-name Is the given name of a readied relation you want to finish. If you specify the names of more than one relation, separate each from the next with a comma (,). dbms-record-name Is the given name of a Oracle CODASYL DBMS record readied with the READY database command. If you specify the names of more than one record, separate each from the next with a comma (,). 3 Example The following example releases control of the domain YACHTS: DTR> SHOW READY Ready sources: YACHTS: Domain, RMS indexed, protected read No loaded tables. DTR> FINISH YACHTS DTR> SHOW READY No ready sources. No loaded tables. DTR> 2 FOR_Statement Causes DEC DATATRIEVE to execute a statement or group of statements once for each record in the record stream formed by a record selection expression (RSE). The FOR statement provides repeating loops for DEC DATATRIEVE operations. Format FOR rse statement 3 Arguments rse Is a record selection expression that forms the record stream that controls the number of times DEC DATATRIEVE executes the statement and controls the single-record context for the statement. statement Is either a simple or a compound statement you want DEC DATATRIEVE to execute once for each record in the record stream formed by the RSE. You can form compound DEC DATATRIEVE statements with the BEGIN-END, IF-THEN-ELSE, and THEN statements, which are described in this chapter. 3 Examples The following example assigns a value to the field PRICE for three yachts with prices equal to zero: DTR> READY YACHTS MODIFY DTR> SET NO PROMPT DTR> FIND FIRST 3 A IN YACHTS WITH PRICE = 0 [3 records found] DTR> PRINT A LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE BLOCK I. 40 SLOOP 39 18,500 12 BUCCANEER 270 SLOOP 27 5,000 08 BUCCANEER 320 SLOOP 32 12,500 10 DTR> FOR A CON> MODIFY USING PRICE = DISP * 1.3 + 5000 DTR> PRINT A LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE BLOCK I. 40 SLOOP 39 18,500 12 $29,050 BUCCANEER 270 SLOOP 27 5,000 08 $11,500 BUCCANEER 320 SLOOP 32 12,500 10 $21,250 DTR> The following example uses a variable to force an end to a FOR loop before all records in the record stream have been acted upon: DTR> READY YACHTS DTR> DECLARE A PIC 9. DTR> PRINT A A 0 DTR> SET NO PROMPT DTR> FOR YACHTS CON> BEGIN CON> A = A + 1 CON> PRINT A, BOAT CON> IF A = 5 THEN ABORT "END OF LOOP" CON> END LENGTH OVER A MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 1 ALBERG 37 MK II KETCH 37 20,000 12 $36,951 2 ALBIN 79 SLOOP 26 4,200 10 $17,900 3 ALBIN BALLAD SLOOP 30 7,276 10 $27,500 4 ALBIN VEGA SLOOP 27 5,070 08 $18,600 5 AMERICAN 26 SLOOP 26 4,000 08 $9,895 ABORT: END OF LOOP DTR> The following example contains a SORTED BY clause that allows the FOR loop to select records according to their length. The context variable X identifies the record stream in the FOR statement. DTR> READY YACHTS DTR> FOR FIRST 4 X IN YACHTS SORTED BY LOA CON> PRINT BUILDER, LOA LENGTH OVER MANUFACTURER ALL WINDPOWER 16 CAPE DORY 19 ENCHILADA 20 VENTURE 21 DTR> The following example uses nested FOR loops to increase by one year the age of each child in the first two records of the domain FAMILIES: DTR> READY FAMILIES MODIFY DTR> PRINT FIRST 2 FAMILIES NUMBER KID FATHER MOTHER KIDS NAME AGE JIM ANN 2 URSULA 7 RALPH 3 JIM LOUISE 5 ANNE 31 JIM 29 ELLEN 26 DAVID 24 ROBERT 16 DTR> SET NO PROMPT DTR> FOR FIRST 2 FAMILIES CON> FOR KIDS CON> MODIFY USING AGE = AGE + 1 DTR> PRINT FIRST 2 FAMILIES NUMBER KID FATHER MOTHER KIDS NAME AGE JIM ANN 2 URSULA 8 RALPH 4 JIM LOUISE 5 ANNE 32 JIM 30 ELLEN 27 DAVID 25 ROBERT 17 2 HELP_Command Provides on-line information about the use of DEC DATATRIEVE commands, statements, and language elements. Format { HELP } { ? } [ERROR] [topic][...] { } 3 Arguments ERROR Provides additional information on the last error message that you received. topic Is a DEC DATATRIEVE command, statement, statement element, or error. Use commas to separate each topic from the next. . . . (ellipsis) Indicates that all help subtopics and any of their subtopics should be displayed. ? (question mark) Is a synonym for HELP. 3 Examples The following example shows how to ask for a list of the help that is available: DTR> HELP The following example shows how to ask for help on the screen- oriented Help facility: DTR> HELP VIDEO The following example shows how to ask for help on the last error message you received. For example, if you use the SORT statement without first forming a collection, DEC DATATRIEVE displays an error message: DTR> READY YACHTS DTR> SORT BY LOA No collection for sort. You can issue the HELP ERROR command to find out the reason for the error message, possible actions to correct the error, and how to obtain more on-line information: DTR> HELP ERROR No collection for sort. ERROR_MESSAGES Errors NOCOLSOR 008D8352 No collection for sort. Explanation: You can use the SORT statement only with an established collection. User Action: Use the SORTED BY clause in an RSE to order records not contained in an established collection. For example: PRINT EMPLOYEES SORTED BY LAST_NAME. You can also use the SORTED BY clause in the RSE of the FIND statement to order records when a collection is being created. In addition, you can use a SORT statement to reorder records after the collection is created. 2 IF_THEN_ELSE_Statement Causes DEC DATATRIEVE to execute one of two statements or compound statements, depending on the evaluation of a conditional (Boolean) expression. Format IF boolean-expression [THEN] statement-1 [ELSE statement-2] 3 Arguments boolean-expression Is a Boolean expression. THEN Is an optional language element you can use to clarify syntax. statement-1 Is a simple or compound statement you want DEC DATATRIEVE to execute if the Boolean expression evaluates to true. ELSE statement-2 Specifies the statement you want DEC DATATRIEVE to execute if the Boolean expression evaluates to false. 3 Examples The following example shows how to print each yacht built by Pearson, and modify the price if you want to: DTR> SET NO PROMPT DTR> READY YACHTS WRITE DTR> FOR YACHTS WITH BUILDER = "PEARSON" CON> BEGIN CON> PRINT CON> IF *."Y TO MODIFY PRICE, N TO SKIP" CONT "Y" CON> THEN MODIFY PRICE ELSE CON> PRINT "NO CHANGE" CON> IF *."Y TO CONTINUE" NOT CONT "Y" THEN CON> ABORT "END OF PRICE CHANGES" CON> END LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE PEARSON 10M SLOOP 33 12,441 11 Enter Y TO MODIFY PRICE, N TO SKIP: N NO CHANGE Enter Y TO CONTINUE, N TO ABORT: Y PEARSON 26 SLOOP 26 5,400 08 Enter Y TO MODIFY PRICE, N TO SKIP: N NO CHANGE Enter Y TO CONTINUE, N TO ABORT: N ABORT: END OF PRICE CHANGES DTR> In the following example the IF statement is used to select families with fathers named Jim and list the children in those families: DTR> READY FAMILIES DTR> FOR FAMILIES WITH ANY KIDS CON> IF FATHER EQ "JIM" THEN CON> PRINT "The Kids of JIM and"|||MOTHER, CON> ALL KID_NAME ("Kids with Fathers"/ CON> "Named Jim") OF KIDS, SKIP Kids with Fathers Named Jim The Kids of JIM and ANN URSULA RALPH The Kids of JIM and LOUISE ANNE JIM ELLEN DAVID ROBERT DTR> 2 LIST_Statement Causes DEC DATATRIEVE to format and write to your terminal, to a file, or to a unit record device one or more values of implied or specified fields from records in one or more readied domains. Format For retrieving from selected records and target record streams formed by FOR loops: [ {file-spec } ] LIST [print-list] [ ON {*.prompt } ] [ { } ] For retrieving from the current collection: [ {file-spec } ] LIST ALL [print-list] [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the LIST statement using one RSE: [ {file-spec } ] LIST [print-list OF] rse [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the LIST statement using two RSEs (the inner print list follows another print list): LIST print-list, ALL print-list OF rse-1 [,print-list] OF rse-2 [ {file-spec } ] [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the LIST statement using two RSEs (the inner print list precedes any other print list): LIST ALL ALL print-list OF rse-1 [,print-list] OF rse-2 [ {file-spec } ] [ ON {*.prompt } ] [ { } ] 3 Arguments print-list Is a list of field names; it can also include only the print list elements SKIP, NEW_PAGE, and inner print lists. You can control the format in which DEC DATATRIEVE displays values from the specified fields with the USING edit-string modifiers described in the Results section of the PRINT command section. ALL When used alone following LIST, causes the records in the current collection to be displayed or written to the specified file or device. When used with a print list, ALL causes the print list to be evaluated for each record in the current collection. When used with the OF rse clause, ALL is optional. You can use it to clarify the LIST statement, but, regardless of the presence of ALL, DEC DATATRIEVE evaluates the LIST statement once for each record in the record stream formed by the RSE. When the print list begins with an inner print list, ALL is required to establish the proper context in which to resolve references to the items in the hierarchical list. rse Is a record selection expression that creates the record stream DEC DATATRIEVE uses to evaluate the elements of the print list. file-spec Is the file specification to which you want to write the output of the statement. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version *.prompt-name Is a prompting value expression that prompts you for a device name or file specification to which you want to write the output of the statement. 3 Examples The following example lists three records from YACHTS: DTR> READY YACHTS DTR> LIST FIRST 3 YACHTS MANUFACTURER : ALBERG MODEL : 37 MK II RIG : KETCH LENGTH_OVER_ALL : 37 DISPLACEMENT : 20,000 BEAM : 12 PRICE : $36,951 MANUFACTURER : ALBIN MODEL : 79 RIG : SLOOP LENGTH_OVER_ALL : 26 DISPLACEMENT : 4,200 BEAM : 10 PRICE : $17,900 MANUFACTURER : ALBIN MODEL : BALLAD RIG : SLOOP LENGTH_OVER_ALL : 30 DISPLACEMENT : 7,276 BEAM : 10 PRICE : $27,500 The following example lists the first two records in FAMILIES: DTR> READY FAMILIES DTR> LIST FIRST 2 FAMILIES FATHER : JIM MOTHER : ANN NUMBER_KIDS : 2 KID_NAME : URSULA AGE : 7 KID_NAME : RALPH AGE : 3 FATHER : JIM MOTHER : LOUISE NUMBER_KIDS : 5 KID_NAME : ANNE AGE : 31 KID_NAME : JIM AGE : 29 KID_NAME : ELLEN AGE : 26 KID_NAME : DAVID AGE : 24 KID_NAME : ROBERT AGE : 16 DTR> 2 MATCH_Statement Relates two list names with their subordinate elementary fields, so that data from the second list can be stored in the first list. Format MATCH list-rse-1, list-rse-2 statement 3 Arguments list-rse-1 Is an RSE containing a list name from the record definition of the domain that is to receive the data. list-rse-2 Is an RSE containing a list name from the record definition of the source domain for the data. statement Is a DEC DATATRIEVE Assignment statement or series of Assignment statements enclosed by a BEGIN-END block. 3 Example Consider the following record definition for the domain FAM: DTR> SHOW FAM_REC RECORD FAM_REC USING 01 FAMILY. 03 PARENTS. 06 FATHER PIC X(10). 06 MOTHER PIC X(10). 03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 03 KIDS_N OCCURS 10 TIMES. 06 EACH_KID. 09 KID_NAME PIC X(10) QUERY_NAME IS KID. 03 KIDS_A OCCURS 10 TIMES. 06 EACH_KID. 09 AGE PIC 99 EDIT_STRING IS Z9. ; The fixed-length list format means that values are displayed for 10 KIDS_N and 10 KIDS_A, no matter what the value for NUMBER_ KIDS. In displays and reports, this means that most FAM records would be separated by strings of blanks (for "empty" occurrences of KIDS_N) and zeros (for "empty" occurrences of KIDS_A). DTR> PRINT FAM NUMBER KID FATHER MOTHER KIDS NAME AGE JIM ANN 2 URSULA 7 RALPH 3 0 0 0 0 0 0 0 0 JIM LOUISE 5 ANNE 31 JIM 29 ELLEN 26 DAVID 24 ROBERT 16 0 0 0 0 0 . . . . . . . . . To improve display and report formats for this domain, you could restructure it using the MATCH statement so that it contains one variable-length list field. In other words, the modified record definition would look like the current one for the FAMILIES domain. DTR> SHOW FAMILY_REC RECORD FAMILY_REC 01 FAMILY. 03 PARENTS. 06 FATHER PIC X(10). 06 MOTHER PIC X(10). 03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS. 06 EACH_KID. 09 KID_NAME PIC X(10) QUERY_NAME IS KID. 09 AGE PIC 99 EDIT_STRING IS Z9. ; If you attempted to restructure FAM without using the MATCH statement, DEC DATATRIEVE would not store the list elements. This problem occurs because the modified record definition combines two list fields into one. Therefore, to restructure the FAM domain, you must use the MATCH statement within a STORE statement that is controlled by a FOR loop. The following series of statements stores the data from the records in FAM into the records in FAMILIES and then prints the results: DTR> READY FAM DTR> DEFINE FILE FOR FAMILIES DTR> READY FAMILIES WRITE DTR> FOR FAM CON> STORE FAMILIES USING CON> BEGIN CON> PARENTS = PARENTS CON> NUMBER_KIDS = NUMBER_KIDS CON> MATCH KIDS, KIDS_N CON> KID_NAME = KID_NAME CON> MATCH KIDS, KIDS_A CON> AGE = AGE CON> END DTR> PRINT FAMILIES NUMBER KID FATHER MOTHER KIDS NAME AGE JIM ANN 2 URSULA 7 RALPH 3 JIM LOUISE 5 ANNE 31 JIM 29 ELLEN 26 DAVID 24 ROBERT 16 . . . . . . . . . 2 MISSING_VALUE_Clause Designates a value for a field that DEC DATATRIEVE recognizes, not as the literal value, but as a marker that no value is stored in the field. DEC DATATRIEVE ignores fields containing the "missing value" marker when evaluating statistical expressions (AVERAGE, MAX, MIN, TOTAL, and STD_DEV). When you store a record and do not directly assign a value to a field with a MISSING VALUE defined, DEC DATATRIEVE uses the missing value to initialize the field if it contains no DEFAULT VALUE clause. Format MISSING [VALUE [IS]] literal 3 Arguments VALUE IS Are optional keywords you can use to clarify the syntax of the clause. literal Is either a numeric or character string literal. 3 Examples The following example defines a record that contains MISSING VALUE clauses: DTR> DEFINE DOMAIN THINGS USING THINGREC ON THINGS; DTR> DEFINE RECORD THINGREC USING DFN> 01 THINGS. DFN> 03 NUM PIC 9(5) DFN> MISSING VALUE IS 11111 DFN> EDIT_STRING IS ZZ,Z99?"***MISSING***". DFN> 03 STR PIC X(10) MISSING VALUE IS "EMPTY" DFN> EDIT_STRING IS X(10)?"***MISSING***". DFN> ; DTR> The following example defines a new domain based on YACHTS that uses a new missing value and a MISSING VALUE edit string: DTR> DEFINE DOMAIN YACHTS_PRICE_LIST USING YPL_REC ON YPL.DAT; DTR> DEFINE RECORD YPL_REC USING DFN> 01 BOAT. DFN> 03 TYPE. DFN> 05 BUILDER PIC X(10). DFN> 05 MODEL PIC X(8). DFN> 03 PRICE PIC 9(5) MISSING VALUE IS 0 DFN> EDIT_STRING $$$,$$$?"NOT LISTED". DFN> ; [Record is 23 bytes long.] DTR> DEFINE FILE FOR YACHTS_PRICE_LIST KEY = TYPE DTR> READY YACHTS_PRICE_LIST AS YPL WRITE DTR> READY YACHTS DTR> YPL = YACHTS WITH LOA GT 35 DTR> FIND YPL WITH PRICE MISSING [12 records found] DTR> PRINT FIRST 3 CURRENT BUILDER MODEL PRICE BLOCK I. 40 NOT LISTED CABOT 36 NOT LISTED DOWN EAST 38 NOT LISTED DTR> 2 MODIFY_Statement Changes the value of one or more fields in a selected record or in any or all records in a collection or record stream. Format 1 [ field-name [,...] ] MODIFY [ALL] [ USING statement-1 ] [ ] [VERIFY [USING] statement-2] [OF rse] Format 2 MODIFY [ALL] rse USING statement-1 [VERIFY [USING] statement-2] 3 Arguments ALL Specifies that you want to modify either all records in the CURRENT collection or all records in the record stream specified in the record selection expression (rse). field-name Specifies the name of a field in the target records you want to modify. If you specify more than one field name, use a comma to separate each field name from the next. DEC DATATRIEVE prompts you to supply a value for each field you specify. USING statement-1 Specifies a simple or compound DEC DATATRIEVE statement that assigns values to one or more fields in the target records you want to modify. This clause can also contain any other DEC DATATRIEVE statements, such as PRINT, STORE, and other MODIFY statements. VERIFY [USING] statement-2 Specifies a statement that DEC DATATRIEVE executes before modifying the target record. OF rse Is a record selection expression that forms a record stream of the records you want to modify. An OF rse clause is optional in format 1 of the MODIFY statement. In format 2, an rse without OF is required. 3 Examples The following example changes one field value in a selected record: DTR> READY YACHTS MODIFY DTR> FIND FAMILIES WITH FATHER = "JOHN" [2 records found] DTR> PRINT No record selected, printing whole collection. NUMBER KID FATHER MOTHER KIDS NAME AGE JOHN JULIE 2 ANN 29 JEAN 26 JOHN ELLEN 1 CHRISTOPHR 0 DTR> SELECT 1 DTR> MODIFY FATHER Enter FATHER: JON DTR> PRINT NUMBER KID FATHER MOTHER KIDS NAME AGE JON JULIE 2 ANN 29 JEAN 26 DTR> The following example makes a 10 percent increase in the price of the first five yachts. Each yacht begins and ends with a unique price, but the new price of each yacht is 10 percent greater than the old price of that same yacht. DTR> MODIFY FIRST 5 YACHTS USING PRICE = PRICE * 1.1 DTR> PRINT FIRST 5 YACHTS LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBERG 37 MK II KETCH 37 20,000 12 $40,646 ALBIN 79 SLOOP 26 4,200 10 $19,690 ALBIN BALLAD SLOOP 30 7,276 10 $30,250 ALBIN VEGA SLOOP 27 5,070 08 $20,460 AMERICAN 26 SLOOP 26 4,000 08 $10,885 DTR> 2 OCCURS_Clause The OCCURS clause defines multiple occurrences (or repetitions) of a field or group of fields. The multiple occurrences, called a list, create a hierarchy in the domain. The OCCURS clause has two formats: one format for a fixed number of occurrences and one for a variable number of occurrences. Each is described in the following sections. To define a fixed number of occurrences use the following format: OCCURS n TIMES To define a variable number of occurrences use the following format: OCCURS min TO max TIMES DEPENDING ON field-name 2 ON_Statement Sends the output of all indicated statements to the specified output file or device. Format { file-spec } ON { *.prompt } statement { } 3 Arguments file-spec Specifies the file to which you want to write the output of the statement. The file specification has the following format: node-spec::device:[directory]file-name.type;version statement Is a simple or compound statement you want DEC DATATRIEVE to execute and write the output to the specified file. *.prompt Is a prompting value expression that prompts you for a file specification to which you want to write the output of the statement. 3 Examples The following example shows how to search all yachts built by AMERICAN and print the TYPE, PRICE, and RIG for each sloop. For all yachts built by AMERICAN which are not sloops, a line is skipped and a message is printed. The output is written to an RMS file. Since an IF-THEN-ELSE statement is used and the same file name is specified in the THEN and ELSE clauses, DEC DATATRIEVE creates two versions of the file. DTR> FOR YACHTS WITH BUILDER = "AMERICAN" CON> IF RIG = "SLOOP" THEN CON> PRINT TYPE, PRICE, RIG ON BOAT.RNO ELSE CON> PRINT SKIP, "NOT A SLOOP" ON BOAT.RNO Creating file DB0:[MORRISON.REF]BOAT.RNO;1 ... Creating file DB0:[MORRISON.REF]BOAT.RNO;2 ... The content of BOAT.RNO;1 is as follows: MANUFACTURER MODEL PRICE RIG AMERICAN 26 $9,895 SLOOP The content of BOAT.RNO;2 is as follows: NOT A SLOOP However, if you use the ON statement, all of the data can be written to the same file as follows: DTR> ON SHIP.RNO CON> FOR YACHTS WITH BUILDER = "AMERICAN" CON> IF RIG = "SLOOP" THEN PRINT TYPE, PRICE, RIG ELSE CON> PRINT SKIP, "NOT A SLOOP" Creating file DB0:[MORRISON.REF]SHIP.RNO;1 ... The contents of SHIP.RNO is as follows: MANUFACTURER MODEL PRICE RIG AMERICAN 26 $9,895 SLOOP NOT A SLOOP The following example shows how to write the output of a LIST statement to three files and display the output. Data on every family with three children is included: DTR> ON FAM1.RNO CON> ON FAM2.RNO CON> ON FAM3.RNO CON> ON TT: CON> LIST FAMILIES WITH NUMBER_KIDS = 3 Creating file DB0:[MORRIS.REF]FAM1.RNO;1 ... Creating file DB0:[MORRIS.REF]FAM2.RNO;1 ... Creating file DB0:[MORRIS.REF]FAM3.RNO;1 ... Sending output to terminal TT. FATHER : GEORGE MOTHER : LOIS NUMBER_KIDS : 3 KID_NAME : JEFF AGE : 23 KID_NAME : FRED AGE : 26 KID_NAME : LAURA AGE : 21 FATHER : HAROLD MOTHER : SARAH NUMBER_KIDS : 3 KID_NAME : CHARLIE AGE : 31 KID_NAME : HAROLD AGE : 35 KID_NAME : SARAH AGE : 27 DTR> DEC DATATRIEVE sends the output to the terminal and creates the three files specified. All three files contain the data displayed on the terminal. 2 OPEN_Command Opens an RMS file to serve as a log of your interactive dialogue with DEC DATATRIEVE. DEC DATATRIEVE copies your input and the DEC DATATRIEVE output including error messages to the file exactly as displayed. Format OPEN file-spec 3 Argument file-spec Is the OpenVMS file specification of the file to be opened. The file specification must be in the following format: node-spec::device:[directory]file-name.type;version 3 Example This example opens a log file, displays the contents of a procedure, invokes the procedure, closes the log file with a CTRL/Z exit from DEC DATATRIEVE, and uses the OpenVMS TYPE command to display the contents of the log file: DTR> OPEN LOG DTR> !THIS IS A TEST OF THE OPEN COMMAND. DTR> READY YACHTS DTR> SHOW SELL_BOAT PROCEDURE SELL_BOAT FIND YACHTS WITH BUILDER EQ *.BUILDER AND MODEL EQ *.MODEL PRINT ALL IF *."Y IF BOAT SOLD" EQ "Y" THEN ERASE ALL ELSE PRINT "SELL IT NOW!" END_PROCEDURE DTR> :SELL_BOAT Enter BUILDER: ALBIN Enter MODEL: VEGA LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN VEGA SLOOP 27 5,070 08 $18,600 Enter Y IF BOAT SOLD: N SELL IT NOW! DTR> $ TYPE LOG.LIS DTR> !THIS IS A TEST OF THE OPEN COMMAND. DTR> READY YACHTS DTR> SHOW SELL_BOAT PROCEDURE SELL_BOAT FIND YACHTS WITH BUILDER EQ *.BUILDER AND MODEL EQ *.MODEL PRINT ALL IF *."Y IF BOAT SOLD" EQ "Y" THEN ERASE ALL PRINT "SELL IT NOW !" END_PROCEDURE DTR> :SELL_BOAT Enter BUILDER: ALBIN Enter MODEL: VEGA LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN VEGA SLOOP 27 5,070 08 $18,600 Enter Y IF BOAT SOLD: N SELL IT NOW! $ 2 PICTURE_Clause Specifies the format of the field value as it is stored. Format PIC[TURE] [IS] picture-string 3 Argument picture-string Is one or more picture-string characters describing the format in which the field value is stored. Picture-String Characters contains a list of the picture-string characters. The picture-string characters you specify for a field depend on the class of the field: alphabetic, alphanumeric, or numeric. Table 1-3 Picture-String Characters Field Picture Class Character Meaning Alphabetic A Each A represents one alphabetic character in the field. The following field definition specifies an alphabetic field of six characters: 06 LETTERS_ONLY PIC A(6). AlphanumericX Each X represents one character in the field. The following field definition specifies that the MODEL field contains 10 alphanumeric characters: 06 MODEL PIC X(10). Numeric 9 Each 9 represents one digit in the field. You can specify from 1 to 31 digits for a numeric field. The following field definition specifies that the BEAM field contains two digits: 03 BEAM PIC 99. S An S indicates that a sign (+ or -) is stored in the field. A picture string can have only one S and it must be the leftmost character. If there is no SIGN clause for the field, the sign shares the rightmost character position with the lowest-valued digit. The picture string S9(4) indicates a signed field, four digits in length; the field value can range from -9999 to +9999. V A V indicates an implied decimal point. The decimal point does not occupy a character position in the field, although DEC DATATRIEVE uses its location to align data in the field. A picture string can contain only one V. The picture string 9(5)V99 specifies a 7-digit field; the last two digits of the field value follow the decimal point. P Each P specifies a decimal scaling position. Each P represents a "distance" in digits from an implied decimal point. (A P does not count toward the limit of 31 digits per field.) A P can appear at the right or left of the picture string. A V is unnecessary for any picture string containing a P. 2 PLOT_Statement Each DEC DATATRIEVE plot statement uses the following general syntax. Format PLOT plotname [USING] [ALL] [arg [,arg]...] [OF rse] [ { file-spec } ] [ ON {*.prompt } ] [ { } ] 3 Arguments plotname Is the name of the plot, for example: DTR> PLOT BAR BAR is the name of the plot. Refer to the DEC DATATRIEVE User's Guide for plotname descriptions. USING Is an optional keyword to make the syntax more like English. The keyword USING does not affect the plot statement. ALL Is a keyword that may be optional or required, depending on the structure of the plot statement you use. It is optional if you use the OF rse clause; it is required if you use the current collection without any qualification. For example, the following two plot statements are the same: DTR> PLOT BAR BUILDER, PRICE OF YACHTS WITH CON> PRICE NE 0 DTR> FIND YACHTS WITH PRICE NE 0 DTR> PLOT BAR ALL BUILDER, PRICE The first example uses an OF rse clause in which the keyword ALL is not required. In the second example, ALL is required because it refers to the collection created in the FIND statement. In the syntax diagrams of the sections that follow, the keyword ALL is shown in brackets as an optional element. Note, however, that if you use the keyword ALL to refer to the contents of the current collection, ALL is required. arg Is a field name or other value expression. The argument can also contain an optional label string. To specify a label string, put a quoted string inside parentheses after the value expression. For example: DTR> PLOT X_Y LOA, CON> DISP / 2000 ("Weight in tons") OF YACHTS OF rse Specifies the record stream to be used in the plot. If you do not specify an RSE, the plot statement will use data from the current collection. ON { file-spec } { *.prompt } Specifies a device or file for output. If you do not specify a device or file specification, DEC DATATRIEVE displays the plot on your terminal screen. You can use a complete OpenVMS file specification or simply a file name. DEC DATATRIEVE uses .LIS as the default file type. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version You can also use a prompting value expression that prompts you for a file or device specification. For example: DTR> PLOT PIE ALL RIG ON DRA0:[IACOBONE]RIGPLOT.LIS DTR> PLOT PIE ALL RIG ON *."File Name or Device Specification" You can use the ON clause with any of the plot statements to create a file containing the ReGIS[TM] graphics commands. 3 Examples The following example produces a simple bar chart showing the salary for each employee in PERSONNEL: DTR> FIND PERSONNEL SORTED BY DEPT DTR> PLOT BAR ALL LAST_NAME, SALARY DTR> The following example plots a marsupial: DTR> PLOT WOMBAT DTR> 2 PRINT_Statements Causes DEC DATATRIEVE to format and write one or more values of specified or implied DEC DATATRIEVE value expressions to your terminal or workstation, to a file, or to a unit record device. Format For retrieving from selected records and target record streams formed by FOR loops: [ {file-spec } ] PRINT print-list [ ON {*.prompt } ] [ { } ] For retrieving from the current collection: [ {file-spec } ] PRINT ALL [print-list] [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the PRINT statement using one RSE: [ {file-spec } ] PRINT [print-list OF] rse [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the PRINT statement using two RSEs (the inner print list follows another print list): PRINT print-list, ALL print-list OF rse-1 [,print-list] OF rse-2 [ {file-spec } ] [ ON {*.prompt } ] [ { } ] For retrieving from record streams formed by the PRINT statement using two RSEs (the inner print list precedes any other print list): PRINT ALL ALL print-list OF rse-1 [,print-list] OF rse-2 [ {file-spec } ] [ ON {*.prompt } ] [ { } ] 3 Arguments print-list Is a list of value expressions and formatting specifications. ALL When used alone following PRINT, ALL causes the records in the current collection to be displayed or written to the specified file or device. When used with a print list, ALL causes the print list to be evaluated for each record in the current collection. When the print list begins with an inner print list, ALL is required to establish the proper context in which to resolve references to the items in the hierarchical list. rse Is a record selection expression that creates the record stream DEC DATATRIEVE uses to evaluate the elements of the print list. file-spec Is the file specification of the file to which you want to write the output of the statement. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version *.prompt-name Is a prompting value expression that prompts you for a file specification to which you want to write the output of the statement. 3 Examples The following example retrieves data from selected records and prints the data: DTR> FIND FIRST 2 YACHTS DTR> SELECT; PRINT TYPE, LOA, PRICE LENGTH OVER MANUFACTURER MODEL ALL PRICE ALBERG 37 MK II 37 $36,951 The following example shows how to retrieve data from target streams formed by FOR loops: DTR> FOR FIRST 2 YACHTS CON> PRINT TYPE, LOA, PRICE LENGTH OVER MANUFACTURER MODEL ALL PRICE ALBERG 37 MK II 37 $36,951 ALBIN 79 26 $17,900 DTR> The following example shows how to retrieve data from hierarchical records using nested FOR loops: DTR> FOR FIRST 2 FAMILIES CON> FOR KIDS CON> PRINT MOTHER, FATHER, KID_NAME KID MOTHER FATHER NAME ANN JIM URSULA ANN JIM RALPH LOUISE JIM ANNE LOUISE JIM JIM LOUISE JIM ELLEN LOUISE JIM DAVID LOUISE JIM ROBERT DTR> 2 PRINT_Statement_(Report_Writer) Specifies the following characteristics of the detail lines in a report: o The content, such as field values, other desired values, and text strings o The format of fields, including issues such as the order, column position, print attributes, and edit string format of print objects o Column headers for print objects You can include only one PRINT statement in a report specification. If your report specification contains an AT statement, then it does not have to contain a PRINT statement. Format PRINT print-list-element [, . . . ] 3 Argument print-list-element Specifies the values, position, print attributes, and format of the print objects in the detail line. Report Parameters Controlled by Print List Elements indicates the parameters of the report controlled by various print list elements. Table 1-4 Report Parameters Controlled by Print List Elements Print List Parameter Element Usage Notes Content Field-name Can include elementary, group, list, of [modifier] REDEFINES or COMPUTED BY fields; detail to print all fields, specify the line top-level field name. Related value- Derived from field values using expression arithmetic operators or RUNNING [modifier] TOTAL. Other value- Can include literals, variables, or expression RUNNING COUNT. [mod{fier] } Format ATT {RESET } Resets the attributes, or uses of {name } the named attribute list. (See the detail DECLARE_ATT statement.) line SKIP [n] Begins printing the next print list element n lines from the current line. See also Usage Notes. SPACE [n] Leaves spaces between the output of the preceding and following print list elements. See also Usage Notes. COL n Specifies where the output of the next print list element begins. See also Usage Notes. TAB [n] Inserts the space of n tab characters before the output of the next print list element. See also Usage Notes. Beginning NEW_PAGE Causes the Report Writer to start a of new report page. Ignored in DTIF new page Report Parameters Affected by Print List Modifiers indicates the parameters of the report controlled by modifiers of print list elements. Table 1-5 Report Parameters Affected by Print List Modifiers Print List Parameter Modifier Usage Notes Column ("header- Specifies one or two line headers headers segment"[ for the preceding field or value for / . . . ]) expression, overriding the field print name or query header from the record items definition. (-) Suppresses the header indicated for the field in the record definition. Format USING edit-string Imposes the characteristics of the of the edit string on the preceding field detail name or value expression. line item WIDTH [n] Specifies the length of the string field. See also Usage Notes. 3 Example For examples of the PRINT statement in the Report Writer, see the DEC DATATRIEVE User's Guide. 2 PURGE_Command Deletes all but the highest version of specified dictionary objects. Format [ path-name [,...] ] PURGE [ ALL ] [KEEP [=] n] [ ] 3 Arguments path-name Specifies the object you want to purge. The path name must include the name of a domain, record, procedure, or table. The path name cannot contain a version number or a semicolon. If you do not specify a path name, DEC DATATRIEVE purges all objects in your default dictionary directory. PURGE accepts both DMU and CDO style path names. ALL Purges all the definitions in the default dictionary directory. ALL is the default. KEEP [=] n Specifies the number of versions of each object you want to keep. The number must be greater than zero. The default is KEEP=1. 3 Examples The following example shows how PURGE deletes all but the highest versions of objects in a user's DMU format directory: DTR> SHOW ALL Domains: * FAMILIES;3 * FAMILIES;2 * FAMILIES;1 * OWNERS;2 * OWNERS;1 * PETS;2 * PETS;1 * PROJECTS;3 * PROJECTS;2 * PROJECTS;1 * YACHTS;5 * YACHTS;4 Records: * FAMILY_REC;2 * FAMILY_REC;1 * OWNER_RECORD;2 * OWNER_RECORD;1 * PET_REC;1 * PROJECT_REC;1 * YACHT;2 * YACHT;1 The default directory is CDD$TOP.DTR$USERS.BELL No established collections. No ready sources. No loaded tables. DTR> PURGE DTR> SHOW DOMAINS, RECORDS Domains: * FAMILIES;3 * OWNERS;2 * PETS;2 * PROJECTS;3 * YACHTS;5 Records: * FAMILY_REC;2 * OWNER_RECORD;2 * PET_REC;1 * PROJECT_REC;1 * YACHT;2 DTR> The following example shows the error message generated if you specify a dictionary directory as the final object in the path name. It then shows how PURGE works with the path name and KEEP arguments. DTR> SHOW DICTIONARY The default directory is CDD$TOP.DTR$USERS.BELL DTR> PURGE CDD$TOP.DTR$USERS.BELL Element "CDD$TOP.DTR$USERS.BELL" is not a Domain, Record, Procedure, or Table. No objects purged for dictionary element "CDD$TOP.DTR$USERS.BELL". DTR> SHOW RECORDS Records: * FAMILY_REC;4 * FAMILY_REC;3 * FAMILY_REC;2 * FAMILY_REC;1 * OWNER_RECORD;2 * OWNER_RECORD;1 * PET_REC;1 * PROJECT_REC;1 * YACHT;2 * YACHT;1 DTR> PURGE CDD$TOP.DTR$USERS.BELL.FAMILY_REC KEEP=2 DTR> SHOW RECORDS Records: * FAMILY_REC;4 * FAMILY_REC;3 * OWNER_RECORD;2 * OWNER_RECORD;1 * PET_REC;1 * PROJECT_REC;1 * YACHT;2 * YACHT;1 DTR> 2 QUERY_HEADER_Clause Specifies the column header DEC DATATRIEVE uses when it formats the display of a field value for the PRINT statement or for the Report Writer AT and PRINT statements. If you omit this clause, DEC DATATRIEVE uses the field name as the default column header when printing this field. Format QUERY_HEADER [IS] {"header-segment"} [/...] 3 Argument "header-segment" Is the column header displayed above a column of data. If you specify only one character string literal, that string is printed on one line above the column. You can specify more than one character string literal by separating each from the next with a slash (/). The literals are printed on successive lines, centered above the column. 3 Examples The following example shows how to set up a record so that when the DISPLACEMENT field is displayed, a column header of WEIGHT is used: 06 DISPLACEMENT PIC 99999 QUERY_HEADER IS "WEIGHT" EDIT_STRING IS ZZ,ZZ9 QUERY_NAME IS DISP. DEC DATATRIEVE prints the column header as follows: WEIGHT The following example shows how to set up a record so that when the LENGTH_OVER_ALL field is printed, a column header of LENGTH (IN FEET) is printed on two separate lines: 06 LENGTH_OVER_ALL PIC XXX QUERY_HEADER IS "LENGTH" /"(IN FEET)". DEC DATATRIEVE prints the column header as follows: LENGTH (IN FEET) The following example shows how to set up a record so that when the LENGTH_OVER_ALL field is printed, a column header of Length Over All ("LOA") is printed on two separate lines: 06 LENGTH_OVER_ALL PIC XXX QUERY_HEADER IS "Length Over All"/"(""LOA"")". DEC DATATRIEVE prints the column header as follows: Length Over All ("LOA") The following example shows how to set up a record so that when the LENGTH_OVER_ALL field is printed, a 3-line column header is printed with one letter per line: 06 LENGTH_OVER_ALL PIC XXX QUERY_HEADER IS "L"/"O"/"A". DEC DATATRIEVE prints the column header as follows: L O A 2 QUERY_NAME_Clause Specifies an alternate name for the field name. Format QUERY_NAME [IS] query-name 3 Argument query-name Is the query name. The rules for forming and using a query name are the same as those for a field name. 3 Examples The following example shows how to set up a record so that DISP is defined as an alternate name for the DISPLACEMENT field: 06 DISPLACEMENT PIC 99999 QUERY_NAME IS DISP. The following example shows how to set up a record so that SPECS is defined as an alternate name for the group field SPECIFICATIONS: 03 SPECIFICATIONS QUERY_NAME SPECS. The following example shows how to set up a record so that a query name of SPECIAL_HANDLING is defined for the field DELINQUENT_ACCOUNT_STATUS: 09 DELINQUENT_ACCOUNT_STATUS PIC X QUERY_NAME IS SPECIAL_HANDLING. 2 READY_Command Gives you access to one or more domains, relations, databases, or record types and controls the access of other users to those domains or databases. You can also use the READY command to ready a domain or database again in order to change your access mode or access option. Format 1 READY domain-path-name [AT node-spec] [AS alias-1] [ PROTECTED ] [ READ ] [ ] [ WRITE ] [ CONSISTENCY ] [ SHARED ] [ MODIFY ] [ CONCURRENCY ][,...] [ EXCLUSIVE ] [ ] [ ] [ EXTEND ] [SNAPSHOT] Format 2 READY database-path-name [SNAPSHOT] [PROTECTED ] [ READ ] [ ] [ WRITE ] [ CONSISTENCY ] [SHARED ] [ MODIFY ] [ CONCURRENCY ] [EXCLUSIVE ] [ ] [ ] [ EXTEND ] [ { rdb-relation-name } ] [USING { dbms-record-name } [ AS alias ] ] [ { } ] [ [SNAPSHOT] ] [ ][,...] [ [ PROTECTED ] [READ ] ] [ [ ] [WRITE ] [CONSISTENCY ] ] [ [ SHARED ] [MODIFY ] [CONCURRENCY ] ] [ [ EXCLUSIVE ] [ ] [ ] ] [ [EXTEND ] ] 3 Arguments domain-path-name Is the dictionary path name of a domain to which you want access or the domain table whose access option you want to change. node-spec Is the name of a node and an optional access control string. A node name is a 1- to 6-character name that identifies the location on the network. Examples are BIGSYS and LILSYS. An access control string indicates a particular account on the remote node. It consists of a user name, followed by one or more blanks or tabs, a password, and an optional account name. The following three node specifications are valid: BIGSYS BIGSYS"MORRISON RYLE" BIGSYS"MORRISON RYLE KANT" On DECnet links to some non-OpenVMS systems, you can use the UIC number in place of the user name. For example: BIGSYS"[240,240] RYLE" BIGSYS"[240,240] RYLE KANT" In the examples, the remote node is BIGSYS the user name is MORRISON, the UIC is [240,240], the password is RYLE, and the account name is KANT. You can also use a prompting value expression to prompt the user for the user name, password, account name, or UIC. Use single quotation marks for the prompt string. For example: DTR> READY CDD$TOP.DTR32.MORRISON.YACHTS AT CON> BIGSYS"*.'username' *.'password'" Enter username: MORRISON Enter password: DTR> alias Is a name you use if you include the AS clause in the READY command to refer to the domain, relation, or Oracle CODASYL DBMS record specified. You use the alias in place of the given name of the domain, relation, or Oracle CODASYL DBMS record where the syntax of a statement calls for that domain, relation, or Oracle CODASYL DBMS record name. If you are using an alias for a domain name, do not use the alias in full or relative dictionary path names. database-path-name Is the Oracle CDD/Repository path name defined for the DEC DATATRIEVE definition of the Oracle CODASYL DBMS, Oracle Rdb, VAX Rdb/ELN, or DEC DB Integrator Gateway database, or for the relational database definition created by Oracle Rdb. It can also be a CDD$DATABASE object. If you ready a Oracle CODASYL DBMS or relational database without specifying any relation or record names, DEC DATATRIEVE readies all relations or records in the database. READY accepts both DMU and CDO style path names. relation-name Is the name assigned to the relation when the relational database was created. The relation name can be the name of a view relation. record-name Is the name assigned to the Oracle CODASYL DBMS record when the database was created. SNAPSHOT Are the options you can select to control the access of other users to a domain, relation, or Oracle CODASYL DBMS record you ready. The specific constraints are explained in Access Options: Table 1-6 Access Options Option Access Constraints SNAPSHOT SNAPSHOT is a READ access for databases that takes a "picture" of the database when it is readied. In order to have SNAPSHOT access, all relations or records pertaining to the database must be readied with SNAPSHOT access. Any other user can access the same database with any access mode and option. In general, you do not see other users' changes until the end of the transaction. If you use SNAPSHOT with another option, such as CONCURRENCY, you may see other users' changes, depending on the database system. SNAPSHOT is the default for relational databases, relations, and domains based on relational sources. PROTECTED Any other user can have only READ access to records in the domain or relation. No other user can have WRITE, MODIFY, or EXTEND access to the records in the domain or relation. This option is the default for domains containing records from RMS files and for all view domains. SHARED Any other user can have access to the domain, database, relation, or Oracle CODASYL DBMS record at the same time, in any access mode. This option is the default for Oracle CODASYL DBMS domains, Oracle CODASYL DBMS databases, and Oracle CODASYL DBMS records. EXCLUSIVE No other user can have access to the domain, database, relation, or Oracle CODASYL DBMS record at the same time, in any access mode. If the domain is based on a RMS file, the file containing the data is locked by RMS. READ Are the options you can select to request a mode of access to a domain, database, relation, or Oracle CODASYL DBMS record. When using Format 1, whether you get that mode of access is determined by privileges assigned to you in the access control list of the domain. When using Format 2, whether you get that mode of access is determined by privileges assigned to you in the access control list of the database definition. When you are using either Format 1 or Format 2 and you are accessing a Oracle CODASYL DBMS or relational database, you must also have appropriate privileges in the Oracle CODASYL DBMS, Oracle Rdb or VAX Rdb/ELN access control lists to request the access mode you select. For Oracle CODASYL DBMS, you need access to the schema, subschema, record and DEC DATATRIEVE database definitions in the data dictionary. CONSISTENCY Are the options you can select to determine whether you can see changes made by other users to the data you are accessing. CONSISTENCY guarantees that while you are accessing data, you do not see updates made by other users. CONCURRENCY allows you to see other users' updates to the data you are accessing. CONSISTENCY is the DEC DATATRIEVE default for the first ready of a relational source. Once you specify CONSISTENCY or CONCURRENCY, that option becomes the default until you change the option in a subsequent ready or you finish the database. Multi-User Access to Domains Based on RMS Files summarizes the effects of various combinations of access options and access modes for domains based on RMS files. Table 1-7 Multi-User Access to Domains Based on RMS Files Another User Your Can Then Effect You Ready a Ready the on Other Domain Domain Users Other Users'Effect on You EXCLUSIVE No access. No one No effect. READ else can EXCLUSIVE read the WRITE file. PROTECTED PROTECTED No one No effect. READ READ else can SHARED READ write to the file. PROTECTED SHARED READ No one No effect. WRITE else can write to the file. SHARED READ PROTECTED No one Users with WRITE access READ with may change records you are PROTECTED WRITE reading or have read. WRITE access SHARED READ can SHARED WRITE select your selected record. SHARED WRITE SHARED READ No one You cannot write to the SHARED WRITE else can selected record of any modify other user. You cannot your write to the target record selected of a MODIFY or ERASE record statement entered by or the a SHARED WRITE user. A target SHARED WRITE user can also record write to a record you have of your just modified. MODIFY or ERASE state- ment. You can modify a record another user has just modi- fied. When two applications try to access the same domain based on a RMS file, RMS may lock a record that DEC DATATRIEVE needs to access. DEC DATATRIEVE then tries for 12 seconds to access the record. At the end of this period, DEC DATATRIEVE takes one of two actions, depending on whether SET LOCK_WAIT is in effect. o If SET NO LOCK_WAIT is in effect, you receive an RMS$_RLK message: "Target record currently locked by another stream." Then DEC DATATRIEVE aborts the statement. SET NO LOCK_WAIT is the default. o If SET LOCK_WAIT is in effect, DEC DATATRIEVE turns control over to RMS to wait for the record. You cannot use CTRL/C to cancel the wait. RMS waits until the record is released, or, in case of deadlock, you receive the RMS deadlock error message. The LOCK_WAIT setting applies to all sources, including Oracle CODASYL DBMS and relational databases which are readied after the SET LOCK_WAIT command is issued. NO LOCK_WAIT was selected as the default for DATATRIEVE because it is the RMS default. However, NO LOCK_WAIT is not always the recommended mode for relational access. LOCK_WAIT is required for DEC DB Integrator Gateway. Multi-User Access to Oracle CODASYL DBMS, Oracle Rdb, and VAX Rdb/ELN Sources summarizes the effects of various combinations of access options and access modes for Oracle CODASYL DBMS domains and Oracle Rdb or VAX Rdb/ELN domains and relations. Table 1-8 Multi-User Access to Oracle CODASYL DBMS, Oracle Rdb, and VAX Rdb/ELN Sources Another You Ready User Can a Domain, Then Ready Database, the Domain, Relation, Database, Your Oracle Oracle Effect CODASYL CODASYL on Other DBMS Record DBMS Record Users Other Users' Effect on You EXCLUSIVE No access. No one No effect. READ else can EXCLUSIVE read the WRITE realm or rela- tion. PROTECTED PROTECTED No one No effect. READ READ else can SHARED READ write to the realm or rela- tion. PROTECTED SHARED READ No one You may encounter read WRITE else can locks other users have put write on a record when you try to the to modify it. realm or re- lation. Other users may en- counter write locks during your transac- tion. SHARED READ PROTECTED A SHARED You may encounter write READ WRITE locks during another PROTECTED user user's transaction. WRITE may have SHARED READ to wait SHARED WRITE until you release your read locks. SNAPSHOT for With any No You do not see changes Oracle Rdb access and effect other users make to the or VAX Rdb mode. on database until a COMMIT or /ELN domains users. ROLLBACK is performed. and Oracle CODASYL DBMS records SHARED WRITE SHARED READ Other You may encounter read and SHARED WRITE users write locks during another may en- user's transaction. counter read and write locks during your transac- tion. 3 Examples The following example readies the domain YACHTS for WRITE access: DTR> READY YACHTS WRITE The following example readies the domain PHONES for EXTEND access: DTR> READY PHONES (*) EXTEND Enter password for PHONES: DTR> The following example defines a domain with the prompt built into the domain definition. DEC DATATRIEVE does not display the password: DTR> DEFINE DOMAIN PROMPT_YACHTS USING YACHT(*) ON YACHT; DTR> READY PROMPT_YACHTS AS PYTS Enter password for YACHT: DTR> The following example readies the relations EMPLOYEES and SALARY_ HISTORY in the Oracle Rdb database PERSONNEL for SNAPSHOT access: DTR> READY PERSONNEL USING EMPLOYEES, SALARY_HISTORY DTR> The following example readies the SALARY_HISTORY relation in the Oracle Rdb database PERSONNEL for SHARED WRITE access with the CONCURRENCY option: DTR> READY PERSONNEL SHARED WRITE USING SALARY_HISTORY CONCURRENCY The following example readies the Oracle CODASYL DBMS domain VENDORS for the default access mode SHARED READ: DTR> READY VENDORS DTR> 2 RECONNECT_Statement Removes a record from the set occurrence in which it participates and connects it to the set occurrence specified by the TO list. Before the RECONNECT is performed, DEC DATATRIEVE sets up a currency indicator for each set specified in the TO list. Format RECONNECT context-name-1 [TO] [context-name-2. ] set-name-1 [,...] 3 Arguments context-name-1 Is the name of a valid context variable or the name of a collection with a selected record. The target record must be a member of the sets specified by the TO list. context-name-2 Is the name of a valid context variable or the name of a collection with a selected record. It must identify a record that participates in the specified set. If the SYSTEM owns the set, you do not need to establish a context for the set. If the set is not owned by the SYSTEM and the context name is not present, DEC DATATRIEVE uses the most recent single record context of a domain with a record type that participates in the specified set type. set-name Is the name of a set type. 3 Example The following example uses nested FOR loops to create the necessary contexts. The procedure uses prompting value expressions to get information from the user. DTR> DEFINE PROCEDURE NEW_MANAGER DFN> FOR G IN GROUPS WITH GROUP_NAME = *."the name of the group" DFN> FOR E IN EMPLOYEES WITH EMP_ID = DFN> *."the id of the new manager" DFN> RECONNECT G TO E.MANAGES DFN> END_PROCEDURE DTR> 2 REDEFINE_Command Creates a new version of an object. Format { DATABASE } { DOMAIN } { PORT } REDEFINE { } definition { PROCEDURE } { RECORD } { TABLE } { } 3 Argument definition Is the path name of the definition and any other keywords, path names, or arguments that an object takes. (For an explanation of these arguments, see the DEFINE command for each object.) 3 Examples The following example redefines the domain YACHTS using the record definition YACHT and storing the data in the file DB2:[SMYTHE]YACHT.DAT: DTR> SHOW DOMAINS Domains: * YACHTS;1 DTR> REDEFINE DOMAIN YACHTS DFN> USING YACHT ON DB2:[SMYTHE]YACHT.DAT; DTR> SHOW DOMAINS Domains: * YACHTS;2 * YACHTS;1 2 REDEFINES_Clause Provides an alternate way to define a field. Format level-no field-name-1 REDEFINES field-name-2 3 Arguments level-no Is the level number of field-name-1. Although not a part of the REDEFINES clause, the level number is shown in the format to clarify its position relative to the clause. field-name-1 Is the name of the REDEFINES field. You use this name when you want to refer to this field. Although not a part of the REDEFINES clause, the field name is shown in the format to clarify its function and its position relative to the clause. field-name-2 Is the name of the field being redefined. 3 Example The following record definition shows a redefinition of the field PART_NUMBER. PART_NUMBER is a numeric field containing 10 digits. Two group fields redefine PART_NUMBER: PART_NUMBERS_PARTS and PART_NUMBER_GROUPS. Each redefinition specifies a group field containing a total of 10 digits (the total number of digits in all subordinate fields): 05 PART_NUMBER PIC 9(10) 05 PART_NUMBER_PARTS REDEFINES PART_NUMBER. 07 PRODUCT_GROUP PIC 99. 07 PRODUCT_YEAR PIC 99. 07 ASSEMBLY_CODE PIC 9. 07 SUB_ASSEMBLY PIC 99. 07 PART_DETAIL PIC 999. 05 PART_NUMBER_GROUPS REDEFINES PART_NUMBER. 07 PRODUCT_GROUP_ID PIC 9(4). 07 PART_DETAIL_ID PIC 9(6). In this example, the field PRODUCT_GROUP refers to the lowest- valued digits of PART_NUMBER; PRODUCT_YEAR refers to the next two lowest-valued digits, and so on. 2 REDUCE_Statement Retains only the unique field values or combinations of field values in a DEC DATATRIEVE collection, dropping all other values, depending on the reduce key or keys specified. Format REDUCE [collection-name] TO reduce-key-1 [,...] 3 Arguments collection-name Is the name of a collection from which you want to retrieve unique occurrences of values. reduce-key Is a field whose values form the basis for the reduction. You can also use a value expression as a reduce key, if the value expression refers to at least one field of the records forming the collection. Use a comma to separate multiple reduce keys. 3 Examples The following example searches through the YACHTS domain and, for each type of RIG, lists the prices of all boats that cost over $35,000: DTR> DEFINE PROCEDURE RIG_QUERY DFN> FIND YACHTS DFN> REDUCE CURRENT TO RIG DFN> PRINT SKIP, RIG, ALL PRICE OF YACHTS WITH DFN> PRICE GT 35000 AND RIG = Y.RIG OF Y IN CURRENT DFN> END_PROCEDURE DTR> :RIG_QUERY RIG PRICE KETCH $36,951 $51,228 $41,350 $39,500 $36,950 $54,970 $50,000 $80,500 MS $35,900 SLOOP $37,850 $39,215 $37,850 $48,490 DTR> Note the format of this PRINT statement: PRINT print-list, ALL print-list OF rse-1 OF rse-2 RSE-1 is: ALL PRICE OF YACHTS WITH PRICE GT 35000 AND RIG = Y.RIG RSE-2 is: Y IN CURRENT RSE-2 controls the printing of the first print list (SKIP, RIG) and RSE-1 controls the printing of the second print-list (PRICE). You can use the REDUCED TO statement to match values of a date field for the month and year. The following example uses the domain PAYABLES described in the DEC DATATRIEVE User's Guide. Records in PAYABLES have the same TYPE field as in YACHTS, a date field (INVOICE_DUE), and a field for wholesale price (WHSLE_PRICE). The example shows how to display the records in PAYABLES where INVOICE_DUE is later than January 1, 1983. The records are separated according to the month they are due. The REDUCED TO statement is used to identify the unique values of month and year for PAYABLES. Then the records are searched for matches to these values. DTR> SHOW MONTHLY_RPT PROCEDURE MONTHLY_RPT READY PAYABLES FIND PAYABLES WITH INVOICE_DUE AFTER "JAN 1, 1983" REDUCE CURRENT TO FORMAT INVOICE_DUE USING YYNN FOR A IN CURRENT BEGIN PRINT SKIP, "Invoices Due for the Month of"||| FORMAT A.INVOICE_DUE USING M(9), SKIP FOR PAYABLES WITH FORMAT INVOICE_DUE USING YYNN = FORMAT A.INVOICE_DUE USING YYNN SORTED BY INVOICE_DUE PRINT INVOICE_DUE, TYPE, WHSLE_PRICE END END_PROCEDURE DTR> :MONTHLY_RPT Invoices Due for the Month of January INVOICE WHSLE DUE VENDOR ITEM_TYPE PRICE 1/02/83 ALBERG 37 MK II $28,500 1/25/83 SALT 19 $4,850 1/31/83 AMERICAN 26-MS $15,150 Invoices Due for the Month of February 2/12/83 WINDPOWER IMPULSE $1,500 . . . . . . . . . . . . Invoices Due for the Month of April 4/01/83 BAYFIELD 30/32 $13,000 4/01/83 IRWIN 37 MARK II $29,999 4/15/83 ALBIN VEGA $14,250 DTR> 2 RELEASE_Command Ends your control over one or more collections, forms, tables, or global variables and frees the workspace occupied by them. Format [ ALL ] [ collection-name ] RELEASE [ form-name ] [,...] [ table-name ] [ ] [ variable-name ] 3 Arguments ALL Causes DEC DATATRIEVE to release all collections, tables, or variables. form-name Is the name of a form, a collection, a dictionary or domain table, or a variable you want to release. If you specify more than one item, use a comma to separate each from the next. 3 Examples The following example releases first one of two named collections, then the other: DTR> SHOW COLLECTIONS Collections: BIG-ONES (CURRENT) A DTR> RELEASE BIG-ONES DTR> SHOW COLLECTIONS Collections: A (CURRENT) DTR> RELEASE A DTR> SHOW COLLECTIONS No established collections. DTR> The following example releases the dictionary table DEPT-TABLE and the global variables X and Y: DTR> SHOW READY No ready sources. Loaded tables: DEPT_TBL: Dictionary table DTR> SHOW VARIABLES Global variables X Declared as: X REAL MISSING VALUE IS 36. Y Declared as: Y PIC X(9). DTR> RELEASE DEPT_TBL, X, Y DTR> SHOW READY; SHOW VARIABLES No ready sources. No loaded tables. No global variables are declared. DTR> The following example uses the RELEASE ALL command to release the collections LITTLE_ONES and B, and also the global variables T and TERRY: DTR> SHOW COLLECTIONS Collections: B (CURRENT) LITTLEONES DTR> SHOW VARIABLES Global variables T Declared as: T DATE. TERRY Declared as: TERRY PIC X(9). DTR> RELEASE ALL DTR> SHOW COLLECTIONS No established collections. DTR> SHOW VARIABLES No global variables are declared. DTR> 2 RELEASE_SYNONYM_Command Releases the definition of a synonym for a DEC DATATRIEVE keyword. Format RELEASE SYNONYM synonym-name-1 [,...] 3 Argument synonym-name Is a synonym already defined for a DEC DATATRIEVE keyword. 3 Example The following example defines synonyms for PRINT and READY and then releases the synonym definitions: DTR> DECLARE SYNONYM P FOR PRINT, R FOR READY DTR> R OWNERS; P FIRST 1 OWNERS BOAT NAME NAME BUILDER MODEL SHERM MILLENNIUM FALCON ALBERG 35 DTR> RELEASE SYNONYM R, P DTR> R YACHTS R YACHTS Expected statement, encountered "R". DTR> P OWNERS P OWNERS Expected statement, encountered "P". DTR> 2 REPEAT_Statement Causes DEC DATATRIEVE to execute a simple or compound DEC DATATRIEVE statement a specified number of times. Format REPEAT value-expression statement 3 Arguments value-expression Is a value expression indicating the number of times to execute the statement. This argument must evaluate to a positive integer less than or equal to 2,147,483,647. statement Is any simple or compound DEC DATATRIEVE statement (except a FIND, SELECT, DROP, or SORT statement). 3 Examples The following example prints TEST REPEAT three times: DTR> REPEAT 3 PRINT "TEST REPEAT" TEST REPEAT TEST REPEAT TEST REPEAT DTR> The following example aborts a REPEAT statement by responding to a prompt with a CTRL/Z: DTR> READY YACHTS WRITE DTR> REPEAT 5 STORE YACHTS Enter MANUFACTURER: HOBIE Enter MODEL: CAT Enter RIG: SLOOP Enter LENGTH-OVER-ALL: 22 Enter DISPLACEMENT: 4000 Enter BEAM: 8 Enter PRICE: 6500 Enter MANUFACTURER: Execution terminated by operator DTR> FIND YACHTS WITH BUILDER = "HOBIE" [1 record found] DTR> The following example shows the effect of nesting REPEAT statements in procedures. The procedure NUM1 contains two PRINT statements. The procedure NUM2 contains two REPEAT statements, one nested in the other. The inner REPEAT statement causes DEC DATATRIEVE to execute the first PRINT statement in NUM1 twice each time DEC DATATRIEVE loops through the outer REPEAT statement: DTR> SET NO PROMPT DTR> SHOW NUM1 PRINT SKIP, "ONE, TWO, THREE" PRINT "ONE, TWO, THREE, FOUR, FIVE" DTR> :NUM1 ONE, TWO, THREE ONE, TWO, THREE, FOUR, FIVE DTR> SHOW NUM2 REPEAT 2 BEGIN REPEAT 2 :NUM1 END :NUM1 DTR> :NUM2 ONE, TWO, THREE ONE, TWO, THREE ONE, TWO, THREE, FOUR, FIVE ONE, TWO, THREE ONE, TWO, THREE ONE, TWO, THREE, FOUR, FIVE ONE, TWO, THREE ONE, TWO, THREE, FOUR, FIVE DTR> 2 REPORT_Statement_(Report_Writer) Invokes the Report Writer and is the first entry in a report specification. In the REPORT statement you can specify the following: o The data you want to report o The output device for the report o The output format for the report The other statements in the report specification are AT BOTTOM, AT TOP, DECLARE_ATT, END_REPORT, PRINT, and SET. These statements are discussed in separate sections of this chapter. Format [ {file-spec } ] REPORT [rse] [ ON {*.prompt } ] [FORMAT format-spec] [ { } ] 3 Arguments rse Specifies the data for your report. To create a record stream for your report, enter the appropriate RSE in the REPORT statement. You can make reports using data from: o Readied domains o Collections o Lists When you omit the RSE, the Report Writer uses the data in your current collection for the report. If there is no current collection, DEC DATATRIEVE displays the following error message: A current collection has not been established. file-spec Is the file to which you want to write the report. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version format_spec Is the format in which you want the report presented. The following formats are supported: FormatExplanation Output type DDIF The CDA format for page-based page documents. DDIF allows files produced by the Report Writer to be processed directly, for example, by DECwrite, DECpresent, or conversion to other formats. PS PostScript[R], produced by page conversion from DDIF to obtain high quality printout. null The default ASCII format page produced by the Report Writer. Format encoded as ASCII characters. TEXT Format encoded as ASCII page characters, with ANSI escape sequences that produce certain attributes on terminals and printers. DTIF The CDA format for tables. DTIF table allows files produced by the Report Writer to be processed directly, for example, by DECdecision, DECchart, or conversion to other formats. *.prompt Is a prompting value expression that allows you to specify a file specification when DEC DATATRIEVE processes the report specification. 3 Example For examples of the PRINT statement in the Report Writer, see the DEC DATATRIEVE User's Guide. 2 Restructure_Statement Transfers data from the fields of records in a record stream to fields with the corresponding names in a domain. Format domain-name = rse 3 Arguments domain-name Is the given name or alias of a domain readied for EXTEND or WRITE access. That domain receives data from the records identified by the RSE. rse Is an RSE that identifies records containing one or more fields corresponding to fields of the same name in the domain that receives the data. 3 Examples The following example defines a new domain using FAMILY_REC and stores only those records of families that have no children younger than 15: DTR> DEFINE DOMAIN NEWFAMS USING FAMILY_REC ON FAMS; DTR> DEFINE FILE FOR NEWFAMS MAX, KEY = MOTHER (DUP) DTR> NEWFAMS = FAMILIES WITH NOT ANY KIDS WITH AGE LE 15 DTR> FIND NEWFAMS [8 records found] DTR> FIND FAMILIES [16 records found] DTR> The following example defines a new domain called YACHTS_PRICE_ LIST, which contains only the fields TYPE and PRICE from the old YACHT record definition. The number of records transferred is checked with the FIND statement and the accuracy of the transfer is checked with the CROSS statement. The example displays some of the records from the new domain to check the presence of the MISSING VALUE edit string. DTR> DEFINE DOMAIN YACHTS_PRICE_LIST USING YPL_REC ON YPL.DAT; DTR> DEFINE RECORD YPL_REC USING DFN> 01 BOAT. DFN> 03 TYPE. DFN> 05 BUILDER PIC X(10). DFN> 05 MODEL PIC X(8). DFN> 03 PRICE PIC 9(5) MISSING VALUE IS 0 DFN> EDIT_STRING $$$,$$$?"NOT LISTED". DFN> ; [Record is 23 bytes long.] DTR> DEFINE FILE FOR YACHTS_PRICE_LIST KEY = TYPE DTR> READY YACHTS_PRICE_LIST AS YPL WRITE DTR> READY YACHTS DTR> SHOW READY Ready domains: YACHTS: Domain, RMS indexed, protected read YPL: Domain, RMS indexed, protected write No loaded tables. DTR> YPL = YACHTS WITH LOA GT 35 DTR> FIND YACHTS WITH LOA GT 35 [23 records found] DTR> FIND YPL [23 records found] DTR> FIND A IN YPL CROSS B IN YACHTS OVER [Looking for field name] CON> TYPE WITH A.PRICE NE B.PRICE [0 records found] DTR> FIND YPL WITH PRICE MISSING [12 records found] DTR> PRINT FIRST 3 CURRENT BUILDER MODEL PRICE BLOCK I. 40 NOT LISTED CABOT 36 NOT LISTED DOWN EAST 38 NOT LISTED DTR> The following example uses the Restructure statement to transfer data from an indexed file to a sequential file: DTR> SET NO PROMPT DTR> READY YACHTS AS OLD DTR> DEFINE FILE FOR YACHTS DTR> READY YACHTS AS NEW WRITE DTR> NEW = OLD DTR> FIND NEW [113 records found] DTR> If the field has a DEFAULT VALUE clause, DEC DATATRIEVE initializes the field with the default value. If the field has a MISSING VALUE clause and no DEFAULT VALUE clause, DEC DATATRIEVE initializes the field with the missing value. If the field has neither a DEFAULT VALUE clause nor a MISSING VALUE clause, DEC DATATRIEVE initializes a numeric field as 0 and an alphabetic or alphanumeric field as spaces. 2 ROLLBACK_Statement Undoes all the changes you made to the database since the last COMMIT or ROLLBACK statement, or since your first READY if you have not done a ROLLBACK or a COMMIT. The ROLLBACK statement performs a Oracle CODASYL DBMS or relational rollback and releases all collections associated with Oracle CODASYL DBMS domains and records and with relational domains and relations. ROLLBACK then readies Oracle CODASYL DBMS realms again or finishes and starts a new relational source transaction. The ROLLBACK statement also acts as an ABORT in procedures, nested statements, and command files. The ROLLBACK statement affects all readied parts of Oracle CODASYL DBMS and relational databases, whether or not you made any changes to the data they contain. Domains based on RMS files are not affected by the ROLLBACK statement. Format ROLLBACK 3 Example The following example for the Oracle CODASYL DBMS database PARTS_DB connects an employee named Hill to a part LA36 in the RESPONSIBLE_FOR set. The ROLLBACK statement undoes the change: DTR> FIND E IN EMPLOYEES WITH EMP_LAST_NAME = "HILL" DTR> SELECT 1 DTR> FOR P IN PART WITH PART_DESC = "LA36" CON> CONNECT P TO E.RESPONSIBLE_FOR DTR> ROLLBACK DTR> 2 SCALE_Clause Establishes explicitly the scale factor to be applied to the value stored in the field. Format SCALE [IS] [-]integer 3 Arguments - (minus sign) Is an optional minus sign to indicate a negative scale factor. integer Indicates the number of decimal places the implied decimal point is from the right or left end of the value stored in the field. 3 Examples The following example uses a positive scale factor to store a large number in a small field: 03 BARRELS_PER_DAY WORD SCALE 6 EDIT_STRING Z(5)" Million". The following example uses a negative scale factor to store a minute number in a small field: 03 PROJECT. 05 PROBABILITY_OF_FINISHING. 07 EVER DEFAULT VALUE IS 1 PIC 99 SCALE -2. 07 ON_TIME 99 SCALE -6 MISSING VALUE 0 EDIT_STRING 0.9(6)?"Better late than never". 2 SELECT_Statement Establishes a target record in a collection. Format [ FIRST ] [ NEXT ] [ PRIOR ] SELECT [ ] [collection-name] [WITH boolean] [ LAST ] [ value-expression ] [ NONE ] [ ] 3 Arguments FIRST Selects the first record in the target collection. NEXT Selects the next record in the target collection. (See the second and third items in the Results section.) When you omit a position specification, NEXT is the default. PRIOR Selects the previous record in the target collection. (See the fifth and sixth items in the Results section.) LAST Selects the last record in the target collection. value-expression Evaluates to a positive number. DEC DATATRIEVE uses the integer part of the number to select the record with that position number in the collection. NONE Releases the selected record so that no selected record exists for the current collection. If the collection was formed from a file-structured database, SELECT NONE also releases the RMS lock on the selected record. collection-name Is the name of the target collection containing the record to be selected. If you omit the collection name, the target collection is the current collection. WITH boolean Causes DEC DATATRIEVE to select the record that satisfies both the Boolean expression and the collection position references (FIRST, LAST, NEXT, PRIOR, and value-expression). 3 Examples The following example selects the last record in the CURRENT collection: DTR> SELECT LAST DTR> The following example selects the fifth record in the collection BIG_ONES: DTR> SELECT 5 BIG_ONES DTR> The following example selects the last 30-foot boat in the YACHTS inventory from the CURRENT collection: DTR> FIND YACHTS [113 records found] DTR> SELECT LAST WITH LOA = 30 DTR> PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE SOLNA CORP SCAMPI SLOOP 30 6,600 10 DTR> The following example selects a record from the CURRENT collection, modifies a field value, and releases the selected record and, in this case, the RMS lock on the record: DTR> READY YACHTS SHARED MODIFY DTR> FIND YACHTS WITH BUILDER = "SOLNA CORP" [1 record found] DTR> SELECT DTR> PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE SOLNA CORP SCAMPI SLOOP 30 6,600 10 DTR> MODIFY PRICE Enter PRICE: 50000 DTR> PRINT LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE SOLNA CORP SCAMPI SLOOP 30 6,600 10 $50,000 DTR> SELECT NONE DTR> 2 SET_Command o Controls the DEC DATATRIEVE response to ABORT statements. o Sets the keypad mode (application or numeric) within DEC DATATRIEVE. o Sets the maximum number of columns per page for DEC DATATRIEVE output. o Establishes your default directory in the Oracle CDD/Repository data dictionary. o Determines whether DEC DATATRIEVE creates a DTREDIT.DTR backup file when you edit dictionary objects. o Determines whether DEC DATATRIEVE uses its forms interface to control the video display of your terminal. o Starts DEC DATATRIEVE Guide Mode. o Determines whether DEC DATATRIEVE recognizes null values of relational databases. o Permits or inhibits automatic syntax prompting for continued commands and statements. o Permits or inhibits creation of an implicit inner print list in a PRINT statement and an implicit ANY in a Boolean expression. o Determines whether a semicolon is required at the end of each command or statement. o Controls whether commands and statements in command files are displayed when the command file is invoked Format { [NO] ABORT } { [NO] APPLICATION_KEYPAD } { COLUMNS_PAGE=n } { } { [NO] CDD } { DICTIONARY path-name } { [NO] EDIT_BACKUP } { [NO] FORM } { } { [NO] GRID } { GUIDE [ADVANCED] } { KEYDEFS file-spec } SET { } [,...] { [NO] LOCK_WAIT } { [NO] NULLS } { PLOTS path-name } { } { [NO] PROMPT } { [NO] SEARCH } { [NO] SEMICOLON } { } { [NO] VARIABLES PROCEDURES } { [NO] VERIFY } { NOVERIFY } { } To change settings for HELP: { [NO] HELP_PROMPT } SET { [NO] HELP_WINDOW } [,...] { HELP_LINES n TO m } { } 3 Arguments ABORT Causes DEC DATATRIEVE to abort the remainder of a procedure or command file when DEC DATATRIEVE executes an ABORT statement, when you enter a CTRL/Z to a prompt, or when a syntax or logical error occurs during the execution of a command or statement. The exception to the logical error condition is the DELETE command. If you list two or more objects as arguments for the DELETE command, DEC DATATRIEVE does not abort if it fails to find an object of a specified name. Instead, DEC DATATRIEVE continues to delete the remaining objects in the list. NO ABORT Causes DEC DATATRIEVE, when processing a procedure or a command file, to abort only the one statement containing an ABORT statement. SET NO ABORT also causes DEC DATATRIEVE to take the same action when you respond with a CTRL/Z to a prompt in a procedure or command file. DEC DATATRIEVE then executes the next command or statement in the procedure or command file. SET NO ABORT is in effect when you start a DEC DATATRIEVE session. APPLICATION_KEYPAD Sets the keypad mode as application keypad within DEC DATATRIEVE. The default keypad mode for DEC DATATRIEVE is numeric keypad mode. You can also set the keypad mode using the function FN$KEYPAD_ MODE. This command is not available in a DECwindows Motif environment. NO APPLICATION_KEYPAD Sets the keypad mode as numeric keypad within DEC DATATRIEVE. The default keypad mode for DEC DATATRIEVE is numeric keypad mode. You can also set the keypad mode using the function FN$KEYPAD_ MODE. This command is not available in a DECwindows Motif environment. COLUMNS_PAGE = n Establishes the number of columns per page for DEC DATATRIEVE output and the default page width for the Report Writer. When you start your session, the default COLUMNS_PAGE setting is 80. To set the terminal's width, use the DEC DATATRIEVE function FN$WIDTH. DICTIONARY path-name Causes DEC DATATRIEVE to set your default directory node of the Oracle CDD/Repository data dictionary to the node specified by the dictionary path name. When you start your DEC DATATRIEVE session, your default Oracle CDD/Repository directory is either CDD$TOP or the directory designated by the logical name CDD$DEFAULT. SET DICTIONARY accepts both DMU and CDO style path names. EDIT_BACKUP Causes DEC DATATRIEVE to save the original definition in the Oracle CDD/Repository data dictionary when you use the EDIT command to edit a dictionary object. When you start your DEC DATATRIEVE session, SET EDIT_BACKUP is in effect. Use the SHOW EDIT command to see whether or not SET EDIT_BACKUP is currently in effect. NO EDIT_BACKUP Causes DEC DATATRIEVE to delete the highest version of the object in the Oracle CDD/Repository data dictionary, or the version you specify, and replace it with the definition in the edit buffer when you use the EDIT command to edit a dictionary object. FORM Determines whether DEC DATATRIEVE uses its forms interface when you use the PRINT, MODIFY, and STORE statements. For terminals supported by the forms product you are using, SET FORM causes DEC DATATRIEVE to display and use forms when you enter the PRINT, MODIFY, or STORE statement. When you start your DEC DATATRIEVE session, SET FORM is in effect. NO FORM Prevents DEC DATATRIEVE from using its forms interface. If SET NO FORM is in effect when you use the PRINT, MODIFY, or STORE statements, DEC DATATRIEVE does not use the forms interface. GRID Causes a client application (DEC DATATRIEVE Client for Windows or programs calling DEC DATATRIEVE) to display the output of a PRINT statement on the grid (Dataset Viewer). If the output is directed to a file, that file contains all the necessary tab characters that make it readable by other PC applications (e.g. Excel[R]). This command is for client applications only, and it's ignored by the DEC DATATRIEVE server if this is not connected to a client. NO CDD Specifies whether DEC DATATRIEVE should attach to Oracle CDD/Repository or use textfile-based dictionary only. When this qualifier is missing, the DEC DATATRIEVE behaviour depends on the equivalent string of the logical name DTR$ENVIRONMENT: if the equivalent string contains /NOCDD , no attachment to Oracle CDD/Repository occurs. If DTR$ENVIRONMENT is not defined, the DEC DATATRIEVE behaviour depends on the configuration selected at installation time. If Oracle CDD/Repository is linked to DEC DATATRIEVE at installation time its use can dynamically be disabled using the DATATRIEVE SET NO CDD command, which switches to the textfile-based dictionary. NO GRID Causes a client application (DEC DATATRIEVE Client for Windows or programs calling DEC DATATRIEVE) to display the output of a PRINT statement on the Output window. SET NO GRID is the default. This command is for client applications only, and it is ignored by the server if this is not connected to a client. GUIDE Starts Guide Mode, the tutorial mode of DEC DATATRIEVE. Refer to the DEC DATATRIEVE User's Guide for a description of Guide Mode. KEYDEFS file-spec Lets you define multiple keypad keys from a file containing DCL DEFINE/KEY commands (see the OpenVMS documentation for more information on the DEFINE/KEY command). By using SET KEYDEFS, you do not have to make multiple calls to the FN$DEFINE_KEY function. The file specification is the full DCL file specification for the file containing the DCL DEFINE/KEY commands. This command is not available in a DECwindows Motif environment. LOCK_WAIT When two applications try to access the same file, RMS may lock a record that DEC DATATRIEVE needs to access. DEC DATATRIEVE tries for 12 seconds to access a locked record. SET LOCK_WAIT causes DEC DATATRIEVE to turn control over to RMS after this period. RMS then waits for the locked record until it is released, or until RMS sends you a deadlock message. The default is SET NO LOCK_ WAIT. NO LOCK_WAIT Instructs DEC DATATRIEVE not to try to access a locked record after 12 seconds. At the end of this period, you receive an RMS message informing you that the record is locked. When you begin your DEC DATATRIEVE session, SET NO LOCK_WAIT is in effect. NULLS When the you issue a SET NULLS command, DEC DATATRIEVE recognizes null values of relational databases as such. SET NULLS is the default. NO NULLS When you issue a SET NO NULLS command, DEC DATATRIEVE does not recognize null values of relational databases as such, it returns the type-dependent default values of relational databases. You can examine the current condition with the SHOW SET_UP command. PLOTS Establishes the default Oracle CDD/Repository DMU data dictionary directory for your DEC DATATRIEVE plot definitions. PROMPT Causes DEC DATATRIEVE to prompt for elements needed to complete the syntax of the current command or statement. When you press the RETURN key before completing a command or statement, DEC DATATRIEVE prompts you for the next syntactic element of that statement or command. The prompt takes the following form: [Looking for element] At the start of a DEC DATATRIEVE session, SET PROMPT is in effect. NO PROMPT Prevents DEC DATATRIEVE from prompting for elements needed to complete the syntax of the current command or statement. SEARCH Causes the DEC DATATRIEVE Context Searcher to create implicit inner print lists in PRINT statements and implicit ANYs in Boolean expressions. When you work with Oracle CODASYL DBMS domains, the SET SEARCH command causes the DEC DATATRIEVE Context Searcher to walk sets to look for a context to resolve references to field names. NO SEARCH Prevents the DEC DATATRIEVE Context Searcher from creating implicit inner print lists in PRINT statements and implicit ANYs in Boolean expressions. At the start of a DEC DATATRIEVE session, SET NO SEARCH is in effect. SEMICOLON Causes DEC DATATRIEVE to require a semicolon at the end of commands or statements. NO SEMICOLON Causes DEC DATATRIEVE to make semicolons at the end of commands or statements optional. At the start of a DEC DATATRIEVE session, SET NO SEMICOLON is in effect. VARIABLES PROCEDURES Allows you to use variables as procedures: you can store in a DEC DATATRIEVE variable commands and statements. You can then execute the variable as if it was a procedure. Variables declared as procedures are not stored in the Oracle CDD/Repository. NO VARIABLES PROCEDURES Causes variables to be interpreted as variables and not as procedures. At the start of your DEC DATATRIEVE session, SET NO VARIABLES PROCEDURES is the default. VERIFY Causes lines from command files to be displayed when a command file is invoked. NO VERIFY Suppresses the display of lines from command files when a command file is invoked. At the start of your DEC DATATRIEVE session, the current setting for SET VERIFY/NOVERIFY at the DCL level is in effect. HELP_PROMPT Causes DEC DATATRIEVE to prompt for the topic or subtopic when help text is displayed. NO HELP_PROMPT Suppresses the prompting for the topic or subtopic when help text is displayed. HELP_WINDOW Causes help text to be displayed in a scrolling region of a video terminal. NO HELP_WINDOW Causes help text to be displayed in a nonscrolling region of a video terminal. HELP_LINES n TO m Sets the lines for scrolling help text between lines n and m, where n represents the beginning of the scrolling region and m represents the end. 3 Examples The following example displays the default settings and change the default settings with one SET statement: DTR> SHOW SET_UP Set-up: Columns_page: 80 No abort Prompt No search Form No verify No semicolon No lock_wait NULLs support Application keypad mode DTR> SET COLUMNS_PAGE = 132, ABORT, NO PROMPT, SEARCH, [Looking for SET option] CON> 9 NO FORM, VERIFY, SEMICOLON, LOCK_WAIT, NO APPLICATION_KEYPAD DTR>SHOW SET_UP Set-up: Columns_page: 132 Abort No prompt Search No form Verify Semicolon Lock_wait NULLs support Numeric keypad mode DTR> The following example sets your default dictionary directory at CDD$TOP and uses a variety of path names to change your default directory: DTR> SET DICTIONARY CDD$TOP DTR> SET DICTIONARY DTR$LIB.DEMO DTR> SHOW DICTIONARY The default directory is CDD$TOP.DTR$LIB.DEMO DTR> SHOW DICTIONARIES Dictionaries: DTR> SET DICTIONARY -.-; DTR> SHOW DICTIONARY The default directory is CDD$TOP DTR> SET DICTIONARY CDD$TOP.DTR32 Element "CDD$TOP.DTR32.JONES" not found in dictionary. DTR> SET DICTIONARY CDD$TOP.DTR32.TEST DTR> SHOW DICTIONARIES Dictionaries: DTR> SET DEF -; SHOW DICTIONARY The default directory is CDD$TOP.DTR32 DTR> SHOW DICTIONARIES Dictionaries: AWS BRADS BRENT DBF DDD DEMO DENN DETRIC DUNCAN JAS KELLERMAN LANDAU MARISON PLOTS STRONG TEST WAYNE DTR> SET DICTIONARY WAYNE DTR> SET DICTIONARY DISK1:[SWANSON.DTRWORK]TEST.NEWDICT DTR> The following example uses the SET SEARCH command to walk sets in a Oracle CODASYL DBMS database: DTR> READY SUPPLIES, VENDORS, PART_S DTR> SET SEARCH DTR> PRINT VEND_NAME, PART_DESC OF [Looking for name of domain, collection, or list] CON> VENDORS WITH VEND_NAME = "QUALITY COMPS" Not enough context. Some field names resolved by Context Searcher. --------------Vendor Name--------------- QUALITY COMPS VT100 KEYBOARD ASSY NUMERIC KEYPAD FRAME VT52 HOUSING When SET SEARCH is not in effect, you need to provide explicitly the inner print lists to give DEC DATATRIEVE the necessary context, as follows: DTR> SET NO SEARCH DTR> PRINT VEND_NAME, ALL ALL PART_DESC OF PART_S OWNER OF [Looking for set name] CON> PART_INFO OF SUPPLIES MEMBER OF VENDOR_SUPPLY OF [Looking for name of domain, collection, or list] CON> VENDORS WITH VEND_NAME = "QUALITY COMPS" --------------Vendor Name--------------- QUALITY COMPS VT100 KEYBOARD ASSY NUMERIC KEYPAD FRAME VT52 HOUSING DTR> 2 SET_Statement_(Report_Writer) Controls the report header and defines the size of report pages and the length of the report. With Report Writer SET statements, you can specify the following: o The report header-the report name (if any), the date, page numbering, and their print attributes o The size of report pages-the number of columns and the number of lines per page, or the physical paper size o The orientation of the paper to be printed on. o The length of the report-the maximum number of lines and the maximum number of pages o Whether or not column headers are printed Format For naming the report: { "string"[/ . . . ]} SET REPORT_NAME = [ ATT att-name, ] { *.prompt } { } For controlling the printing of default page numbers and for specifying the beginning page number at the upper right of a page: { [ { ATT att-name } ] } { [ { { } } ] } { [ { ATT att-name, { n } } ] } { NUMBER [ = { { *.prompt } } ] } { [ { } ] } SET { [ { { n } } ] } { [ { { *.prompt } } ] } { [ { { } } ] } { } { } { NO NUMBER } For specifying a date or string at the upper right of each page or for disabling the printing of a date: { [ { ATT att-name } ] } { DATE [ = { ATT att-name, "string" } ] } { [ { } ] } SET { [ { "string" } ] } { } { } { NO DATE } For disabling the printing of the entire report header: SET NO REPORT_HEADER For specifying the printing of column headers: { COLUMN_HEADER = ATT att-name } SET { NO COLUMN_HEADER } { } For specifying page width or length, or overall report length: { { COLUMNS_PAGE = } } { { LINES_PAGE = } { n } } SET { { MAX_LINES = } { *.prompt } } [, . . . ] { { } { } } { { MAX_PAGES = } } For specifying paper size: { { A } } { { B } } { { } } { { C } } { { D } } { { LETTER } } { { } } { { LEDGER } } { { LEGAL } } { { EXECUTIVE } } { { } } { { 7_BY_9 } } { { A1 } } { PAPER_SIZE { A2 } } { { } } { { A3 } } { { A4 } } SET { { A5 } } { { } } { { B4 } } { { C4 } } { { C5 } } { { } } { { C6 } } { { C7/6 } } { { C5/6 } } { { } } { { DL } } { { PAPER_HEIGHT } {MM } } { { } =n { } } { { PAPER_WIDTH } {IN } } { { } } { PAPER_ORIENTATION = {PORTRAIT } } { {LANDSCAPE } } { } 2 SHOW_Command Displays information about the Oracle CDD/Repository data dictionary and its contents. 3 Arguments SHOW ALL Displays the names of all the objects and directories listed in your default Oracle CDD/Repository dictionary, the name of your default directory, the names of the collections, the other readied RSE sources (domains, relations, Oracle CODASYL DBMS records), and the loaded tables and forms in your workspace. DMU format record and domain definitions are indicated with an asterisk (*). SHOW collection-name Displays the collection name, the name of the domain, relation, or Oracle CODASYL DBMS record within which the collection has been established, the number of records in the collection, the status of the selected record within the collection, the names of the keys on which the collection has been sorted, and the command that created the collection. SHOW COLLECTIONS Displays the names of the collections you are using. SHOW CURRENT Displays the name of the domain, relation, or Oracle CODASYL DBMS record within which the CURRENT collection has been formed, the number of records in the CURRENT collection, the status of the selected record in the CURRENT collection, and the names of the keys on which the collection has been sorted. SHOW database-name For relational databases, displays the name and the file specification of the database. For Oracle CODASYL DBMS, displays the name, the subschema name, the schema path name, and the root file specification of the database. SHOW DATABASES Displays the names of the relational and Oracle CODASYL DBMS databases listed in your default directory. SHOW DICTIONARIES Displays the names of the dictionary directories appended to your default directory. (This option tells you if the dictionary branch continues lower than your current location.) SHOW DICTIONARY Displays the full dictionary path name of your default directory. SHOW domain-name Displays the name, the record definition name, and the file specification of the domain based on a RMS file. Displays the domain name, the associated Oracle CODASYL DBMS record, and the database name associated with the Oracle CODASYL DBMS domain. Displays the domain name, the associated relation name, and the database name associated with the relational domain. SHOW DOMAINS Displays the names of all domains cataloged in your default directory. DMU format domains are indicated by an asterisk (*). SHOW EDIT Indicates whether SET EDIT_BACKUP or SET NO EDIT_BACKUP is in effect in your DEC DATATRIEVE session. SET EDIT_BACKUP is the default. If you enter the command SET NO EDIT_BACKUP and edit any definitions, DEC DATATRIEVE deletes the highest version of the definitions when you exit the editor. SET NO EDIT_BACKUP automatically keeps outdated versions of definitions from piling up in your directory, but could erase the only definition you have to fall back on should you make a mistake in your editing. SHOW FIELDS Displays the names, data types, and index-key information of the fields of all domains you have readied. It also displays the names and data types of global variables. For RMS sources, the SHOW FIELDS command indicates whether or not a key field is the primary key or an alternate key. For fields from non-RMS sources, SHOW FIELDS indicates an indexed key. SHOW FIELDS FOR domain-name collection-name dbms-record rdb-relational-name Displays the names, data types, end index-key information of the fields in the domain, collection, dbms-record, or rdb-relation you specify after FOR. You can only specify the name of a readied domain. SHOW FORMS Displays the form name, the form file, and the form product name of all loaded forms. SHOW FUNCTIONS Displays all the loaded user functions and the subset they belong to. SHOW HELP Indicates which of the settings for the HELP command is in effect. The settings are HELP_LINES, HELP_PROMPT, and HELP_ WINDOW. SHOW KEYDEFS Shows all current key definitions in all states. A state allows the same key to be assigned multiple definitions by associating each definition with a different state key. In addition to SHOW KEYDEFS, you can use the function FN$SHOW_KEYDEFS to show all key definitions. This command is not available in a DECwindows Motif environment. SHOW path-name Displays the text of the domain, record, procedure, or table definition specified by the dictionary path name. SHOW PLOTS Displays the names of the loaded plots from the directory specified in the SET PLOTS command. SHOW PRIVILEGES Displays the access privileges you have to the directory at which you are currently located. SHOW PRIVILEGES FOR path-name Displays the access privileges you have to the directory or object you name in the FOR clause. SHOW procedure-name Displays the name of the procedure, the commands and statements contained in the procedure, and the END_PROCEDURE clause. SHOW PROCEDURES Displays the names of all procedures cataloged in the directory at which you are currently located. SHOW READY Displays for each readied domain based on a RMS file the full dictionary path name, the file organization of the associated data file, the access control option (EXCLUSIVE, PROTECTED, or SHARED), and the access mode (READ, WRITE, EXTEND, or MODIFY). For all readied relational and Oracle CODASYL DBMS domains, the SHOW READY command displays the name, type, access option, access mode, and the domain path. For individual relations and Oracle CODASYL DBMS records, the SHOW READY command displays the name, type, access option, access mode, and the dictionary path to the database. The most recently readied domain, relation, or Oracle CODASYL DBMS record is at the top of the displayed list. The SHOW READY command also displays the full dictionary path name and table type of all tables loaded in your workspace. SHOW record-name Displays the name, level numbers, fields, and field definitions of the record. It also allows you to display those records defined by the CDO utility. SHOW RECORDS Displays the names of all record definitions cataloged at your current directory location. DMU format records are indicated by an asterisk (*). SHOW SET_UP Displays the current status of the options you can control with the SET command: ABORT/NO ABORT, APPLICATION_KEYPAD/ NO APPLICATION_KEYPAD, COLUMNS_PAGE, FORM/NO FORM, NULLS/NO NULLS, PROMPT/NO PROMPT, SEARCH/NO SEARCH, SEMICOLON/ NO SEMICOLON, VARIABLES PROCEDURES, and VERIFY/NOVERIFY. SHOW SETS Displays the names of any available Oracle CODASYL DBMS sets and their Oracle CODASYL DBMS insertion and retention classes. SHOW SYNONYMS Displays the names of any synonyms for DEC DATATRIEVE keywords in effect during your DEC DATATRIEVE session. SHOW table-name Displays the name of the table, the code and translation pairs, and the END_TABLE clause. SHOW TABLES Displays the names of all dictionary tables and domain tables cataloged in your default directory. SHOW VARIABLES Displays the contents of all variable declarations in effect in the current DEC DATATRIEVE session. 3 Examples The following example displays the record definition OWNER_REC: DTR> SHOW OWNER_REC RECORD OWNER_REC 01 OWNER. 03 NAME PIC X(10). 03 BOAT_NAME PIC X(17). 03 TYPE. 06 BUILDER PIC X(10). 06 MODEL PIC X(10). ; DTR> The following example displays the status of the SET command options that affect your DEC DATATRIEVE session: DTR> SHOW SET_UP Set-up: Columns_page: 80 No abort Prompt No search Form No verify No semicolon No lock wait NULLs support Application keypad mode DTR> 2 SHOWP_Command Displays the access control list (ACL) of an object or directory in the Oracle CDD/Repository data dictionary. Format SHOWP path-name 3 Argument path-name Is the given name, full dictionary path name, or relative path name of the dictionary object or directory whose access control list you want to display. 3 Examples The following example displays the access control list for the DMU YACHTS domain: DTR> SHOWP YACHTS 1: [*,*], Username: "JONES" Grant - CDEHMRSUW, Deny - none, Banish - none DTR> The following example uses a password to gain C (CONTROL) access to the DMU record YACHT and then display its access control list: DTR> SHOWP YACHT (*) Enter password for YACHT: !You enter CEP, which is not echoed. DTR> SHOWP YACHT 1: [*,*], Password: "P" Grant - P, Deny - CDESUX, Banish - none 2: [*,*], Password: "DP" Grant - DP, Deny - CESUX, Banish - none 3: [*,*], Password: "EP" Grant - EP, Deny - CDSUX, Banish - none 4: [*,*], Password: "PS" Grant - PS, Deny - CDEUX, Banish - none 5: [*,*], Password: "PU" Grant - PU, Deny - CDESX, Banish - none 6: [*,*], Password: "PX" Grant - PX, Deny - CDESU, Banish - none 7: [*,*], Password: "CEP" Grant - CEP, Deny - DSUX, Banish - none 8: [*,*], Password: "CDP" Grant - CDP, Deny - ESUX, Banish - none DTR> The following example displays the ACL of the CDO format dictionary SYS$COMMON:[CDDPLUS.PERSONNEL]: DTR> SHOWP SYS$COMMON:[CDDPLUS.PERSONNEL] 1: [*,*], Username: "CASADAY" GRANT - RWMESUDC, DENY - none ACCESS=READ+WRITE+MODIFY+EXTEND+SHOW+DEFINE+CHANGE+DELETE+CONTROL 2: [*,*] GRANT - S, DENY - RWMEUDC ACCESS=SHOW DTR> 2 SIGN_Clause Specifies the location and representation of a sign (+ or -) in a numeric elementary field. Format { LEADING } SIGN [IS] { TRAILING } [SEPARATE] { } 3 Arguments LEADING Indicates that the sign is at the left (LEADING) or right (TRAILING) of the field value. SEPARATE Indicates that the sign occupies its own character position in the field. If this argument is omitted, the sign shares a character position with the field's leftmost (LEADING) or rightmost (TRAILING) digit. 3 Examples The following example defines the field CURRENT_BALANCE as a 6- digit signed field, with the sign sharing the leftmost character position: 03 CURRENT_BALANCE PIC IS S9999V99 EDIT_STRING IS $$$$9.99- SIGN IS LEADING. The following example defines the field NEW_PRICE as a 4-digit signed field. The sign is a separate character in the rightmost character position: 03 NEW_PRICE PIC S99V99 SIGN TRAILING SEPARATE EDIT_STRING +++.99. 2 SORT_Statement Arranges a DEC DATATRIEVE collection according to the order you specify for the contents of one or more fields in the records. Format SORT [collection-name] [BY] sort-key-1 [,...] 3 Arguments collection-name Is the name of the collection to be sorted. BY Is an optional language element you can use to clarify syntax. sort-key Is a field whose contents form the basis for the sort. You can also use a value expression as a sort key as long as the value expression does not contain a SORTED BY or REDUCED TO clause. The sort key can be preceded or followed by a keyword that determines the order in which DEC DATATRIEVE sorts the records in the collection. ASCENDING is the default order. To specify the sort order for each sort key, use one of the following terms: ASC[ENDING] DESC[ENDING] INCREASING DECREASING If you specify more than one sort key, use a comma to separate each sort key from the next. 3 Examples The following example sorts the first ten yachts by the ratio of PRICE to DISPLACEMENT: DTR> FIND FIRST 10 YACHTS [10 records found] DTR> SORT BY PRICE/DISP DTR> PRINT ALL TYPE, PRICE, DISP, [Looking for next element in list] CON> PRICE/DISP ("$/LB."/"RATIO") USING $$$.99 $/LB. MANUFACTURER MODEL PRICE WEIGHT RATIO BLOCK I. 40 18,500 $.00 BUCCANEER 270 5,000 $.00 ALBERG 37 MK II $36,951 20,000 $1.85 AMERICAN 26 $9,895 4,000 $2.47 BOMBAY CLIPPER $23,950 9,400 $2.55 AMERICAN 26-MS $18,895 5,500 $3.44 BAYFIELD 30/32 $32,875 9,500 $3.46 ALBIN VEGA $18,600 5,070 $3.67 ALBIN BALLAD $27,500 7,276 $3.78 ALBIN 79 $17,900 4,200 $4.26 DTR> The following example forms a collection of FAMILIES CROSS KIDS and sorts the collection by decreasing age of the children: DTR> FIND FIRST 6 FAMILIES CROSS KIDS [6 records found] DTR> SORT BY DESC AGE DTR> PRINT ALL FATHER, MOTHER, EACH_KID KID FATHER MOTHER NAME AGE JIM LOUISE ANNE 31 JIM LOUISE JIM 29 JIM LOUISE ELLEN 26 JIM LOUISE DAVID 24 JIM ANN URSULA 7 JIM ANN RALPH 3 2 STORE_Statements Creates a record in a DEC DATATRIEVE domain and stores values in one or more fields of the record. For information on using STORE with Oracle CODASYL DBMS and relational databases, see the section on the STORE statement for Oracle CODASYL DBMS and relational sources in this chapter. Format STORE [context-variable IN] domain-name [USING statement-1] [VERIFY [USING] statement-2] 3 Arguments context-variable Is the name of the record to be inserted. domain-name Is the given name or alias of the domain that contains the new record. USING statement-1 Specifies a DEC DATATRIEVE statement that can store one value for one or more fields in the new record. VERIFY [USING] statement-2 Specifies a statement DEC DATATRIEVE executes just before storing the new record. 3 Examples The following example stores two records in the FAMILIES domain: DTR> READY FAMILIES WRITE DTR> REPEAT 2 STORE FAMILIES Enter FATHER: GEORGE Enter MOTHER: SANDY Enter NUMBER_KIDS: 2 Enter KID_NAME: DANA Enter AGE: 12 Enter KID_NAME: DACIA Enter AGE: 9 Enter FATHER: WAYNE Enter MOTHER: SHEEL Enter NUMBER_KIDS: 2 Enter KID_NAME: BETE Enter AGE: 8 Enter KID_NAME: ALEX Enter AGE: 5 DTR> FIND FAMILIES WITH MOTHER = "SANDY", "SHEEL" [2 records found] DTR> PRINT ALL NUMBER KID FATHER MOTHER KIDS NAME AGE GEORGE SANDY 2 DANA 12 DACIA 9 WAYNE SHEEL 2 BETE 8 ALEX 5 DTR> The following example stores a record in the YACHTS domain, using a context variable and a VERIFY clause: DTR> SHOW HINKLEY_STORE PROCEDURE HINKLEY_STORE STORE A IN YACHTS USING BEGIN BUILDER = "HINKLEY" MODEL = "BERMUDA 40" RIG = "YAWL" LOA = 40 DISP = 20000 BEAM = 12 PRICE = 82000 END VERIFY USING BEGIN PRINT A.BOAT, SKIP IF *.CONFIRMATION CONT "N" THEN PRINT SKIP THEN ABORT "BAD RECORD" END END_PROCEDURE DTR> READY YACHTS WRITE DTR> :HINKLEY_STORE LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE HINKLEY BERMUDA 40 YAWL 40 20,000 12 $82,000 Enter CONFIRMATION: N ABORT: BAD RECORD DTR> The following example defines a domain for single-digit integers and their squares, and uses a WHILE statement to control the number of records stored in the domain: DTR> DEFINE DOMAIN SQUARES USING DFN> SQUARES_REC ON SQUARES.DAT; DTR> DEFINE RECORD SQUARES_REC USING DFN> 01 SQUARES. DFN> 03 NUMBER PIC 9. DFN> 03 ITS_SQUARE PIC 99. DFN> ; [Record is 3 bytes long.] DTR> DEFINE FILE FOR SQUARES; DTR> READY SQUARES WRITE DTR> DECLARE N PIC 99. DTR> N = 0 DTR> WHILE N NE 10 STORE SQUARES USING CON> BEGIN CON> NUMBER=N CON> ITS_SQUARE = N * N CON> N = N + 1 CON> END DTR> FIND SQUARES [10 records found] DTR> PRINT ALL ITS NUMBER SQUARE 0 00 1 01 2 04 3 09 4 16 5 25 6 36 7 49 8 64 9 81 DTR> The following example stores data from the WORKER domain into the expanded NEW_WORKER domain. These domains have duplicate elementary field names that are subordinate to different group field names. The example uses a FOR statement to control the STORE statement so that DEC DATATRIEVE stores the data from the elementary fields correctly. The record definitions and the STORE statement are as follows: DTR> SHOW WORK_REC RECORD WORK_REC USING 01 WORK. 03 LOCAL. 05 CITY PIC X(10). 05 STATE PIC X(2). 03 REMOTE. 05 CITY PIC X(10). 05 STATE PIC X(2). ; DTR> SHOW NEW_WORK_REC RECORD NEW_WORK_REC USING 01 WORK. 03 NEW_LOCAL. 05 CITY PIC X(10). 05 STATE PIC X(2). 03 NEW_REMOTE. 05 CITY PIC X(10). 05 STATE PIC X(2). 03 NAME. 05 FIRST PIC X(10). 05 LAST PIC X(15). ; DTR> READY NEW_WORKER WRITE DTR> FOR WORKER CON> STORE NEW_WORKER USING CON> BEGIN CON> NEW_LOCAL = LOCAL CON> NEW_REMOTE = REMOTE CON> END DTR> 2 STORE_Statement_(for_Oracle_CODASYL_DBMS_and_Relational_Sources) Adds a new record to the database. Format { rdb-domain-name } { rdb-relation-name } STORE { dbms-domain-name } { } { dbms-record-name } [USING statement-1] [VERIFY [USING] statement-2] [ [CURRENCY] [context-name.]set-name-1 [,...] ] 3 Arguments rdb-domain-name Is the given name of the domain to contain the new relation. rdb-relation-name Is the name assigned to the relation when the database was created. The relation name can be the name of a view relation. dbms-domain-name Is the given name of the domain to contain the new record. dbms-record-name Is the name assigned to the record when the database was created and to the record which will be stored. USING statement-1 Specifies a DEC DATATRIEVE statement that can store one value for one or more fields in the new record. VERIFY [USING] statement-2 Specifies a statement DEC DATATRIEVE executes just before storing the new record. CURRENCY Is a keyword that is used only with Oracle CODASYL DBMS records or domains. context-name Is the name of a valid context variable or the name of a collection with a selected Oracle CODASYL DBMS record. It must identify a record that participates in the specified set. If the SYSTEM owns the set, you do not need to establish a context for the set. If the set is not owned by the SYSTEM and the context name is not present, DEC DATATRIEVE uses the most recent single record context of a domain with a record type that participates in the specified set type. set-name Is the name of a Oracle CODASYL DBMS set. The record being stored must be an AUTOMATIC member of that set. Use the CONNECT statement to connect the record to MANUAL insertion sets. It is not necessary to put SYSTEM-owned sets in the currency list. For all other AUTOMATIC sets, you must establish currency, but it is not necessary to put them in the currency list. 3 Examples The following example stores a new record in the relation JOB_ HISTORY and makes the change permanent by entering a COMMIT statement: DTR> READY PERSONNEL USING JOB_HISTORY WRITE DTR> STORE JOB_HISTORY Enter DEPARTMENT_CODE: HENG Enter EMPLOYEE_ID: 78645 Enter JOB_CODE: B-78 Enter JOB_END: 021783 Enter JOB_START: 052181 DTR> COMMIT The following example adds a new COMPONENT record to the database. A valid context must be established for current records in the sets PART_USED_ON and PART_USES to store a COMPONENT. The STORE_COMP procedure prompts for values so that DEC DATATRIEVE knows which record you want to be current. The nested FOR loop establishes the context, and the CURRENCY clause translates DEC DATATRIEVE contexts into Oracle CODASYL DBMS currencies. After you enter your response to the last prompt for the values in a record, Oracle CODASYL DBMS automatically inserts the record into the specified set occurrences: DTR> DEFINE PROCEDURE STORE_COMP DFN> DECLARE USED_ON PIC X(8). DFN> DECLARE SUB_PART PIC X(8). DFN> SUB_PART = *."I.D. number of the component part" DFN> USED_ON = *."I.D. number of the part it is used on" DFN> FOR A IN PART WITH PART_ID = USED_ON DFN> FOR B IN PART WITH PART_ID = SUB_PART DFN> STORE COMPONENTS USING DFN> BEGIN DFN> COMP_SUB_PART = SUB_PART DFN> COMP_OWNER_PART = USED_ON DFN> COMP_MEASURE = *."component measure" DFN> COMP_QUANTITY = *."quantity" DFN> END CURRENCY A.PART_USED_ON , B.PART_USES DFN> END_PROCEDURE DTR> 2 SUM_Statement Provides a summary of totals for one or more numeric fields in the current collection. The summary is sorted according to the values in one or more fields of the current collection. The summary includes subtotals for control groups. The summary can be written to a file or an output device. Format [ {file-spec } ] SUM print-list BY sort-list [ ON {*.prompt } ] [ { } ] 3 Arguments print-list Is a list of one or more numeric fields, other value expressions, and modifiers. The print list has the following format: {value-expression [ {modifier} [...] ] } [,...] The section on the PRINT statement describes the value expressions and modifiers you can use in a print list. sort-list Is a list of one or more sort keys that determine the order in which DEC DATATRIEVE presents the summary totals. An item in the sort list consists of the name of a field whose contents form the basis for the sort, preceded or followed by a keyword that determines the order DEC DATATRIEVE uses to sort the data. To specify the sort order for each sort key, use one of the following keywords: ASC[ENDING] DESC[ENDING] INCREASING DECREASING If you specify more than one sort key, use a comma to separate each sort key from the next. file-spec Is the file specification to which you want to write the output of the statement. A complete file specification has the following format: node-spec::device:[directory]file-name.type;version *.prompt-name Is the prompting value expression that prompts you for the file specification to which you want to write the output of the statement. 3 Example The following example forms a collection of yachts and uses the SUM statement to summarize the prices of yachts in the collection and to display the number of yachts built by each builder. Edit strings are used to format the values: DTR> READY YACHTS; FIND FIRST 6 YACHTS [6 records found] DTR> SUM 1 ("NUMBER"/"OF YACHTS") USING 9, CON> PRICE USING $$$$,$$$ BY BUILDER NUMBER NUMBER MANUFACTURER OF YACHTS PRICE OF YACHTS PRICE ALBERG 1 $36,951 ALBIN 3 $64,000 AMERICAN 2 $28,790 6 $129,741 DTR> 2 SYNCHRONIZED_Clause Causes word boundary alignment of an elementary field. Format { SYNCHRONIZED } [ LEFT ] { SYNC } [ RIGHT] { } [ ] 3 Arguments LEFT Allows compatibility with DEC COBOL record definitions. DEC DATATRIEVE accepts the argument but ignores the boundary alignment specification that the field begin at the left boundary of the unit of storage the field occupies. RIGHT Allows compatibility with DEC COBOL record definitions. DEC DATATRIEVE accepts the arguments but ignores the boundary alignment specification that the field end at the right boundary of the unit of storage the field occupies. 3 Example This example shows the difference in storage allocation a SYNC clause can make. A field of USAGE type LONG occupies four bytes of storage (the equivalent of one longword): DTR> DEFINE RECORD NOSYNC_REC USING DFN> 01 TOP. DFN> 03 ONE PIC X. DFN> 03 TWO LONG. DFN> ; [Record is 5 bytes long.] DTR> DEFINE RECORD SYNC_REC USING DFN> 01 TOP. DFN> 03 ONE PIC X. DFN> 03 TWO SYNC RIGHT LONG. DFN> ; [Record is 8 bytes long.] DTR> 2 THEN_Statement Joins two or more DEC DATATRIEVE statements into a compound statement. Format statement-1 {THEN statement-2} [...] 3 Argument statement Is a DEC DATATRIEVE statement. 3 Example The following example uses a THEN statement to join a PRINT statement and a MODIFY statement in a FOR loop: DTR> SET NO PROMPT DTR> READY YACHTS MODIFY DTR> FOR YACHTS WITH BUILDER EQ "ALBIN" CON> PRINT THEN MODIFY LENGTH OVER MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE ALBIN 79 SLOOP 26 4,200 10 $17,900 Enter MANUFACTURER: Execution terminated by operator DTR> 2 USAGE_Clause Specifies the internal format of a numeric field or specifies a date field. Format { DISPLAY } { BYTE } { WORD } { } { LONG } { QUAD } { } { } { {COMP } } { {INTEGER } } { { } } { } { {COMP-1 } } { { } } { {REAL } } { } { { } } { {COMP-2 } } { {DOUBLE } } { } USAGE [IS] { } { G_FLOATING } { } { } { H_FLOATING } { } { S_FLOATING } { } { } { T_FLOATING } { } { } { {COMP-3 } } { {PACKED } } { { } } { } { {COMP-5 } } { { } } { {ZONED } } { } { } { DATE } 3 Arguments DISPLAY Indicates that each digit occupies one byte of storage. DISPLAY is the default if you do not include a USAGE clause. BYTE Indicates that field value is stored in binary format and that the value is stored in one byte of storage. WORD Indicates that field value is stored in binary format and that the value is stored in one word (two bytes) of storage. LONG Indicates that field value is stored in binary format and that the value is stored in one longword (four bytes) of storage. QUAD Indicates that field value is stored in binary format and that the value is stored in one quadword (eight bytes) of storage. COMP Indicates that the field value is stored in binary format. INTEGER is a synonym for COMP. The size of a COMP (or INTEGER) field depends on the number of digit positions specified in its PICTURE clause. You can avoid having both a USAGE IS COMP clause and a PICTURE clause by using the keywords WORD, LONG, and QUAD to specify the three types of storage allocation available with COMP. COMP Storage Allocation Types shows the COMP storage allocation types. Table 1-9 COMP Storage Allocation Types Size of PIC Clause Field Alternate USAGE Type 9(1) to 2 bytes WORD 9(4) 9(5) to 4 bytes LONG 9(9) 9(10) to 8 bytes QUAD 9(18) COMP-1 Indicates that the field value is stored in single-precision real format. REAL is a synonym for COMP-1. COMP-1 fields are four bytes long and they correspond to the Oracle CDD/Repository F_ floating-point data types. COMP-2 Indicates that the field value is stored in double-precision real format. DOUBLE is a synonym for COMP-2. COMP-2 fields are eight bytes long and they correspond to the Oracle CDD/Repository D_ floating-point data types. G_FLOATING Indicates that a field is an extended range 64-bit floating-point number with precision to approximately 15 decimal digits. H_FLOATING Indicates that a field is an extended range 128-bit floating- point number with precision to approximately 33 decimal digits. S_FLOATING Indicates that the field is a floating-point number accurate to approximately 7 decimal digits. An S_floating-point field is 4 bytes long. T_FLOATING Indicates that the field is a floating-point number accurate to approximately 15 decimal digits. T_floating-point fields occupy 8 contiguous bytes in memory. COMP-3 Indicates that the field value is stored in packed-decimal format. PACKED is a synonym for COMP-3. The value is stored two digits per byte. The value of a COMP-3 field must contain a sign. The sign occupies the four low-ordered bits in the rightmost byte. The size of the field depends on the number of digit positions specified by the field's PICTURE clause: size (in bytes) = (digit-positions+1)__ 2 For example, a field with three digit positions is two bytes long. If the field contains an even number of digits, the size is rounded up. Thus, a 6-digit field is stored in four bytes. COMP-5 Indicates that the field value is stored in signed decimal format. ZONED is a synonym for COMP-5. A value in a COMP-5 field is stored one digit per byte. Therefore, the size of a COMP-5 field is the number of digit positions specified in its PICTURE clause. The sign of a COMP-5 value shares the rightmost byte with the lowest-valued digit of the value. The lowercase letters P through Y represent a negative sign for the values 0 through 9. DATE Indicates that the field is a date field. 3 Examples The following example defines the field SALE_PRICE as a REAL (COMP-1) field: 05 SALE_PRICE PIC 9(5) USAGE REAL EDIT_STRING IS $(6). The following example defines the field SALE_DATE as a date field, to be printed in the default format for date fields: 06 SALE_DATE USAGE IS DATE. 2 VALID_IF_Clause Validates a field value before it is stored in the record. Format VALID IF boolean-expression 3 Argument boolean-expression Is a DEC DATATRIEVE Boolean expression. 3 Examples The following example compares the value entered for the RIG field to the character strings SLOOP, KETCH, MS, and YAWL and stores the value in the field if it is one of those character strings: 06 RIG PIC X(6) VALID IF RIG EQ "SLOOP", "KETCH", "MS", "YAWL". The following example stores a value in the LOA field if it is between 15 and 50: 06 LENGTH_OVER_ALL PIC XXX VALID IF LOA BETWEEN 15 AND 50 QUERY_NAME IS LOA. The following example stores a value in the PRICE field if it is greater than 1.3 times the displacement or if it is zero: 06 PRICE PIC 99999 VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 EDIT_STRING IS $$$,$$$. 2 WHILE_Statement Causes DEC DATATRIEVE to repeat a statement as long as the condition specified in the Boolean expression is true. Format WHILE boolean-expression statement 3 Arguments boolean-expression Is a Boolean expression. In the WHILE statement, Boolean expressions are limited to the following format: { variable-name } { *.prompt } boolean-operator value-expression { } statement Is a simple or compound statement you want DEC DATATRIEVE to execute if the Boolean expression evaluates to true. 3 Example The following example groups the boats with LOA less than 35 according to the value of BEAM and displays the TYPE, LOA, and BEAM of the shortest boat from each group of boats with the same value for BEAM: DTR> SHOW WHILE_EX PROCEDURE WHILE_EX BEGIN DECLARE X PIC 99. X = 0 FOR YACHTS WITH LOA < 35 AND BEAM NE 0 SORTED BY BEAM, LOA WHILE X < BEAM BEGIN PRINT TYPE, LOA, BEAM, X X = BEAM END END END_PROCEDURE DTR> :WHILE_EX LENGTH OVER MANUFACTURER MODEL ALL BEAM X CAPE DORY TYPHOON 19 06 00 WINDPOWER IMPULSE 16 07 06 ERICSON 23/ SPECIA 23 08 07 EASTWARD HO 24 09 08 ALBIN 79 26 10 09 BOMBAY CLIPPER 31 11 10 IRWIN 25 25 12 11 DTR> 2 WITH_FORM_Statement Sends and receives data to and from a DECforms form. Control text items can be also sent and received. Format WITH_FORM form-name IN file-name SEND FROM datatrieve-source [USING exchange-record] [,] . . . . . . . . . TO decforms-name RECEIVE FROM decforms-name TO datatrieve-destination [USING exchange-record] [,] . . . . . . . . . [SEND_CONTROL_TEXT send-control-item [,...]] [RECEIVE_CONTROL_TEXT receive-control-item [,...]] 3 Arguments form-name Is the name of the DECforms form in the form file. The form name is syntactically required but ignored when the file name is a .FORM file. file-name Is the DECforms file name. It can either be a .FORM or a .EXE file (the default file extension is .EXE). A complete file specification has the following format: node-spec::device:[directory]file-name.type;version decforms-name Is a DECforms record name or list name. A list is a DECforms structure. If a list name is specified as decforms-name, all the equivalent datatrieve-sources or datatrieve-destinations must be specified. datatrieve-source/datatrieve-destination Is the name of a DEC DATATRIEVE data element; a data element can be represented by a DEC DATATRIEVE record, by a group field, by a field, or by a variable. When datatrieve-source and datatrieve- destination can be used interchangeably, they are referred to as "DEC DATATRIEVE data element". The DEC DATATRIEVE data element can not be a COMPUTED BY field (for more information see the DEC DATATRIEVE Guide to Interfaces). When the decforms-name is a list name, specify a list of DEC DATATRIEVE data elements separated by commas. exchange-record Is the Oracle CDD/Repository path name of a record used to send and receive data with DECforms. It is an optional argument of the datatrieve-source and datatrieve-destination structures. send-control-item Is the input parameter (variable or string literal) that activates the proper actions defined by the user inside the .IFDL file. If you specify more than one input parameter, separate them with commas. Every control-item has to be from one to five characters long. For more details on how to build and use a SEND_ CONTROL_TEXT see the DECforms documentation. receive-control-item Is a DEC DATATRIEVE variable previously declared which receives a text control item returned by the form. The content of the variable will be loaded by the form depending on the rules established by the user in the .IFDL file. If you specify more than one output parameter, separate them with commas. Every receive-control-item should be five characters long. 3 Example In the following example the WITH_FORM statement causes DEC DATATRIEVE to send records contained in the YACHTS domain to the form record named BOAT. The form responds to the send operation by displaying the form record data (one record at a time) on the screen. DTR> READY YACHTS DTR> FOR X IN YACHTS CON> WITH_FORM YACHT IN DTR$LIBRARY:FORMS CON> SEND FROM X TO BOAT; 2 Wombat Wombats are native Australian or Tasmanian mammals. Like many other antipodean animals, they have strange* reproductive habits (less so than the platypus which lays green eggs and is a monotreme). They also have constantly growing incisors allowing (nay, encouraging) them to chew on bark, wood, softer rocks, etc. (Wombats are friendly, loyal, nocturnal, and not overly intelligent. Sir Everard Home reports, "In captivity it is as a rule amiable, the amiability being possibly associated with stupidity." He probably woke it from a nap.) * strange to us-they wouldn't have it any other way. The family Vombatidae is divided into two groups: the naked nosed and the hairy nosed wombats. The naked nosed group constitutes the genus Vombatuis (or Phascolomis) and includes the Tasmanian wombat (V. Ursinus) from Tasmania and Flinders Island and the common Wombat (V. hirsutus) from south east Australia. These have coarse, harsh, blackish brown fur, a naked area on the muzzle, and short ears. The hairy nosed group contains Lasiorhinus latifrons from south Australia and wombatula gillespiei from southern Queensland. These species have silky grizzled gray fur, a hairy muzzle, and larger ears. The consequences of all this to wombat society is further complicated by the question of who has more ribs. 3 Advanced Wombats, particular Dante Gabriel Rossetti had a wombat who slept (during the day) in an epergne on the dining room table. He (the wombat) reappeared as a dormouse in Rev. Dodgson's book. Wombats, uses of live-conversation piece, alarm clock (third shift) dead-doormats; for food, see Wombats, food? Wombats, food grass, bark, leaves, fungi Epergne Who knows? ...clearly someplace wombats sleep. Marsupials Include bandicoots (which should be rabbits), koalas (which should be bears), tasmanian wolves (which should be coyotes), and wombats (which should be lethargic badgers). Pogo was a marsupial. Sexual habits These are of interest only to other wombats, and then only between April and June. Wombats, prehistoric Pleistocene Giant Wombat was as large as a rhinoceros. Wombats, food? Would you want to eat a doormat that ate bark and fungus?